Skip to navigation
Wallets & credits

Credit types & wallets

Credit types define what a “credit” means in your system. Wallets hold a customer’s credit balance. You need both before you can grant credits through a pricing plan.

Credit types

A credit type is the unit of account for credits in your system. Before you can create a wallet or grant credits to a customer, you need at least one credit type defined.

Go to Product Catalog in the sidebar, then open Credits & Wallets and select the Credits tab. Click Add credit type.

Credits & Wallets page, credit types tab

Fill in the following fields:

FieldRequiredDescription
NameYesInternal label for this credit type (e.g. “Streaming credits”)
ReferenceYesUnique identifier
DescriptionNoOptional context for your team
Unit name singularNoHow a single credit appears in the UI (e.g. “Credit”)
Unit name pluralNoHow multiple credits appear in the UI (e.g. “Credits”)

Add credit type form

Click Save and activate to make the credit type available immediately, or Save as draft if you want to complete the configuration in a second moment.

Wallets

A wallet holds a customer’s balance for a given credit type. When credits are granted through a subscription, they are deposited into the matching wallet. When a customer consumes a usage-based product priced in credits, the balance is drawn down.

In Credits & Wallets, open the Wallets tab and click Add wallet.

Wallets tab, list view

Fill in the following fields:

FieldRequiredDescription
Wallet typeYesThe type of wallet. Select Credits for credit-based wallets
NameYesInternal label for this wallet
ReferenceYesUnique identifier
Grant typeYesHow the wallet is funded. Select Credits to fund with a credit type
Credit typeYesThe credit type this wallet holds

Create wallet form

A wallet is a template-level definition. The actual per-customer balance is tracked when a customer subscribes to a pricing plan that grants credits into this wallet.

Once a wallet exists, see Wallet top-ups for how credits get into it after the initial grant, including customer-driven purchases and automatic top-ups when the balance runs low.

Wallet types

A wallet holds either credits or money, set by the wallet type:

Wallet typeFunded withUse it for
CREDITA credit type, or a monetary amount converted into credits at a rateConsumption priced in credits (API calls, minutes, tokens)
BALANCEA monetary amount in a currencyPrepaid money that offsets invoiced charges

The wallet type is a template. Each customer who subscribes to a plan that grants into it gets their own wallet, and each grant into that wallet is tracked separately.

A CREDIT wallet type funded with an amount (credit.amount_grant) carries a tax_category and a default_currency. Both are the declared spending scope of the wallet type: money funded under one tax category must not become spendable under another. Once wallets exist for the wallet type, neither can be changed or removed; an attempt is rejected with a validation error on credit.amount_grant.tax_category or credit.amount_grant.default_currency. Changing either is still allowed on a wallet type that has no wallets yet.

POST
/v:version/wallets
curl -X POST https://test.api.solvimon.com/v1/wallets \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "reference": "brightline_prepaid_credits",
  "wallet_type_id": "wtyp_BwDeeN0vxxHxWOCkua1f",
  "customer_id": "cust_lwDeeN0vxxHxMWCVef1S",
  "status": "ACTIVE"
}'
Try it
Response
{
  "object_type": "string",
  "id": "string",
  "reference": "string",
  "status": "DRAFT",
  "wallet_type_id": "string",
  "wallet_type": {
    "object_type": "string",
    "id": "string",
    "name": "string",
    "reference": "string",
    "status": "DRAFT",
    "type": "CREDIT",
    "credit": {
      "grant_type": "CREDITS",
      "amount_grant": {
        "default_currency": "AED",
        "tax_category": "STANDARD"
      },
      "credits_grant": {
        "credit_type_id": "string"
      }
    },
    "balance": {
      "default_currency": "string"
    },
    "created_at": "string",
    "updated_at": "string"
  },
  "auto_top_up_configs": [
    {
      "object_type": "string",
      "id": "string",
      "wallet_id": "string",
      "status": "ACTIVE",
      "threshold": {
        "amount": {
          "quantity": "string",
          "currency": "AED"
        },
        "credits": {
          "quantity": "string",
          "credit_type_id": "string",
          "credit_type": {
            "object_type": "string",
            "id": "string",
            "reference": "string",
            "status": "DRAFT",
            "name": "string",
            "description": "string",
            "unit_name": {
              "singular": "string",
              "plural": "string"
            },
            "created_at": "string",
            "updated_at": "string"
          }
        }
      },
      "topup_amount": {
        "quantity": "string",
        "currency": "AED"
      },
      "pricing_plan_schedule_id": "string",
      "pricing_item_id": "string",
      "payment_method_id": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "customer_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

Wallets follow the standard resource lifecycle. A newly created wallet is in DRAFT until you activate it with POST /v{version}/wallets/{resourceIdOrReference}/activate, and can later be deactivated, deprecated, or archived.

An amount-denominated wallet pays for the invoice

A CREDIT wallet type funded with an amount holds money rather than credits, so it does not reduce a volume the way credits do. It reduces the charge. A funded wallet pays for the invoice lines it is allowed to pay for, and the customer is invoiced for the rest.

The wallet holds a net amount. Tax was already charged on the top-up that funded it: a top-up of 12.10 EUR including 21% VAT puts 10.00 EUR in the wallet. So the money comes off the net side of the line, and the covered part is not taxed a second time:

NetVATTotal
Line as priced30.006.3036.30
Covered from the wallet-10.000.00-10.00
Charged20.004.2024.20

Coverage is always split, never skipped. A balance that does not cover the whole line covers part of it, and the remainder is charged and taxed as normal. A wallet with nothing in it produces no wallet block on the line at all.

Which lines it may pay for. Only lines whose product tax category matches the wallet type’s credit.amount_grant.tax_category. That is what the tax category on the wallet type declares: money funded under one tax category must not become spendable under another. Lines outside it are untouched.

When it is applied. Last. The deduction runs after included volume, after credits, after discounts and after minimum commitment, on the net amount those leave behind, and therefore before tax is calculated.

The order matters in both directions. The wallet is the only reduction denominated in money, so anything applied after it would change the figure the wallet was measured against. And anything applied after tax would leave the deduction taxed.

A customer holding both kinds of wallet spends credits first. Credits reduce the volume being priced; the money wallet reduces what that pricing came to.

What each wallet paid. The charge reports one entry per wallet that paid, in wallet_balances:

One wallet's share of a charge
"wallet_balances": [
  {
    "wallet_id": "wall_5RmXe2QbtKfYuA9DcNH3P",
    "used_balance": { "amount": { "quantity": "10.00", "currency": "EUR" } },
    "left_balance": { "amount": { "quantity": "0.00", "currency": "EUR" } },
    "available_balance": { "amount": { "quantity": "10.00", "currency": "EUR" } }
  }
]

used_balance is what the charge took out, available_balance is what it could have drawn on, and left_balance is what remains of that for further usage in the same period. A wallet holding credits reports the same three fields with a credits value instead of an amount.

wallet_balance_details, with used_wallet_credits, left_wallet_credits and available_wallet_credits, is deprecated in favour of wallet_balances. It holds one wallet at a time, so a charge paid by a credits wallet and a money wallet reports the figures of whichever paid last, and it can only express credits. It keeps working for backwards compatibility.

Granting into the wallet. A grant has to be in the wallet’s own currency, since there is no conversion between one currency and another on the way in. A fixed grant in another currency is rejected with wallet type <reference> is denominated in EUR, but the grant is in USD. A grant that takes a percentage of pricing in another currency is rejected for the same reason, and the error names the two ways out: grant a fixed amount in the wallet’s currency, or grant into a wallet type denominated in the pricing currency.

A wallet type created before default_currency became mandatory has none. Nothing can be granted into it until it is given one.

Spend on an amount-denominated wallet books out at final

A CREDIT wallet type funded with an amount keeps its ledger in a currency. Usage covered by such a wallet is held as a reservation while the invoice is not yet final: the available balance already reflects the reservation, so a second invoice cannot spend the same money, but the money has not yet left the wallet.

When the invoice goes FINAL, the covered amount leaves the wallet, oldest-expiring grant first. Solvimon recognises it as revenue with no tax, because tax was already charged on the top-up that funded the balance.

Voiding or recalculating the invoice before it is final releases the reservation, and the balance becomes spendable again. Re-running a final invoice does not book the spend twice.

Read a wallet with its type and top-up rules

GET /v1/wallets and GET /v1/wallets/{id} accept expand[], which saves resolving a wallet’s denomination and its funding rules through separate calls:

ExpansionInlines
wallet_type_idThe full wallet_type, so you have the denomination without a second lookup
auto_top_up_configsThe automatic top-up configs attached to that wallet
GET
/v:version/wallets/:resourceIdOrReference
curl https://test.api.solvimon.com/v1/wallets/ \
     -H "X-API-KEY: <apiKey>"
Try it
Response
{
  "object_type": "WALLET",
  "id": "wall_jwDeeN0vxxHxXDCnRA1I",
  "reference": "brightline_prepaid_credits",
  "status": "ACTIVE",
  "wallet_type_id": "wtyp_BwDeeN0vxxHxWOCkua1f",
  "wallet_type": {
    "object_type": "WALLET_TYPE",
    "id": "wtyp_BwDeeN0vxxHxWOCkua1f",
    "name": "Prepaid credits",
    "reference": "prepaid_credits",
    "status": "ACTIVE",
    "type": "CREDIT",
    "credit": {
      "grant_type": "CREDITS",
      "credits_grant": {
        "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
      }
    },
    "created_at": "2026-09-14T08:30:12Z"
  },
  "auto_top_up_configs": [
    {
      "object_type": "AUTO_TOPUP_CONFIG",
      "id": "atco_wwDeeN0vxxHyEACyDR1J",
      "wallet_id": "wall_jwDeeN0vxxHxXDCnRA1I",
      "status": "ACTIVE",
      "threshold": {
        "credits": {
          "quantity": "5000",
          "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
        }
      },
      "topup_amount": {
        "quantity": "500.00",
        "currency": "EUR"
      },
      "pricing_plan_schedule_id": "ppsc_vwDeeN0vxxHy8HCJrM1D",
      "pricing_item_id": "prii_dwDeeN0vxxHy1OCkls19",
      "payment_method_id": "pmet_mwDeeN0vxxHymZCqwx1l",
      "created_at": "2026-10-02T11:18:45Z"
    }
  ],
  "customer_id": "cust_lwDeeN0vxxHxMWCVef1S",
  "created_at": "2026-10-01T08:00:03Z"
}

The same expansions apply when a wallet is reached through the customer balance call, using the nested key:

POST
/v:version/customers/:resourceIdOrReference/wallets/balance
curl -X POST https://test.api.solvimon.com/v1/customers//wallets/balance \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "balance_at": "2026-10-09T12:00:00Z",
  "include_customer_details": true
}'
Try it
Response
{
  "wallet_balances": [
    {
      "wallet_id": "wall_jwDeeN0vxxHxXDCnRA1I",
      "wallet": {
        "object_type": "WALLET",
        "id": "wall_jwDeeN0vxxHxXDCnRA1I",
        "reference": "brightline_prepaid_credits",
        "status": "ACTIVE",
        "wallet_type_id": "wtyp_BwDeeN0vxxHxWOCkua1f",
        "wallet_type": {
          "object_type": "WALLET_TYPE",
          "id": "wtyp_BwDeeN0vxxHxWOCkua1f",
          "name": "Prepaid credits",
          "reference": "prepaid_credits",
          "status": "ACTIVE",
          "type": "CREDIT",
          "credit": {
            "grant_type": "CREDITS",
            "credits_grant": {
              "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
            }
          },
          "created_at": "2026-09-14T08:30:12Z"
        },
        "customer_id": "cust_lwDeeN0vxxHxMWCVef1S",
        "created_at": "2026-10-01T08:00:03Z"
      },
      "wallet_balance": {
        "balance": {
          "credits": {
            "quantity": "55000",
            "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
          }
        },
        "reserved_balance": {
          "credits": {
            "quantity": "12480",
            "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
          }
        },
        "open_balance": {
          "credits": {
            "quantity": "42520",
            "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
          }
        },
        "balance_at": "2026-10-09T12:00:00Z",
        "customer_details": [
          {
            "customer_id": "cust_lwDeeN0vxxHxMWCVef1S",
            "reserved_balance": {
              "credits": {
                "quantity": "12480",
                "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
              }
            }
          }
        ]
      }
    }
  ],
  "balance_at": "2026-10-09T12:00:00Z"
}

Rendering a wallet with its denomination and its top-up rules took three calls before these expansions. See Expanding responses for how expand[] behaves generally.

See whose usage reserved the balance

A wallet balance shared by several child customers, or spent through several subscriptions, reports one reserved figure with no way to see where it came from. Pass include_customer_details on a balance call to get the reserved balance split per customer:

POST
/v:version/wallets/:resourceIdOrReference/balance
curl -X POST https://test.api.solvimon.com/v1/wallets//balance \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "balance_at": "2026-10-09T12:00:00Z",
  "include_customer_details": true
}'
Try it
Response
{
  "balance": {
    "credits": {
      "quantity": "55000",
      "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
    }
  },
  "reserved_balance": {
    "credits": {
      "quantity": "12480",
      "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
    }
  },
  "open_balance": {
    "credits": {
      "quantity": "42520",
      "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
    }
  },
  "balance_at": "2026-10-09T12:00:00Z",
  "customer_details": [
    {
      "customer_id": "cust_lwDeeN0vxxHxMWCVef1S",
      "reserved_balance": {
        "credits": {
          "quantity": "12480",
          "credit_type_id": "ctyp_xwDeeN0vxxHxVWCZif14"
        }
      }
    }
  ]
}

Each entry in the returned customer_details carries customer_id and that customer’s share of the reserved balance. The split is recorded when an invoice is built or refreshed, so it reflects usage that has actually been drafted against the wallet, not a live estimate. It only covers credit wallets: a BALANCE wallet returns an empty customer_details, since the attribution is recorded per credit type on the invoice line. The same flag works on POST /v1/customers/{id}/wallets/balance. It defaults to false, so existing integrations are unaffected. See Seat-based credits for a worked example on a seat-scaled pool.

Credit pools and commitments

Two things are commonly mistaken for credit pools. Neither is one:

  • A wallet is not shared across customers. Every wallet balance belongs to a single customer. A parent company and its children each hold their own wallets; there is no cross-customer pool that several customers draw from, and there is no pooling across a customer’s own wallets. Consumption priced in a given credit type draws only from the wallet holding that credit type.
  • A minimum-spend commitment is not a credit balance. A commitment sets a floor on what a customer is invoiced over a period. If actual charges fall short, the shortfall is invoiced as a true-up. Nothing is prepaid, nothing is granted into a wallet, and nothing expires. See Schedule configurations.

Use a wallet when the customer pays up front and draws down. Use a commitment when the customer promises a spend level and you bill against it. The two can coexist on one subscription: a committed annual spend that is delivered as monthly credit grants.