Metafields

Get brand metafields

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/brands/{brand_id}/metafields

Request

Returns a list of brand metafields. Optional filter parameters can be passed in.

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
brand_id in path - integer
required
The ID of the brand to which the resource belongs.
Accept in header with default of application/json - string
required
The MIME type of the response body.
id in query - integer
Filter items by ID.
id:in in query - array
Type: array[integer]
id:not_in in query - array
Type: array[integer]
id:min in query - array
Type: array[integer]
id:max in query - array
Type: array[integer]
id:greater in query - array
Type: array[integer]
id:less in query - array
Type: array[integer]
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 namespaces.
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

curl --request GET \

--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/brands/[brand_id]/metafields' \

--header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Auth-Token: {{token}}'

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": "brand",

"resource_id": 111,

"description": "Location in the warehouse",

"date_created": "1973-01-20T21:34:57.903Z",

"date_modified": "1990-12-30T00:29:23.515Z",

"owner_client_id": "e8o0nm9ujew7byzu6x5dwjqe2rya2fv"

{

"id": 7,

"key": "Brand location",

"value": "4HG",

"namespace": "Warehouse Locations",

"permission_set": "read",

"resource_type": "brand",

"resource_id": 111,

"description": "Location in the warehouse",

Create a Brand Metafield

POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/brands/{brand_id}/metafields

Request

Creates a brand metafield.

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

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
brand_id in path - integer
required
The ID of the brand to which the resource belongs.
Accept in header with default of application/json - string
required
The MIME type of the response body.
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

dataobject
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.
metaobject
Empty meta object; may be used later.

example-1

{

"data": {

"id": 4,

"key": "location_id",

"value": "Shelf 3, Bin 5",

"namespace": "App Namespace",

"permission_set": "app_only",

"resource_type": "brand",

"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",

"owner_client_id": "e8o0nm9ujew7byzu6x5dwjqe2rya2fv"

"meta": {}

}

example-2

{

"data": {

"id": 6,

"key": "Location",

"value": "4HG",

"namespace": "Warehouse Locations",

"permission_set": "app_only",

"resource_type": "category",

"resource_id": 111,

"description": "Location in the warehouse.",

"date_created": "2018-05-07T20:14:17+00:00",

"date_modified": "2018-05-07T20:14:17+00:00",

"owner_client_id": "e8o0nm9ujew7byzu6x5dwjqe2rya2fv"

"meta": {}

}

example-3

{

"data": {

"id": 4,

"key": "location_id",

"value": "Shelf 3, Bin 5",

"namespace": "App Namespace",

"permission_set": "app_only",

"resource_type": "brand",

"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",

"owner_client_id": "e8o0nm9ujew7byzu6x5dwjqe2rya2fv"

"meta": {}

}

Get a Brand Metafields

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

Request

Returns a brand metafield. Optional filter parameters can be passed in.

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
brand_id in path - integer
required
The ID of the brand to which the resource belongs.
metafield_id in path - integer
required
The ID of the Metafield.
Accept in header with default of application/json - string
required
The MIME type of the response body.
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

curl --request GET \

--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/brands/[brand_id]/metafields/[metafield_id]' \

--header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

dataobject
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.
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",

"owner_client_id": "e8o0nm9ujew7byzu6x5dwjqe2rya2fv"

"meta": {}

}

Update a Brand Metafield

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

Request

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

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
brand_id in path - integer
required
The ID of the brand to which the resource belongs.
metafield_id in path - integer
required
The ID of the Metafield.
Accept in header with default of application/json - string
required
The MIME type of the response body.
Content-Type in header with default of application/json - string
required
The MIME type of the request body.

Body

object | application/json

Common Metafield properties.

permission_setstring
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 the storefront. | | write_and_sf_access | Open for reading and writing by other API consumers, including on the storefront. |
Allowed: app_only | read | write | read_and_sf_access | write_and_sf_access
namespacestring
Namespace for the metafield, for organizational purposes.
>= 1 characters<= 64 characters
Example: Sales Department
keystring
The name of the field, for example: location_id, color.
>= 1 characters<= 64 characters
Example: Staff Name
valuestring
The value of the field, for example: 1, blue.
>= 1 characters<= 65535 characters
Example: Ronaldo
descriptionstring
Description for the metafields.
>= 0 characters<= 255 characters
Example: Name of Staff Member

example

{

"permission_set": "app_only",

"namespace": "Sales Department",

"key": "Staff Name",

"value": "Ronaldo",

"description": "Name of Staff Member"

}

Response

Body

object | application/json

dataobject
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.
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 Brand Metafield

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

Request

Deletes a brand metafield.

Authentication

X-Auth-Token in header

Parameters

store_hash in path - string
brand_id in path - integer
required
The ID of the brand to which the resource belongs.
metafield_id in path - integer
required
The ID of the Metafield.
Accept in header with default of application/json - string
required
The MIME type of the response body.

example

curl --request DELETE \

--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/brands/[brand_id]/metafields/[metafield_id]' \

--header 'Accept: application/json' \

--header 'Content-Type: application/json' \

--header 'X-Auth-Token: {{token}}'

Response

Did you find what you were looking for?

Delete a Brand Image Get brand metafields

Metafields

Get brand metafields

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Create a Brand Metafield

Request

Authentication

Parameters

Body

keystringrequired

valuestringrequired

namespacestringrequired

permission_setstringrequired

descriptionstring

example

Response

Body

dataobject

metaobject

example-1

example-2

example-3

Get a Brand Metafields

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

example

Update a Brand Metafield

Request

Authentication

Parameters

Body

permission_setstring

namespacestring

keystring

valuestring

descriptionstring

example

Response

Body

dataobject

metaobject

example

Delete a Brand Metafield

Request

Authentication

Parameters

example

Response

keystring
required

valuestring
required

namespacestring
required

permission_setstring
required