Pages

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

GET read_pages

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

GET read_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.

Example: 1
limit integer

Page size.

Example: 20
search string

Search Pages by title or slug.

Example: about-us
status string

Filter by status.

Example: published
sort_by string

Sort field from the Page list contract.

Allowed values
titlestatuscreated_atupdated_at
Example: created_at
sort_direction string

Sort direction from the Page list contract.

Allowed values
ascdesc
Example: desc

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Search pages

GET read_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.

Example: about
status string

Filter by status.

Example: published
limit integer

Suggestion count.

Example: 10
offset integer

Result offset.

Example: 0

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Get a page

GET read_pages

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_PAGE_ID

    The Page id is not a valid UUID.

  • 404 NOT_FOUND

    Page does not exist in this store.

Create a page

POST write_pages

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.

Example: About us
slug string

Optional slug. Omit to generate from title.

Example: about-us
content string

Optional sanitized HTML content.

Example: <p>Learn more about our store.</p>
seo_title string

Optional SEO title.

Example: About us
seo_description string

Optional SEO description.

Example: Learn more about our store.
status string

Page status: draft or published. Omit to create a draft.

Example: published
template_handle string

Template assignment. On create, omitting this field or sending an empty string assigns default_page. Use default_page for the default Page template, or pass an alternate Page template handle configured for the store. On update, omit template_handle to leave the assignment unchanged, use default_page to reset it to default, and do not send an empty string.

Example: default_page

Errors

  • 400 PAGE_TITLE_REQUIRED

    Title is empty after normalization.

  • 400 PAGE_TITLE_TOO_LONG

    Title exceeds the Page contract max length.

  • 400 PAGE_SLUG_INVALID_FORMAT

    Slug is not valid for Page URLs.

  • 400 PAGE_SLUG_TOO_LONG

    Slug exceeds the Page contract max length.

  • 400 PAGE_CONTENT_TOO_LONG

    Content exceeds the Page contract max length.

  • 400 PAGE_SEO_TITLE_TOO_LONG

    SEO title exceeds the Page contract max length.

  • 400 PAGE_SEO_DESCRIPTION_TOO_LONG

    SEO description exceeds the Page contract max length.

  • 400 PAGE_STATUS_INVALID

    Status is not one of the allowed values.

  • 400 TEMPLATE_HANDLE_INVALID

    Template handle is not valid for Page templates.

  • 400 TEMPLATE_HANDLE_NOT_FOUND

    Template handle does not exist on the store's primary active theme for Page.

  • 404 NOT_FOUND

    Page does not exist in this store.

  • 409 PAGE_SLUG_DUPLICATE

    Slug already exists in this store.

Update a page

PUT write_pages

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
title string

Page title.

Example: About us
slug string

Optional slug. Omit to generate from title.

Example: about-us
content string

Optional sanitized HTML content.

Example: <p>Learn more about our store.</p>
seo_title string

Optional SEO title.

Example: About us
seo_description string

Optional SEO description.

Example: Learn more about our store.
status string

Page status: draft or published. Omit to create a draft.

Example: published
template_handle string

Template assignment. On create, omitting this field or sending an empty string assigns default_page. Use default_page for the default Page template, or pass an alternate Page template handle configured for the store. On update, omit template_handle to leave the assignment unchanged, use default_page to reset it to default, and do not send an empty string.

Example: default_page
create_redirect boolean

When the slug changes, create a redirect from the old page URL to the new one. Defaults to true.

Example: true

Errors

  • 400 PAGE_TITLE_REQUIRED

    Title is empty after normalization.

  • 400 PAGE_TITLE_TOO_LONG

    Title exceeds the Page contract max length.

  • 400 PAGE_SLUG_INVALID_FORMAT

    Slug is not valid for Page URLs.

  • 400 PAGE_SLUG_TOO_LONG

    Slug exceeds the Page contract max length.

  • 400 PAGE_CONTENT_TOO_LONG

    Content exceeds the Page contract max length.

  • 400 PAGE_SEO_TITLE_TOO_LONG

    SEO title exceeds the Page contract max length.

  • 400 PAGE_SEO_DESCRIPTION_TOO_LONG

    SEO description exceeds the Page contract max length.

  • 400 PAGE_STATUS_INVALID

    Status is not one of the allowed values.

  • 400 TEMPLATE_HANDLE_INVALID

    Template handle is not valid for Page templates.

  • 400 TEMPLATE_HANDLE_NOT_FOUND

    Template handle does not exist on the store's primary active theme for Page.

  • 404 NOT_FOUND

    Page does not exist in this store.

  • 409 PAGE_SLUG_DUPLICATE

    Slug already exists in this store.

Delete a page

DELETE write_pages

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.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

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

Example: false
confirmation_token string

Token returned by the first delete attempt.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    The delete request body is malformed.

  • 400 STORE_API_INVALID_PAGE_ID

    A Page id is not a valid UUID.

  • 400 PAGE_BULK_NO_IDS

    No Page ids were provided.

  • 400 PAGE_BULK_DELETE_TOO_MANY

    Batch exceeds the Page bulk delete cap.

  • 400 PAGE_CONFIRMATION_INVALID

    The confirmation token is missing, expired, or does not match this delete.

  • 404 NOT_FOUND

    Page does not exist in this store.

  • 409 CONFIRMATION_REQUIRED

    Menus link to the requested Page; repeat the request with the returned confirmation token to remove those links and delete.

Bulk delete pages

POST write_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.

Example: ["5ff7d4ea-3250-4a4d-9d26-07f64d917d31"]
confirmed boolean

Set true when repeating a delete that returned CONFIRMATION_REQUIRED.

Example: false
confirmation_token string

Token returned by the first delete attempt.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    The delete request body is malformed.

  • 400 STORE_API_INVALID_PAGE_ID

    A Page id is not a valid UUID.

  • 400 PAGE_BULK_NO_IDS

    No Page ids were provided.

  • 400 PAGE_BULK_DELETE_TOO_MANY

    Batch exceeds the Page bulk delete cap.

  • 400 PAGE_CONFIRMATION_INVALID

    The confirmation token is missing, expired, or does not match this delete.

  • 404 NOT_FOUND

    Page does not exist in this store.

  • 409 CONFIRMATION_REQUIRED

    Menus 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

title

text

Yes

Yes

create

Yes

slug

slug

Yes

Yes

Yes

content

rich_text

Yes

Yes

Yes

seo_title

text

Yes

Yes

Yes

seo_description

textarea

Yes

Yes

Yes

status

select

Yes

Yes

No

template_handle

template

Yes

Yes

No

create_redirect

boolean

No

Yes

No

created_at

datetime

No

No

No

updated_at

datetime

No

No

No

storefront_url

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

EVENT pages/create write_pages pages:write

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

EVENT pages/update write_pages pages:write

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

EVENT pages/delete write_pages pages:write

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