Metafields | BigCommerce Dev Center

Get All Product Variant Metafields

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

Request

Returns a list of product variant 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.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.
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]/variants/[variant_id]/metafields' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataarray[object]
metaobject
Returns the categories tree, a nested lineage of the categories with parent->child relationship. The Category objects returned are simplified versions of the category objects returned in the rest of this API.

example

{
  "data": [
    {
      "key": "Location",
      "value": "4HG",
      "namespace": "Warehouse Locations",
      "permission_set": "app_only",
      "description": "Location in the warehouse",
      "resource_type": "product",
      "resource_id": 111
    }
  ],
  "meta": {
    "data": [
      {
        "id": 26,
        "parent_id": 25,
        "name": "Bath",
        "is_visible": true,
        "url": "/towels/bath-towels/"
      }
    ],
    "meta": {}
  }
}

Create a Product Variant Metafield

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

Request

Creates a product variant Metafield.

Required Fields:

permission_set
namespace
key
value

Read-Only Fields

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.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.

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": "variant",
    "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": {}
}

Get a Product Variant Metafields

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

Request

Returns a single product variant 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.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.
metafield_id in path - integer - required
The ID of the Metafield.
metafield_id in path - integer - required
The ID of the Metafield.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.
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]/variants/[variant_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": 8,
    "key": "location_id",
    "value": "Shelf 3, Bin 5",
    "namespace": "Inventory Namespace",
    "permission_set": "read",
    "resource_type": "variant",
    "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": {}
}

Update Product Variant Metafields

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

Request

Updates a product variant 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
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.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.

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": "variant",
    "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": {}
}

Delete a Variant Metafield

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

Request

Deletes a product variant 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.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.
metafield_id in path - integer - required
The ID of the Metafield.
metafield_id in path - integer - required
The ID of the Metafield.
variant_id in path - integer - required
ID of the variant on a product, or on an associated Price List Record.

example

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

Get All Product Variant Metafields

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Create a Product Variant Metafield

Request

Authentication

Parameters

Body

keystringrequired

valuestringrequired

namespacestringrequired

permission_setstringrequired

descriptionstring

example

Response

Body

data

metaobject

example

Get a Product Variant Metafields

Request

Authentication

Parameters

example

Response

Body

data

metaobject

example

Update Product Variant Metafields

Request

Authentication

Parameters

Body

keystringrequired

valuestringrequired

namespacestringrequired

permission_setstringrequired

descriptionstring

example

Response

Body

data

metaobject

example

Delete a Variant Metafield

Request

Authentication

Parameters

example

Response

keystring
required

valuestring
required

namespacestring
required

permission_setstring
required

keystring
required

valuestring
required

namespacestring
required

permission_setstring
required