Custom Template Associations

Efficiently associate a stencil themeʼs custom templates to products, categories, brands, and pages.

Creating template associations

To associate custom templates to entities, send a PUT request to /v3/storefront/custom-template-associations.

PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/custom-template-associations
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "channel_id": 1,
    "entity_type": "product",
    "entity_id": 12,
    "file_name": "custom-template-1.html"
  }
]

Note

The allowed values for entity_type are product, category, brand, and page.

Getting entity IDs

Use the Catalog API to get the entity_id for category, product, and brand entity types. For example, to get all products, send a GET request to /v3/catalog/products.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

To get the entity_id for a content page, send a GET request to /v3/pages.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/content/pages
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

Getting available templates

To get available custom templates for each entity_type, send a GET request to /v3/themes/custom-templates/{version_uuid}.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/themes/custom-templates/{version_uuid}
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

Response:

{
  "data": {
    "product": [
      "custom-product-1.html"
    ],
    "category": [],
    "brand": [
      "custom-brand-1.html"
    ],
    "page": [
      "custom-page-1.html",
      "holiday-page.html"
    ]
  },
  "meta": {}
}

Getting theme UUIDs

To get the version_uuid for an active theme, send a GET request to /v3/channels/{channel_id}/active-theme.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/channels/{channel_id}/active-theme
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

Response:

{
  "data": {
    "active_theme_configuration_uuid": "748c5390-0b42-0139-b008-0242ac110013",
    "active_theme_uuid": "94bd1450-b873-0137-6902-0242ac11001f",
    "active_theme_version_uuid": "94dde070-b873-0137-6902-0242ac11001f",
    "saved_theme_configuration_uuid": "748c5390-0b42-0139-b008-0242ac110013"
  },
  "meta": {}
}

Additional information

Get Custom Template Associations

GET https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/custom-template-associations

Request

Get a collection of the storeʼs custom template associations across all storefronts

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.
channel_id in query - integer
Channel ID to return only custom template associations for a given Channel
entity_id:in in query - string
Filter by a list of entity IDs. Must be used together with "type" filter.
limit in query - integer
Number of results to return per page
page in query - integer
Which page number to return, based on the page size. Used to paginate large collections.
type in query - string
Filter associations by type
is_valid in query - boolean
Optional toggle to filter for exclusively valid or invalid associations entries. An invalid entry is one where its file name does not match up to an existing custom layout file in the currently active theme for the channel.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/storefront/custom-template-associations' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataarray[object]
metaobject

example-1

{
  "data": [
    {
      "id": 1,
      "channel_id": 1,
      "entity_type": "product",
      "entity_id": 123,
      "file_name": "custom-product-1.html"
    },
    {
      "id": 2,
      "channel_id": 12345,
      "entity_type": "page",
      "entity_id": 123,
      "file_name": "custom-page.html"
    }
  ],
  "meta": {
    "pagination": {
      "total": 246,
      "count": 5,
      "per_page": 5,
      "current_page": 1,
      "total_pages": 50,
      "links": {
        "next": "?limit=5&page=2",
        "current": "?limit=5&page=1"
      }
    }
  }
}

Upsert Custom Template Associations

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/custom-template-associations

Request

Upsert new custom template associations data across all storefronts. If an existing record is found for the combination of channel ID, entity ID, and type, the existing record will be overwritten with the new template.

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

array | application/json

channel_idinteger
entity_typestring
Allowed: product | category | brand | page
entity_idinteger
file_namestring
Example: custom-product-1.html

example-1

[
  {
    "id": 1,
    "channel_id": 1,
    "entity_type": "product",
    "entity_id": 123,
    "file_name": "custom-product-1.html"
  },
  {
    "id": 2,
    "channel_id": 12345,
    "entity_type": "page",
    "entity_id": 123,
    "file_name": "custom-page.html"
  }
]

Response

Success response for batch upsert of custom template associations

Body

object | application/json

example

{}

Delete Custom Template Associations

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/custom-template-associations

Request

Delete custom template associations. At least one query parameter must be used.

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 in query - integer
List of Association IDs to delete explicitly.
entity_id:in in query - integer
List of Entity IDs to delete explicitly. Must be used together with "type"
channel_id in query - integer
Channel ID provided to delete all custom template associations for a given Channel
type in query - string
Filter associations by type

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/storefront/custom-template-associations' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

No Content