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

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

Create a Brand

POST /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

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]

    Comma-separated list of meta keywords to include in the HTML.

  • 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

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

Delete Brands

DELETE /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 /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

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

Update a Brand

PUT /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

object | application/json

Common Brand properties.

  • id    integer

    Unique ID of the Brand. Read-Only.

  • 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]

    Comma-separated list 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

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

Delete a Brand

DELETE /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.

example

Response

OverviewGet All Brands