Accounts

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

Parameter	Type	Required	Description
`customer_id`	string	✅	The customer this account belongs to
`name`	string		A label for this account. Default: `"default"`. Unique per customer
`unit_label`	string		What to call the units — “points”, “gems”, “credits”. Default: `"credits"`
`initial_balance`	string		Seed 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.

Status	Can 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.

Get Started

AI

Features

Code

Integrations

Community

Merchant of Record

For Customers

What is an account?

loyalty_points

referral_credits

promo_credits

Creating accounts

Options

Checking balance

Point-in-time balance

Listing accounts

Getting a single account

Account lifecycle

Freeze — pause an account

Unfreeze — resume an account

Close — permanently retire an account

Next steps

Transactions

Recipes

API Reference

Introduction

​What is an account?

loyalty_points

referral_credits

promo_credits

​Creating accounts

​Options

​Checking balance

​Point-in-time balance

​Listing accounts

​Getting a single account

​Account lifecycle

​Freeze — pause an account

​Unfreeze — resume an account

​Close — permanently retire an account

​Next steps

Transactions

Recipes

API Reference

Introduction

What is an account?

Creating accounts

Options

Checking balance

Point-in-time balance

Listing accounts

Getting a single account

Account lifecycle

Freeze — pause an account

Unfreeze — resume an account

Close — permanently retire an account

Next steps