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 /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.
- name:like in query - string
Filter items by part of a name. For example,
name:like=new
returns brands with names that includenew
. - 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.
- sort in query - string
Field name to sort by.
Allowed values: name
example
Response
Body
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.
example
Create a Brand
POST /stores/{store_hash}/v3/catalog/brands
Request
Creates a Brand.
Required Fields
- name
Read-Only Fields
- id
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
Common brand properties.
namestring
required>= 1 characters<= 255 charactersThe name of the brand. Must be unique. Required in POST.
Example: Common Good
page_titlestring
>= 0 characters<= 255 charactersThe title shown in the browser while viewing the brand.
Example: Common Good
meta_keywordsarray[string]
Comma-separated list of meta keywords to include in the HTML.
meta_descriptionstring
>= 0 characters<= 65535 charactersA meta description to include.
Example: Common Good is a modern brand.
search_keywordsstring
>= 0 characters<= 65535 charactersA comma-separated list of keywords that can be used to locate this brand.
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
Response
Body
Brand Response returns for:
- Create Brand
- Get Brand by Id
- Update Brand by Id
dataobject
Common Brand properties.
metaobject
Response metadata.
example
Delete Brands
DELETE /stores/{store_hash}/v3/catalog/brands
Request
To delete brand objects, you must include a filter.
Required Fields
- name
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 - required
Filter items by name.
- page_title in query - string
Filter items by page_title.
example
Response
Get a Brand
GET /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. - 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
Response
Body
Brand Response returns for:
- Create Brand
- Get Brand by Id
- Update Brand by Id
dataobject
Common Brand properties.
metaobject
Response metadata.
example
Update a Brand
PUT /stores/{store_hash}/v3/catalog/brands/{brand_id}
Request
Updates a Brand.
Required Fields
- None
Read-Only Fields
- id
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.
Body
Common Brand properties.
idinteger
Unique ID of the Brand. Read-Only.
namestring
required>= 1 characters<= 255 charactersThe name of the brand. Must be unique. Required in POST.
Example: Common Good
page_titlestring
>= 0 characters<= 255 charactersThe title shown in the browser while viewing the brand.
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
>= 0 characters<= 65535 charactersA meta description to include.
Example: Common Good is a modern brand.
search_keywordsstring
>= 0 characters<= 65535 charactersA comma-separated list of keywords that can be used to locate this brand.
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
Response
Body
Brand Response returns for:
- Create Brand
- Get Brand by Id
- Update Brand by Id
dataobject
Common Brand properties.
metaobject
Response metadata.
example
Delete a Brand
DELETE /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.