Docs
Content API
Custom template associations

Custom Template Associations

Associate a Stencil themeʼs custom templates with products, categories, brands, and pages.

Creating template associations

To create a template association, use the Upsert custom template associations endpoint

Entity IDs

The value of the entity ID is the ID property for the given entity. For example, a category entity ID is the id property for the particular category object you want to act upon.

To get the entity IDs for categories, products, and brands, use the Get categories, Get products, and Get brands endpoints, respectively.

To get the entity ID for a page, use the Get pages endpoint.

Getting available templates

To get a list of available custom templates for each entity type, send a request to the Get all themes endpoint, then use the variation.uuid property as the path parameter in a request to the Get custom templates endpoint.

To get the version UUID for an active theme, use the Get a channel active theme endpoint.

Resources

Get Custom Template Associations

GET /storefront/custom-template-associations

Request

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

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.
  • channel_id in query - integer
    Return results or act upon only template associations in the specified channel.
  • entity_id:in in query - array
    A comma-separated list of entity IDs to return or act upon. Must be used together with the type filter. Currently, all supported entities have integer-type IDs.
    Type: array[integer]
  • type in query - string
    Filter associations by type.

    Allowed: product | category | brand | page

  • limit in query - integer
    Number of results to return per page.
  • page in query - integer
    Which page number to return, based on the limit value. Used to paginate large collections.
  • 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: {{token}}'

Response

OK

Body

object | application/json

  • data    array[object]

  • meta    object

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

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

array | application/json

  • channel_id    integer
    required

  • entity_type    string
    required

    Allowed: product | category | brand | page

  • entity_id    integer
    required

  • file_name    string
    required

example-1

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

Response

Success response for batch upsert of custom template associations

Body

object | application/json

    example

    {}

    Delete Custom Template Associations

    DELETE /storefront/custom-template-associations

    Request

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

    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 in query - array
      A comma-separated string that specifies a list of association IDs to delete.
      Type: array[integer]
    • channel_id in query - integer
      Return results or act upon only template associations in the specified channel.
    • type in query - string
      Filter associations by type.

      Allowed: product | category | brand | page

    • entity_id:in in query - array
      A comma-separated list of entity IDs to return or act upon. Must be used together with the type filter. Currently, all supported entities have integer-type IDs.
      Type: array[integer]

    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: {{token}}'

    Response

    No Content

    See something you can improve? Edit this file on GitHub

    Did you find what you were looking for?
    Update email template settingsGet Custom Template Associations