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
    required

Parameters

  • store_hash in path - 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
    required

Parameters

  • store_hash in path - string

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

  • 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
    required

Parameters

  • store_hash in path - string

example

Response

Body

object | application/json

  • data

  • 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
    required

Parameters

  • store_hash in path - string

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

  • 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
    required

Parameters

  • store_hash in path - string

example

Response

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