Catalog - Product variants
Get Product Variant Metafields
GET /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/metafields
Request
Returns a list of product variant Metafields. Optional parameters can be passed in.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- include_fields in query - array
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- exclude_fields in query - array
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
- page in query - integer
Specifies the page number in a limited (paginated) list of products.
- limit in query - integer
Controls the number of items per page in a limited (paginated) list of products.
- key in query - string
Filter based on a metafieldʼs key.
- namespace in query - string
Filter based on a metafieldʼs namespaces.
example
Response
Body
dataarray[object]
metaobject
Returns the categories tree, a nested lineage of the categories with parent->child relationship. The Category objects returned are simplified versions of the category objects returned in the rest of this API.
example
Create a Product Variant Metafield
POST /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/metafields
Request
Creates a product variant Metafield.
Required Fields:
- permission_set
- namespace
- key
- value
Read-Only Fields
- id
Note: The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see Platform Limits in the Help Center.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see Platform Limits in the Help Center.
keystring
required>= 1 characters<= 64 charactersThe name of the field, for example:
location_id
,color
. Required for POST.Example: Location
valuestring
required>= 1 characters<= 65535 charactersThe value of the field, for example:
1
,blue
. Required for POST.Example: 4HG
namespacestring
required>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes. This is set by the developer. Required for POST.
Example: Warehouse Locations
permission_setstring
requiredDetermines the visibility and writeability of the field by other API consumers.
Value Description app_only
Private to the app that owns the field read
Visible to other API consumers write
Open for reading and writing by other API consumers read_and_sf_access
Visible to other API consumers, including on storefront write_and_sf_access
Open for reading and writing by other API consumers, including on storefront Allowed: app_only | read | write | read_and_sf_access | write_and_sf_access
descriptionstring
>= 1 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
example
Response
Body
data
metaobject
Response metadata.
example
Get a Product Variant Metafields
GET /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}
Request
Returns a single product variant Metafield. Optional parameters can be passed in.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- include_fields in query - array
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- exclude_fields in query - array
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
example
Response
Body
data
metaobject
Response metadata.
example
Update Product Variant Metafields
PUT /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}
Request
Updates a product variant Metafield.
Required Fields:
- none
Read-Only Fields
- id
- These fields can only be modified by the app (API credentials) that created the metafield:
- namespace
- key
- permission_set
Usage Notes
- Attempting to modify
namespace
,key
, andpermission_set
fields using a client ID different from the one used to create those metafields will result in a 403 error message.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see Platform Limits in the Help Center.
keystring
required>= 1 characters<= 64 charactersThe name of the field, for example:
location_id
,color
. Required for POST.Example: Location
valuestring
required>= 1 characters<= 65535 charactersThe value of the field, for example:
1
,blue
. Required for POST.Example: 4HG
namespacestring
required>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes. This is set by the developer. Required for POST.
Example: Warehouse Locations
permission_setstring
requiredDetermines the visibility and writeability of the field by other API consumers.
Value Description app_only
Private to the app that owns the field read
Visible to other API consumers write
Open for reading and writing by other API consumers read_and_sf_access
Visible to other API consumers, including on storefront write_and_sf_access
Open for reading and writing by other API consumers, including on storefront Allowed: app_only | read | write | read_and_sf_access | write_and_sf_access
descriptionstring
>= 1 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
example
Response
Body
data
metaobject
Response metadata.
example
Delete a Product Variant Metafield
DELETE /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}
Request
Deletes a product variant Metafield.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- product_id in path - integerrequired
The ID of the
Product
to which the resource belongs. Product variant metafield endpoints that have theproduct_id
in the request path are successful as long as the parameter is not empty. Theproduct_id
segment is there only for path consistency. - variant_id in path - integerrequired
ID of the variant on a product, or on an associated Price List Record.
- metafield_id in path - integerrequired
The ID of the
Metafield
.