Inspiration

Shopping assistants answer a sentence with a ranked list. The list says which product came third, and nothing about why: whether it failed one of your requirements, or whether its listing simply never mentioned it. Those are different answers. A product that fails is out; a product whose listing is silent is worth one click to check. Errand is built around keeping the two apart, for every product and every requirement, on one screen.

What it does

You type one sentence. Errand turns it into requirements, searches, and comes back with a grid where every product carries a mark against every requirement.

The plan. "a sealed One Piece Card Game booster box in English, not a Japanese print" becomes three requirements: sealed, English edition, not a Japanese print. Put a price in the sentence and it is handled differently: a ceiling goes into the search as price.max_price rather than becoming a column, and the screen prints what it did, under $150.00, as a filter, not a column. A number the index can filter on is already settled, so grading products against it would be theatre.

The ledger. One AG Grid column per requirement, three marks: holds, fails, or the index does not say. A row pinned at the top reads each column downwards (how many rows hold that requirement, as a count and a bar) and is rebuilt from whatever rows survive the filters, so it always describes what is on screen. In the demo run, 2 of 24 boxes hold all three, and the other 22 each show which mark they lost and why. The model never writes a row of its own. It judges only products Channel3 returned, and a verdict carrying a product id that was not in that set is dropped before the grid sees it (server/src/ai/shopper.ts). A row the model never read shows empty marks instead of a zero.

The link out. The retailer's name under each product title is the link to that listing, and Errand earns a commission there if you buy. It never buys on a shop's site for you: the purchase stays with the person.

What PayPal pays for. The search. A free errand reads one page of the index (24 products; 5 free errands a day per device, 25 per address). A $3.00 pass reads three pages on every run, 55 products in the demo, fifteen times. Whatever you do not spend comes back pro rata: nine runs left is $1.80 refunded.

How it uses PayPal

Every price lives on the server. /api/pass/order accepts no amount from the browser: the only thing on sale is the pass, and the server sets its price.

  • Orders v2. POST /v2/checkout/orders with user_action: PAY_NOW, shipping_preference: NO_SHIPPING (a pass has nothing to ship), brand_name: Errand and locale: en-US, plus invoice_id, custom_id and a 22-character soft_descriptor so the pass can be reconciled from a bank line. POST /v2/checkout/orders/{id}/capture carries a PayPal-Request-Id supplied by the caller, so a retried capture cannot charge twice.
  • Webhooks, signature-verified. Every notification goes through POST /v1/notifications/verify-webhook-signature, and anything that fails verification is refused rather than logged and trusted. CHECKOUT.ORDER.APPROVED captures and grants the pass whether or not your tab is still open; PAYMENT.CAPTURE.COMPLETED grants it idempotently; PAYMENT.CAPTURE.REFUNDED and REVERSED void it. On a refund event resource.id is the refund's id, so the capture is read from supplementary_data.related_ids.capture_id and the up link (server/src/paypal/webhooks.ts).
  • Payments v2. POST /v2/payments/captures/{id}/refund for the unspent runs, to the cent.
  • Orders v2, read back on screen. "Check with PayPal" calls GET /v2/checkout/orders/{id} and prints what PayPal says, to the buyer: COMPLETED · 3.00 USD · capture 8DM85911KH3134848 (COMPLETED) · invoice pass-…. The app's own store is never the authority on whether you paid.

Sandbox throughout. The demo video is a real sandbox buyer logging in and paying, and no real funds move.

How I built it

TypeScript end to end: Node and Express 5 on the server, React + Vite + AG Grid Community 36 on the client, pnpm workspace, deployed on Render.

  • Channel3 POST /v1/search with limit 24 and page_token paging for paid runs (the API caps a page at 30). description (400 characters), materials, the structured attributes, key features, variants and the photo's colours all go into the ranking input, because "the index does not say" has to mean the index, not the fields I happened to forward. Channel3 returns colours as hex swatches with coverage, so they are named by rule first (navy 62%, server/src/channel3/colours.ts); a model is not asked to read hex.
  • OpenAI gpt-4.1: one call turns the sentence into requirements and a search, then one call per batch of 24 products (one batch on a free errand, three on a paid one) to rule on each requirement and quote what the index entry said. A meter prices every call from the API's usage and refuses calls once the day's ERRAND_AI_SPEND_USD is spent (per UTC day, $3.00 by default).
  • Limits for a public URL with no login: 5 free errands a day per device and 25 per address, 90 free errands an hour across everyone, the daily model-spend ceiling above, and a Channel3 rate limit is shown as an error, never as an empty grid. A paid errand is bounded by the runs left on its pass.
  • AG Grid Community 36: requirement columns generated from the plan under a column group, custom cell renderers for the marks, tooltips quoting the index, the pinned tally row rebuilt on modelUpdated, an external filter behind the figure band, quick filter, column filters and CSV export.
  • 83 unit tests (pnpm test), MIT.

Challenges I ran into

Filming found three bugs the tests did not. Recording the payment leg end to end meant a sandbox buyer actually paying, and the camera caught things the suite could not: a refund asked for while an errand was still running paid back a run that was then delivered (the pass was spent after the work, so used still read 0, and PR #35 moves the charge to the gate and releases it if the errand throws); a refund raised in the PayPal dashboard was logged action: "ignored" because the pass was looked up by the refund's id; and a refund response without an amount left the screen saying a refund had happened without saying how much.

The checkout page is part of the product. The first take rendered in Vietnamese, showed the sandbox account name "Test Store" as the merchant, and asked for a shipping address for a digital pass. brand_name, locale and NO_SHIPPING fixed all three. I would never have found any of them from the API reference alone.

Making the agent say no. Early runs marked almost everything "the index does not say", which is a safe answer and a useless one. Passing the fields Channel3 actually returns, and asking for the sentence the index entry said instead of a yes or no, is what turned the grid into something worth reading.

Accomplishments I'm proud of

The read-back. Most hackathon checkouts end at "thanks, your order is complete", with the app's own state as the only witness. Errand asks PayPal and prints the answer, capture id and invoice included, next to the pass it granted. Under it, the same screen lists the signature-verified webhooks PayPal sent the server for that order, with the time and what the server did, so the capture can be seen not to depend on the browser coming back.

The refusals are visible too. "0 of 24 hold your requirements" is a result Errand is willing to show, and the headline and the counts are written for that case as much as for the happy one.

What I learned

An honest unknown is a feature, and it has to be earned in the data layer before it can be printed on screen. A mark saying "the listing does not say" is a lie if the code never passed the listing to the model.

Idempotency is cheap when you design for it and expensive afterwards. A capture with a caller-supplied PayPal-Request-Id, a grant keyed by order id, and a run reserved before the work rather than charged after it are all the same lesson.

What's next

Persisting passes and errands, which today live in memory and are lost on a restart. Channel3's price-tracking webhooks, so a shortlist can tell you when a listing moves. And if Channel3 opens its checkout API, which is documented as "not yet available", an agent that can place the order at the retailer, still behind an explicit approval.

Honest limits

  • Price and stock come from Channel3's index snapshot, not from the retailer's page at that second. The grid says so above the table, and the price column is headed "Price · as indexed".
  • Errand never buys at the retailer. Channel3's checkout API is documented as "not yet available" (checked 2026-11-04), and buying on a shop's site without a human is not something I want the agent doing anyway.
  • Passes and errands are in memory. A Render restart loses them (a pass is restored from PayPal on reload, but whole: the count of runs already used is lost), and on the free plan the instance sleeps after 15 idle minutes, so the first request after that waits for it to wake (21 s measured, up to a minute).
  • The model-spend ceiling is counted per UTC day in memory, so a restart within the day resets the count; the free-run limits still bound each device and address.
  • Sandbox only. Nothing has been tested against live PayPal, and PAYPAL_SANDBOX stays on.

Built With

Share this project:

Updates

Submission history