> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextintent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The facts sheet

> Every field of a site's facts sheet, its limits and how the engine uses it, and the merge semantics of PATCH /v1/sdk/{id}/facts.

The facts sheet is what a site is willing to have said on its behalf. Every sentence the engine composes is built from it and checked against it. The Shopify app writes it from the store; on any other site you write it through the API.

## Read and write

```
GET   /v1/sdk/{id}/facts     scope facts:read
PATCH /v1/sdk/{id}/facts     scope facts:write
```

<Info>
  PATCH merges by top-level key. A key that is present replaces that whole section; a key that is absent is kept. A body of `{ "shipping_zones": [...] }` rewrites the zones and leaves codes, size notes and links as they were. To clear a section, send it empty: `"codes": []`, `"delivery_promise": null`.
</Info>

Every value is validated and clipped on write; anything outside the shape below is dropped silently rather than rejected, so read the sheet back after writing.

## Fields

| Field | Type and limits | How the engine uses it |
| - | - | - |
| `currency` | string, up to 8 chars, default `USD` | Money formatting in sentences |
| `free_shipping_threshold` | number or null | The line for the home zone. Null means shipping is never mentioned |
| `shipping_flat` | number or null | The standard rate stated after the line: "\$6 below that" |
| `shipping_zones` | array, up to 40 | Per destination. Each `{ countries: ["DE","FR"], rest_of_world: false, free_shipping_threshold, shipping_flat }`. Country codes are two letters, up to 260 per zone. A country may appear in one zone only; at most one `rest_of_world` zone; a zone with no threshold is dropped. A visitor whose country matches no zone hears nothing about shipping |
| `return_days` | number or null | "Returns are accepted within N days." Null means returns are never mentioned |
| `delivery_promise` | string, up to 200 chars | Stated when a visitor stalls on delivery |
| `size_notes` | array, up to 50 | `{ handle, text, url }`. The note said on that product's page when the visitor flips options. `url` must be a same-origin path |
| `links` | object | `size_guide`, `shipping`, `returns`, `contact`: same-origin paths a card may link to. Any other link is refused |
| `codes` | array, up to 20 | `{ label, percent, starts_at, expires_at, first_order_only }`. Named only when `discounts_allowed` is true and the visitor's own code was declined |
| `fillers` | array, up to 20 | `{ handle, title, price, url }`: cheap items that close a gap to the free shipping line. Named by title and price in the shipping sentence |
| `discounts_allowed` | boolean, default false | Gate for any offer word in a sentence |
| `output` | `card`, `popup`, `event`, `none` | How the page delivers the sentence. See [The card and the event](/api/the-card) |
| `popup` | object or null | `{ provider, campaign_id, code_campaign_id }`; provider one of `optimonk`, `justuno`, `privy`, `wisepops`, `klaviyo`, `custom` |

Text fields are trimmed and cut at 200 characters (labels at 40, titles at 60). Paths must start with `/` and contain no whitespace. Instants are stored as UTC ISO strings.

## Example

```json theme={null}
{
  "currency": "USD",
  "free_shipping_threshold": 75,
  "shipping_flat": 6,
  "shipping_zones": [
    { "countries": ["US"], "free_shipping_threshold": 75, "shipping_flat": 6 },
    { "countries": ["CA"], "free_shipping_threshold": 120, "shipping_flat": 14 }
  ],
  "return_days": 30,
  "delivery_promise": "Ships in 1 to 2 business days.",
  "size_notes": [
    { "handle": "merino-crew-tee", "text": "Runs small. Most people take one size up.", "url": "/pages/size-guide" }
  ],
  "links": { "size_guide": "/pages/size-guide", "shipping": "/pages/shipping", "returns": "/policies/refund-policy" },
  "codes": [
    { "label": "WELCOME10", "percent": 10, "first_order_only": true }
  ],
  "fillers": [
    { "handle": "camp-mug", "title": "Camp Mug", "price": 18, "url": "/products/camp-mug" }
  ],
  "discounts_allowed": false,
  "output": "card"
}
```

## What the engine will not say without a fact

No free shipping line: nothing about shipping. No return days: nothing about returns, and never "free returns" unless the site states it. No size note for the product: nothing on that product page. No code, or `discounts_allowed` false: no offer. The sheet is the boundary of what can be said, which is why it is worth keeping complete.

## Related

* [Facts: read the sheet](/api/reference/facts/retrieve)
* [Facts: update the sheet](/api/reference/facts/update)
* [What it says](/shopify/how-it-works/what-it-says)