Shipday is pre-order checkout for small makers that charges a buyer only when their unit is about to ship, and gives the money back on its own when freight slips. This is the calendar of one real campaign on the PayPal sandbox: a board game called Tidewater, $49.00 a copy, ship date December 3, with a 30 day charge window. Every id below was read back from PayPal itself.
Try it
Day 0: the reservation
A buyer lands on the Tidewater page. The page makes one promise in large type: you are charged only when your unit is ready to ship. There is a date, December 3, and a single button.
The buyer saves a card with PayPal. Behind that button, Shipday creates a PayPal Vault setup token (3WE674246S470514S, APPROVED), exchanges it for a reusable payment token (3cl44512ff145213d, a Visa ending 1111), and reads that token back from PayPal before it writes anything. Only then does the reservation (8d3e0258-904e-4d45-87b2-69bbb1150984) become RESERVED.
No order exists. No capture exists. The buyer has paid nothing, and PayPal holds a card that Shipday can charge later on the buyer's behalf. If the buyer changes their mind before the charge, cancelling deletes the saved token on PayPal.
The buyer page. One date, one promise, one PayPal button, and no charge today.
This is the shift Shipday is built on. A normal pre-order turns "pay now, wait months" into a support queue. Vault turns it into "save now, pay on ship day", and the rest of the product exists to decide which day that is.
The freight email
A week later the merchant's forwarder writes. It is the kind of email every small maker gets: a booking confirmation buried in a signature block, a vessel name, a port pair, a departure date.
The merchant pastes it into Shipday's "Update from a supplier" box (a PDF or a photo of a packing list or bill of lading works too). An AI model, google/gemini-2.5-flash through OpenRouter at temperature 0, reads it into structured fields: 480 units, departed November 12, Yantian to Long Beach, vessel MSC ARIANE. Every field is printed next to the exact sentence of the email it came from, and Shipday checks that quote against the source before it shows anything. A field without a matching quote is rejected and the read is retried.
The merchant confirms. That confirmation, not the model, creates Wave 1 (c63817c1-3a75-4b6f-a1f6-36a215825bb4): 480 units, shipping December 3.
Wave 1 appears on a Bryntum Gantt, which is the merchant's main screen. The wave expands into its milestones: production, freight, warehouse, the charge window, and the ship date, each a bar, chained by dependencies. A deterministic planner allocates confirmed units to reservations in the order they arrived and builds the waves. The plan explains itself in plain English from the confirmed milestones, so the merchant reads why a wave sits where it does.
The merchant desk. The orange bar is the charge window; the Charge button only lights inside it.
Ship day minus 30: the window opens
The charge window opens 30 days before the ship date. Until then, the Charge button for Wave 1 is disabled and says why. Inside the window, it reads "Charge Wave 1" with the number of reservations it will charge.
The merchant presses it. For each reservation, Shipday creates a merchant-initiated PayPal order against the saved payment token, captures it, and reads it back:
- Order
1BF263347V690202F: COMPLETED, payment source card - Capture
1JU59747UW5095009: COMPLETED, $49.00
The buyer's status page flips from "Reserved" to "Charged", with the PayPal capture id as the receipt.
Then the merchant presses Charge again, the way a tired person double clicks. Shipday refuses: "This reservation has already been charged." The button now shows 0 reservations and disables itself. PayPal still shows exactly one capture on the order. A unique constraint on the reservation, a persisted PayPal-Request-Id on every charge, and a pure refusal function close every path to a second charge: a double click, a retry after a timeout, a webhook landing mid-request. We proved that guard bites by removing it, watching the idempotency test go red, and restoring it.
The ship date slips
Freight is freight. The vessel rolls, and the warehouse date moves. The merchant drags Wave 1's ship bar on the Gantt from December 3 to December 20.
That drag runs the same server planner that gates charging, so the screen and the money rules never disagree. The planner sees the problem at once: the buyer was charged on a promise that their unit ships within 30 days, and now it ships 38 days after the charge. The wave card turns red and reads "1 charged order ships 38 days after the charge. That is past the 30 day window." The Gantt row reads "Charged too early: refund due".
This is the moment most pre-order tools stop paying attention. The money is in, the promise is broken, and the buyer finds out from a forum thread. PayPal's own Seller Protection guidance asks pre-order sellers to ship within the timeframe they stated. Shipday keeps that promise mechanically.
The merchant clicks "Refund 1 and hold for Dec 20":
- Refund
6WH63857EB372964X: COMPLETED, $49.00 - Capture
1JU59747UW5095009: now REFUNDED
The buyer is not cancelled. The reservation goes back to RESERVED on the same saved card token. Their place in the plan holds. Their status page reads "Refunded. Still reserved." with the PayPal refund id and the reason.
With Auto-protect switched on, Shipday does this refund on its own. It shows who is affected and the old and new dates, then holds for 60 seconds so an accidental drag can be undone with nothing sent to PayPal. After the hold, it refunds each late capture, reads each refund back COMPLETED, and puts each buyer back to RESERVED. The ledger records whether Auto-protect or the merchant settled each refund, so every automatic money movement is deliberate and traceable. A refund in flight blocks both tracking and a second charge until PayPal reports it complete.
The date comes back
The forwarder finds space on an earlier sailing. The merchant moves Wave 1 back to December 3. The charge window is open again, and the same buyer, on the same saved card, is charged again with no action from them:
- Order
3AC87679JC481620R: COMPLETED, payment source card - Capture
21W073348X096610A: COMPLETED, $49.00
Money followed the ship date out, and money followed it back in. The buyer never re-entered a card and never chased a refund.
The buyer's status page tracks the unit through the plan and shows each PayPal receipt as it happens.
Ship day
The 3PL sends a dispatch confirmation: three parcels, three order references, carriers and tracking numbers in a table that was clearly pasted from a spreadsheet.
The merchant pastes it into "Read dispatch confirmation". The AI lists every parcel with its order reference, recipient, carrier and tracking number, and each tracking number must appear verbatim in the email. Shipday matches parcels to charged reservations with deterministic code: it matches Order #1 to UPS 1Z999AA10123456784 with its quoted line, and leaves the two parcels that belong to no charged reservation unmatched rather than guessing.
For the match, Shipday posts the tracker to the PayPal order and reads it back. PayPal order 3AC87679JC481620R now carries exactly one tracker, 21W073348X096610A-1Z999AA10123456784, status SHIPPED. The reservation reads SHIPPED, with its capture id and the earlier refund id kept on the record.
The buyer paid on ship day, was refunded when ship day moved, was charged again when it came back, and can see the parcel's tracking inside PayPal.
Under the hood
PayPal, all in src/paypal.ts:
| Call | What it does in Shipday |
|---|---|
POST /v3/vault/setup-tokens |
Saves the buyer's card or PayPal at reservation, no charge |
POST /v3/vault/payment-tokens, GET |
Exchanges the approved setup token, reads it back before RESERVED |
DELETE /v3/vault/payment-tokens/{id} |
Buyer cancels before the charge |
POST /v2/checkout/orders, /capture, GET |
Merchant-initiated charge on the saved token, read back COMPLETED |
POST /v2/payments/captures/{id}/refund, GET /v2/payments/refunds/{id} |
Refunds a charge whose wave slipped, read back COMPLETED |
POST /v2/checkout/orders/{id}/track |
Posts tracking for each shipped parcel |
POST /v1/notifications/verify-webhook-signature |
Verifies PayPal webhooks before reconciling |
Every mutation carries a persisted PayPal-Request-Id and reads back its resulting state before Shipday changes its own.
AI reads, code decides. The model reads freight emails, PDFs, photos and dispatch confirmations into Zod-validated fields, each tied to a verbatim quote, and writes plan explanations from confirmed milestones only. Allocation, wave dates, charge eligibility, the Auto-protect refund rule, parcel matching and the double-charge guard are deterministic code with unit tests. A misread date never moves money, because only merchant-confirmed milestones reach the planner.
Bryntum Gantt is the product, not a picture. Dragging a bar calls the same server planner that gates charging. Bryntum loads only on merchant routes, so the buyer page stays light.
Stack: TypeScript on Node 24, Hono, SQLite, React 19, Bryntum Gantt for React, Vite, Vitest, Zod, live updates over Server-Sent Events, deployed on Fly.io with a persistent volume.
Proof, read back from PayPal
One full campaign loop on the PayPal sandbox, every status read from the PayPal REST API:
- Vault setup token
3WE674246S470514SAPPROVED, payment token3cl44512ff145213d(Visa 1111), reservation RESERVED, nothing charged. - Freight email read into Wave 1: 480 units, Yantian to Long Beach, MSC ARIANE, ship December 3.
- Charge: order
1BF263347V690202FCOMPLETED, capture1JU59747UW5095009COMPLETED, $49.00. - Second charge refused; PayPal still shows one capture.
- Ship date moved to December 20: refund
6WH63857EB372964XCOMPLETED, capture REFUNDED, buyer back to RESERVED on the same token. - Ship date back to December 3: order
3AC87679JC481620RCOMPLETED, capture21W073348X096610ACOMPLETED, same token. - Dispatch email read: UPS tracker
21W073348X096610A-1Z999AA10123456784SHIPPED on the PayPal order.
A pre-order that costs the buyer nothing until their unit ships, and refunds itself when the calendar breaks the promise.
Built With
- bryntum-gantt
- fly.io
- gemini
- hono
- node.js
- openrouter
- paypal-orders-api
- paypal-vault-api
- paypal-webhooks
- react
- server-sent-events
- sqlite
- typescript
- vite
- vitest
- zod