Store credit

Permission: store_credit (read / write). It is its own permission, separate from customers, because it is money.

Store credit belongs to a customer. Every change is a row in the customer's credit ledger (signed cents, with the balance after it), and the balance is mirrored to the shop's BigCommerce store so the credit spends online as well as at the register. Credit comes from refunds, trade-in allowances, consignment payouts, adjustments and the API; it is spent at the register, online, or through the API.

A customer's balance and ledger

GET /v1/customers/{id}/store-credit (read). Returns the balance and the most recent ledger entries, newest first. ?limit= sets how many entries (default 50, up to 200).

{
  "status": "ok",
  "data": {
    "object": "store_credit",
    "customer_id": 1166,
    "balance_cents": 4200,
    "ledger": [
      { "object": "store_credit_entry", "id": 912, "customer_id": 1166, "kind": "refund", "amount_cents": 1500, "balance_after_cents": 4200, "reference_type": "api", "reference_id": null, "note": "Issued via API (Helpdesk) · ref RMA-7", "created_at": "2026-09-25T15:02:11Z" },
      { "object": "store_credit_entry", "id": 874, "customer_id": 1166, "kind": "trade_in", "amount_cents": 2700, "balance_after_cents": 2700, "reference_type": "trade_in", "reference_id": 41, "note": null, "created_at": "2026-09-19T20:14:08Z" }
    ]
  }
}

kind is one of trade_in, consignment_payout, refund, adjustment, redeem, online_redeem, reversal. amount_cents is positive when credit was added and negative when it was spent. reference_type is sale, return, trade_in, api or bc_order (null otherwise); reference_id is set for sales, returns and trade-ins.

The balance also appears on the customer as store_credit_cents (with the customers permission).

The ledger across customers

GET /v1/store-credit (read). Every ledger entry, oldest first, cursor-paginated. Filters: customer_id, updated_since (on the entry's created_at), limit, cursor. Use it to keep a loyalty or accounting system in step.

Issue credit

POST /v1/customers/{id}/store-credit/issue (write). An Idempotency-Key header is required; without one the call is 400 IDEMPOTENCY_KEY_REQUIRED, so a retry can never add credit twice.

Field	Required	Notes
amount_cents	yes	1–1000000
reason	yes	refund (money owed back to the customer) or adjustment (a goodwill or correction credit). Becomes the entry's kind.
note	no	Up to 200 characters
reference	no	Your id (a ticket, an RMA), up to 120 characters; recorded in the note

curl -X POST https://app.ironregister.com/api/v1/customers/1166/store-credit/issue \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: RMA-7-credit" \
  -d '{ "amount_cents": 1500, "reason": "refund", "reference": "RMA-7" }'

{
  "status": "ok",
  "data": {
    "object": "store_credit",
    "customer_id": 1166,
    "balance_cents": 4200,
    "entry": { "object": "store_credit_entry", "id": 912, "customer_id": 1166, "kind": "refund", "amount_cents": 1500, "balance_after_cents": 4200, "reference_type": "api", "reference_id": null, "note": "Issued via API (Helpdesk) · ref RMA-7", "created_at": "2026-09-25T15:02:11Z" }
  }
}

Redeem credit

POST /v1/customers/{id}/store-credit/redeem (write), with amount_cents (required, 1–1000000), optional note and reference. An Idempotency-Key header is required. The response has the same shape as issue, with a redeem entry (negative amount_cents).

More than the balance is 422 INSUFFICIENT_CREDIT; the balance never goes below zero through the API.

Errors

Status	Code	When
400	IDEMPOTENCY_KEY_REQUIRED	Issue or redeem without an Idempotency-Key
400	VALIDATION_ERROR	A missing or out-of-range amount_cents, or a missing / unknown reason on issue
404	NOT_FOUND	No such customer
422	INSUFFICIENT_CREDIT	Redeeming more than the balance
422	IDEMPOTENCY_MISMATCH	The same key was used with a different body

Webhooks

store_credit.changed fires on every balance change, from any source: the register, BigCommerce checkout, a refund, a trade-in, an adjustment or the API.

{
  "object": "store_credit",
  "customer_id": 1166,
  "balance_cents": 4200,
  "entry": { "object": "store_credit_entry", "id": 912, "kind": "refund", "amount_cents": 1500, "balance_after_cents": 4200, "…": "…" }
}