> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# List Custom Template Associations

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

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

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/content/custom-template-associations/get-custom-template-associations

## Authentication

- `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Themes |Read-only|`store_themes_read_only`| | Themes |Manage|`store_themes_manage`| ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

## Request

### Path parameters

- `store_hash` (string, required) — Permanent ID of the BigCommerce store.

### Query parameters

- `channel_id` (integer, optional) — Return results or act upon only template associations in the specified channel.
- `entity_id:in` (list of integer, optional) — 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` (enum, optional) — Filter associations by type.
  - Allowed values: `product`, `category`, `brand`, `page`
- `limit` (integer, optional) — Number of results to return per page.
- `page` (integer, optional) — Which page number to return, based on the limit value. Used to paginate large collections.
- `is_valid` (boolean, optional) — 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.

### Headers

- `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

## Response

### 200

OK

- `data` (list of CustomTemplateAssociation, optional)
- `meta` (MetaPaginationObject, optional)

## Types

### CustomTemplateAssociation

- `id` (integer, optional)
- `channel_id` (integer, optional)
- `entity_type` (enum, optional)
  - Allowed values: `product`, `category`, `brand`, `page`
- `entity_id` (integer, optional)
- `file_name` (string, optional)
- `is_valid` (boolean, optional) — An invalid file name does not match with an existing custom layout file in the currently active theme for the channel. When an association is invalid the store will fallback to using the default for that entity type.
- `date_created` (string, optional)
- `date_modified` (string, optional)

### MetaPaginationObject

- `pagination` (MetaPaginationObjectPagination, optional)

### MetaPaginationObjectPagination

- `total` (integer, optional)
- `count` (integer, optional)
- `per_page` (integer, optional)
- `current_page` (integer, optional)
- `total_pages` (integer, optional)
- `links` (MetaPaginationObjectPaginationLinks, optional)

### MetaPaginationObjectPaginationLinks

- `next` (string, optional)
- `current` (string, optional)

## Examples

**Response**

```json
{
  "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"
      }
    }
  }
}
```

**SDK Code**

```python example-1
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations"

headers = {
    "Accept": "application/json",
    "X-Auth-Token": "<apiKey>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript example-1
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations';
const options = {
  method: 'GET',
  headers: {Accept: 'application/json', 'X-Auth-Token': '<apiKey>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go example-1
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("X-Auth-Token", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby example-1
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'
request["X-Auth-Token"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java example-1
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations")
  .header("Accept", "application/json")
  .header("X-Auth-Token", "<apiKey>")
  .asString();
```

```php example-1
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations', [
  'headers' => [
    'Accept' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp example-1
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Token", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift example-1
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Token": "<apiKey>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/storefront/custom-template-associations")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```