AdminWidgets & ScriptsPage Widgets

Guide to page widgets

A POST request to Publish or overwrite a page deletes any and all existing data for the requested page and replaces it with the data in the request payload.

Prerequisites

UI NamePermissionParameterDescription
Contentmodifystore_v2_contentView and modify store content

Get a page snapshot

To download a snapshot of a single page’s regions, layouts, dropzones, and widgets, use the Get a page snapshot endpoint.

You can use a number of query parameters to describe the page features you want to retrieve. See more descriptions, defaults, and examples in the REST Content API reference

ParameterRequiredDescription
channel_idnoThe channel ID of the subject storefront.
template_filenoThe name of the subject theme template file. If you want a snapshot of global regions in a storefront, do not include a value for the template_file query parameter.
entity_idnoIf you want a snapshot of global regions in a storefront, do not include a value for the entity_id query parameter.

Some template files don’t have an entity ID. For example, the pages/home template file doesn’t have an entity ID.

Get a page snapshot
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/content/page-widgets?channel_id={{CHANNEL_ID}}&template_file={{TEMPLATE_FILE}}&entity_id={{ENTITY_ID}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

Publish or overwrite a page

To publish or overwrite the content of a page, use the Publish or overwrite a page endpoint. One way to prepare a publication payload is to Get a snapshot of a page that you want to copy or modify. The snapshot contains region data that you can use as a request body payload for the Publish or overwrite a page endpoint.

When starting with a snapshot from another storefront, make sure to replace any store or channel-specific data in the request body.

PropertyRequiredDescription
channel_idyesThe channel ID of the target storefront.
template_filenoThe name of the target theme template file.
entity_idno

Ensure that you have the widget_template_uuid of each widget you want to publish. The widget_template_uuid is unique to each store channel. If you are publishing to a different store or channel than you got the page snapshot from, you must re-register any widget templates you use in the target store channel using the Create a widget template endpoint. In your payload for the Publish or overwrite a page endpoint, substitute the correct widget_template_uuid for the target store or channel.

In addition, some widgets might require store or channel-specific data in the configuration or storefront_api_query_params objects. Notice productId in configuration or storefront_api_query_params in the following example. In this case, the correct productId corresponds with the desired product on the target store and channel.

A successful request to the Publish or overwrite a page endpoint returns a 201 Created status code, and does not return a response body.

Publish or overwrite a page
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/content/page-widgets
2X-Auth-Token: {{ACCESS_TOKEN}}
3Accept: application/json
4Content-Type: application/json
5
6{
7  "channel_id": 1,
8  "template_file": "pages/page",
9  "entity_id": "5",
10  "regions": [
11    {
12      "name": "home_below_menu",
13      "children": [
14        {
15          "widget_template_uuid": "d181ebd5-f42c-4f96-8f9d-c605023f5cb6",
16          "configuration": {
17            "title": "Hero Banner Title",
18            "subtitle": "Add a description for this hero banner. This is a great place to highlight a promotion.",
19            "buttonText": "Shop now",
20            "contentAlignment": {
21              "horizontal": "left"
22            },
23            "containerHeight": "small",
24            "backgroundType": "image",
25            "backgroundColor": "#444444",
26            "imageUrl": {
27              "src": "https://images.unsplash.com/photo-1533038590840-1cde6e668a91?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2000&q=100",
28              "type": "IMAGE_MANAGER"
29            },
30            "imageFit": "fill",
31            "imageParallax": "off",
32            "imageAlignment": {
33              "horizontal": "center",
34              "vertical": "middle"
35            },
36            "imageOpacity": 100,
37            "titleVisible": "show",
38            "titleStyle": "default",
39            "titleFontFamily": "inherit",
40            "titleFontWeight": "400",
41            "titleFontSize": {
42              "value": 36,
43              "type": "px"
44            },
45            "descriptionVisible": "show",
46            "descriptionStyle": "default",
47            "descriptionFontFamily": "inherit",
48            "descriptionFontWeight": "400",
49            "descriptionFontSize": {
50              "value": 21,
51              "type": "px"
52            },
53            "textColor": "#444444",
54            "mobileTextColor": "#444444",
55            "buttonVisible": "show",
56            "buttonFont": "default",
57            "buttonFontFamily": "inherit",
58            "buttonStyle": "round",
59            "buttonColor": "#444444",
60            "mobileButtonColor": "#444444",
61            "buttonTextColor": "rgba(255,255,255,1)",
62            "mobileButtonTextColor": "rgba(255,255,255,1)"
63          },
64          "storefront_api_query_params": {},
65          "name": "Hero Banner",
66          "description": "",
67          "type": "widget"
68        }
69      ]
70    },
71    {
72      "name": "header_bottom",
73      "children": [
74        {
75          "layout_template_uuid": "7d42d0b1-1152-4ce3-a6c1-3709f786f295",
76          "configuration": {
77            "columnWeights": [
78              "33.333333%",
79              "33.333333%",
80              "33.333333%"
81            ],
82            "layoutBackgroundColor": "rgba(0,0,0,0)",
83            "layoutBackgroundImageAlignment": {
84              "horizontal": "center",
85              "vertical": "middle"
86            },
87            "layoutBackgroundImageFit": "fill",
88            "layoutBackgroundImageOpacity": 100,
89            "layoutBackgroundImageUrl": "",
90            "layoutBorderColor": "#333333",
91            "layoutBorderStyle": "solid",
92            "layoutBorderThickness": 0,
93            "layoutHeight": "",
94            "layoutMargin": {
95              "bottom": {
96                "type": "px",
97                "value": "0"
98              },
99              "left": {
100                "type": "px",
101                "value": "0"
102              },
103              "right": {
104                "type": "px",
105                "value": "0"
106              },
107              "top": {
108                "type": "px",
109                "value": "0"
110              }
111            },
112            "layoutPadding": {
113              "bottom": {
114                "type": "px",
115                "value": "0"
116              },
117              "left": {
118                "type": "px",
119                "value": "0"
120              },
121              "right": {
122                "type": "px",
123                "value": "0"
124              },
125              "top": {
126                "type": "px",
127                "value": "0"
128              }
129            },
130            "numberOfDropzones": 3,
131            "layoutBackgroundType": "",
132            "layoutZIndex": "auto",
133            "name": "Layout"
134          },
135          "name": "Layout",
136          "dropzones": [
137            {
138              "configuration": {
139                "dropzoneBackgroundColor": "rgba(0,0,0,0)",
140                "dropzoneBackgroundImageAlignment": {
141                  "horizontal": "center",
142                  "vertical": "middle"
143                },
144                "dropzoneBackgroundImageFit": "fill",
145                "dropzoneBackgroundImageOpacity": 100,
146                "dropzoneBackgroundImageUrl": "",
147                "dropzoneBorderColor": "#333333",
148                "dropzoneBorderStyle": "solid",
149                "dropzoneBorderThickness": 0,
150                "dropzoneHeight": "",
151                "dropzoneJustifyContent": "center",
152                "dropzoneMargin": {
153                  "bottom": {
154                    "type": "px",
155                    "value": "0"
156                  },
157                  "left": {
158                    "type": "px",
159                    "value": "0"
160                  },
161                  "right": {
162                    "type": "px",
163                    "value": "0"
164                  },
165                  "top": {
166                    "type": "px",
167                    "value": "0"
168                  }
169                },
170                "dropzonePadding": {
171                  "bottom": {
172                    "type": "px",
173                    "value": "0"
174                  },
175                  "left": {
176                    "type": "px",
177                    "value": "10.5"
178                  },
179                  "right": {
180                    "type": "px",
181                    "value": "10.5"
182                  },
183                  "top": {
184                    "type": "px",
185                    "value": "0"
186                  }
187                },
188                "dropzoneZIndex": "auto",
189                "dropzoneBackgroundType": ""
190              },
191              "widgets": [
192                {
193                  "widget_template_uuid": "e59c1412-2d85-4f18-ab4b-8a55412d945c",
194                  "configuration": {
195                    "productCardContentAlignment": {
196                      "horizontal": "center"
197                    },
198                    "productImage": {
199                      "visibility": "show",
200                      "imageFit": "fill"
201                    },
202                    "brand": {
203                      "visibility": "show",
204                      "textStyle": "default",
205                      "color": "#444444"
206                    },
207                    "productName": {
208                      "visibility": "show",
209                      "textStyle": "default",
210                      "color": "#444444"
211                    },
212                    "price": {
213                      "visibility": "show",
214                      "textStyle": "default",
215                      "color": "#444444"
216                    },
217                    "productRating": {
218                      "visibility": "hide",
219                      "starColorFilled": "#3C64F4",
220                      "starColorEmpty": "#ECEEF5",
221                      "reviewsColor": "#8C93AD"
222                    },
223                    "button": {
224                      "visibility": "hide",
225                      "shape": "round",
226                      "buttonColor": "rgba(68,68,68,1)",
227                      "textStyle": "default",
228                      "buttonTextColor": "rgba(255,255,255,1)",
229                      "buttonActionType": "addToCart"
230                    },
231                    "productId": "77"
232                  },
233                  "storefront_api_query_params": {
234                    "productId": 77
235                  },
236                  "name": "Product",
237                  "description": "",
238                  "type": "widget"
239                }
240              ]
241            },
242            {
243              "configuration": {
244                "dropzoneBackgroundColor": "rgba(0,0,0,0)",
245                "dropzoneBackgroundImageAlignment": {
246                  "horizontal": "center",
247                  "vertical": "middle"
248                },
249                "dropzoneBackgroundImageFit": "fill",
250                "dropzoneBackgroundImageOpacity": 100,
251                "dropzoneBackgroundImageUrl": "",
252                "dropzoneBorderColor": "#333333",
253                "dropzoneBorderStyle": "solid",
254                "dropzoneBorderThickness": 0,
255                "dropzoneHeight": "",
256                "dropzoneJustifyContent": "center",
257                "dropzoneMargin": {
258                  "bottom": {
259                    "type": "px",
260                    "value": "0"
261                  },
262                  "left": {
263                    "type": "px",
264                    "value": "0"
265                  },
266                  "right": {
267                    "type": "px",
268                    "value": "0"
269                  },
270                  "top": {
271                    "type": "px",
272                    "value": "0"
273                  }
274                },
275                "dropzonePadding": {
276                  "bottom": {
277                    "type": "px",
278                    "value": "0"
279                  },
280                  "left": {
281                    "type": "px",
282                    "value": "10.5"
283                  },
284                  "right": {
285                    "type": "px",
286                    "value": "10.5"
287                  },
288                  "top": {
289                    "type": "px",
290                    "value": "0"
291                  }
292                },
293                "dropzoneZIndex": "auto",
294                "dropzoneBackgroundType": ""
295              },
296              "widgets": [
297                {
298                  "widget_template_uuid": "e59c1412-2d85-4f18-ab4b-8a55412d945c",
299                  "configuration": {
300                    "productCardContentAlignment": {
301                      "horizontal": "center"
302                    },
303                    "productImage": {
304                      "visibility": "show",
305                      "imageFit": "fill"
306                    },
307                    "brand": {
308                      "visibility": "show",
309                      "textStyle": "default",
310                      "color": "#444444"
311                    },
312                    "productName": {
313                      "visibility": "show",
314                      "textStyle": "default",
315                      "color": "#444444"
316                    },
317                    "price": {
318                      "visibility": "show",
319                      "textStyle": "default",
320                      "color": "#444444"
321                    },
322                    "productRating": {
323                      "visibility": "hide",
324                      "starColorFilled": "#3C64F4",
325                      "starColorEmpty": "#ECEEF5",
326                      "reviewsColor": "#8C93AD"
327                    },
328                    "button": {
329                      "visibility": "hide",
330                      "shape": "round",
331                      "buttonColor": "rgba(68,68,68,1)",
332                      "textStyle": "default",
333                      "buttonTextColor": "rgba(255,255,255,1)",
334                      "buttonActionType": "addToCart"
335                    },
336                    "productId": "80"
337                  },
338                  "storefront_api_query_params": {
339                    "productId": 80
340                  },
341                  "name": "Product",
342                  "description": "",
343                  "type": "widget"
344                }
345              ]
346            },
347            {
348              "configuration": {
349                "dropzoneBackgroundColor": "rgba(0,0,0,0)",
350                "dropzoneBackgroundImageAlignment": {
351                  "horizontal": "center",
352                  "vertical": "middle"
353                },
354                "dropzoneBackgroundImageFit": "fill",
355                "dropzoneBackgroundImageOpacity": 100,
356                "dropzoneBackgroundImageUrl": "",
357                "dropzoneBorderColor": "#333333",
358                "dropzoneBorderStyle": "solid",
359                "dropzoneBorderThickness": 0,
360                "dropzoneHeight": "",
361                "dropzoneJustifyContent": "center",
362                "dropzoneMargin": {
363                  "bottom": {
364                    "type": "px",
365                    "value": "0"
366                  },
367                  "left": {
368                    "type": "px",
369                    "value": "0"
370                  },
371                  "right": {
372                    "type": "px",
373                    "value": "0"
374                  },
375                  "top": {
376                    "type": "px",
377                    "value": "0"
378                  }
379                },
380                "dropzonePadding": {
381                  "bottom": {
382                    "type": "px",
383                    "value": "0"
384                  },
385                  "left": {
386                    "type": "px",
387                    "value": "10.5"
388                  },
389                  "right": {
390                    "type": "px",
391                    "value": "10.5"
392                  },
393                  "top": {
394                    "type": "px",
395                    "value": "0"
396                  }
397                },
398                "dropzoneZIndex": "auto",
399                "dropzoneBackgroundType": ""
400              },
401              "widgets": [
402                {
403                  "widget_template_uuid": "e59c1412-2d85-4f18-ab4b-8a55412d945c",
404                  "configuration": {
405                    "productCardContentAlignment": {
406                      "horizontal": "center"
407                    },
408                    "productImage": {
409                      "visibility": "show",
410                      "imageFit": "fill"
411                    },
412                    "brand": {
413                      "visibility": "show",
414                      "textStyle": "default",
415                      "color": "#444444"
416                    },
417                    "productName": {
418                      "visibility": "show",
419                      "textStyle": "default",
420                      "color": "#444444"
421                    },
422                    "price": {
423                      "visibility": "show",
424                      "textStyle": "default",
425                      "color": "#444444"
426                    },
427                    "productRating": {
428                      "visibility": "hide",
429                      "starColorFilled": "#3C64F4",
430                      "starColorEmpty": "#ECEEF5",
431                      "reviewsColor": "#8C93AD"
432                    },
433                    "button": {
434                      "visibility": "hide",
435                      "shape": "round",
436                      "buttonColor": "rgba(68,68,68,1)",
437                      "textStyle": "default",
438                      "buttonTextColor": "rgba(255,255,255,1)",
439                      "buttonActionType": "addToCart"
440                    },
441                    "productId": "93"
442                  },
443                  "storefront_api_query_params": {
444                    "productId": 93
445                  },
446                  "name": "Product",
447                  "description": "",
448                  "type": "widget"
449                }
450              ]
451            }
452          ],
453          "type": "layout"
454        }
455      ]
456    }
457  ]
458}

Resources

REST Content API reference