Pages require pages scopes. Reads use read_pages; writes use write_pages. Pages support title, slug, content, seo_title, seo_description, status, and template_handle fields. title is required on create; omitted status defaults to draft; slug is optional on create and generated from the title when omitted. On update, a supplied slug must be non-empty and valid, and create_redirect controls whether the old URL redirects to the new one. content is sanitized HTML. On create, omitting template_handle assigns default_page. Use default_page for the default Page template, or pass an alternate Page template handle configured for the store. Omit template_handle on update to leave the current assignment unchanged; an empty string is invalid. AI translation is not exposed through the Store API.
Endpoints#
Page limits
Fetch Page limits and per-field constraints.
Returns the per-field maximum lengths, enum values, and request caps that apply to Page endpoints.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
List pages
List pages for the store.
Returns paginated Pages. Use search or status to filter. Missing or non-positive pagination values use the contract defaults, values above the maximum are capped, and invalid sort values are rejected.
Query parameters
| Name | Type | Description |
|---|---|---|
page
|
integer |
Page number. |
limit
|
integer |
Page size. |
search
|
string |
Search Pages by title or slug. |
status
|
string |
Filter by status. |
sort_by
|
string |
Sort field from the Page list contract.
Allowed values
titlestatuscreated_atupdated_at |
sort_direction
|
string |
Sort direction from the Page list contract.
Allowed values
ascdesc |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Search pages
Search pages for picker UIs.
Returns lightweight page options. Missing or non-positive pagination values use the contract defaults, and limit is capped by the Page contract.
Query parameters
| Name | Type | Description |
|---|---|---|
q
|
string |
Search query. |
status
|
string |
Filter by status. |
limit
|
integer |
Suggestion count. |
offset
|
integer |
Result offset. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Get a page
Fetch one page by id.
Returns the Page if it belongs to the token's store.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Page id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400STORE_API_INVALID_PAGE_IDThe Page id is not a valid UUID.
-
404NOT_FOUNDPage does not exist in this store.
Create a page
Create a page.
Creates a Page. title is required. Omitted status defaults to draft. slug is optional on create; when omitted or empty, the backend generates it from the title. Optional SEO, content, and template fields follow the Page resource contract.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
title
required
|
string |
Page title. |
slug
|
string |
Optional slug. Omit to generate from title. |
content
|
string |
Optional sanitized HTML content. |
seo_title
|
string |
Optional SEO title. |
seo_description
|
string |
Optional SEO description. |
status
|
string |
Page status: draft or published. Omit to create a draft. |
template_handle
|
string |
Template assignment. On create, omitting this field or sending an empty string assigns |
Errors
-
400PAGE_TITLE_REQUIREDTitle is empty after normalization.
-
400PAGE_TITLE_TOO_LONGTitle exceeds the Page contract max length.
-
400PAGE_SLUG_INVALID_FORMATSlug is not valid for Page URLs.
-
400PAGE_SLUG_TOO_LONGSlug exceeds the Page contract max length.
-
400PAGE_CONTENT_TOO_LONGContent exceeds the Page contract max length.
-
400PAGE_SEO_TITLE_TOO_LONGSEO title exceeds the Page contract max length.
-
400PAGE_SEO_DESCRIPTION_TOO_LONGSEO description exceeds the Page contract max length.
-
400PAGE_STATUS_INVALIDStatus is not one of the allowed values.
-
400TEMPLATE_HANDLE_INVALIDTemplate handle is not valid for Page templates.
-
400TEMPLATE_HANDLE_NOT_FOUNDTemplate handle does not exist on the store's primary active theme for Page.
-
404NOT_FOUNDPage does not exist in this store.
-
409PAGE_SLUG_DUPLICATESlug already exists in this store.
Update a page
Update a page.
Updates provided Page fields. Omitted fields are left unchanged. When slug is provided it must be non-empty and valid; create is the only path that auto-generates a blank slug from the title.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Page id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
title
|
string |
Page title. |
slug
|
string |
Optional slug. Omit to generate from title. |
content
|
string |
Optional sanitized HTML content. |
seo_title
|
string |
Optional SEO title. |
seo_description
|
string |
Optional SEO description. |
status
|
string |
Page status: draft or published. Omit to create a draft. |
template_handle
|
string |
Template assignment. On create, omitting this field or sending an empty string assigns |
create_redirect
|
boolean |
When the slug changes, create a redirect from the old page URL to the new one. Defaults to true. |
Errors
-
400PAGE_TITLE_REQUIREDTitle is empty after normalization.
-
400PAGE_TITLE_TOO_LONGTitle exceeds the Page contract max length.
-
400PAGE_SLUG_INVALID_FORMATSlug is not valid for Page URLs.
-
400PAGE_SLUG_TOO_LONGSlug exceeds the Page contract max length.
-
400PAGE_CONTENT_TOO_LONGContent exceeds the Page contract max length.
-
400PAGE_SEO_TITLE_TOO_LONGSEO title exceeds the Page contract max length.
-
400PAGE_SEO_DESCRIPTION_TOO_LONGSEO description exceeds the Page contract max length.
-
400PAGE_STATUS_INVALIDStatus is not one of the allowed values.
-
400TEMPLATE_HANDLE_INVALIDTemplate handle is not valid for Page templates.
-
400TEMPLATE_HANDLE_NOT_FOUNDTemplate handle does not exist on the store's primary active theme for Page.
-
404NOT_FOUNDPage does not exist in this store.
-
409PAGE_SLUG_DUPLICATESlug already exists in this store.
Delete a page
Delete a page.
Deletes a Page and its translations atomically. If menus link to the Page, the first request returns CONFIRMATION_REQUIRED; repeat it with the returned token to remove those menu links and delete the Page.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Page id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
confirmed
|
boolean |
Set true when repeating a delete that returned |
confirmation_token
|
string |
Token returned by the first delete attempt. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYThe delete request body is malformed.
-
400STORE_API_INVALID_PAGE_IDA Page id is not a valid UUID.
-
400PAGE_BULK_NO_IDSNo Page ids were provided.
-
400PAGE_BULK_DELETE_TOO_MANYBatch exceeds the Page bulk delete cap.
-
400PAGE_CONFIRMATION_INVALIDThe confirmation token is missing, expired, or does not match this delete.
-
404NOT_FOUNDPage does not exist in this store.
-
409CONFIRMATION_REQUIREDMenus link to the requested Page; repeat the request with the returned confirmation token to remove those links and delete.
Bulk delete pages
Delete multiple pages.
Deletes the existing requested Pages in one transaction and reports missing ids per item. If menus link to any requested Page, the first request returns CONFIRMATION_REQUIRED; repeat it with the returned token to remove those menu links and continue. The request is capped by the Page bulk contract.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
ids
required
|
array<uuid> |
Page ids to delete. |
confirmed
|
boolean |
Set true when repeating a delete that returned |
confirmation_token
|
string |
Token returned by the first delete attempt. |
Errors
-
400STORE_API_INVALID_REQUEST_BODYThe delete request body is malformed.
-
400STORE_API_INVALID_PAGE_IDA Page id is not a valid UUID.
-
400PAGE_BULK_NO_IDSNo Page ids were provided.
-
400PAGE_BULK_DELETE_TOO_MANYBatch exceeds the Page bulk delete cap.
-
400PAGE_CONFIRMATION_INVALIDThe confirmation token is missing, expired, or does not match this delete.
-
404NOT_FOUNDPage does not exist in this store.
-
409CONFIRMATION_REQUIREDMenus link to the requested Page; repeat the request with the returned confirmation token to remove those links and delete.
Fields#
Field |
Kind |
Create |
Update |
Required |
Translatable |
|---|---|---|---|---|---|
|
text |
Yes |
Yes |
create |
Yes |
|
slug |
Yes |
Yes |
Yes |
|
|
rich_text |
Yes |
Yes |
Yes |
|
|
text |
Yes |
Yes |
Yes |
|
|
textarea |
Yes |
Yes |
Yes |
|
|
select |
Yes |
Yes |
No |
|
|
template |
Yes |
Yes |
No |
|
|
boolean |
No |
Yes |
No |
|
|
datetime |
No |
No |
No |
|
|
datetime |
No |
No |
No |
|
|
url |
No |
No |
No |
No |
Webhook events#
Page webhook events are declared by the Page resource contract. The event cards below include the topic, subscription scope, store permission, payload schema, and sample payload.
Page created
Fired when a custom page is created.
Payload fields
| Field | Type | Description |
|---|---|---|
page.id |
string |
Always present |
page.title |
string |
Can be removed/added via the Payload builder |
page.slug |
string |
Can be removed/added via the Payload builder |
page.content |
string |
Can be removed/added via the Payload builder |
page.status |
string |
Can be removed/added via the Payload builder |
page.seo_title |
string |
Can be removed/added via the Payload builder |
page.seo_description |
string |
Can be removed/added via the Payload builder |
page.template_handle |
string |
Can be removed/added via the Payload builder |
page.created_at |
string |
Can be removed/added via the Payload builder |
page.updated_at |
string |
Can be removed/added via the Payload builder |
Page updated
Fired when a custom page is updated.
Payload fields
| Field | Type | Description |
|---|---|---|
page.id |
string |
Always present |
page.title |
string |
Can be removed/added via the Payload builder |
page.slug |
string |
Can be removed/added via the Payload builder |
page.content |
string |
Can be removed/added via the Payload builder |
page.status |
string |
Can be removed/added via the Payload builder |
page.seo_title |
string |
Can be removed/added via the Payload builder |
page.seo_description |
string |
Can be removed/added via the Payload builder |
page.template_handle |
string |
Can be removed/added via the Payload builder |
page.created_at |
string |
Can be removed/added via the Payload builder |
page.updated_at |
string |
Can be removed/added via the Payload builder |
Page deleted
Fired when a custom page is deleted.
Payload fields
| Field | Type | Description |
|---|---|---|
page.id |
string |
Always present |
page.title |
string |
Can be removed/added via the Payload builder |
page.slug |
string |
Can be removed/added via the Payload builder |