Legal Pages API

REST API endpoints for managing store legal pages.

Legal pages are the store's terms, privacy policy, and return policy. Each entry is addressed by a semantic key — not a UUID — and carries a label, rich-text content (TipTap JSON plus rendered HTML), and the storefront href it is hosted at. Entries are created automatically the first time they are read, so a store always has the three standard pages.

The valid keys are terms, privacyPolicy, and returns. Path-style aliases such as privacy-policy and /terms are accepted for compatibility. Use ?lang= to read or write a translation; supported locales are en-US, pl-PL, es-ES, and de-DE.

List Legal Pages

GET /api/v1/legal-pages

Returns the store's legal page entries. Pass ?lang=pl-PL to read a localized version; the response isFallback flag indicates when the default-language content was used because no translation exists.

Query Parameters

Parameter	Type	Default	Description
`lang`	`string`	—	Locale code for translations (e.g. `pl-PL`)

curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/legal-pages

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "key": "terms",
      "label": "Terms of Service",
      "contentHtml": "<p>These are the terms of service.</p>",
      "contentJson": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "These are the terms of service." }]
          }
        ]
      },
      "href": "/terms",
      "locale": "en-US",
      "isFallback": false,
      "createdAt": "2024-05-01T09:00:00.000Z",
      "updatedAt": "2024-05-01T09:00:00.000Z"
    }
  ]
}

An invalid lang value returns 400.

Create Legal Page

POST /api/v1/legal-pages

Creates or replaces a legal page entry by semantic key. Pass ?lang=pl-PL to write a translation; omit lang to write the default-language entry. The content field accepts a plain string (wrapped into a single paragraph) or a TipTap JSON document.

Request Body

Field	Type	Required	Description
`key`	`string`	Yes	Page key: `terms`, `privacyPolicy`, or `returns`
`label`	`string`	Yes	Display title for the page
`content`	`string \| object`	Yes	Plain text or a TipTap JSON document (`type: "doc"`)
`href`	`string \| null`	No	Storefront path to host the page at

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"key": "terms", "label": "Terms of Service", "content": "These are the terms of service."}' \
  https://your-store.yns.store/api/v1/legal-pages

Response (201)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "key": "terms",
  "label": "Terms of Service",
  "contentHtml": "<p>These are the terms of service.</p>",
  "contentJson": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "These are the terms of service." }]
      }
    ]
  },
  "href": "/terms",
  "locale": "en-US",
  "isFallback": false,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}

A 400 is returned for an invalid key, unsupported locale, validation error, or malformed TipTap content.

Get Legal Page

GET /api/v1/legal-pages/{path}

Returns a single legal page entry by key. Legacy aliases such as privacy-policy are accepted. Use ?lang=pl-PL for localized reads.

curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/legal-pages/privacyPolicy

Response

{
  "id": "0191abc0-1234-7def-8000-000000000002",
  "key": "privacyPolicy",
  "label": "Privacy Policy",
  "contentHtml": "<p>How we handle your data.</p>",
  "contentJson": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "How we handle your data." }]
      }
    ]
  },
  "href": "/privacy-policy",
  "locale": "en-US",
  "isFallback": false,
  "createdAt": "2024-05-01T09:00:00.000Z",
  "updatedAt": "2024-05-01T09:00:00.000Z"
}

A 404 is returned when the entry does not exist, and a 400 for an invalid key.

Update Legal Page

PATCH /api/v1/legal-pages/{path}

Partially updates a legal page entry by key. Pass ?lang=pl-PL to patch a translation; omit lang to patch the default-language entry. At least one field must be provided. Passing href: null resets the page to its default storefront path.

Request Body

Field	Type	Required	Description
`label`	`string`	No	Display title for the page
`content`	`string \| object`	No	Plain text or a TipTap JSON document (`type: "doc"`)
`href`	`string \| null`	No	Storefront path, or `null` to reset to default

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"label": "Terms & Conditions"}' \
  https://your-store.yns.store/api/v1/legal-pages/terms

Response

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "key": "terms",
  "label": "Terms & Conditions",
  "contentHtml": "<p>These are the terms of service.</p>",
  "contentJson": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "These are the terms of service." }]
      }
    ]
  },
  "href": "/terms",
  "locale": "en-US",
  "isFallback": false,
  "createdAt": "2024-05-01T09:00:00.000Z",
  "updatedAt": "2024-06-15T11:00:00.000Z"
}

A 404 is returned when the entry does not exist, and a 400 for an invalid key, unsupported locale, validation error, or malformed TipTap content.

PreviousDomainAPI Reference NextFeedback SessionsAPI Reference