Pages

Overview

Read the CMS pages of the shop (the home page, the legal pages and every other content page) with commerce.read; create, change and delete them with commerce.write.content (edit permission Pages, Pagina's, in Settings > API tokens; a token with it lives at most 30 days). Each endpoint is the MCP tool of the same name, described in Content tools, with the same data, the same change log (channel api) and the same write limit. Every write goes through the page editor's own rules (Website > Pages), is recorded in the shop's content activity log with the token as the causer, and shows in the page's history as "API-token" followed by the token name.

• Drafts are visible to read tokens. GET /pages and GET /pages/{id} include drafts and scheduled or expired pages for every token with commerce.read. Do not give a read token to anyone who may not see unpublished content.
• Request size. POST /pages and PATCH /pages/{id} accept a body of up to 262144 bytes (256 KiB). Every other write keeps 65536 bytes.
• No customer data. Pages hold shop content only.

List pages

Query parameters: status (draft, published or all, the default), limit and cursor. Pages by id. The rows have no blocks; use the next endpoint for those.

curl -s -H "Authorization: Bearer $COMMERCE_API_TOKEN" \
  "https://<your-shop-domain>/api/v1/pages?status=draft"

Get a page

The writable fields have the names and forms the write endpoints take, so the answer can be sent back as it is (the image_urls of a block are ignored). With the current version that answers changed: false.

Create a page

Not idempotent: a repeat with the same slug is 422 because the slug is taken; a slug that another page takes at the same moment is 409. The answer is the page as GET /pages/{id} returns it, plus changed and changes ({field: {old, new}}; blocks appear as a count and a sha256 fingerprint so the change log does not keep whole texts).

Change a page

Send expected_updated_at and the fields you want to change; the others keep their value. The input is merged onto the page as it is read under a row lock. Every committed change moves the version, also a second change within the same second, so two writers with the same expected_updated_at never both succeed. When the page was saved after that moment the answer is 409 conflict and nothing changes: read the page again and retry.

curl -sS -X PATCH "https://<your-shop-domain>/api/v1/pages/7" \
  -H "Authorization: Bearer $COMMERCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected_updated_at": "2026-11-01T11:58:00+00:00", "title": "Over ons", "noindex": false, "blocks": [{"type": "heading", "data": {"text": "Over ons", "level": 2}}, {"type": "image", "data": {"path": "https://images.example.com/winkel.jpg", "alt": "Onze winkel"}}]}'

Delete a page

No body. Deletes the page with its saved versions and the menu links that point at it. The answer is page_id, deleted, menu_links_removed, changed, changes. The home page cannot be deleted (422); a repeat is 404.

Blocks

blocks is the whole list in page order and replaces every block, so read the page first, change what you need and send the list back. There are 20 block types. Ten work on any page; ten work only on the home page, or on a page that has that type already. The exact fields of each type are in the OpenAPI document (PageBlock, one schema per type). A block that breaks a rule of its type is 422 and names the field.

• Rich text (richtext.html, media-text.html) is sanitised as in the editor: scripts, event handlers, inline styles and unsafe links (javascript:) are removed. Other block text is stored as plain text.
• References. Collection, brand and product slugs in blocks must exist (422 otherwise), unless the page has them already.

Images

An image field and og_image take either a path the page already uses, which is kept as it is, or an https URL that the shop downloads before the write.

• Public hosts only (no private, loopback or link-local addresses), no redirects, JPEG, PNG or WebP of at most 5 MB each, stored as WebP.
• At most 20 new image URLs per call, 40 MB and 30 seconds of downloading in all. Past the budget the call is 422 and names the field.
• A GIF, an AVIF or an image above 5 MB is 422 and names the field (blocks.2.data.path, og_image). Any other value (an http URL, a path of another page) is 422.
• og_image takes only an https URL, null (removes the share image) or its current value, never a path a block uses.
• A file stored by a call that then fails or rolls back is deleted again.

The home page

• It keeps the slug home; another slug is 422, and no other page may take home.
• It cannot be deleted.
• The ten home-page block types (product-row, category-tiles, brand-carousel, article-teaser, locations-teaser, related-products, product-tabs, hero-slider, newsletter, goal-tiles) are accepted there, and on another page only when that page has the type already.

Search engines and addresses

• noindex: true keeps the page out of search results, the sitemap and llms.txt. The shop-wide "hide from search engines" setting still wins when it is on.
• A page whose canonical_url points to another address stays in the sitemap for now; set noindex as well if it must not be listed.
• A slug change of a page that is public keeps the old address working with a redirect, as in the editor.

Errors