Skip to main content
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:
  1. Create an account — pass a customer_id and you’re done.
  2. Credit or debit — one API call to add or remove units.
  3. 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

FeatureDetail
Any unitCredits, gems, stars, points — you name them, we track them
Full historyEvery change is recorded. You can always see what happened and why
Safe retriesEvery write requires an idempotency_key — retry without fear of double-counting
Reference trackingLink every transaction to your own events with a reference field
Large numbersAmounts are strings — no overflow, no matter the scale

​
Account states

StatusCan 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.