Docs
Management API
Metafields

Metafields

Get Channel Metafields

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

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: asc | desc

example

Response

OK

Body

object | application/json

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.

  • id
    integer

    Unique ID of the Metafield.

    Example: 6

  • permission_set
    string

    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

  • namespace
    string

    Namespace for the metafield, for organizational purposes.

    >= 1 characters<= 64 characters

    Example: Warehouse Locations

  • key
    string

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

    >= 1 characters<= 64 characters

    Example: Location

  • value
    string

    The value of the field.

    >= 1 characters<= 65535 characters

    Example: 4HG

  • description
    string

    Description for the metafields.

    >= 0 characters<= 255 characters

    Example: Location in the warehouse

  • resource_type
    string

    The type of resource with which the metafield is associated.

    Allowed: category | brand | product | variant

    Example: product

  • resource_id
    integer

    The ID for the resource with which the metafield is associated.

    0
    Max: 10000000000

    Example: 111

  • date_created
    string

    Date and time of the metafieldʼs creation. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

  • date_modified
    string

    Date and time when the metafield was last updated. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

example

Create a Channel Metafield

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

Parameters

  • store_hash in path - string
  • 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 product, category, variant, or brand is 250. For more information, see Platform Limits in the Help Center.

  • namespace
    string
    required

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

    >= 1 characters<= 64 characters

    Example: Warehouse Locations

  • key
    string
    required

    The name of the field.

    >= 1 characters<= 64 characters

    Example: Location

  • value
    string
    required

    The value of the field.

    >= 1 characters<= 65535 characters

    Example: 4HG

  • 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 metafield.

    >= 0 characters<= 255 characters

    Example: Location in the warehouse

Response

OK

Body

object | application/json

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.

  • id
    integer

    Unique ID of the Metafield.

    Example: 6

  • permission_set
    string

    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

  • namespace
    string

    Namespace for the metafield, for organizational purposes.

    >= 1 characters<= 64 characters

    Example: Warehouse Locations

  • key
    string

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

    >= 1 characters<= 64 characters

    Example: Location

  • value
    string

    The value of the field.

    >= 1 characters<= 65535 characters

    Example: 4HG

  • description
    string

    Description for the metafields.

    >= 0 characters<= 255 characters

    Example: Location in the warehouse

  • resource_type
    string

    The type of resource with which the metafield is associated.

    Allowed: category | brand | product | variant

    Example: product

  • resource_id
    integer

    The ID for the resource with which the metafield is associated.

    0
    Max: 10000000000

    Example: 111

  • date_created
    string

    Date and time of the metafieldʼs creation. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

  • date_modified
    string

    Date and time when the metafield was last updated. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

example

Get a Channel Metafield

GET /channels/{channel_id}/metafields/{metafield_id}

Request

Returns a single channel metafield.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • channel_id in path - integer
    required

    The ID of a channel.

  • metafield_id in path - string
    required

example

Response

OK

Body

object | application/json

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.

  • id
    integer

    Unique ID of the Metafield.

    Example: 6

  • permission_set
    string

    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

  • namespace
    string

    Namespace for the metafield, for organizational purposes.

    >= 1 characters<= 64 characters

    Example: Warehouse Locations

  • key
    string

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

    >= 1 characters<= 64 characters

    Example: Location

  • value
    string

    The value of the field.

    >= 1 characters<= 65535 characters

    Example: 4HG

  • description
    string

    Description for the metafields.

    >= 0 characters<= 255 characters

    Example: Location in the warehouse

  • resource_type
    string

    The type of resource with which the metafield is associated.

    Allowed: category | brand | product | variant

    Example: product

  • resource_id
    integer

    The ID for the resource with which the metafield is associated.

    0
    Max: 10000000000

    Example: 111

  • date_created
    string

    Date and time of the metafieldʼs creation. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

  • date_modified
    string

    Date and time when the metafield was last updated. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

example

Update a Channel Metafield

PUT /channels/{channel_id}/metafields/{metafield_id}

Request

Updates a single channel metafield.

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
  • metafield_id in path - string
    required
  • 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 product, category, variant, or brand 250. For more information, see Platform Limits in the Help Center.

  • namespace
    string

    Namespace for the metafield, for organizational purposes.

    >= 1 characters<= 64 characters

    Example: Warehouse Locations

  • key
    string

    The name of the field.

    >= 1 characters<= 64 characters

    Example: Location

  • value
    string

    The value of the field.

    >= 1 characters<= 65535 characters

    Example: 4HG

  • permission_set
    string

    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 metafield.

    >= 0 characters<= 255 characters

    Example: Location in the warehouse.

example

Response

OK

Body

object | application/json

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.

  • id
    integer

    Unique ID of the Metafield.

    Example: 6

  • permission_set
    string

    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

  • namespace
    string

    Namespace for the metafield, for organizational purposes.

    >= 1 characters<= 64 characters

    Example: Warehouse Locations

  • key
    string

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

    >= 1 characters<= 64 characters

    Example: Location

  • value
    string

    The value of the field.

    >= 1 characters<= 65535 characters

    Example: 4HG

  • description
    string

    Description for the metafields.

    >= 0 characters<= 255 characters

    Example: Location in the warehouse

  • resource_type
    string

    The type of resource with which the metafield is associated.

    Allowed: category | brand | product | variant

    Example: product

  • resource_id
    integer

    The ID for the resource with which the metafield is associated.

    0
    Max: 10000000000

    Example: 111

  • date_created
    string

    Date and time of the metafieldʼs creation. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

  • date_modified
    string

    Date and time when the metafield was last updated. Read-Only.

    Example: 2018-05-07T20:14:17.000Z

example

Delete a Channel Metafield

DELETE /channels/{channel_id}/metafields/{metafield_id}

Request

Deletes a single channel metafield.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required

    The MIME type of the response body.

  • channel_id in path - integer
    required

    The ID of a channel.

  • metafield_id in path - string
    required

example

Response

No Content

Did you find what you were looking for?