API docs

Gift certificates

Permission: gift_certificates (read / write).

GET /v1/gift-certificates. Filters: code (dashes and case ignored), status, purchaser_customer_id, updated_since, limit, cursor.

GET /v1/gift-certificates/{id} also returns the last 50 ledger rows as transactions (kind, amount_cents, balance_after_cents, note, created_at).

curl "https://app.blackbeachpos.com/api/v1/gift-certificates?code=WE-7K2M-9QXA" -H "Authorization: Bearer $KEY"

{
  "object": "gift_certificate",
  "id": 58,
  "code": "WE-7K2M-9QXA",
  "status": "active",
  "source": "pos",
  "initial_cents": 10000,
  "balance_cents": 6450,
  "purchaser_customer_id": 1166,
  "recipient_name": "Sam Reyes",
  "recipient_email": "sam@example.com",
  "expires_on": null,
  "issued_at": "2026-08-30T20:11:00Z",
  "updated_at": "2026-09-21T18:40:00Z"
}

status is one of active, depleted, disabled, expired. source is pos or bigcommerce.

Issue a certificate

POST /v1/gift-certificates — for a certificate sold on another channel. It becomes a real code in Black Beach POS, spendable at the counter, and mirrors to BigCommerce like one sold at the register.

Field	Notes
`amount_cents`	Required, 500 to 200000 ($5 to $2,000)
`code`	Optional; a code is generated when omitted. `409` if taken
`recipient_name`, `recipient_email`, `message`	Optional
`purchaser_customer_id` or `purchaser_name` / `purchaser_email`	Optional
`expires_on`	Optional `YYYY-MM-DD`
`location_id`	Optional; the store credited with the sale
`reference`	Optional; your order id, kept in the ledger note

curl -X POST https://app.blackbeachpos.com/api/v1/gift-certificates \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: etsy-gc-3381920" \
  -d '{"amount_cents": 5000, "recipient_name": "Sam Reyes", "recipient_email": "sam@example.com", "reference": "ETSY-3381920"}'

Returns 201 with the certificate and its first ledger row.

Redeem and reverse

POST /v1/gift-certificates/{id}/redeem spends from the balance; POST /v1/gift-certificates/{id}/reverse gives an amount back (a refund on your side). Body: { "amount_cents": 1000, "reference": "ORDER-4410" }.

An Idempotency-Key header is required on every move of value — redeem, reverse, reload and adjust (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.
Find the id from a code with GET /v1/gift-certificates?code=….
422 GIFT_CERTIFICATE_INSUFFICIENT when the balance is short (details.balance_cents); 422 GIFT_CERTIFICATE_INACTIVE when the certificate is disabled or expired.
The response is the certificate plus transaction, the ledger row just written.

Reload and adjust

POST /v1/gift-certificates/{id}/reload adds value: { "amount_cents": 2500, "reference": "TOPUP-88" }. It's refused on a disabled or expired certificate (422 GIFT_CERTIFICATE_INACTIVE).

POST /v1/gift-certificates/{id}/adjust corrects the balance either way. amount_cents is signed (negative removes value) and a reason is required:

curl -X POST https://app.blackbeachpos.com/api/v1/gift-certificates/42/adjust \
  -H "Authorization: Bearer ir_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: adj-42-20260925" \
  -d '{"amount_cents": -1000, "reason": "Price-match correction"}'

An Idempotency-Key header is required on both, as on redeem and reverse.
An adjustment can't take the balance below zero (422 GIFT_CERTIFICATE_INSUFFICIENT).
The response is the certificate plus transaction, the ledger row just written (kind reload or adjustment).

Disable and enable

POST /v1/gift-certificates/{id}/disable with { "reason": "…" } stops it being spent; POST /v1/gift-certificates/{id}/enable turns it back on (an expired certificate can't be re-enabled).