Credit consumption & expiry

How Solvimon draws down a customer’s credit balance when several grants are live at once, what the different balance figures mean, and what happens to credits that are never used.

Why this matters

A customer rarely holds a single block of credits. A recurring monthly grant, a promotional grant, and a purchased top-up can all sit in the same wallet with different expiry dates. Which block gets consumed first determines how much value the customer keeps at the end of the month, and it determines your deferred revenue and breakage numbers.

Drawdown order

Credits are consumed earliest expiry first. Solvimon orders the customer’s active grants in the wallet by expire_at and draws down the grant closest to expiring before touching any other.

Grants with no expiry are consumed last, after every expiring grant is exhausted. When two grants share the same expire_at, the older grant (earlier start_at) is consumed first.

Worked example. A customer holds two grants in the same wallet:

The customer consumes 1,200 credits during August. The first 1,000 come out of the monthly grant, because it expires on 31 August. The remaining 200 come out of the top-up. On 1 September the monthly grant is spent, the top-up holds 4,800, and a fresh 1,000-credit monthly grant is created.

Had the order been reversed, the customer would have lost 1,000 credits to expiry while still holding a paid balance. Earliest-expiry-first protects the customer’s paid credits and puts the shortest-lived credits to work first.

Reading a balance

A wallet balance is not a single number. POST /v{version}/wallets/{resourceIdOrReference}/balance returns four figures:

Use open_balance for anything customer-facing, such as a “credits remaining” figure in your product. Use balance when reconciling against accounting.

1
curl -X POST https://test.api.solvimon.com/v1/wallets//balance \
2
     -H "X-API-KEY: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{}'

1
{
2
  "balance": {
3
    "credits": {
4
      "quantity": "string",
5
      "credit_type_id": "string"
6
    },
7
    "amount": {
8
      "quantity": "string",
9
      "currency": "AED"
10
    }
11
  },
12
  "reserved_balance": {
13
    "credits": {
14
      "quantity": "string",
15
      "credit_type_id": "string"
16
    },
17
    "amount": {
18
      "quantity": "string",
19
      "currency": "AED"
20
    }
21
  },
22
  "open_balance": {
23
    "credits": {
24
      "quantity": "string",
25
      "credit_type_id": "string"
26
    },
27
    "amount": {
28
      "quantity": "string",
29
      "currency": "AED"
30
    }
31
  },
32
  "balance_at": "string"
33
}

Pass balance_at to ask for a historical balance. The default is now(), so omitting it gives the current balance. This is how you reproduce a month-end balance after the fact, which is what a reconciliation needs.

To read every wallet a customer holds in a single call, use POST /v{version}/customers/{resourceIdOrReference}/wallets/balance. The response returns one wallet_balance per wallet_id.

1
curl -X POST https://test.api.solvimon.com/v1/customers//wallets/balance \
2
     -H "X-API-KEY: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{}'

1
{
2
  "wallet_balances": [
3
    {
4
      "wallet_id": "string",
5
      "wallet_balance": {
6
        "balance": {
7
          "credits": {
8
            "quantity": "string",
9
            "credit_type_id": "string"
10
          },
11
          "amount": {
12
            "quantity": "string",
13
            "currency": "AED"
14
          }
15
        },
16
        "reserved_balance": {
17
          "credits": {
18
            "quantity": "string",
19
            "credit_type_id": "string"
20
          },
21
          "amount": {
22
            "quantity": "string",
23
            "currency": "AED"
24
          }
25
        },
26
        "open_balance": {
27
          "credits": {
28
            "quantity": "string",
29
            "credit_type_id": "string"
30
          },
31
          "amount": {
32
            "quantity": "string",
33
            "currency": "AED"
34
          }
35
        },
36
        "balance_at": "string"
37
      }
38
    }
39
  ],
40
  "balance_at": "string"
41
}

Expiry

Expiry is configured on the wallet grant in the pricing plan, as a period rather than a fixed date. The expiry_period on the grant’s expiry policy is measured from the grant’s start_at, so a one-month expiry period on a monthly recurring grant means each month’s credits expire as the next month’s credits arrive.

At expire_at, whatever is left in that grant stops being spendable. The remaining credits do not roll into another grant and they do not extend: the grant simply stops contributing to balance. Other grants in the same wallet are unaffected.

A grant with no expiry policy never expires. Its credits stay spendable until they are consumed.

Rollover on top-ups

A top-up pricing item exposes a rollover flag. With rollover enabled, an unused balance from the previous period carries into the next period instead of expiring with it. With it disabled, the balance resets each period. Rollover is a property of the top-up configuration, not of the wallet, so two top-up items funding the same wallet can behave differently.

Edge cases

• Balance never goes negative. Once a wallet is empty, further usage is either charged in currency through a credit overage item or not charged at all. See Credits in pricing plans.
• A refunded or reversed top-up does not claw credits back automatically. Create a compensating adjustment if credits were already consumed.
• Low balance is an event, not a block. A WalletThreshold and the wallet balance workflow trigger notify you or trigger an automatic top-up; they do not stop consumption.

See Credit revenue and breakage for how consumption and expiry translate into recognised revenue.