Metafields | BigCommerce Dev Center

Get All Product Metafields

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/metafields

Request

Returns a list of Product Metafields. Optional parameters can be passed in.

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.
product_id in path - integer - required
The ID of the Product to which the resource belongs.
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.
include_fields in query - string
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
exclude_fields in query - string
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/metafields' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataarray[object]
metaobject
Data about the response, including pagination and collection totals.

example

{
  "data": [
    {
      "id": 6,
      "key": "Location",
      "value": "4HG",
      "namespace": "Warehouse Locations",
      "permission_set": "app_only",
      "resource_type": "product",
      "resource_id": 111,
      "description": "Location in the warehouse",
      "date_created": "1973-01-20T21:34:57.903Z",
      "date_modified": "1990-12-30T00:29:23.515Z"
    },
    {
      "id": 7,
      "key": "Sublocation",
      "value": "4HG",
      "namespace": "Warehouse Locations",
      "permission_set": "read",
      "resource_type": "product",
      "resource_id": 111,
      "description": "Location in the warehouse",
      "date_created": "1973-01-20T21:34:57.903Z",
      "date_modified": "1990-12-30T00:29:23.515Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}

Create a Product Metafield

POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/metafields

Request

Creates a Product Metafield.

Required Fields:

permission_set
namespace
key
value

Note: The maxiumum number of metafields allowed on each order, product, category, variant, 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 is 50. For more information, see Platform Limits in the Help Center.

keystring
required
The name of the field, for example: location_id, color. Required for POST.
>= 1 characters<= 64 characters
Example: Location
valuestring
required
The value of the field, for example: 1, blue. Required for POST.
>= 1 characters<= 65535 characters
Example: 4HG
namespacestring
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_setstring
required

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
Description for the metafields.
>= 0 characters<= 255 characters
Example: Location in the warehouse

example

{
  "key": "Location",
  "value": "4HG",
  "namespace": "Warehouse Locations",
  "permission_set": "app_only",
  "description": "Location in the warehouse"
}

Response

Body

object | application/json

data
metaobject
Response metadata.

example

{
  "data": {
    "id": 8,
    "key": "location_id",
    "value": "Shelf 3, Bin 5",
    "namespace": "Inventory Namespace",
    "permission_set": "read",
    "resource_type": "product",
    "resource_id": 158,
    "description": "Where products are located",
    "date_created": "2018-09-13T16:42:37+00:00",
    "date_modified": "2018-09-13T16:42:37+00:00"
  },
  "meta": {}
}

Get a Product Metafield

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/metafields/{metafield_id}

Request

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

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.
product_id in path - integer - required
The ID of the Product to which the resource belongs.
metafield_id in path - integer - required
The ID of the Metafield.
metafield_id in path - integer - required
The ID of the Metafield.
include_fields in query - string
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
exclude_fields in query - string
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/metafields/[metafield_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

data
metaobject
Response metadata.

example

{
  "data": {
    "id": 4,
    "key": "location_id",
    "value": "Shelf 3, Bin 5",
    "namespace": "App Namespace",
    "permission_set": "app_only",
    "resource_type": "product",
    "resource_id": 137,
    "description": "Where products are located",
    "date_created": "2021-08-06T19:15:35+00:00",
    "date_modified": "2021-08-06T19:15:35+00:00"
  },
  "meta": {}
}

Update a Product Metafield

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/metafields/{metafield_id}

Request

Updates a Product Metafield.

Required Fields

none

Read-Only Fields

id
These fields can only be modified using the API account that created the metafield:
- namespace
- key
- permission_set
- value

Usage Notes

Attempting to modify the namespace, key, permission_set, or value field using an API account 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
Content-Type in header with default of application/json - string - required
The MIME type of the request body.
metafield_id in path - integer - required
The ID of the Metafield.

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 in the Help Center.

keystring
required
The name of the field, for example: location_id, color. Required for POST.
>= 1 characters<= 64 characters
Example: Location
valuestring
required
The value of the field, for example: 1, blue. Required for POST.
>= 1 characters<= 65535 characters
Example: 4HG
namespacestring
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_setstring
required

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
Description for the metafields.
>= 0 characters<= 255 characters
Example: Location in the warehouse

example

{
  "key": "Location",
  "value": "4HG",
  "namespace": "Warehouse Locations",
  "permission_set": "app_only",
  "description": "Location in the warehouse"
}

Response

Body

object | application/json

data
metaobject
Response metadata.

example

{
  "data": {
    "id": 4,
    "key": "location_id",
    "value": "Shelf 3, Bin 5",
    "namespace": "App Namespace",
    "permission_set": "app_only",
    "resource_type": "product",
    "resource_id": 137,
    "description": "Where products are located",
    "date_created": "2021-08-06T19:15:35+00:00",
    "date_modified": "2021-08-06T19:15:35+00:00"
  },
  "meta": {}
}

Delete a Product Metafield

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/metafields/{metafield_id}

Request

Deletes a Product 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.
product_id in path - integer - required
The ID of the Product to which the resource belongs.
metafield_id in path - integer - required
The ID of the Metafield.
metafield_id in path - integer - required
The ID of the Metafield.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/metafields/[metafield_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Get All Product Metafields

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Create a Product Metafield

Request

Authentication

Parameters

Body

keystringrequired

valuestringrequired

namespacestringrequired

permission_setstringrequired

descriptionstring

example

Response

Body

data

metaobject

example

Get a Product Metafield

Request

Authentication

Parameters

example

Response

Body

data

metaobject

example

Update a Product Metafield

Request

Authentication

Parameters

Body

keystringrequired

valuestringrequired

namespacestringrequired

permission_setstringrequired

descriptionstring

example

Response

Body

data

metaobject

example

Delete a Product Metafield

Request

Authentication

Parameters

example

Response

keystring
required

valuestring
required

namespacestring
required

permission_setstring
required

keystring
required

valuestring
required

namespacestring
required

permission_setstring
required