Store credit

Store credit in BenchKey is tracked per customer identity key, a normalized string of the form email:<address> or phone:<digits>. Credit is issued as a side effect of buybacks and redeemed through invoice payments in the BenchKey app; the API exposes read-only access to balances and the full ledger history.

Scope required: store_credit.read for all endpoints below.

The store credit object

{
  "object": "store_credit",
  "customer_key": "email:alex@example.com",
  "customer_email": "alex@example.com",
  "customer_phone": null,
  "customer_name": "Alex Rivera",
  "balance": { "amount_cents": 3500, "amount": "35.00", "currency": "USD" },
  "currency": "USD",
  "created_at": "2025-09-14T10:05:00.000Z",
  "updated_at": "2025-11-01T16:42:00.000Z"
}

Field	Type	Description
customer_key	string	Normalized identity key: email:<addr> or phone:<digits>
customer_email	string|null	Email address associated with this key, if any
customer_phone	string|null	Phone number associated with this key, if any
customer_name	string|null	Customer name at the time of the last credit event
balance	object	Current balance, amount_cents (integer), amount (decimal string), currency
currency	string	ISO 4217 currency code
created_at	string|null	ISO-8601 timestamp when the first credit was recorded
updated_at	string|null	ISO-8601 timestamp of the most recent balance change

Zero-balance visibility: rows with a zero balance are hidden by default. Pass include_zero=true to include them in the list, single-key lookup, or ledger endpoints.

---

The store credit ledger entry object

{
  "object": "store_credit_ledger_entry",
  "id": "88201",
  "customer_key": "email:alex@example.com",
  "entry_type": "buyback_credit",
  "amount": { "amount_cents": 5000, "amount": "50.00", "currency": "USD" },
  "balance_after": { "amount_cents": 5000, "amount": "50.00", "currency": "USD" },
  "currency": "USD",
  "buyback_id": "BK-221",
  "invoice_id": null,
  "reference": null,
  "note": "iPhone 14 Pro, fair condition",
  "created_at": "2025-09-14T10:05:00.000Z"
}

Field	Type	Description
id	string	Ledger entry ID (string-encoded integer)
customer_key	string	Customer identity key
entry_type	string|null	Type of transaction: buyback_credit, buyback_void, invoice_payment, adjustment, etc.
amount	object	Signed credit/debit, positive values are credits, negative are debits
balance_after	object|null	Running balance after this entry
currency	string	ISO 4217 currency code
buyback_id	string|null	Associated buyback ID, if applicable
invoice_id	string|null	Associated invoice ID, if applicable
reference	string|null	External reference string, if set
note	string|null	Optional note describing the entry
created_at	string|null	ISO-8601 timestamp of the entry

---

List store credit balances

GET /api/v1/store_credit

Returns a cursor-paginated list of customer store credit balances, ordered by customer_key ascending. Only non-zero balances are returned by default.

Scope required: store_credit.read

Query parameters

Parameter	Type	Description
customer_email	string	Filter by customer email (case-insensitive, exact match)
customer_phone	string	Filter by customer phone (digits only, format-insensitive)
include_zero	boolean	Include zero-balance rows (default: false)
limit	integer	Page size, 1–100 (default: 25)
cursor	string	Opaque cursor from a previous response’s next_cursor

curl

curl "https://app.benchkey.com/api/v1/store_credit?limit=20" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch(
  "https://app.benchkey.com/api/v1/store_credit?limit=20",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const { data, has_more, next_cursor } = await res.json();

Response

{
  "object": "list",
  "data": [
    {
      "object": "store_credit",
      "customer_key": "email:alex@example.com",
      "customer_email": "alex@example.com",
      "customer_phone": null,
      "customer_name": "Alex Rivera",
      "balance": { "amount_cents": 3500, "amount": "35.00", "currency": "USD" },
      "currency": "USD",
      "created_at": "2025-09-14T10:05:00.000Z",
      "updated_at": "2025-11-01T16:42:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for how to page through results.

---

Retrieve a store credit balance

GET /api/v1/store_credit/:customer_key

Returns the current balance for a single customer identity key (e.g. email:alex@example.com or phone:15551234567). Returns 404 if no balance record exists for that key.

Zero-balance rows: a zero-balance row is hidden by default (it would expose customer-identity data the list also hides) and returns 404. Pass include_zero=true to retrieve a zero-balance row.

Query parameters

Parameter	Type	Description
include_zero	boolean	Include the row even if balance is zero (default: false)

Scope required: store_credit.read

curl

curl "https://app.benchkey.com/api/v1/store_credit/email%3Aalex%40example.com" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const key = encodeURIComponent("email:alex@example.com");
const res = await fetch(
  `https://app.benchkey.com/api/v1/store_credit/${key}`,
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const credit = await res.json();

Response

Returns the store credit object. Returns 404 if the key does not exist.

---

List ledger entries for a customer

GET /api/v1/store_credit/:customer_key/ledger

Returns the full credit/debit history for a customer, sorted newest-first. Returns 404 if no credit record exists for that customer key, or if the customer’s balance is zero (unless include_zero=true is passed).

Scope required: store_credit.read

Query parameters

Parameter	Type	Description
entry_type	string	Filter by entry type (e.g. buyback_credit, invoice_payment), case-insensitive
include_zero	boolean	Include the ledger even if the customer’s balance is zero (default: false). Mirrors the balance read’s visibility contract, a zero-balance customer returns 404 on this endpoint unless include_zero=true
limit	integer	Page size, 1–100 (default: 25)
cursor	string	Opaque cursor from a previous response’s next_cursor

curl

curl "https://app.benchkey.com/api/v1/store_credit/email%3Aalex%40example.com/ledger?limit=10" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const key = encodeURIComponent("email:alex@example.com");
const res = await fetch(
  `https://app.benchkey.com/api/v1/store_credit/${key}/ledger?limit=10`,
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const { data, has_more, next_cursor } = await res.json();

Response

{
  "object": "list",
  "data": [
    {
      "object": "store_credit_ledger_entry",
      "id": "88215",
      "customer_key": "email:alex@example.com",
      "entry_type": "invoice_payment",
      "amount": { "amount_cents": -1500, "amount": "-15.00", "currency": "USD" },
      "balance_after": { "amount_cents": 3500, "amount": "35.00", "currency": "USD" },
      "currency": "USD",
      "buyback_id": null,
      "invoice_id": "INV-10042",
      "reference": null,
      "note": null,
      "created_at": "2025-11-01T16:42:00.000Z"
    },
    {
      "object": "store_credit_ledger_entry",
      "id": "88201",
      "customer_key": "email:alex@example.com",
      "entry_type": "buyback_credit",
      "amount": { "amount_cents": 5000, "amount": "50.00", "currency": "USD" },
      "balance_after": { "amount_cents": 5000, "amount": "50.00", "currency": "USD" },
      "currency": "USD",
      "buyback_id": "BK-221",
      "invoice_id": null,
      "reference": null,
      "note": "iPhone 14 Pro, fair condition",
      "created_at": "2025-09-14T10:05:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for how to page through results.

---

Customer key format

Store credit is keyed on customer identity, not on a customer record ID. The key format is:

Prefix	Format	Example
email:	email:<lowercase-address>	email:alex@example.com
phone:	phone:<digits-only>	phone:15551234567

URL-encode the colon and any special characters when using a key as a path segment (: → %3A, @ → %40).

---

Error codes

HTTP status	Code	Meaning
400	invalid_query	A query parameter has an invalid type or value, returned before any 404 check, so a malformed include_zero or entry_type always yields 400 regardless of whether the customer key exists
403	insufficient_scope	API key lacks store_credit.read
404	not_found	No store credit balance record exists for that customer key

See Errors for the full error envelope format.