Backed by: @pithy-sh/payments. Scopes: payments:catalog:read · payments:purchases:read · payments:entitlements:read · payments:reconcile:read · payments:webhooks:read, and payments:entitlements:grant · payments:entitlements:revoke for its acts.
What it answers
Who pays and is locked out, and who is entitled and does not pay.
Every rail your Worker takes money through resolves to one entitlement key, so the join is one list rather than five. Purchases is what was paid, entitlements is what was granted, and reconciliation is the pass that repairs the gap between them.
The pane sits in the rail after Reconciliation, and only when your Worker composes payments. It reads six things from your Worker: the catalog, the purchase log, the entitlements, the overrides, the reconcile runs and the webhook events. Every answer is dropped with the screen, like every other pane.
It is also a question a report can name. There it reads the same six things, shows the counts beside the rows, and exports its answer as JSON. The rows still ask for Team, and nothing in a report acts: grant and revoke stay on the pane.
Three classes, worst first
| Class | Severity | What it ends in |
|---|---|---|
| Pays and is locked out: a paying purchase whose product’s keys the holder does not all hold | Critical | pithy payments reconcile --subject <type>:<id>, or grant the missing key |
| A notification that never became its purchase: a webhook event still pending, abandoned by a repair pass, matched to no holder, or naming a purchase your log does not hold | High, and Low when it matched no holder | pithy payments reconcile --rail <rail>, once per store, and a link to its purchase when the log holds one. One that matched no holder ends in advice instead |
| Entitled and does not pay: an entitlement whose purchase is refunded, revoked, expired, never paid, on hold, paused, or missing from your log, or which names no purchase at all | Medium | Revoke the key, and a link to its purchase |
Within a severity, rows rank by the amount at risk, then by how long the row has been wrong. A notification and an entitlement with no purchase risk an unknown sum, so they rank as zero. Every reconcile command carries --env for the environment on screen, and is narrowed to the one holder or the one store, never the whole pass.
Notifications of one cause are one row
One store, one variant and one error code make one row. It counts the notifications, gives the oldest and newest dates, and lists a count per event type, with every event id folded away below it. A report’s JSON export still holds each one. The row ranks by its oldest notification.
A store’s reconcile command is on one of its rows. Its other rows say that the same command retries them too, so you run it once, not once per row.
A notification that matched no holder ends in advice, not a command. Your store sends its whole event stream to your Worker, so most of these are customers your Worker never linked, and the reconcile sweep passes them on purpose. The row says what does fix one: link the holder at checkout so the next notification names them, or replay it from the store. On Paddle, linking means passing the subject in the checkout’s custom_data. Its row ranks Low, below every other class, so the rows where someone may be paying for nothing come first.
Every row names the last reconcile pass that saw it, or says that no pass has, and the store wherever it has one. A row of notifications names the pass that saw its newest. A row of notifications that matched no holder names none, because a pass skips them. Every entitled and does not pay row says what its entitlement rests on, so not paid is never a guess.
Deliberately unpaid is never a finding
- A manual grant or a comp-only key, one your catalog declares and no product sells.
- A holder with an override. Any override is one somebody set on purpose.
- A purchase in its grace period, a renewal still retrying.
- A holder on a tier’s defaults holds no entitlement row, so there is nothing to find.
An entitlement another paying purchase also covers is not a finding either.
The count on every plan, the rows on Team
The count of each class renders on every plan. The itemised rows are Team’s; below it, the pane says what Team buys, and that the same reads answer from your Worker’s API on any plan.
Grant and revoke are the entitlements pane’s acts, under the same scopes and the same roles, and anyone who may not act sees them locked. Where your Worker declares no revoke route, an entitled and does not pay row ends in the reconcile command instead.
When it cannot answer
It sends nothing it would be refused. When your Worker does not compose payments, declares no route the question reads, or this connection is not granted one of its scopes, the record names what is missing instead. Scopes is how to add one.
The catalog is read whole, and every other read asks for one page of 100 rows. When one of those is longer, the counts read at least, and the pane says the rows past the page were not checked. A row of notifications says its count is the page’s when the notification log is longer. A row that would be a finding only if an unread page held nothing is left out: telling you somebody is locked out when they are not would send you to grant twice.