Channels
Get Channel Metafields
GET /stores/{store_hash}/v3/channels/{channel_id}/metafields
Request
Returns a list of metafields on a channel. Optional filter parameters can be passed in.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- 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 namespace.
- direction in query - string
Sort direction. Acceptable values are:
asc
,desc
.Allowed values: asc | desc
example
Response
OK
Body
Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see Platform Limits in the Help Center.
idinteger
Unique ID of the Metafield.
Example: 6
permission_setstring
Determines 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
namespacestring
>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes.
Example: Warehouse Locations
keystring
>= 1 characters<= 64 charactersThe name of the field, for example:
location_id
,color
.Example: Location
valuestring
>= 1 characters<= 65535 charactersThe value of the field.
Example: 4HG
descriptionstring
>= 0 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
resource_typestring
The type of resource with which the metafield is associated.
Allowed: category | brand | product | variant
Example: product
resource_idinteger
The ID for the resource with which the metafield is associated.
Example: 111
date_createdstring
Date and time of the metafieldʼs creation. Read-Only.
Example: 2018-05-07T20:14:17.000Z
date_modifiedstring
Date and time when the metafield was last updated. Read-Only.
Example: 2018-05-07T20:14:17.000Z
example
Create a Channel Metafield
POST /stores/{store_hash}/v3/channels/{channel_id}/metafields
Request
Creates a channel metafield.
Note: The maxiumum number of metafields allowed on each order, product, category, variant, channel, 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 product, category, variant, or brand is 250. For more information, see Platform Limits in the Help Center.
namespacestring
required>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes. This is set by the developer.
Example: Warehouse Locations
keystring
required>= 1 characters<= 64 charactersThe name of the field.
Example: Location
valuestring
required>= 1 characters<= 65535 charactersThe value of the field.
Example: 4HG
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
>= 0 characters<= 255 charactersDescription for the metafield.
Example: Location in the warehouse
Response
OK
Body
Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see Platform Limits in the Help Center.
idinteger
Unique ID of the Metafield.
Example: 6
permission_setstring
Determines 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
namespacestring
>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes.
Example: Warehouse Locations
keystring
>= 1 characters<= 64 charactersThe name of the field, for example:
location_id
,color
.Example: Location
valuestring
>= 1 characters<= 65535 charactersThe value of the field.
Example: 4HG
descriptionstring
>= 0 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
resource_typestring
The type of resource with which the metafield is associated.
Allowed: category | brand | product | variant
Example: product
resource_idinteger
The ID for the resource with which the metafield is associated.
Example: 111
date_createdstring
Date and time of the metafieldʼs creation. Read-Only.
Example: 2018-05-07T20:14:17.000Z
date_modifiedstring
Date and time when the metafield was last updated. Read-Only.
Example: 2018-05-07T20:14:17.000Z
example
Get a Channel Metafield
GET /stores/{store_hash}/v3/channels/{channel_id}/metafields/{metafield_id}
Request
Returns a single channel 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.
- channel_id in path - integerrequired
The ID of a channel.
- metafield_id in path - stringrequired
example
Response
OK
Body
Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see Platform Limits in the Help Center.
idinteger
Unique ID of the Metafield.
Example: 6
permission_setstring
Determines 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
namespacestring
>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes.
Example: Warehouse Locations
keystring
>= 1 characters<= 64 charactersThe name of the field, for example:
location_id
,color
.Example: Location
valuestring
>= 1 characters<= 65535 charactersThe value of the field.
Example: 4HG
descriptionstring
>= 0 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
resource_typestring
The type of resource with which the metafield is associated.
Allowed: category | brand | product | variant
Example: product
resource_idinteger
The ID for the resource with which the metafield is associated.
Example: 111
date_createdstring
Date and time of the metafieldʼs creation. Read-Only.
Example: 2018-05-07T20:14:17.000Z
date_modifiedstring
Date and time when the metafield was last updated. Read-Only.
Example: 2018-05-07T20:14:17.000Z
example
Update a Channel Metafield
PUT /stores/{store_hash}/v3/channels/{channel_id}/metafields/{metafield_id}
Request
Updates a single channel metafield.
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 a403
error message.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- metafield_id in path - stringrequired
- 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 product, category, variant, or brand 250. For more information, see Platform Limits in the Help Center.
namespacestring
>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes.
Example: Warehouse Locations
keystring
>= 1 characters<= 64 charactersThe name of the field.
Example: Location
valuestring
>= 1 characters<= 65535 charactersThe value of the field.
Example: 4HG
permission_setstring
Determines 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
>= 0 characters<= 255 charactersDescription for the metafield.
Example: Location in the warehouse.
example
Response
OK
Body
Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see Platform Limits in the Help Center.
idinteger
Unique ID of the Metafield.
Example: 6
permission_setstring
Determines 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
namespacestring
>= 1 characters<= 64 charactersNamespace for the metafield, for organizational purposes.
Example: Warehouse Locations
keystring
>= 1 characters<= 64 charactersThe name of the field, for example:
location_id
,color
.Example: Location
valuestring
>= 1 characters<= 65535 charactersThe value of the field.
Example: 4HG
descriptionstring
>= 0 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
resource_typestring
The type of resource with which the metafield is associated.
Allowed: category | brand | product | variant
Example: product
resource_idinteger
The ID for the resource with which the metafield is associated.
Example: 111
date_createdstring
Date and time of the metafieldʼs creation. Read-Only.
Example: 2018-05-07T20:14:17.000Z
date_modifiedstring
Date and time when the metafield was last updated. Read-Only.
Example: 2018-05-07T20:14:17.000Z
example
Delete a Channel Metafield
DELETE /stores/{store_hash}/v3/channels/{channel_id}/metafields/{metafield_id}
Request
Deletes a single channel 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.
- channel_id in path - integerrequired
The ID of a channel.
- metafield_id in path - stringrequired
example
Response
No Content