BigCommerce
Theme & Content APIs
Custom Template Associations

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

    Allowed values: product | category | brand | page
  • 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

Response

OK

Body

object | application/json
  • data
    array[object]

  • meta
    object

example-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 - 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_id
    integer
    required

  • entity_type
    string
    required

    Allowed: product | category | brand | page

  • entity_id
    integer
    required

  • file_name
    string
    required

    Example: custom-product-1.html

example-1

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

      Allowed values: product | category | brand | page

    example

    Response

    No Content

    Did you find what you were looking for?