Billing & usage

Amounts and pricing

The ledger uses integer microusd: 1 USD = 1,000,000 microusd. Avoid floating-point currency arithmetic. The pricing implementation adds a 20% markup to the configured upstream cost and rounds up to whole microusd.

upstream cost:       1_000_000 microusd ($1.00)
with 20% markup:     1_200_000 microusd ($1.20)
difference:            200_000 microusd ($0.20)

The difference is 16.7% of the sale price before other costs. Markup is not gross margin. Product subscriptions and credit allowances follow the configured catalog, which may scope credit by product and expiry.

Reserve, dispatch, reconcile

1. Reserve. The gateway checks authorization, idempotency, the route, and available funds before dispatching paid work.
2. Dispatch. The provider may accept the work even if the client disconnects later.
3. Reconcile. Usage settles the reservation; unused reserved value can be released. Missing usage requires conservative reconciliation. On the inference path, the gateway caps the user charge and records upstream costs above the cap as provider-absorbed cost.

The SDK defaults to a reservation when one is not supplied. Set an explicit amount appropriate to the user’s action instead of treating a library default as a product spending policy.

Idempotency and retries

Create one idempotency key per logical metered action and retain it across retries of that same action. Generate a new DPoP proof for every HTTP attempt. A reused proof is a replay, even when the operation’s idempotency key is unchanged.

Do not automatically resubmit a paid action after an ambiguous timeout with a new key. First determine whether it was accepted or completed. Aborting a stream does not guarantee a zero charge.

Create a checkout

Use a token with billing:checkout. Supply a configured stable plan_id or pack_id, an HTTPS return_url, and an idempotency key. The gateway maps catalog IDs to allowlisted Paddle prices on the server.

const checkout = await client.billing.createPackCheckout(
  configuredPackId,
  "https://client.example/billing/return",
  { idempotencyKey: checkoutAttemptId },
);
// Navigate only after receiving a successful response with checkout.url.

Pack IDs are obtained from the approved product catalog, not invented in the client. A missing mapping can produce missing_billing_product; a configured price without a payment API key produces checkout_unavailable.

The response contains id, url, and provider: "paddle". The integration retains return_url as transaction metadata; it does not establish an automatic Paddle redirect to that URL.

Verify payment before granting credit

A success page is not evidence of a paid transaction. The server must verify the signed provider notification, validate the product and event, and issue the entitlement or credit once. The repository’s Paddle webhook handling lives in convex/http.ts at /webhooks/paddle; configure the actual Convex HTTP endpoint as the notification destination.

Paddle checkout URLs need the configured payment-link domain and a correctly initialized Paddle.js checkout page. Returning a transaction URL alone does not prove that the browser payment flow works.

Before enabling real purchases, verify checkout, payment, signed webhook, entitlement, credit, metered debit, reconciliation, and refund in the appropriate test environment. This documentation does not claim that chain is currently proven in production.