PATCH /v1/sdk/{id}/facts. The full field table with types and limits is in The facts sheet (API); this page is about what each fact buys you.
Why a sheet at all
A generic “need any help?” is worth almost nothing; visitors have learned to ignore it. A specific true sentence at the right moment is worth a sale: “Add $12 more and shipping is free” to someone whose cart has sat at $63 for a minute. The engine can only be specific about things you have told it. The sheet is that list, and it is also the boundary: nothing outside it can be said, which is what makes it safe to let the engine speak.What each fact lets it say
Shipping:free_shipping_threshold, shipping_flat, shipping_zones, fillers. With a free shipping line, a visitor whose cart is just under it hears the gap: “Add $12 more and shipping is free.” With a filler list, the gap is named as a product: “Add the Camp Mug ($18) and shipping is free.” With zones, the line is the one for the visitor’s country; a visitor whose country matches no zone hears nothing about shipping rather than the wrong line. Without any of this, shipping is never mentioned. This is the most common moment on a store, so it is the first fact to fill.
Returns: return_days. On a cart, a visitor hesitating over a purchase hears “Returns are accepted within 30 days.” The engine says accepted, never free, unless you have stated free returns. Without it, returns are never mentioned.
Delivery: delivery_promise. “Ships in 1 to 2 business days.” Said when a visitor stalls on a delivery question. Without it, nothing.
Size and fit: size_notes. One note per product handle, said on that product’s page when the visitor flips options without adding: “Runs small. Most people take one size up.” With a url, the card links to your size guide. This is the fact that catches the size stall, which is otherwise a silent exit. Without a note for the product on the page, nothing is said there.
Links: links. Same-origin paths for size_guide, shipping, returns, contact. A card may only link to a path on this list; anything else is refused before it is shown. Without links, cards have text and no button.
Offers: codes and discounts_allowed. Off by default, and off means no offer word ever appears. With discounts_allowed true and a code on the list, a visitor whose own code was declined hears the current offer: “WELCOME10 takes 10% off a first order.” That is the only situation an offer is named, so a code on the sheet is not a coupon shown to everyone. starts_at, expires_at and first_order_only are honoured.
Delivery of the sentence: output and popup. card draws NextIntent’s card; event fires a browser event and draws nothing; popup hands the sentence to a popup tool’s campaign; none records without showing. See The card.
currency. How money is written in sentences. Default USD.
When a fact is missing
Silence. The engine drops any proposed sentence that rests on a fact the sheet does not carry, and the visitor sees nothing. The moment is still recorded, with the sentence the engine wanted to say, so the Moments view shows you which facts would have been used. Read it after a week in watch mode and you have the list of facts to add.Updating the sheet
PATCH /v1/sdk/{id}/facts merges by top-level key: a key you send replaces that section in full, a key you leave out is kept. So a nightly job that only knows about codes can send { "codes": [...] } without touching shipping zones. To clear a section, send it empty. Values are validated and clipped on write (a zone with no rate is dropped, a country can be in one zone only, text is cut at 200 characters), so read the sheet back after a write. Every write is audited.
Keep it current: an expired code or an old shipping line becomes a wrong sentence. The Shopify app re-reads the store every ten minutes and on every change; a site that writes the sheet itself should do the same from wherever those facts live.