Partners

Policies

Read, update, translate, and subscribe to store policies through the Store API.

Each store has five policies: privacy, terms, refund, shipping, and cookie. Read and update a policy by its type. These endpoints do not create or delete policies. Reads require read_pages; writes require write_pages.

Updates preserve omitted fields. They can change content, publishing, SEO, and the URL slug. A source field with translations cannot be cleared until those translations are removed. The privacy and cookie policies used by an active consent banner must remain published with content.

Policy translations use the policy's UUID returned by a read. Translation reads require read_pages and read_translations; writes require write_pages and write_translations.

Endpoints#

Policy limits

GET read_pages

Fetch Policy limits and per-field constraints.

Returns the per-field maximum lengths, enum values, and the fixed policy-type set that apply to Policy endpoints.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

List policies

GET read_pages

List all policies for the store.

Returns the store's fixed set of Policies — one row per policy type. There is no pagination: Policies are a fixed singleton set. storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply translated slugs and locale/country prefixes.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Get a policy

GET read_pages

Fetch one policy by type.

Returns the Policy for the given type (privacy, terms, refund, shipping, or cookie). storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply translated slugs and locale/country prefixes.

Path parameters

Name Type Description
type required string

Policy type: privacy, terms, refund, shipping, or cookie.

Example: privacy

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 POLICY_TYPE_INVALID

    Type is not one of the fixed policy types.
  • 404 NOT_FOUND

    The policy row does not exist in this store.

Update a policy

PUT write_pages

Update one policy by type.

Updates provided fields on the existing fixed Policy row. Omitted fields are left unchanged. An empty slug resets to the default slug for the policy type. When slug changes, create_redirect controls whether the old policy URL redirects to the new one and defaults to true. storefront_url is the canonical absolute URL on the store's primary domain. storefront_path is the domain-independent baseline route; join it to the storefront address you are targeting. Hosted storefront responses apply translated slugs and locale/country prefixes.

Path parameters

Name Type Description
type required string

Policy type: privacy, terms, refund, shipping, or cookie.

Example: privacy

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
title string

Policy title. When supplied, it must be non-empty after normalization.

Example: Privacy policy
slug string

Optional slug. Omit to leave unchanged; send an empty string to reset to the default slug for the policy type.

Example: privacy-policy
content string

Optional sanitized HTML content.

Example: <p>How we handle your data.</p>
seo_title string

Optional SEO title.

Example: Privacy policy
seo_description string

Optional SEO description.

Example: How we handle your data.
status string

Policy status: draft or published.

Example: published
create_redirect boolean

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

Example: true

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    The request body is malformed or contains an unknown field.
  • 400 POLICY_TYPE_INVALID

    Type is not one of the fixed policy types.
  • 400 POLICY_TITLE_REQUIRED

    Title is empty after normalization.
  • 400 POLICY_TITLE_TOO_LONG

    Title exceeds the Policy contract max length.
  • 400 POLICY_SLUG_INVALID_FORMAT

    Slug is not valid for Policy URLs.
  • 400 POLICY_SLUG_TOO_LONG

    Slug exceeds the Policy contract max length.
  • 400 POLICY_CONTENT_TOO_LONG

    Content exceeds the Policy contract max length.
  • 400 POLICY_SEO_TITLE_TOO_LONG

    SEO title exceeds the Policy contract max length.
  • 400 POLICY_SEO_DESCRIPTION_TOO_LONG

    SEO description exceeds the Policy contract max length.
  • 400 POLICY_STATUS_INVALID

    Status is not one of the allowed values.
  • 409 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS

    A source field cannot be cleared while it has translations in any locale.
  • 409 POLICY_SLUG_DUPLICATE

    Slug already exists in this store's policies.
  • 409 POLICY_LOCKED_BY_CONSENT_BANNER

    The active consent banner requires its privacy and cookie policies to remain published with content.

Fields#

Field

Type

Create

Update

Required

Translatable

type

string

No

No

No

title

string

No

Yes

Yes

slug

string

No

Yes

Yes

content

string

No

Yes

Yes

seo_title

string

No

Yes

Yes

seo_description

string

No

Yes

Yes

status

string

No

Yes

No

create_redirect

boolean

No

Yes

No

created_at

string (RFC 3339)

No

No

No

updated_at

string (RFC 3339)

No

No

No

storefront_url

url

No

No

No

No

storefront_path

string

No

No

No

No

Webhook events#

Subscribe to these events to keep your integration in sync with policies. Each event shows the required Store API scope and store permission, the available payload fields, and an example payload. Subscription setup is validated against those permissions; delivery is always restricted to the subscription's store.

Policy updated

EVENT policies/update App scope: read_pages Staff permission: pages:write

Fired when a store policy is updated.

Payload fields

Field Type Description
policy.id string Always present
policy.type string Selectable in the Payload builder
policy.title string Selectable in the Payload builder
policy.slug string Selectable in the Payload builder
policy.content string Selectable in the Payload builder
policy.status string Selectable in the Payload builder
policy.seo_title string Selectable in the Payload builder
policy.seo_description string Selectable in the Payload builder
policy.created_at string Selectable in the Payload builder
policy.updated_at string Selectable in the Payload builder

Last updated Oct 21, 2026