Catalog - Categories
Get Category Metafields
GET /stores/{store_hash}/v3/catalog/categories/{category_id}/metafields
Request
Returns a list of Metafields on a Category. Optional filter parameters can be passed in.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- id in query - integer
Filter items by metafield ID.
- id:in in query - array
Explicitly include objects by passing a comma-separated list of IDs.
- id:not_in in query - array
Exclude objects by passing a comma-separated list of IDs.
- id:min in query - integer
- id:max in query - integer
- id:greater in query - integer
- id:less in query - integer
- key in query - string
Filter based on a metafieldʼs key.
- namespace in query - string
Filter based on a metafieldʼs namespaces.
- 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.
- 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
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.
example
Create a Category Metafield
POST /stores/{store_hash}/v3/catalog/categories/{category_id}/metafields
Request
Creates a Category Metafield.
Required Fields:
- permission_set
- namespace
- key
- value
Read-Only Fields
- id
Note: The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see Platform Limits (Help Center) 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 (Help Center) 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
>= 0 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
example
Response
Body
data
metaobject
Response metadata.
example
Get a Category Metafield
GET /stores/{store_hash}/v3/catalog/categories/{category_id}/metafields/{metafield_id}
Request
Returns a single Category 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 a Category Metafield
PUT /stores/{store_hash}/v3/catalog/categories/{category_id}/metafields/{metafield_id}
Request
Updates a Category 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 (Help Center) 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
>= 0 characters<= 255 charactersDescription for the metafields.
Example: Location in the warehouse
example
Response
Body
data
metaobject
Response metadata.
example
Delete a Category Metafield
DELETE /stores/{store_hash}/v3/catalog/categories/{category_id}/metafields/{metafield_id}
Request
Deletes a Category 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.
- category_id in path - integerrequired
The ID of the
Category
to which the resource belongs. - metafield_id in path - integerrequired
The ID of the
Metafield
.