For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
        • Abandoned Cart Emails
        • Custom Template Associations
        • Email Templates
        • Pages
        • Marketing
        • Store Content
        • Themes
        • Widgets
        • Page Widgets
            • GETGet Page Snapshot
            • POSTPublish or Overwrite Page Content
      • Payments
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTAdminContentPage Widgets

Get Page Snapshot

GET
https://api.bigcommerce.com/stores/:store_hash/v3/content/page-widgets
GET
/stores/:store_hash/v3/content/page-widgets
$curl -G https://api.bigcommerce.com/stores/store_hash/v3/content/page-widgets \
>     -H "Accept: application/json" \
>     -H "X-Auth-Token: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d channel_id=12
1{
2  "data": {
3    "regions": [
4      {
5        "name": "home_below_menu",
6        "children": [
7          {
8            "type": "layout",
9            "layout_template_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
10            "name": "Featured Products Layout",
11            "configuration": {
12              "columns": 3,
13              "spacing": "medium"
14            },
15            "dropzones": [
16              {
17                "configuration": {
18                  "max_widgets": 5
19                },
20                "widgets": [
21                  {
22                    "type": "widget",
23                    "widget_template_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
24                    "name": "Featured Product Widget",
25                    "description": "Displays a featured product with image and price",
26                    "configuration": {
27                      "product_id": 12345,
28                      "show_price": true,
29                      "show_image": true
30                    },
31                    "storefront_api_query_params": {
32                      "include": "reviews,ratings",
33                      "limit": 1
34                    }
35                  }
36                ]
37              }
38            ]
39          }
40        ]
41      }
42    ]
43  },
44  "meta": {
45    "pagination": {
46      "total": 1,
47      "count": 1,
48      "per_page": 50,
49      "current_page": 1,
50      "total_pages": 1,
51      "links": {
52        "previous": null,
53        "current": "https://api.bigcommerce.com/stores/abc123/v3/content/page-widgets?channel_id=12&template_file=homepage.html&entity_id=1001&page=1",
54        "next": null
55      }
56    }
57  }
58}
Get a snapshot of all the page widget regions for a given channel, template file, or entity.
Was this page helpful?
Previous

Page widgets

Next

Publish or Overwrite Page Content

Built with

Authentication

X-Auth-Tokenstring
### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Add scopes ++++ | modify | `...` | | Add | read-only | `store_v2_marketing_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate access tokens, see [API Accounts and OAuth Scopes](/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). For more about BigCommerce OAuth scopes, see [API Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
X-Correlation-IdstringOptionalformat: "uuid"
An identifier unique to a set of related requests. For use on headless storefronts, excluding BigCommerce for WordPress. For more information, see [Best Practices](/developer/docs/storefront/headless#correlating-requests) or the [Headless Guide](/developer/docs/storefront/headless#correlating-requests).

Query parameters

channel_idintegerOptionalDefaults to 1
The ID of the channel for which you want to retrieve page widgets. Defaults to the first channel created on the store.
template_filestringOptional
The template file that you would like to target. Leave it empty if the request is for Global regions.
entity_idstringOptional

The identifier of a page you would like to target. For product pages, choose product ID. For category pages, choose category ID. Home page does not support entity_id. Leave empty if the request is for global regions.

Response headers

Datestring
An [RFC 2822](a href="http://tools.ietf.org/html/rfc2822#section-3.3) date.
Last-Modifiedstring
An [RFC 2822](a href="http://tools.ietf.org/html/rfc2822#section-3.3) date. The date the resource was last modified.
Content-Encodingstring
Lets API clients request compressed responses.
Transfer-Encodingstring
Specifies the form of encoding used to transfer the resource.
X-Rate-Limit-Time-Window-Msinteger

number | Shows the size of your current rate-limiting window, in milliseconds.

X-Rate-Limit-Time-Reset-Msinteger

Shows how many milliseconds are remaining in the window. In this case, 15000 milliseconds – so, 15000 milliseconds after this request, the API quota will be refreshed.

X-Rate-Limit-Requests-Quotainteger
Shows how many API requests are allowed in the current window for your client.
X-Rate-Limit-Requests-Leftinteger

Details how many remaining requests your client can make in the current window before being rate-limited. In this case, you would expect to be able to make 35 more requests in the next 15000 milliseconds; on the 36th request within 15000 milliseconds, you would be rate-limited and receive an HTTP 429 response.

X-Retry-Afterinteger

Rate limited response, indicating the number of seconds before the quota refreshes. See Rate Limits.

X-BC-ApiLimit-Remaininginteger

The number of API requests remaining for the current period (rolling one hour).

X-BC-Store-Versionstring

The version of BigCommerce on which the store is running. This header is available on versions 7.3.6+.

Response

dataobject
metaobject
Data about the response, including pagination and collection totals.

Errors

422
Unprocessable Entity Error

OAuth scopes

UI NamePermissionParameter
Add scopes ++++modify...
Addread-onlystore_v2_marketing_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access tokens, see API Accounts and OAuth Scopes.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see API Accounts and OAuth Scopes.

For a list of API status codes, see API Status Codes.

The MIME type of the response body.

An identifier unique to a set of related requests. For use on headless storefronts, excluding BigCommerce for WordPress. For more information, see Best Practices or the Headless Guide.

An [RFC 2822](a href=“http://tools.ietf.org/html/rfc2822#section-3.3) date.

An [RFC 2822](a href=“http://tools.ietf.org/html/rfc2822#section-3.3) date. The date the resource was last modified.