Brands | BigCommerce Dev Center

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

Category

Additional Catalog endpoints

Get All Brands

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

Request

Returns a list of Brands. 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.
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
name in query - string
Filter items by name.
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 - 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' \
  --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": 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": {
        "url": "/brands/OFS.html",
        "is_customized": false
      }
    },
    {
      "id": 37,
      "name": "Common Good",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "image_url": "https://cdn8.bigcommerce.com/s-jrah6gmn/product_images/k/screen%20shot%202018-05-07%20at%2012.24.24%20pm_1525785365__65102.png",
      "search_keywords": "",
      "custom_url": {
        "url": "/brands/Common-Good.html",
        "is_customized": false
      }
    },
    {
      "id": 38,
      "name": "BigCommerce",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/bigcommerce/",
        "is_customized": false
      }
    },
    {
      "id": 39,
      "name": "Test Brand One",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "",
      "image_url": "https://cdn8.bigcommerce.com/s-jrah6gmn/product_images/q/apihqggzm__53766.jpg",
      "search_keywords": "",
      "custom_url": {
        "url": "/test-brand-one/",
        "is_customized": false
      }
    },
    {
      "id": 40,
      "name": "Fog Linen Work",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/fog-linen-work/",
        "is_customized": false
      }
    },
    {
      "id": 41,
      "name": "Barr-Co.",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/barr-co/",
        "is_customized": false
      }
    },
    {
      "id": 42,
      "name": "Thames & Hudson",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/thames-hudson/",
        "is_customized": false
      }
    },
    {
      "id": 43,
      "name": "Able Brewing",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/able-brewing/",
        "is_customized": false
      }
    },
    {
      "id": 44,
      "name": "Chemex",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/chemex/",
        "is_customized": false
      }
    },
    {
      "id": 45,
      "name": "Kinfolk",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/kinfolk/",
        "is_customized": false
      }
    },
    {
      "id": 46,
      "name": "Iris Hantverk",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/iris-hantverk/",
        "is_customized": false
      }
    },
    {
      "id": 47,
      "name": "Gather Journal",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/gather-journal/",
        "is_customized": false
      }
    },
    {
      "id": 48,
      "name": "Openhouse Magazine",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/openhouse-magazine/",
        "is_customized": false
      }
    },
    {
      "id": 49,
      "name": "Smith Journal",
      "page_title": "",
      "meta_keywords": [
        ""
      ],
      "meta_description": "description",
      "image_url": "",
      "search_keywords": "",
      "custom_url": {
        "url": "/smith-journal/",
        "is_customized": false
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 15,
      "count": 15,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}

Create a Brand

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

Request

Creates a Brand.

Required Fields

name

Read-Only Fields

Limits

30,000 brands per store limit

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

Common brand properties.

namestring
required
The name of the brand. Must be unique. Required in POST.
>= 1 characters<= 255 characters
Example: Common Good
page_titlestring
The title shown in the browser while viewing the brand.
>= 0 characters<= 255 characters
Example: Common Good
meta_keywordsarray[string]
Comma-separated list of meta keywords to include in the HTML.
meta_descriptionstring
A meta description to include.
>= 0 characters<= 65535 characters
Example: Common Good is a modern brand.
search_keywordsstring
A comma-separated list of keywords that can be used to locate this brand.
>= 0 characters<= 65535 characters
Example: kitchen, laundry, cart, storage
image_urlstring
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_urlobject
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

dataobject
Common Brand properties.
metaobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/brands

Request

By default, it deletes all Brand objects. A filter should be added to avoid deleting all Brand objects in a store.

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.
name in query - string
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: xxxxxxxxxxxxxxxxx'

Response

Get a Brand

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

Request

Returns a single Brand. 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.
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]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

Brand Response returns for:

Create Brand
Get Brand by Id
Update Brand by Id

dataobject
Common Brand properties.
metaobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/brands/{brand_id}

Request

Updates a Brand.

Required Fields

None

Read-Only Fields

To update a Brand Image, send a request with an image_url.

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

Common Brand properties.

idinteger
Unique ID of the Brand. Read-Only.
namestring
required
The name of the brand. Must be unique. Required in POST.
>= 1 characters<= 255 characters
Example: Common Good
page_titlestring
The title shown in the browser while viewing the brand.
>= 0 characters<= 255 characters
Example: Common Good
meta_keywordsarray[string]
Comma-separated list of meta keywords to include in the HTML.
Type: array[string]
Example: ["modern, clean, contemporary"]
meta_descriptionstring
A meta description to include.
>= 0 characters<= 65535 characters
Example: Common Good is a modern brand.
search_keywordsstring
A comma-separated list of keywords that can be used to locate this brand.
>= 0 characters<= 65535 characters
Example: kitchen, laundry, cart, storage
image_urlstring
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_urlobject
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

dataobject
Common Brand properties.
metaobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/brands/{brand_id}

Request

Deletes a Brand.

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.

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

Catalog - Brands

Resources

Webhooks

Additional Catalog endpoints

Get All Brands

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Create a Brand

Request

Authentication

Parameters

Body

namestringrequired

page_titlestring

meta_keywordsarray[string]

meta_descriptionstring

search_keywordsstring

image_urlstring

custom_urlobject

example

Response

Body

dataobject

metaobject

example

Delete Brands

Request

Authentication

Parameters

example

Response

Get a Brand

Request

Authentication

Parameters

example

Response

Body

dataobject

metaobject

example

Update a Brand

Request

Authentication

Parameters

Body

idinteger

namestringrequired

page_titlestring

meta_keywordsarray[string]

meta_descriptionstring

search_keywordsstring

image_urlstring

custom_urlobject

example

Response

Body

dataobject

metaobject

example

Delete a Brand

Request

Authentication

Parameters

example

Response

namestring
required

namestring
required