Store Credit

Store credit is a monetary balance held on a customer’s account. Merchants can issue credit manually (goodwill, loyalty, compensation) or via refunds. Customers can spend their credit at checkout, reducing or replacing the card payment.

Credit balances are tracked in the store’s base currency as integer cents. Every mutation creates an immutable transaction record for auditability.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/customers/{id}/credit	Secret	Get customer credit balance
POST	/v1/customers/{id}/credit	Secret	Issue credit to customer
GET	/v1/customers/{id}/credit/transactions	Secret	List credit transactions
GET	/v1/me/credit	Customer	Get own credit balance
GET	/v1/me/credit/transactions	Customer	List own credit transactions

---

Get customer credit balance

GET /v1/customers/{id}/credit

Returns the current store credit balance for a customer.

Path parameters

Parameter	Type	Description
id	string	Customer ID (prefix: cus_)

Request

curl "https://api.hydrajs.dev/v1/customers/cus_abc123def456ghi789/credit" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": {
    "balance": 15000,
    "currency": "usd"
  }
}

---

Issue credit

POST /v1/customers/{id}/credit

Adds store credit to a customer account. The amount is added to the customer’s existing balance. Returns the transaction record.

Path parameters

Parameter	Type	Description
id	string	Customer ID (prefix: cus_)

Request body

Field	Type	Required	Description
amount	integer	Yes	Credit amount in cents (e.g. 10000 = $100.00)
note	string	No	Internal note about why credit was issued
expires_at	string	No	ISO 8601 datetime when credit expires (omit for non-expiring credit)
metadata	object	No	Arbitrary key-value pairs

Request

curl -X POST "https://api.hydrajs.dev/v1/customers/cus_abc123def456ghi789/credit" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "note": "Loyalty reward",
    "expires_at": "2027-06-30T23:59:59Z"
  }'

Response 201

{
  "data": {
    "id": "sct_abc123def456ghi789",
    "customer_id": "cus_abc123def456ghi789",
    "type": "credit",
    "amount": 10000,
    "balance_after": 25000,
    "reason": "manual",
    "note": "Loyalty reward",
    "related_order_id": null,
    "related_refund_id": null,
    "expires_at": "2027-06-30T23:59:59.000Z",
    "metadata": {},
    "created_at": "2026-09-06T14:30:00.000Z",
    "updated_at": "2026-09-06T14:30:00.000Z"
  }
}

---

List credit transactions

GET /v1/customers/{id}/credit/transactions

Returns a cursor-paginated list of store credit transactions for a customer. Includes credits (issued), debits (spent at checkout), and expiry events.

Path parameters

Parameter	Type	Description
id	string	Customer ID (prefix: cus_)

Query parameters

Parameter	Type	Description
limit	integer	Results per page (1-100, default 20)
cursor	string	Pagination cursor from a previous response
sort	string	Sort field: created_at (default), updated_at
order	string	Sort direction: asc, desc (default)

Request

curl "https://api.hydrajs.dev/v1/customers/cus_abc123def456ghi789/credit/transactions?limit=10" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
  "data": [
    {
      "id": "sct_abc123def456ghi789",
      "customer_id": "cus_abc123def456ghi789",
      "type": "debit",
      "amount": 5000,
      "balance_after": 20000,
      "reason": "order_payment",
      "note": null,
      "related_order_id": "ord_abc123def456ghi789",
      "related_refund_id": null,
      "expires_at": null,
      "metadata": {},
      "created_at": "2026-09-06T15:00:00.000Z",
      "updated_at": "2026-09-06T15:00:00.000Z"
    },
    {
      "id": "sct_def456ghi789abc123",
      "customer_id": "cus_abc123def456ghi789",
      "type": "credit",
      "amount": 10000,
      "balance_after": 25000,
      "reason": "manual",
      "note": "Loyalty reward",
      "related_order_id": null,
      "related_refund_id": null,
      "expires_at": "2027-06-30T23:59:59.000Z",
      "metadata": {},
      "created_at": "2026-09-06T14:30:00.000Z",
      "updated_at": "2026-09-06T14:30:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNi...",
    "has_more": false,
    "total": 2
  }
}

---

Checkout integration

Store credit can be applied at checkout to reduce the card payment amount. If the credit covers the entire order total, no card payment is needed and the checkout is completed directly.

Method	Path	Auth	Description
POST	/v1/checkout/{id}/credit	Publishable	Apply store credit to checkout
DELETE	/v1/checkout/{id}/credit	Publishable	Remove store credit from checkout
POST	/v1/checkout/{id}/complete	Publishable	Complete a fully credit-paid checkout

---

Customer self-service

Authenticated customers can view their own balance and transaction history via the /v1/me endpoints. These require a publishable API key and a customer JWT.

Method	Path	Auth	Description
GET	/v1/me/credit	Customer	Get own credit balance
GET	/v1/me/credit/transactions	Customer	List own credit transactions

---

Refund to store credit

When creating a refund, set destination to store_credit to add the refund amount to the customer’s store credit balance instead of reversing the card payment. See the Refunds API for details.

curl -X POST "https://api.hydrajs.dev/v1/orders/ord_abc123/refunds" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "reason": "goodwill",
    "destination": "store_credit"
  }'

---

Webhooks

Store credit changes fire the following webhook events:

Event	Trigger
store_credit.issued	Credit added (manual issue or refund-to-credit)
store_credit.used	Credit spent at checkout
store_credit.expired	Credit expired by the daily cron job

See Webhooks for subscription setup.

---

Credit expiration

Credits with an expires_at date are automatically expired by a daily cron job. When credits expire:

1. The customer’s balance is reduced by the expired amount (capped at current balance)
2. An expiry transaction is recorded
3. A store_credit.expired webhook is fired

---

Transaction types

Type	Description
credit	Balance increased (manual issue or refund)
debit	Balance decreased (used at checkout)
expiry	Balance decreased (credit expired)

---

Transaction reasons

Reason	Description
manual	Merchant issued credit manually
refund	Credit from a refund (destination: store_credit)
order_payment	Credit spent at checkout
expiry	Credit expired past its expiration date

---

The credit transaction object

Field	Type	Description
id	string	Unique ID (prefix: sct_)
customer_id	string	Customer this transaction belongs to
type	string	credit, debit, or expiry
amount	integer	Transaction amount in cents (always positive)
balance_after	integer	Customer’s balance after this transaction (cents)
reason	string	Why the transaction occurred (see table above)
note	string | null	Staff or system note
related_order_id	string | null	Associated order ID (for debits and refund credits)
related_refund_id	string | null	Associated refund ID (for refund credits)
expires_at	string | null	ISO 8601 expiration date (credit type only)
metadata	object	Arbitrary key-value pairs
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

The credit balance object

Field	Type	Description
balance	integer	Current balance in cents
currency	string	ISO 4217 currency code (e.g. usd)