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 immediately usable after they are created.

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["Invoice lifecycle:\nauthorize & settle payment"]
    C --> D["Credits available\nafter settlement"]
    D --> 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 per-unit cost.
4. Let the invoice lifecycle handle payment authorization and settlement.
5. Show the customer their credit grant and credit balance.

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 per-unit cost.

Use externally funded credits when invoicing and payment happen outside Metering & Billing through custom invoicing.

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.
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 --> F["Settled balance:\ncommitted value"]
    D & E --> G["Pending balance:\nconservative value"]
  

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 pending balance for conservative operational decisions.

The pending 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 rate card settlement modes.

The flow looks like this:

 
flowchart LR
    A["Configure rate card\nwith credit settlement mode"] --> B["Charge is created\nfor customer"]
    B --> C{"Settlement mode"}
    C -->|credit_only| D["Credits settle\nthe full charge"]
    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. Configure the relevant rate card with a credit settlement mode.
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.

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.