Metafields | BigCommerce Dev Center

Get All 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 - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
brand_id in path - integer - required
The ID of the Brand to which the resource belongs.
brand_id in path - integer - required
The ID of the Brand to which the resource belongs.
id in query - integer
Filter items by ID.
id:in in query - array
id:not_in in query - array
id:min in query - array
id:max in query - array
id:greater in query - array
id:less in query - array
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/brands/[brand_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": "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"
    },
    {
      "id": 7,
      "key": "Brand location",
      "value": "4HG",
      "namespace": "Warehouse Locations",
      "permission_set": "read",
      "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"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}

Create a Brand Metafield

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

Request

Creates a Brand 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.
brand_id in path - integer - required
The ID of the Brand to which the resource belongs.

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

Parameters

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

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

Parameters

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

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: xxxxxxxxxxxxxxxxx'

Get All 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

data

metaobject

example-1

example-2

example-3

Get a Brand Metafields

Request

Authentication

Parameters

example

Response

Body

data

metaobject

example

Update a Brand Metafield

Request

Authentication

Parameters

Body

keystringrequired

valuestringrequired

namespacestringrequired

permission_setstringrequired

descriptionstring

example

Response

Body

data

metaobject

example

Delete a Brand Metafield

Request

Authentication

Parameters

example

Response

keystring
required

valuestring
required

namespacestring
required

permission_setstring
required

keystring
required

valuestring
required

namespacestring
required

permission_setstring
required