Skip to main content
Customer Credits is in Experimental preview.

​
What is an account?

An account holds a credit balance for one customer. Think of it as a digital wallet — you create it, add credits to it, and debit from it when the customer uses them. Most customers need just one account. But you can create multiple per customer for different purposes:

loyalty_points

Earned from purchases

referral_credits

Earned from inviting friends

promo_credits

Given during campaigns

​
Creating accounts

Pass a customer_id and you’re done. Everything else is optional. 
curl -X POST https://api.creem.io/v1/customer-credits/accounts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "name": "loyalty_points",
    "unit_label": "points",
    "initial_balance": "100"
  }'

{
  "id": "cca_7kXmR2pQ9vN",
  "store_id": "store_xxx",
  "customer_id": "cust_abc123",
  "name": "loyalty_points",
  "unit_label": "points",
  "status": "active",
  "created_at": "2026-04-14T12:00:00.000Z",
  "updated_at": "2026-04-14T12:00:00.000Z"
}

​
Options

ParameterTypeRequiredDescription
customer_idstring✅The customer this account belongs to
namestringA label for this account. Default: "default". Unique per customer
unit_labelstringWhat to call the units — “points”, “gems”, “credits”. Default: "credits"
initial_balancestringSeed the account with credits on creation
If you set initial_balance and the initial credit fails, the account isn’t created either. No orphaned accounts.

​
Checking balance

One call to see what’s available. 
curl https://api.creem.io/v1/customer-credits/accounts/{account_id}/balance \
  -H "x-api-key: YOUR_API_KEY"

{
  "balance": "5000",
  "updated_at": "2026-04-14T14:30:00.000Z"
}

​
Point-in-time balance

Need to know what the balance was last Tuesday? Pass an at parameter. 
curl "https://api.creem.io/v1/customer-credits/accounts/{account_id}/balance?at=2026-04-01T00:00:00.000Z" \
  -H "x-api-key: YOUR_API_KEY"

{
  "balance": "3000",
  "as_of": "2026-04-01T00:00:00.000Z"
}

​
Listing accounts

# All accounts in your store
curl https://api.creem.io/v1/customer-credits/accounts \
  -H "x-api-key: YOUR_API_KEY"

# For a specific customer
curl "https://api.creem.io/v1/customer-credits/accounts?customer_id=cust_abc123" \
  -H "x-api-key: YOUR_API_KEY"
Supports cursor-based pagination with limit, starting_after, and ending_before.

​
Getting a single account

curl https://api.creem.io/v1/customer-credits/accounts/{account_id} \
  -H "x-api-key: YOUR_API_KEY"

​
Account lifecycle

Accounts have three states. You can move between them as needed.

​
Freeze — pause an account

Temporarily block all credits and debits. The account stays readable. 
curl -X POST https://api.creem.io/v1/customer-credits/accounts/{account_id}/freeze \
  -H "x-api-key: YOUR_API_KEY"

​
Unfreeze — resume an account

curl -X POST https://api.creem.io/v1/customer-credits/accounts/{account_id}/unfreeze \
  -H "x-api-key: YOUR_API_KEY"

​
Close — permanently retire an account

Balance and history stay readable forever, but no new transactions are allowed. 
curl -X POST https://api.creem.io/v1/customer-credits/accounts/{account_id}/close \
  -H "x-api-key: YOUR_API_KEY"
Closing is permanent. If you might need the account later, freeze it instead.
StatusCan credit/debit?Can read?Use case
active✅✅Default
frozen❌✅Temporarily paused
closed❌✅Permanent

​
Next steps

Transactions

Credit, debit, reverse, and view history.

Recipes

Step-by-step guides for common patterns.

API Reference

Full endpoint schemas.

Introduction

Back to overview.