Get a customer's balance
Gets a customer's store credit. The amount can be negative, for example after a refund paid to the balance was taken back. That is expected and is covered by the next credit. A customer who never had store credit has a balance of 0 in USD.
Send currency to see the amount in another currency, converted at the account's exchange rate. Send expand=transactions to include the transactions.
Secret tokens, and limited tokens tied to the customer.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
customer_id*stringThe id of the customer. With a limited token from a customer login you can send me instead.
currency?stringA three-letter ISO 4217 currency code to show the amount in, for example EUR.
expand?stringComma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.
formatted?booleanWhen true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.
falseThe customer's balance.
application/json- response
A customer's store credit. Money comes in from refunds paid to the balance and from payments made with apply_to_balance: true, and goes out when the customer pays with the customer_account_balance payment method.
The amount can be below zero. That is expected: when a refund paid to the balance is taken back, or a chargeback lands after the credit was spent, the balance goes negative and stays that way until new credit covers it. A payment from the balance can never take it below zero.
A customer with no balance transactions yet has a balance of 0 in USD.
object*"customer_balance"The object type. Always customer_balance.
"customer_balance"url*stringThe full URL of the balance.
customer_id*stringThe id of the customer.
account_id*stringThe id of the account.
test*booleanTrue for a test customer.
amount*numberThe balance, in currency. Can be negative. When you ask for another currency, this is converted at the account's exchange rate.
currency*stringThe currency of amount. The balance is kept in the currency of its first transaction. You can ask for another with the currency parameter.
date_last_transaction*|When the balance last changed, or null if it never has.
date-timetransactions?|The URL of the balance transactions, or the list when expanded (expand=transactions). Only present when your token may read them.
formatted?Only when you send formatted=true. Display text.
curl -X GET 'https://api.comecero.com/api/v1/customers/string/balance'{ "object": "customer_balance", "url": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance", "customer_id": "0091304300408CuoxY9Pf3", "account_id": "AB1234", "test": true, "amount": 25, "currency": "USD", "date_last_transaction": "2026-11-04T15:02:11Z", "transactions": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions"}Update a customer POST
Changes a customer. Only the fields you send change; send an address as `null` to clear it. Changing the country or VAT number can change whether tax is charged on the customer's next cart, invoice or renewal. Secret tokens, and limited tokens tied to the customer. A limited token cannot set `tax_exempt`. No email is sent and no event fires.
Add store credit by payment POST
Takes a payment from the customer and adds it to their store credit. This is the same as Create a payment: the body is a payment, and Comecero reads the customer from the body, not from the URL. To add the money to the balance, send `apply_to_balance: true` and the customer (`customer_id` or `customer`) in the body. The credit is added when the payment is captured, in the payment's currency converted to the balance currency. The payment cannot use `customer_account_balance` as its payment method. Money moves and the usual payment events fire. Secret tokens, and limited tokens. The id in the URL may be `me` only with a token from a customer login.