The facts sheet - NextIntent

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

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.

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

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