Docs
Catalog API
Brands

Catalog - Brands

The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the Catalog Overview.

Our Catalog brands endpoints let you create individual brands and modify the brands associated with a storeʼs products, along with deleting brands.

Brand images have their own dedicated create a brand image and delete a brand image endpoints.

In addition, brands have metafields that you can use to store information structured in key-value pairs; learn more about creating brand metafields, updating brand metafields, and deleting brand metafields.

To learn more about authenticating Catalog endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.

Resources

Webhooks

Additional Catalog endpoints

Get All Brands

GET /catalog/brands

Request

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

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • 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]
  • name in query - string

    Filter items by name.

  • name:like in query - string
    Filter items by part of a name. For example, name:like=new returns brands with names that include new.
  • page_title in query - string

    Filter items by page_title.

  • 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.
  • 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]
  • sort in query - string
    Field name to sort by.

    Allowed: name

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/brands' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

{
"data": [
{
"id": 35,
"name": "Sagaform",
"page_title": "",
"meta_keywords": [
""
],
"meta_description": "",
"image_url": "",
"search_keywords": "",
"custom_url": {
"url": "/brands/Sagaform.html",
"is_customized": false
}
},
{
"id": 36,
"name": "OFS",
"page_title": "OFS",
"meta_keywords": [
"modern",
"clean",
"contemporary"
],
"meta_description": "OFS is a modern brand.",
"image_url": "",
"search_keywords": "kitchen, laundry, cart, storage",
"custom_url": {

Create a Brand

POST /catalog/brands

Request

Creates a brand.

Required Fields

  • name

Limits

  • 30,000 brands per store limit

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • 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 brand properties.

  • name    string
    required

    The name of the brand. Must be unique. Required in POST.

    >= 1 characters<= 255 characters
    Example: Common Good

  • page_title    string

    The title shown in the browser while viewing the brand.

    >= 0 characters<= 255 characters
    Example: Common Good

  • meta_keywords    array[string]

    An array of meta keywords to include in the HTML.

    Type: array[string]
    Example: ["modern","clean","contemporary"]

  • meta_description    string

    A meta description to include.

    >= 0 characters<= 65535 characters
    Example: Common Good is a modern brand.

  • search_keywords    string

    A comma-separated list of keywords that can be used to locate this brand.

    >= 0 characters<= 65535 characters
    Example: kitchen, laundry, cart, storage

  • image_url    string

    Image URL used for this category on the storefront. Images can be uploaded via form file post to /brands/{brandId}/image, or by providing a publicly accessible URL in this field.

    Example: https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png

  • custom_url    object

    The custom URL for the brand on the storefront. If not provided, the URL will be autogenerated from the brand name.

example

{
"name": "Common Good",
"page_title": "Common Good",
"meta_keywords": [
"modern",
"clean",
"contemporary"
],
"meta_description": "Common Good is a modern brand.",
"search_keywords": "kitchen, laundry, cart, storage",
"image_url": "https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png",
"custom_url": {
"url": "/shoes",
"is_customized": true
}
}

Response

Body

object | application/json

Brand Response returns for:

  • Create Brand
  • Get Brand by Id
  • Update Brand by Id

  • data    object

    Common Brand properties.

  • meta    object

    Response metadata.

example

{
"data": {
"id": 50,
"name": "Common Good",
"meta_keywords": [
"modern",
"clean",
"contemporary"
],
"meta_description": "Common Good is a modern brand",
"image_url": "",
"search_keywords": "kitchen, laundry, cart, storage",
"custom_url": {
"url": "/brands/Common-Good.html",
"is_customized": false
}
},
"meta": {}
}

Delete Brands

DELETE /catalog/brands

Request

To delete brand objects, you must include a value for the name filter.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • name in query - string
    required

    Filter items by name.

  • page_title in query - string

    Filter items by page_title.

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/brands' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Get a Brand

GET /catalog/brands/{brand_id}

Request

Returns a single brand. 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.
  • 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]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

Brand Response returns for:

  • Create Brand
  • Get Brand by Id
  • Update Brand by Id

  • data    object

    Common Brand properties.

  • meta    object

    Response metadata.

example

{
"data": {
"id": 50,
"name": "Common Good",
"meta_keywords": [
"modern",
"clean",
"contemporary"
],
"meta_description": "Common Good is a modern brand",
"image_url": "",
"search_keywords": "kitchen, laundry, cart, storage",
"custom_url": {
"url": "/brands/Common-Good.html",
"is_customized": false
}
},
"meta": {}
}

Update a Brand

PUT /catalog/brands/{brand_id}

Request

Updates a brand.

To update a brand image, send a request with an image_url.

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
Common Brand properties.

  • id    integer
    read-only

    Unique ID of the brand.

  • name    string
    required

    The name of the brand. Must be unique. Required in POST.

    >= 1 characters<= 255 characters
    Example: Common Good

  • page_title    string

    The title shown in the browser while viewing the brand.

    >= 0 characters<= 255 characters
    Example: Common Good

  • meta_keywords    array[string]

    An array of meta keywords to include in the HTML.

    Type: array[string]
    Example: ["modern","clean","contemporary"]

  • meta_description    string

    A meta description to include.

    >= 0 characters<= 65535 characters
    Example: Common Good is a modern brand.

  • search_keywords    string

    A comma-separated list of keywords that can be used to locate this brand.

    >= 0 characters<= 65535 characters
    Example: kitchen, laundry, cart, storage

  • image_url    string

    Image URL used for this category on the storefront. Images can be uploaded via form file post to /brands/{brandId}/image, or by providing a publicly accessible URL in this field.

    Example: https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png

  • custom_url    object

    The custom URL for the brand on the storefront.

example

{
"name": "Common Good",
"page_title": "Common Good",
"meta_keywords": [
"modern",
"clean",
"contemporary"
],
"meta_description": "Common Good is a modern brand.",
"search_keywords": "kitchen, laundry, cart, storage",
"image_url": "https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png",
"custom_url": {
"url": "/shoes",
"is_customized": true
}
}

Response

Body

object | application/json

Brand Response returns for:

  • Create Brand
  • Get Brand by Id
  • Update Brand by Id

  • data    object

    Common Brand properties.

  • meta    object

    Response metadata.

example

{
"data": {
"id": 50,
"name": "Common Good",
"meta_keywords": [
"modern",
"clean",
"contemporary"
],
"meta_description": "Common Good is a modern brand",
"image_url": "",
"search_keywords": "kitchen, laundry, cart, storage",
"custom_url": {
"url": "/brands/Common-Good.html",
"is_customized": false
}
},
"meta": {}
}

Delete a Brand

DELETE /catalog/brands/{brand_id}

Request

Deletes a brand.

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.

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/brands/[brand_id]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
OverviewGet All Brands