Config options
Using Payments is the same ground with the code you write around it.
| Option | Default | Meaning |
|---|---|---|
billingSubject | none | user or organization. The one answer only you can give — it lands in a column and a unique index |
basePath | /payments | Where the routes mount, webhooks included |
entitlements | {} | Each key declared once: name, quotas, features, and an optional overrideMax. Every key a product grants must be declared here, and a declared key no product sells is comp-only |
defaults | none | The quotas and features a caller holding no key gets |
meters | {} | Which kit meters enforce their quota: emails, storageBytes, mediaItems. Advisory until named |
graceGrantsAccess | true | Whether a subscription in billing-retry grace still grants |
rails | — | Which rails are on |
products | — | The catalog. A product may carry a billing block to be billed by a reported quantity |
Two options ride on payments(...) beside the config, because a function does not survive the trip into config: resolveSubject, which answers who the caller acts for under organization billing, and resolveQuantity, which answers how many for a product billed by a reported quantity. A reported product with no resolveQuantity is refused at boot.
manualEntitlements is removed. A config still passing it is refused, with the declaration to write instead. Tiers, quotas and features and bill by a count you own have the shapes.
A rail that is on must declare its return URLs, and a return-URL block for a rail that is off is refused. Both checked at config rather than at the first checkout.
The rails
Standing any of them up is pithy payments; the overview is what the capability is for.
| Rail | Merchant of record |
|---|---|
apple | No |
google | No |
stripe | No |
lemonSqueezy | Yes |
paddle | Yes |
Nothing downstream of a rail’s own module branches on a store’s vocabulary. Every one arrives as a normalized rail-and-transaction-id pair, which is what lets one projection serve five stores.
The merchant-of-record difference is commercial rather than technical, and the only place it shows is that a refund can arrive with no local write preceding it — both issue them on their own.
The nine statuses
Each answers two questions independently.
| Status | Grants | Money arrived |
|---|---|---|
active | Yes | Yes |
in_grace | By policy | No |
on_hold | No | No |
canceled | Yes | Yes |
expired | No | Yes |
never_paid | No | No |
refunded | No | No |
revoked | No | No |
paused | No | Yes |
expired and never_paid are the pair to read twice. Both are over, neither grants, and they differ on the only question a balance cares about — reading a never-paid purchase as expired credits a coin pack for money that never arrived, with no clawback ever to follow.
Apple maps nothing to never_paid: no transaction is issued until the money moves.
in_grace carries a date, and the paid period’s end is not it — by the time a store says grace, the period has already ended. One rail reports the window separately and the later of the two is carried; reading the transaction alone would record a grace period and revoke the subscriber in the same commit.
paused carries a resume date — the instant the store said, never one computed here. Null means the store put no end on it, so paused until the 1st and paused indefinitely stay different sentences. A row that is not paused can never carry the field — a constraint enforces it.
Routes
| Route | Purpose | Verification |
|---|---|---|
POST /payments/purchases | Submit a receipt or signed transaction | bearer · session |
GET /payments/entitlements | The caller’s own resolved entitlements, quotas and features | bearer · session |
POST /payments/restore | Rebind store history to the caller | bearer · session |
GET /payments/pricing | What the caller’s subscription pays, and when it changes | bearer · session |
POST /payments/checkout | Create a checkout | bearer · session |
GET /payments/checkout/resume | Paddle only. What a page needs to open the transaction a _ptxn payment link arrived for | none |
POST /payments/portal | A billing-portal session for the caller’s own account | bearer · session |
GET /payments/subscription | Where the caller’s own subscription stands, read live from the store, with the last reported count for a product billed by quantity | bearer · session |
POST /payments/subscription/preview | What moving to one catalog product would cost | bearer · session |
POST /payments/subscription/change | Move the caller’s own subscription onto one catalog product | bearer · session |
POST /payments/subscription/cancel | Stop it renewing, today or at the end of the paid period | bearer · session |
POST /payments/subscription/keep | Withdraw a scheduled cancellation | bearer · session |
POST /payments/subscription/refund | Ask the store to refund the payments made on it | bearer · session |
POST /payments/webhooks/<rail> | One per rail | signed-webhook |
One public route, and it is the resume read. A buyer following a Paddle dunning mail is usually signed out, so GET /payments/checkout/resume takes no session. It discloses nothing: the client token is publishable, the display mode and success URL are config, and the transaction id is the caller’s own. It never asks Paddle whether that transaction exists. In hosted mode it refuses with payments/rail_not_configured. Every other caller is either an authenticated person acting for a subject, or a machine proving authenticity. Turnstile has nothing to gate here.
signed-webhook is one strategy over unrelated mechanisms — a signed payload against a pinned certificate chain, a token verified against published keys with an audience check, a keyed signature inside a timestamp tolerance. Each covers the exact received bytes, which is why these are literal paths per rail rather than one parameterized route: a single route line could not carry several verifiers, and the rail a caller claims is not something to route on.
Control-plane routes
| Route | Scope |
|---|---|
POST /payments/admin/discounts | payments:discounts:create |
GET /payments/admin/discounts | payments:discounts:read |
POST /payments/entitlements/grant | payments:entitlements:grant |
POST /payments/entitlements/revoke | payments:entitlements:revoke |
POST /payments/entitlements/overrides | payments:overrides:set |
POST /payments/entitlements/overrides/unrestricted | payments:overrides:unrestricted |
POST /payments/entitlements/overrides/clear | payments:overrides:clear |
GET /payments/admin/catalog | payments:catalog:read |
GET /payments/admin/purchases | payments:purchases:read |
GET /payments/admin/subscriptions | payments:subscriptions:read |
GET /payments/admin/entitlements | payments:entitlements:read |
GET /payments/admin/entitlements/:subjectType/:subjectId | payments:entitlements:read |
GET /payments/admin/overrides | payments:entitlements:read |
GET /payments/admin/usage-runs | payments:usage:read |
GET /payments/admin/webhook-events | payments:webhooks:read |
GET /payments/admin/reconcile-runs | payments:reconcile:read |
POST /payments/admin/reconcile-runs | payments:reconcile:run |
The purchase log and the reconciliation log narrow on the server. GET /payments/admin/purchases takes the subject, rail, status, environment and type: recurring for a subscription, one_time for a consumable or a non-consumable. GET /payments/admin/reconcile-runs takes rail, environment and outcome: failed when a store refused to answer for at least one purchase, drifted when none failed and at least one was repaired, clean for neither. A pass that drifted and failed reads failed. Both page on the cursor they already had, and a value outside those is refused rather than ignored.
payments:overrides:unrestricted is its own scope because it is the largest grant the kit has: every quota unlimited and every feature on, for every name declared now or later. A credential that may raise one customer’s email cap cannot, by that fact, hand anybody the whole product.
GET /payments/admin/webhook-events is the read that explains the others. Every notification a store sent, newest received first, filtered by rail, state and a since/until window. Each reads as projected, pending with its attempts, or abandoned, so a notification that arrived and never projected shows up as exactly that rather than going missing. A projected one names the purchase and subscription rows it changed as targets; one projected before the Worker recorded them reads targets: null, which means unrecorded, not changed nothing. The payload never crosses, and a stored error crosses as its code alone. It is its own scope because the log is a record of every customer’s commerce as the stores reported it.
The package README’s route table is held to every route this capability registers by a test, which parses it and compares it against the real registrations in both directions. These tables follow that one.
That gate exists because the management reads shipped without rows for long enough that the next person to add one withheld theirs too: a table missing several peers reads as complete, so one more row would have read as a lie.
Tables
pithy_payments_purchases · pithy_payments_entitlements · pithy_payments_provider_accounts · pithy_payments_webhook_events · pithy_payments_reconcile_runs · pithy_payments_sync_cursors · pithy_payments_overrides · pithy_payments_meter_counters · pithy_payments_usage_reports · pithy_payments_usage_runs
pithy_payments_purchases also carries quantity: how many were bought, as the store states it, or null where it does not say.
Bindings
| Binding | Type | Written by |
|---|---|---|
DB | d1 | pithy add |
PAYMENTS_RECONCILE | workflow, optional | pithy payments provision |
PAYMENTS_USAGE | workflow, only for a product billed by a reported quantity | You, with the class exported from your own entry |
The Workflow binding is optional. An unprovisioned project still verifies receipts, accepts webhooks and resolves entitlements — it simply has no nightly pass.
Secrets
One: payments-provider-credentials, with a block per rail.
A rail’s block is present in full or absent entirely, checked before the write lands — so half a credential is a refusal in your terminal rather than a signature check that silently never passes.
Rotation is manual for all of them, because none of the five returns a replacement over an API.
Sandbox isolation
Every purchase carries its store environment, and a mismatch is refused outright.
The environment is an input from this deployment’s own variable and is never inferred from the payload — inferring it from what the store said is exactly the hole.
Only a Worker deployed to production is production. The asymmetry is deliberate: treating production as sandbox loses a purchase reconciliation repairs; the other way round hands out entitlements for test transactions.
Peer capabilities
Required: secrets.
Optional: auth (strongly implied — every route but the Paddle resume read denies without it), controlplane, ledger.