Customer Credits

Customer Credits is in Experimental preview. The API is stable but may receive additive changes.

What is Customer Credits?

Customer Credits lets you give your customers a balance they can earn and spend — points, gems, stars, or whatever fits your product. You add credits when something good happens (a purchase, a referral, a top-up). You remove credits when they’re used (a redemption, an API call, a feature unlock). Creem tracks everything and gives you a complete history. No database tables to design. No race conditions to debug. Just API calls.

Why use it?

AI & LLM Products

Sell credit packs for your AI product. Customers buy credits, each API call deducts from their balance. Different models can cost different amounts.

Loyalty & Rewards

Award points on purchases, let customers redeem them for discounts. Track earning and spending with full history.

Prepaid Balances

Let customers top up a balance and draw down against it for future purchases or service usage.

Referral Programs

Credit both sides automatically when a referred user converts. Track the full lifecycle.

Usage Metering

Allocate credit pools for API calls, compute hours, storage, or any metered resource. Debit on consumption.

Promotional Credits

Issue credits for marketing campaigns, seasonal offers, or beta incentives.

Goodwill & Compensation

Issue credits for service disruptions or support escalations — tracked and auditable.

How it works

Three steps:

Create an account — pass a customer_id and you’re done.
Credit or debit — one API call to add or remove units.
Check balance — instant lookup, always up to date.

Quick start

If you’re in test mode, use https://test-api.creem.io instead of https://api.creem.io. Learn more about Test Mode.

1. Create an account

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": "credits",
    "unit_label": "credits"
  }'

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

2. Add credits

curl -X POST https://api.creem.io/v1/customer-credits/accounts/cca_7kXmR2pQ9vN/credit \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500",
    "reference": "order_789",
    "idempotency_key": "reward_order_789"
  }'

3. Use credits

curl -X POST https://api.creem.io/v1/customer-credits/accounts/cca_7kXmR2pQ9vN/debit \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "200",
    "reference": "redemption_456",
    "idempotency_key": "redeem_456"
  }'

4. Check balance

curl https://api.creem.io/v1/customer-credits/accounts/cca_7kXmR2pQ9vN/balance \
  -H "x-api-key: YOUR_API_KEY"

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

Key features

Feature	Detail
Any unit	Credits, gems, stars, points — you name them, we track them
Full history	Every change is recorded. You can always see what happened and why
Safe retries	Every write requires an `idempotency_key` — retry without fear of double-counting
Reference tracking	Link every transaction to your own events with a `reference` field
Large numbers	Amounts are strings — no overflow, no matter the scale

Account states

Status	Can add/remove credits?	Can read?	Notes
`active`	✅	✅	Default
`frozen`	❌	✅	Temporarily paused
`closed`	❌	✅	Permanent. Balance and history stay readable

Next steps

Accounts

Create, list, freeze, and close accounts.

Transactions

Credit, debit, reverse, and view history.

Recipes

Step-by-step guides for common use cases.

API Reference

Full endpoint docs with schemas.

Get Started

AI

Features

Code

Integrations

Community

Merchant of Record

For Customers

Customer Credits

What is Customer Credits?

Why use it?

AI & LLM Products

Loyalty & Rewards

Prepaid Balances

Referral Programs

Usage Metering

Promotional Credits

Goodwill & Compensation

How it works

Quick start

1. Create an account

2. Add credits

3. Use credits

4. Check balance

Key features

Account states

Next steps

Accounts

Transactions

Recipes

API Reference

​What is Customer Credits?

​Why use it?

AI & LLM Products

Loyalty & Rewards

Prepaid Balances

Referral Programs

Usage Metering

Promotional Credits

Goodwill & Compensation

​How it works

​Quick start

​1. Create an account

​2. Add credits

​3. Use credits

​4. Check balance

​Key features

​Account states

​Next steps

Accounts

Transactions

Recipes

API Reference

What is Customer Credits?

Why use it?

How it works

Quick start

1. Create an account

2. Add credits

3. Use credits

4. Check balance

Key features

Account states

Next steps