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`) |

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

### Response

```json
{
  "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 |

```bash
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)

```json
{
  "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.

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

### Response

```json
{
  "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 |

```bash
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

```json
{
  "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.