Skip to main content
POST
Import Opening Credit Balance
Call this Engine API after importing the externally billed subscription. It records the customer’s current spendable balance without charging them again. Base URL: https://api.nozle.app/api/v1 Auth: secret key with credit_system:write when API permissions are enabled. Publishable keys are rejected. Idempotency-Key is required.

Import a customer balance

For an Entity-scoped balance, include the exact Entity ID associated with the imported subscription. Copy external_subscription_id from the Core billing-state import response; do not substitute the request’s external_reference.
granted_amount must exactly match Nozle’s computed grant for the imported current period. This normally equals the plan grant-rule amount, but an Entity rule using prorated joining can produce a smaller current-period grant. remaining_amount must be between zero and the computed granted amount. Send amounts as decimal strings and use a dry run to validate the amount before importing.

Response

The import preserves both facts:
It does not create an invoice or publish a usage event. It also marks the current plan grant as already represented, preventing the scheduler from adding another 500 credits during cutover. If the plan grants more than one Credit System, import each one. Nozle freezes the applicable grant definitions when the billing state is imported, so later catalog edits cannot change the amounts required during an in-progress cutover. Automatic plan grants resume only after every balance from that frozen snapshot has been imported.

Dry run and retries

Set dry_run to true to validate the customer, subscription, Entity, Credit System, grant rule, period, and amounts without writing ledger state. Retry an uncertain response with the same idempotency key and identical payload. A replay returns the original imported values, even if the customer has consumed credits since the import. Reusing the key with a different request returns 409.
Do not run the merchant’s local credit deduction and Nozle .track() as simultaneous authorities. After the import is accepted, switch the gate cleanly: use .can() for the advisory check and .track() for the authoritative deduction.