Wallet, credit, outcome and unit balances, and composite pools, under the customer's current plan. When hasPlan is false the balance collections are empty. wallet is always returned and holds both wallet balances in USD: balance (the ordinary Wallet — always present, even when the plan has no Wallet component or there is no plan) and reservedBalance (the Reserved Wallet, left out when the workspace hasn't enabled it).
Authorization
apiKey Organisation-scoped key from Settings → API Keys.
In: header
Path Parameters
Customer id.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/customers/cus_abc123/balances"{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "OK" }, "result": { "customerId": "cus_abc123", "currency": { "code": "USD", "rateUsd": 1 }, "hasPlan": true, "wallet": { "balance": 262.5, "reservedBalance": 500 }, "credits": [ { "creditId": "cred_pqr678", "agentKey": "deep-research", "creditName": "Deep Research", "granted": 5000, "used": 1240, "remaining": 3760 } ], "outcomes": [ { "outcomeId": "out_stu901", "outcomeName": "Contract review", "granted": 12, "remaining": 9, "steps": [ { "id": "step_1", "name": "extract-clauses", "agentKey": "extract-clauses" } ] } ], "units": [ { "unitId": "unit_vwx234", "agentKey": "seats", "unitName": "Seats", "granted": 50, "remaining": 37.5 } ], "composites": [ { "compositeId": "cmp_yza567", "refId": "voice_ai", "name": "Voice AI call", "granted": 100, "used": 12, "remaining": 88, "originalGranted": null } ] }}{ "statusCode": 401, "statusDetail": { "status": "ERROR", "message": "Invalid API key." }, "result": {}}{ "statusCode": 404, "statusDetail": { "status": "ERROR", "message": "No customer with id \"cus_abc123\"." }, "result": {}}{ "statusCode": 500, "statusDetail": { "status": "ERROR", "message": "Could not complete the request." }, "result": {}}The same call, addressed by the customer's externalId. Same response.
Authorization
apiKey Organisation-scoped key from Settings → API Keys.
In: header
Path Parameters
Your own id for the customer (its externalId): 1–32 letters, numbers or "-", matched exactly (case-sensitive).
^[A-Za-z0-9-]{1,32}$1 <= length <= 32Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/customers/ext/acme-42/balances"{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "OK" }, "result": { "customerId": "cus_abc123", "currency": { "code": "USD", "rateUsd": 1 }, "hasPlan": true, "wallet": { "balance": 262.5, "reservedBalance": 500 }, "credits": [ { "creditId": "cred_pqr678", "agentKey": "deep-research", "creditName": "Deep Research", "granted": 5000, "used": 1240, "remaining": 3760 } ], "outcomes": [ { "outcomeId": "out_stu901", "outcomeName": "Contract review", "granted": 12, "remaining": 9, "steps": [ { "id": "step_1", "name": "extract-clauses", "agentKey": "extract-clauses" } ] } ], "units": [ { "unitId": "unit_vwx234", "agentKey": "seats", "unitName": "Seats", "granted": 50, "remaining": 37.5 } ], "composites": [ { "compositeId": "cmp_yza567", "refId": "voice_ai", "name": "Voice AI call", "granted": 100, "used": 12, "remaining": 88, "originalGranted": null } ] }}{ "statusCode": 400, "statusDetail": { "status": "ERROR", "message": "Request body must be valid JSON." }, "result": {}}{ "statusCode": 401, "statusDetail": { "status": "ERROR", "message": "Invalid API key." }, "result": {}}{ "statusCode": 404, "statusDetail": { "status": "ERROR", "message": "No customer with id \"cus_abc123\"." }, "result": {}}{ "statusCode": 500, "statusDetail": { "status": "ERROR", "message": "Could not complete the request." }, "result": {}}