comecerodocs
Customers

List balance transactions

GET
/customers/{customer_id}/balance/transactions

Lists every change to a customer's store credit, oldest first: credit added by refunds and top-up payments, and credit spent or taken back. Each transaction shows the balance right after it.

The list is cursor-based: follow next_page_url, or send after_item or before_item. Filter by date_start and date_end (on date_created).

Secret tokens, and limited tokens tied to the customer.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

customer_id*string

The id of the customer. With a limited token from a customer login you can send me instead.

Query Parameters

limit?integer

How many items to return on one page, from 1 to 100. The default is 100. A value outside 1 to 100, or one that is not a whole number, is a 400.

Range1 <= value <= 100
Default100
after_item?string

For cursor-based lists, return the items after the item with this id. Use next_page_after_item (or follow next_page_url) from the page you have. You cannot send it together with before_item (400). An id that does not exist is a 404.

before_item?string

For cursor-based lists, return the items before the item with this id. Use previous_page_before_item (or follow previous_page_url) from the page you have. You cannot send it together with after_item (400). An id that does not exist is a 404.

desc?boolean

Sort in descending order (newest, largest or last first) when true. The default is false. A value other than true or false is a 400.

Defaultfalse
date_start?string

Only items on or after this date. Send ISO 8601 (2026-11-01T00:00:00Z or 2026-11-01T00:00:00-05:00) or a shorthand: 2026 means the start of 2026, 2026-11 the start of November, 2026-11-01 the start of that day. A date with no offset is read in timezone, or in the account's time zone when you send none. It must not be after date_end (400).

date_end?string

Only items on or before this date. Same formats as date_start, but a shorthand means the end of the period: 2026-11 is the last instant of November, 2026-11-30 the last instant of that day. A date with no offset is read in timezone, or in the account's time zone when you send none.

timezone?string

An IANA time zone name, such as America/New_York or UTC. It sets how date_start and date_end are read and the time zone of every date in the response. The default is the account's time zone (Settings, Technical), or UTC when it has none. A name that is not known is a 400.

Response Body

A page of balance transactions.

application/json
  1. response

A cursor-based list of balance transactions.

next_page_url*|

The URL of the next page, or null on the last page.

next_page_after_item*|

The after_item value for the next page.

previous_page_url*|

The URL of the previous page, or null on the first page.

previous_page_before_item*|

The before_item value for the previous page.

current_page_url*string

The URL of this page.

data*array<>

The transactions on this page.

Example Request
curl -X GET 'https://api.comecero.com/api/v1/customers/string/balance/transactions'
Example Response
{  "next_page_url": null,  "next_page_after_item": null,  "previous_page_url": null,  "previous_page_before_item": null,  "current_page_url": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions",  "data": [    {      "object": "customer_balance_transaction",      "url": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions/0093045112207CxAb12Cd3",      "customer_balance_transaction_id": "0093045112207CxAb12Cd3",      "customer_id": "0091304300408CuoxY9Pf3",      "account_id": "AB1234",      "test": true,      "date_created": "2026-11-04T15:02:11Z",      "amount": 25,      "current_balance": 25,      "currency": "USD",      "transaction_amount": 25,      "transaction_currency": "USD",      "memo": null,      "created_by": null,      "payment": null,      "refund": "https://api.comecero.com/api/v1/refunds/0093045112100ReQw34Er5"    },    {      "object": "customer_balance_transaction",      "url": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance/transactions/0093046230511CxZz98Yy7",      "customer_balance_transaction_id": "0093046230511CxZz98Yy7",      "customer_id": "0091304300408CuoxY9Pf3",      "account_id": "AB1234",      "test": true,      "date_created": "2026-11-05T09:41:03Z",      "amount": -10,      "current_balance": 15,      "currency": "USD",      "transaction_amount": -10,      "transaction_currency": "USD",      "memo": null,      "created_by": null,      "payment": "https://api.comecero.com/api/v1/payments/0093046230400PyMn56Bv8",      "refund": null    }  ]}

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.

Get a balance transaction GET

Gets one change to a customer's store credit. Use `expand=payment` or `expand=refund` to include the payment or refund behind it. Secret tokens, and limited tokens tied to the customer.