Prepaid credit operational flows

This reference covers the common workflows for managing prepaid credits.

Use promotional credits when you want to add value without a payment workflow.

Common use case include:

• Giving a new customer onboarding credit.
• Compensating a customer.
• Migrating an existing balance from another system.
• Manually granting trial credit.

The flow looks like this:

flowchart LR
    A["Create credit grant\n(promotional)"] --> B["Set amount, currency,\npriority, expiration"]
    B --> C["Credit available\nimmediately"]
    C --> D["Confirm: read\ncustomer balance"]
    D --> E["Verify: funded\nmovement in history"]

1. Create a credit grant for the customer with the promotional funding method.
2. Set the amount, currency, priority, and optional expiration date.
3. Read the customer’s balance to confirm the credit was added.
4. List transaction history to see the funded movement.

Promotional credits are usable as soon as the grant takes effect, which is immediately unless you set a future effective time.

Use invoice-funded credits when the customer buys credits through Metering & Billing billing.

The flow looks like this:

flowchart LR
    A["Create credit grant\n(invoice)"] --> B["Set credit amount,\npurchase terms"]
    B --> C["Credits available\nwhen the grant takes effect"]
    C --> D["Invoice lifecycle:\nauthorize & settle payment"]
    C --> E["Show customer\ngrant & balance"]

1. Create a credit grant for the customer with the invoice funding method.
2. Set the granted credit amount and currency.
3. Set purchase terms, including the purchase currency and cost basis.
4. Let the invoice lifecycle handle payment authorization and settlement.
5. Show the customer their credit grant and credit balance.

The credits are available as soon as the grant takes effect, without waiting for the invoice to be paid.

The credit amount and the invoice amount are different values. A customer might receive 1,000 credits but pay a negotiated amount based on the cost basis.

Use externally funded credits when the credits are paid for outside Metering & Billing, for example by wire transfer, an external invoice, or manual reconciliation.

The flow looks like this:

flowchart LR
    A["Create credit grant\n(external funding)"] --> B["Set purchase terms"]
    B --> C["External system:\nhandles invoice & payment"]
    C --> D["Update external\nsettlement state"]
    D --> E["Confirm via\nbalance & history"]

1. Create a credit grant for the customer with the external funding method.
2. Set purchase terms.
3. Update the external settlement state as your external system changes, by setting the grant’s external settlement status to pending, authorized, or settled.
4. Use balance and history to confirm credit availability and movement.

This flow is useful when Metering & Billing tracks the credit balance, but your own invoicing system handles the commercial invoice and payment.

Use balance reads when you need to show credit availability or decide whether a customer can continue using a credit-backed feature.

The flow looks like this:

flowchart LR
    A["Resolve customer"] --> B["Query credit balance"]
    B --> C{"Currency-specific?"}
    C -->|Yes| D["Filter by currency"]
    C -->|No| E["Use full balance"]
    D & E --> R["Balance response"]
    R --> F["Settled balance:\ncommitted value"]
    R --> G["Live balance:\nconservative value"]
    R --> H["Pending balance:\ncredits not yet in effect"]

1. Resolve the customer.
2. Query the customer’s credit balance.
3. If the product surface is currency-specific, then filter by currency
4. Use the settled balance for committed historical value.
5. Use the live balance for conservative operational decisions.
6. Use the pending balance to show granted credits that haven’t taken effect yet.

The live balance can differ from the settled balance because open charges may still consume credits. See Credit balance model for details.

Credit consumption happens through billing charges and the settlement mode of the customer’s subscription.

The flow looks like this:

flowchart LR
    A["Configure plan\nwith credit settlement mode"] --> B["Charge is created\nfor customer"]
    B --> C{"Settlement mode"}
    C -->|credit_only| D["Credits settle the full charge;\na shortfall makes the\nbalance negative"]
    C -->|credit_then_invoice| E["Credits reduce\ninvoiced amount"]
    D & E --> F["consumed movement\nin transaction history"]
    F --> G["Updated balance\nreflects remaining credits"]

1. Set the credit settlement mode on the plan, or override it when you create the customer’s subscription.
2. Create or run charges for the customer.
3. Metering & Billing applies credits according to the settlement mode.
4. Read transaction history to inspect consumed credits.
5. Read balance to inspect the remaining customer credit.

For credit_then_invoice, credits reduce the invoiced amount. For credit_only, credits are the sole settlement mechanism for the charge. If the balance can’t cover a credit_only charge, the balance goes negative and the next credits the customer receives repay it first.

Use transaction history when a customer or operator asks why a balance changed.

The flow looks like this:

flowchart LR
    A["List credit transactions\nfor customer"] --> B["Apply filters:\ncurrency, movement type"]
    B --> C["Display each movement:\nsigned amount, balance before/after"]
    C --> D{"More history?"}
    D -->|Yes| E["Use pagination\ncursor"]
    E --> C
    D -->|No| F["Done"]

1. List credit transactions for the customer.
2. Filter by currency when needed.
3. Filter by movement type when investigating a specific change.
4. Display signed amount and balance before and after each movement.
5. Use pagination cursors to move through older or newer history.

Good support tooling shows transaction history next to grants and charges:

• The history explains balance movement
• Grants explain where credit came from
• Charges explain why credit was consumed

See Credit transaction history for field definitions and pagination.