Inspiration

I wanted to build for small and mid-sized merchants, the shops that don't have the scale or the teams of the big players. So I asked myself a simple question: what can the big players afford to do that small shops can't?

The answer I kept coming back to was keeping promises. As a buyer, I've seen how a player like Amazon handles a late delivery: the promise is clear, the refund comes without a fight, and you trust them a little more next time. That takes data, systems and an operations team. A two-person ceramics studio can write the same line, "Arrives by Friday, or shipping's on us," but nobody has time to check every parcel. The buyer has to notice, complain and argue. Most never do, and the promise quietly turns into marketing.

There's a second reason small shops hold back: refund abuse. A generous guarantee invites "it never came" or "it was late" claims that a small merchant can't verify and can't afford to fight. So many shops simply don't promise anything.

I thought there should be a better way for smaller merchants to offer that same trust, and PayPal is where it fits: the purchase, the tracking number and the refund all live on the same PayPal transaction. That became Kept. An agent turns the merchant's own words into a rule that code can check, and when the promise breaks, PayPal refunds the buyer before they have to ask. It also takes the abuse out of the guarantee: refunds follow the evidence, not a claim, so there's nothing to argue about. The merchant sets the levers up front (the condition, the amount and a monthly budget cap), and when the scans point at the buyer, such as "no one available to sign," the refund is paused for the merchant to decide. It's the kind of guarantee the big players offer, for shops of any size.

How Kept differs from what exists

Pieces of this already exist. Weather guarantees that pay out automatically (Sensible Weather, WeatherPromise) are fixed products sold by an insurer. Merchant-run shipping guarantees (ShipAid) still rely on the buyer filing a claim. AI support agents (for example Yuma) can resolve late orders proactively, but a model decides each case. LLM "intelligent contracts" (GenLayer) also have a model judge each claim. Delivery-date tools (Narvar Promise, LateShipment Promise, Shopify Shop Promise) already factor in holidays and weather, but to estimate a date, not to back it with a payout.

Kept makes a different split:

  • The AI compiles the promise; code keeps it. The Kept agent turns the merchant's words into a typed rule once. The merchant reviews and approves it, and from then on code computes every amount and starts every payout. The agent keeps one narrow, one-way lever: it can pause a broken delivery promise's payout for the merchant to review, never start or size one. The outcome is deterministic, auditable, capped and testable.
  • The promise is a contract the buyer can see. The exact rule is shown at checkout and frozen into the order. It isn't an internal policy hidden behind a support bot.
  • Promises that can't be checked are refused. "You'll love it or your money back" gets a rewrite that can be checked, not a fake guarantee.
  • Promises designed for the moment, priced before they go live. The Kept agent suggests promises from the intersection of the product, the season, upcoming holidays, the day, this week's forecast and years of local weather history. Code prices each one, so the merchant sees what it will likely cost per order before approving it.
  • One engine for any promise, in the merchant's own words. Delivery and weather today, on the same rule language, with no fixed product catalog.
  • Native to the payment. Refunds go against the PayPal capture, tracking is attached to the same capture, and a monthly budget caps total exposure.

What it does

▶ Demo video: https://youtu.be/fyTHkRSuUQs · Try it: https://kept-jhjl.onrender.com · Code (MIT): https://github.com/igorbnd/kept

Kept lets a merchant write a promise the way they'd say it, or ask the agent what to promise.

  1. Promise ideas. The Kept agent (Claude) reads the product and the moment: the season, upcoming holidays, the day and time, the live 7-day forecast at the shop and five years of weather for the same weeks. It drafts five promises; code compiles and prices each one and shows the three best that fit this week, such as "Order by Nov 20 and it's here before Thanksgiving, or 20% back" for a mug, or "Rain between 4 and 8 pm on your sunset tour? Half your ticket back" for a kayak tour. Code prices each one before the merchant decides: weather promises from Open-Meteo history ("would have paid out on 15 of 150 days, about $3.25 per booking"), delivery promises from stated carrier on-time assumptions.
  2. The Kept agent (powered by Claude) compiles the promise into a rule we can check, with a condition, a data source and a payout. It lists every assumption it made and any question the merchant should answer. It refuses promises that can't be checked ("you'll love it") and suggests a rewrite.
  3. The merchant approves the rule. It appears as a badge on the product, and the buyer pays with PayPal Checkout. The rule is frozen into the order, and the tracking number is attached to the PayPal transaction.
  4. An autonomous watcher checks real evidence, either carrier tracking or real Open-Meteo weather. When a delivery promise breaks, the Kept agent (Claude) reviews the carrier scans. If the miss looks like the buyer's doing ("no one available to sign"), it pauses the payout for the merchant. Otherwise the payout goes ahead. When a promise breaks, code computes the payout (capped at the captured amount and the merchant's monthly budget) and PayPal refunds the buyer automatically. The Kept agent (Claude) writes the buyer a note citing the evidence.
  5. The merchant's AG Grid ledger shows every order, its evidence, the decision and the PayPal refund id. Every step is in an audit trail.

The product experience

  • The merchant writes a promise in plain words or picks a suggested one, then sees the compiled rule as a contract card: the condition, the payout, every assumption, and what it's likely to cost per order. One click puts it live.
  • The buyer sees the promise as a badge on the product and at checkout, pays with PayPal, and follows it on an order page that says "Watching your promise." If it breaks, the page flips to the refund, with a note explaining why, and the money is already back in their PayPal account.
  • The merchant's ledger (AG Grid) is the operations view: every order with its latest evidence, the decision, the payout and the PayPal refund id, buckets for what needs attention (held payouts, refunds needing a human), and a budget meter for the month.

Why it matters for PayPal

Kept is built on PayPal from end to end: the purchase, the shipment and the payout all run against the same PayPal capture. That gives PayPal and its merchants six things.

  • Disputes settled before they're opened. A late parcel is exactly what turns into an Item Not Received dispute. Kept refunds the agreed amount, with a note citing the scan, before the buyer would think to complain. A buyer who already has their money and an explanation has little reason to open a dispute. That saves the merchant a fight, the buyer a wait, and PayPal a case to review.
  • Guarantees that can't be gamed. A refund is triggered by evidence, never by a buyer's claim, so there's no "it was late" to argue about and nothing to fake. The merchant sets the condition, the amount and a monthly cap up front, and when the scans point at the buyer ("no one available to sign") the refund is paused for the merchant to decide. Small and mid-sized merchants can offer a generous promise without opening themselves to refund abuse, and PayPal sees fewer contested refunds.
  • Tracking on every order, automatically. Kept attaches the tracking number to the capture through the Orders v2 tracking API on every shipped order. PayPal uses valid tracking when it assesses Seller Protection and when it can release held payments sooner, subject to PayPal's own eligibility rules. Small merchants, who are the most likely to skip this step, get it without thinking about it.
  • A reason to choose PayPal at checkout. The guarantee is shown at checkout, frozen into the order, and paid back to the buyer's PayPal account with PayPal's own note_to_payer. The buyer sees PayPal keep the shop's promise.
  • A merchant feature PayPal could offer natively. Amazon-grade delivery promises usually need an ops team. Kept gives them to small and mid-sized merchants, PayPal's core merchants, as a few sentences of plain English, with a monthly budget so exposure is always capped. It could ship as a "Promises" option on any PayPal checkout.
  • Promises an AI shopping agent can read. Each promise is a typed, machine-checkable rule, not marketing copy. In agentic commerce a buying agent can compare guarantees across shops and trust that PayPal will enforce them, which makes PayPal the settlement layer for agent-made promises.

What the demo proves is the whole mechanism: a broken promise is detected from evidence and refunded through PayPal before the buyer would open a dispute. We haven't measured an effect on dispute rates; the expected impact is fewer avoidable disputes and support emails, less room for refund abuse, and a guarantee small and mid-sized merchants could not otherwise afford to run.

What's real and what's simulated in the demo: PayPal (sandbox orders, capture, tracking and refunds), the Claude calls and the Open-Meteo weather, forecast and history are all real. The carrier (KeptPost) and its scans are simulated, and a demo clock lets us jump to Friday instead of waiting. Simulated evidence is labelled as such in the app.

How we built it

  • PayPal (sandbox):
    • Orders v2 for create and capture (item and shipping breakdown).
    • Payments v2 for partial refunds, with idempotency keys and note_to_payer.
    • Orders v2 tracking, to attach shipments to the capture.
    • The JS SDK Buttons for checkout.
  • AI:
    • The Kept agent runs on Claude Haiku 4.5 (claude-haiku-4-5-20251001), which keeps a public demo cheap and fast; KEPT_MODEL switches to a larger Claude model. Using structured outputs validated by Zod, it compiles promises into a small, typed rule language.
    • It suggests promises from a context code assembles: US holidays, season, local time, the Open-Meteo 7-day forecast, and percentiles from five years of same-week weather history, so it picks thresholds a small shop can afford. Each idea is then compiled and priced by server/pricing.ts, never by the model.
    • The agent reviews breached delivery promises against the carrier scans (seller_side, buyer_caused or unclear) and can only hold a payout for the merchant. If it fails or times out, the default is to pay.
    • The agent also writes the buyer refund note, with a deterministic fallback so a refund is never blocked by the model.
  • Watcher: a deterministic loop on a clock the demo can move forward (so we can "jump to Friday"). Real weather comes from Open-Meteo, and a simulated carrier feeds tracking events.
  • Stack: TypeScript, Hono, Node's built-in SQLite, React and Vite.
  • AG Grid (sponsor tool): the merchant ledger is AG Grid Community with the Quartz theme. Rows are keyed with getRowId, so each watcher tick updates them in place, and changed cells flash the moment an order is refunded. It has custom cell renderers for the promise badge, status, evidence, payout and PayPal refund id; status buckets (Watching, Kept, Held, Refunded, Needs a human) built on the external filter; quick search and column filters; a pinned totals row; and CSV export.
  • Render (sponsor tool): the live demo at https://kept-jhjl.onrender.com runs on Render as one Node web service: the API, the React app and the watcher loop. render.yaml describes it as a Blueprint.

Trust by design

  • The AI never sets or starts a payout. It writes the rule and the explanation, and can only pause a delivery payout for the merchant. Code evaluates the rule and computes the amount.
  • Refunds follow evidence, never a claim. The buyer never has to ask, and can't talk a refund out of the system.
  • Every rule needs approval from a human merchant.
  • The buyer gets the promise they saw. It's frozen at purchase.
  • Payouts are capped at the captured amount and at the merchant's monthly guarantee budget.
  • Refunds are idempotent, keyed on the order id, so a retry can never pay twice.

Challenges we ran into

  • Making "Friday" mean something. "Arrives by Friday" has to become an exact moment: 23:59:59 on the first Friday after purchase, in the shop's timezone, correct across the DST change. We did this with Intl alone, no date libraries, and test it against the November clock change.
  • Letting an LLM near money without letting it decide money. Asking a model "was this promise broken, and how much do we owe?" is the obvious design, and we decided against it from day one: it can't be audited, and it can't be guaranteed to stay under a cap. The Kept agent only compiles the promise into a small typed rule language (a discriminated union that structured output constrains) and explains the outcome. Evaluation and payout are plain code. If the model is down, the refund still goes out with a template note.
  • Suggestions that are fun but still honest. Left alone, the agent proposed a "below 6 °C at sunset" promise that history says would pay out on 77% of days: a discount, not a guarantee. We now give it the weather history as percentiles and price every idea in code, so the merchant sees the real cost before approving. We also ruled out payouts tied to chance unrelated to the purchase (no "snow on delivery day" refunds for a mug): that would be a bet, not a promise.
  • Running on a small model. We moved from Claude Opus to Claude Haiku 4.5 to keep the demo cheap. Haiku needed firmer guardrails: explicit good and bad examples in the prompts, real holiday dates and the order total in the compiler's context, five drafts with code keeping the three that compile and are affordable, and notes trimmed to whole sentences. Because code decides every dollar, a smaller model changes the wording, not the money.
  • Holiday promises needed a new kind of deadline. "Before Thanksgiving" isn't relative to purchase, so the rule language gained a fixed-date deadline with an order-by cutoff. After the cutoff the badge disappears and new orders aren't covered.
  • Demoing time. Nobody waits until Friday in a 3-minute video. Every piece of business logic reads a single simulated clock, so the demo can jump to Saturday while weather data and PayPal stay real.
  • Testing a checkout that needs a human. Wallet orders need buyer approval in a popup, so our end-to-end script uses the sandbox's direct card capture. That also gives judges a "pay with test card" button that needs no login.

Accomplishments that we're proud of

  • A real end-to-end loop on the PayPal sandbox: capture, tracking attached to the transaction, a broken promise detected from evidence, a partial refund, and a human-sounding note. Once the merchant has approved the promise, nothing needs a person unless the agent pauses a payout.
  • The compiler refuses to pretend: "You'll love it or your money back" comes back as can't be checked, with a rewrite that can be.
  • Every cent Kept moves comes with its evidence, in an AG Grid ledger the merchant can audit.

What we learned

Agentic commerce needs its boundaries spelled out more than it needs a smarter model. The interesting design work was deciding what the model must not do: pick amounts, approve payouts, or touch money without a cap. Where we do want judgment, reading a messy carrier scan, we gave the agent a one-way lever: it can stop money, never start it. The rest is plumbing that PayPal's APIs make straightforward.

What's next for Kept: promises that keep themselves

None of this is in the demo yet; it's where Kept could go from here.

  • Real carrier webhooks (e.g. Evri, Reply in the UK), adding more data sources such as flight-status and event-cancellation data.
  • PayPal's Agent Ready and Store Sync, so promises travel with products into AI shopping surfaces.
  • Abuse signals across orders, such as the same address repeatedly "not home", shown to the merchant. The agent would still only pause, never pay.
  • Promise analytics: how much a promise lifts conversion against what it costs in payouts, feeding real on-time rates back into the idea pricing.

Built With

  • ag-grid
  • anthropic-api
  • claude
  • hono
  • open-meteo
  • paypal-js-sdk
  • paypal-orders-api
  • paypal-payments-api
  • react
  • render
  • sqlite
  • typescript
Share this project:

Updates

Submission history