Store credit

Permission: store_credit (read / write). Store credit is its own permission, separate from customers, because it's money. Every change is a row in the customer's credit ledger, the balance on the customer follows it, and the balance mirrors to BigCommerce store credit so it can be spent online too.

Balance and ledger

GET /v1/customers/{id}/store-credit returns the balance and the customer's latest ledger rows, newest first (?limit=, up to 200, default 50).

curl https://app.blackbeachpos.com/api/v1/customers/312/store-credit \
  -H "Authorization: Bearer ir_live_…"

{
  "status": "ok",
  "data": {
    "object": "store_credit",
    "customer_id": 312,
    "balance_cents": 1500,
    "ledger": [
      {
        "object": "store_credit_entry",
        "id": 88,
        "customer_id": 312,
        "kind": "refund",
        "amount_cents": 1500,
        "balance_after_cents": 1500,
        "reference_type": "api",
        "reference_id": null,
        "note": "Issued via API (Etsy connector) · ref RMA-7",
        "created_at": "2026-09-25T15:02:11Z"
      }
    ]
  }
}

kind is one of refund, adjustment, redeem (spent at the register or through the API), online_redeem (spent at BigCommerce checkout), reversal, trade_in, consignment_payout. amount_cents is signed: positive adds credit, negative spends it.

GET /v1/store-credit lists ledger rows across all customers, oldest first, cursor-paginated. Filters: customer_id, updated_since (matches the row'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

Field
amount_cents	Required, 1 to 1,000,000
reason	Required: refund (money owed back to the customer) or adjustment (goodwill or a correction)
note	Optional, up to 200 characters
reference	Optional, your id for this change (shown in the ledger note)

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

Redeem credit

POST /v1/customers/{id}/store-credit/redeem with { "amount_cents": 1500, "reference": "ORDER-4410" } spends from the balance. 422 INSUFFICIENT_CREDIT when the balance is short.

Rules

• An Idempotency-Key header is required on issue and redeem (400 IDEMPOTENCY_KEY_REQUIRED without it), so a retry can never move the balance twice. A replay returns the first response with Idempotent-Replayed: true.
• Both answer with the new balance_cents and entry, the ledger row just written.
• An unknown or deleted customer is 404 NOT_FOUND.
• Every change fires the store_credit.changed webhook: { "object": "store_credit", "customer_id", "balance_cents", "entry" }. It also fires for credit issued or spent at the register or online.
• A key with customers:read also sees the balance as store_credit_cents on the customer.