Paid top-ups use fixed catalog packages. A package snapshots its Credit System, credit amount, money amount, currency, and optional expiry.
Checkout creation never grants credits. Credits are granted when the top-up invoice is fully paid, by any route: a card or provider payment, a manual payment for the full amount, a payment request, or marking the invoice paid. A partial manual payment grants nothing until the invoice is fully paid. Nozle then durably records one payment signal for the purchase and materializes exactly one source and one originating grant operation. A reconciliation sweep repairs missed delivery for every paid top-up invoice without duplicating credits.
Expose available packages through your authenticated backend and start checkout from your own billing UI or a merchant callback. Refresh the product-credit balance only after the invoice is paid.
Customer pool and Entity allocation
A successful top-up creates a paid source at the customer level. It does not choose an Entity automatically.
Use the Entity allocation API to move paid value to an active Entity. Allocation preserves the parent purchase, payment provenance, priority, and expiry. Returning unused value moves it back to the same parent source.
Subscription grants cannot be allocated or returned: they already belong to the customer or Entity selected by the plan grant rule.
See Entity Credit Transfers for request examples.
The package’s money-to-credit exchange is different from a metric rate. $10 -> 250 AI credits defines a product package; 1 agent execution -> 2 AI credits defines usage cost.
Refunds and lost disputes
When the money for a paid top-up comes back, Nozle takes back the credits it bought, once:
- A credit note on a paid top-up invoice (refund or credit) takes back the credit note’s share of the top-up’s credits. A full credit note takes back the whole package; a credit note for 40% of the invoice total takes back 40% of the credits.
- A lost payment dispute on a paid top-up invoice (
POST /api/v1/invoices/{id}/lose_dispute, or a Stripe, Adyen or Razorpay chargeback) takes back every top-up credit that earlier credit notes did not. Repeating it takes nothing more.
- Credits the customer already spent stay spent. Nozle revokes only what is still remaining in the top-up’s source and never forces a source below zero.
- An unpaid top-up invoice was never granted, so a credit note on it takes nothing back.
The Engine applies the revocation within about a minute. It appears in credit operations as a revoke operation with the reason top_up_credit_note or top_up_dispute_lost. requested_credit_amount is what was asked to be taken back and credit_amount is what was revoked; the difference had already been spent. 