Docs
Catalog API
Categories
Metafields

Metafields

Get Category Metafields

GET /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 header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • category_id in path - integer
    required

    The ID of the Category to which the resource belongs.

  • 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.
    Type: array[integer]
  • id:not_in in query - array
    Exclude objects by passing a comma-separated list of IDs.
    Type: array[integer]
  • 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 results.

  • limit in query - integer

    Controls the number of items per page in a limited (paginated) list of results.

  • include_fields in query - array
    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
    Type: array[string]
  • 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.
    Type: array[string]

example

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

Create a Category Metafield

POST /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 header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • category_id in path - integer
    required

    The ID of the Category to which the resource belongs.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
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.

  • key    string
    required

    The name of the field, for example: location_id, color. Required for POST.

    >= 1 characters<= 64 characters
    Example: Location

  • value    string
    required

    The value of the field, for example: 1, blue. Required for POST.

    >= 1 characters<= 65535 characters
    Example: 4HG

  • namespace    string
    required

    Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST.

    >= 1 characters<= 64 characters
    Example: Warehouse Locations

  • permission_set    string
    required

    Determines the visibility and writeability of the field by other API consumers.

    ValueDescription
    app_onlyPrivate to the app that owns the field
    readVisible to other API consumers
    writeOpen for reading and writing by other API consumers
    read_and_sf_accessVisible to other API consumers, including on storefront
    write_and_sf_accessOpen for reading and writing by other API consumers, including on storefront

    Allowed: app_only | read | write | read_and_sf_access | write_and_sf_access

  • description    string

    Description for the metafields.

    >= 0 characters<= 255 characters
    Example: Location in the warehouse

example

Response

Body

object | application/json

  • data    object

    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.

  • meta    object

    Response metadata.

example

Get a Category Metafield

GET /catalog/categories/{category_id}/metafields/{metafield_id}

Request

Returns a single Category Metafield. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • category_id in path - integer
    required

    The ID of the Category to which the resource belongs.

  • metafield_id in path - integer
    required

    The ID of the Metafield.

  • include_fields in query - array
    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
    Type: array[string]
  • 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.
    Type: array[string]

example

Response

Body

object | application/json

  • data    object

    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.

  • meta    object

    Response metadata.

example

Update a Category Metafield

PUT /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, and permission_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 header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • category_id in path - integer
    required

    The ID of the Category to which the resource belongs.

  • metafield_id in path - integer
    required

    The ID of the Metafield.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
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.

  • key    string
    required

    The name of the field, for example: location_id, color. Required for POST.

    >= 1 characters<= 64 characters
    Example: Location

  • value    string
    required

    The value of the field, for example: 1, blue. Required for POST.

    >= 1 characters<= 65535 characters
    Example: 4HG

  • namespace    string
    required

    Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST.

    >= 1 characters<= 64 characters
    Example: Warehouse Locations

  • permission_set    string
    required

    Determines the visibility and writeability of the field by other API consumers.

    ValueDescription
    app_onlyPrivate to the app that owns the field
    readVisible to other API consumers
    writeOpen for reading and writing by other API consumers
    read_and_sf_accessVisible to other API consumers, including on storefront
    write_and_sf_accessOpen for reading and writing by other API consumers, including on storefront

    Allowed: app_only | read | write | read_and_sf_access | write_and_sf_access

  • description    string

    Description for the metafields.

    >= 0 characters<= 255 characters
    Example: Location in the warehouse

example

Response

Body

object | application/json

  • data    object

    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.

  • meta    object

    Response metadata.

example

Delete a Category Metafield

DELETE /catalog/categories/{category_id}/metafields/{metafield_id}

Request

Deletes a Category Metafield.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • category_id in path - integer
    required

    The ID of the Category to which the resource belongs.

  • metafield_id in path - integer
    required

    The ID of the Metafield.

example

Response

Did you find what you were looking for?
Delete a Category ImageGet Category Metafields