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:
| Grant | Credits | start_at | expire_at |
|---|---|---|---|
wgr_5tKqPz3nAvBd7YsLmQ2Rf (monthly recurring) | 1,000 | 2026-08-01 | 2026-08-31 |
wgr_9HdXbN4vTcRe2WkJpS6Yz (purchased top-up) | 5,000 | 2026-07-14 | 2027-07-14 |
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.
Drawdown order is fixed platform behavior. There is no per-grant priority or weighting field, and there is no way to make consumption draw from a specific grant.
Reading a balance
A wallet balance is not a single number. POST /v{version}/wallets/{resourceIdOrReference}/balance returns four figures:
| Field | Meaning |
|---|---|
balance | Credits (or amount) currently held, after all completed consumption |
reserved_balance | Credits committed to usage that has been metered but not yet invoiced |
open_balance | balance minus reserved_balance: what the customer can still spend |
balance_at | The moment the balance was determined |
Use open_balance for anything customer-facing, such as a “credits remaining” figure in your product. Use balance when reconciling against accounting.
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"}'
Response
{"balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"reserved_balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"open_balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"balance_at": "string","over_granted": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"customer_details": [{"customer_id": "string","reserved_balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"over_granted": {"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"}},"amount": {"quantity": "string","currency": "AED"}}}]}
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.
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}'
Response
{"wallet_balances": [{"wallet_id": "string","wallet": {"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"},"wallet_balance": {"balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"reserved_balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"open_balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"balance_at": "string","over_granted": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"customer_details": [{"customer_id": "string","reserved_balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"balance": {"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"}},"amount": {"quantity": "string","currency": "AED"}},"over_granted": {"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"}},"amount": {"quantity": "string","currency": "AED"}}}]},"charge_on_demand_pricing_items": [{"pricing_item_id": "string","pricing_plan_schedule_id": "string","pricing_item": {"object_type": "string","id": "string","original_pricing_item_id": "string","original_pricing_item": {},"override": "ALL","product_item_ids": ["string"],"product_items": [{"object_type": "string","id": "string","product_id": "string","product": {"object_type": "string","id": "string","category_id": "string","category": {"object_type": "string","id": "string","name": "string","reference": "string","description": "string","tax_category": "STANDARD","display_order": 1,"customer_id": "string"},"parent_product_id": "string","name": "string","reference": "string","description": "string","status": "DRAFT","product_type": "DEFAULT","tax_category": "STANDARD","features": [{"id": "string","reference": "string"}],"custom_fields": [{"id": "string","reference": "string","value": "string","values": ["string"],"integration_details": {"id": "string","reference": "string","payment_gateway_variant": "ADYEN","adyen": {"recurring_detail_reference": "string"},"stripe": {"payment_method_id": "string"}},"integration_id": "string"}],"display_order": 1,"linked_integrations": [{"id": "string","link_details": [{"url": "string","custom_field_name": "string"}]}],"billing_entity_id": "string","customer_id": "string","agent_context": {"guidance": "string"}},"name": "string","status": "DRAFT","reference": "string","description": "string","type": "REVENUE","model_type": "USAGE_BASED","usage_based": {"meter_value_calculation_id": "string","meter_value_calculation": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","calculation_type": "SUM","persist": true,"meter_id": "string","meter": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","meter_values": [{"id": "string","object": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER"},"required": true}],"meter_properties": [{"id": "string","object": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"required": true}]},"meter_value_id": "string","meter_value": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER"},"meter_property_id": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]}},"tiering_meter_value_calculation_id": "string","tiering_meter_value_calculation": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","calculation_type": "SUM","persist": true,"meter_id": "string","meter": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","meter_values": [{"id": "string","object": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER"},"required": true}],"meter_properties": [{"id": "string","object": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"required": true}]},"meter_value_id": "string","meter_value": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER"},"meter_property_id": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]}},"report_meter_value_calculation_ids": ["string"],"conditions": {"name": "string","expression": {"operator": "AND","operands": [{"meter_property": {"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"},"expression": {}}]},"meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}]}},"credits": {"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"}},"meter_value_calculation": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","calculation_type": "SUM","persist": true,"meter_id": "string","meter": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","meter_values": [{"id": "string","object": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER"},"required": true}],"meter_properties": [{"id": "string","object": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"required": true}]},"meter_value_id": "string","meter_value": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER"},"meter_property_id": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]}},"tax_category": "STANDARD","display_order": 1,"unit_name": {"singular": "string","plural": "string"},"custom_fields": [{"id": "string","reference": "string","value": "string","values": ["string"],"integration_details": {"id": "string","reference": "string","payment_gateway_variant": "ADYEN","adyen": {"recurring_detail_reference": "string"},"stripe": {"payment_method_id": "string"}},"integration_id": "string"}],"customer_id": "string","agent_context": {"guidance": "string"},"meter_value_calculation_id": "string","report_meter_value_calculation_ids": ["string"]}],"configs": [{"object_type": "string","id": "string","original_pricing_item_config_id": "string","original_pricing_item_config": {},"details": {"billing_period": {"type": "DAY","value": 1},"pricing_type": "FLAT","pricing_period": {"type": "DAY","value": 1},"bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]},"billing_period": {"type": "DAY","value": 1},"pricing_period": {"type": "DAY","value": 1},"default_included_volume": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string","reset_type": "string"},"default_seats_value": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"default_units": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"conditions": {"name": "string","meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}],"configs": [{}]},"tiering_conditions": {"name": "string","expression": {"operator": "AND","operands": [{"meter_property": {"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"},"expression": {}}]},"meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}]},"order": 1,"billing_in_advance": true,"volume_group_reference": "string","top_up": {"rollover": true},"split_pricing": {"meter_properties": [{"id": "string","reference": "string","value": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]}}]},"on_demand": true,"wallet_grants": [{"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"},"amount_grant": {"amount": {"quantity": "string","currency": "AED"},"percentage": "string"},"credits_grant": {"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"}},"conversion": {"credit_type_id": "string","rate": "string"}},"expiry_policy": {"expiry_period": {"type": "DAY","value": 1}},"source": "FIXED"}],"type": "FLAT","pricing_type": "FLAT","bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]}],"pricing_currency_configs": [{"currency": "AED","configs": [{"object_type": "string","id": "string","original_pricing_item_config_id": "string","original_pricing_item_config": {},"details": {"billing_period": {"type": "DAY","value": 1},"pricing_type": "FLAT","pricing_period": {"type": "DAY","value": 1},"bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]},"billing_period": {"type": "DAY","value": 1},"pricing_period": {"type": "DAY","value": 1},"default_included_volume": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string","reset_type": "string"},"default_seats_value": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"default_units": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"conditions": {"name": "string","meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}],"configs": [{}]},"tiering_conditions": {"name": "string","expression": {"operator": "AND","operands": [{"meter_property": {"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"},"expression": {}}]},"meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}]},"order": 1,"billing_in_advance": true,"volume_group_reference": "string","top_up": {"rollover": true},"split_pricing": {"meter_properties": [{"id": "string","reference": "string","value": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]}}]},"on_demand": true,"wallet_grants": [{"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"},"amount_grant": {"amount": {"quantity": "string","currency": "AED"},"percentage": "string"},"credits_grant": {"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"}},"conversion": {"credit_type_id": "string","rate": "string"}},"expiry_policy": {"expiry_period": {"type": "DAY","value": 1}},"source": "FIXED"}],"type": "FLAT","pricing_type": "FLAT","bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]}],"billing_period_configs": [{"billing_period": {"type": "DAY","value": 1},"configs": [{"object_type": "string","id": "string","original_pricing_item_config_id": "string","original_pricing_item_config": {},"details": {"billing_period": {"type": "DAY","value": 1},"pricing_type": "FLAT","pricing_period": {"type": "DAY","value": 1},"bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]},"billing_period": {"type": "DAY","value": 1},"pricing_period": {"type": "DAY","value": 1},"default_included_volume": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string","reset_type": "string"},"default_seats_value": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"default_units": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"conditions": {"name": "string","meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}],"configs": [{}]},"tiering_conditions": {"name": "string","expression": {"operator": "AND","operands": [{"meter_property": {"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"},"expression": {}}]},"meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}]},"order": 1,"billing_in_advance": true,"volume_group_reference": "string","top_up": {"rollover": true},"split_pricing": {"meter_properties": [{"id": "string","reference": "string","value": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]}}]},"on_demand": true,"wallet_grants": [{"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"},"amount_grant": {"amount": {"quantity": "string","currency": "AED"},"percentage": "string"},"credits_grant": {"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"}},"conversion": {"credit_type_id": "string","rate": "string"}},"expiry_policy": {"expiry_period": {"type": "DAY","value": 1}},"source": "FIXED"}],"type": "FLAT","pricing_type": "FLAT","bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]}]}],"fallback_currency": "AED"}],"billing_period_configs": [{"billing_period": {"type": "DAY","value": 1},"configs": [{"object_type": "string","id": "string","original_pricing_item_config_id": "string","original_pricing_item_config": {},"details": {"billing_period": {"type": "DAY","value": 1},"pricing_type": "FLAT","pricing_period": {"type": "DAY","value": 1},"bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]},"billing_period": {"type": "DAY","value": 1},"pricing_period": {"type": "DAY","value": 1},"default_included_volume": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string","reset_type": "string"},"default_seats_value": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"default_units": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"conditions": {"name": "string","meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}],"configs": [{}]},"tiering_conditions": {"name": "string","expression": {"operator": "AND","operands": [{"meter_property": {"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"},"expression": {}}]},"meter_properties": [{"id": "string","reference": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]},"value": "string","values": ["string"],"meter_property_variable_id": "string","meter_property_variable": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","meter_property_id": "string","type": "LIST","status": "DRAFT","value_count": 1,"created_at": "string","updated_at": "string"},"comparator": "EQUALS"}]},"order": 1,"billing_in_advance": true,"volume_group_reference": "string","top_up": {"rollover": true},"split_pricing": {"meter_properties": [{"id": "string","reference": "string","value": "string","meter_property": {"object_type": "string","id": "string","reference": "string","name": "string","description": "string","status": "DRAFT","type": "NUMBER","enum_values": ["string"]}}]},"on_demand": true,"wallet_grants": [{"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"},"amount_grant": {"amount": {"quantity": "string","currency": "AED"},"percentage": "string"},"credits_grant": {"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"}},"conversion": {"credit_type_id": "string","rate": "string"}},"expiry_policy": {"expiry_period": {"type": "DAY","value": 1}},"source": "FIXED"}],"type": "FLAT","pricing_type": "FLAT","bands": [{"amount": {"quantity": "string","currency": "AED"},"percentage": "string","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"}},"fixed_amount": {"quantity": "string","currency": "AED"},"maximum_amount": {"quantity": "string","currency": "AED"},"minimum_amount": {"quantity": "string","currency": "AED"},"maximum_number": "string","minimum_number": "string","block_size": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"},"tier_top_bound": {"number": "string","amount": {"quantity": "string","currency": "AED"},"count": "string"}}]}]}],"display_order": 1}}]}],"balance_at": "string"}
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.
Expiry applies per grant, not per wallet. A wallet balance can drop at the turn of a period even though no usage was recorded, because an expiring grant left the balance. Reconcile per grant (GET /v{version}/wallet-grants) when a balance change looks unexplained.
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
WalletThresholdand 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.