Quickstart

Go from zero to a working credit-based billing flow in seven API calls. By the end you'll have a customer with credits, a billable metric with pricing, and a usage event that debits the balance.

Time: ~5 minutes. All calls use the test environment — nothing touches production.

Prerequisites

A QuotaStack account — sign up if you don't have one.
Your test API key (qs_test_...) from the dashboard.
curl or any HTTP client.

Set your key once so you can copy-paste the commands below:

export QS_KEY="qs_test_your_key_here"

1. Create a customer

curl -X POST https://api.quotastack.io/v1/customers \
  -H "X-API-Key: $QS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-customer-1" \
  -d '{
    "external_id": "user_quickstart",
    "display_name": "Quickstart User"
  }'

2. Define a metric

A billable metric is the unit you charge for — API calls, messages, generations, anything. Create one:

curl -X POST https://api.quotastack.io/v1/billable-metrics \
  -H "X-API-Key: $QS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-metric-1" \
  -d '{
    "key": "api_call",
    "name": "API Call",
    "description": "One API request."
  }'

3. Set pricing

Attach a metering rule that says each api_call costs 1 credit (1,000 millicredits):

curl -X POST https://api.quotastack.io/v1/metering-rules \
  -H "X-API-Key: $QS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-rule-1" \
  -d '{
    "billable_metric_key": "api_call",
    "cost_type": "per_unit",
    "unit_cost": 1000
  }'

4. Grant credits

Give the customer 100 credits (100,000 millicredits). Every credit grant creates an immutable credit block.

curl -X POST https://api.quotastack.io/v1/customer-by-external-id/user_quickstart/credits/grant \
  -H "X-API-Key: $QS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-grant-1" \
  -d '{
    "credits": 100000,
    "source": "promotional",
    "reason": "Quickstart welcome credits"
  }'

5. Check entitlement

Before doing work, ask: "Can this customer afford 1 API call?" The entitlement check is read-only and Redis-backed (~50 ms P99).

curl https://api.quotastack.io/v1/customer-by-external-id/user_quickstart/entitlements/api_call \
  -H "X-API-Key: $QS_KEY"

You'll see "allowed": true and the current balance.

6. Record usage

The customer made an API call. Record it — QuotaStack looks up the metering rule, computes the cost, and debits the right credit blocks.

curl -X POST https://api.quotastack.io/v1/usage \
  -H "X-API-Key: $QS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-usage-1" \
  -d '{
    "external_customer_id": "user_quickstart",
    "billable_metric_key": "api_call",
    "units": 1,
    "idempotency_key": "quickstart-event-1"
  }'

The response comes back 202 Accepted immediately. The debit happens asynchronously — typically within milliseconds.

7. Verify the balance

Check the balance after the usage event is processed. It should settle at 99,000 mc (100,000 minus the 1,000 mc debit):

curl https://api.quotastack.io/v1/customer-by-external-id/user_quickstart/credits \
  -H "X-API-Key: $QS_KEY"

That's it. You've created a customer, defined what you charge for, granted credits, gated access, and recorded usage — the complete billing loop.

Next steps

Add idempotency keys to every mutation. You already did — every call above has one. Derive them from business events (payment IDs, request IDs), not random UUIDs. See Idempotency.
Pick the use case that matches your product. Each one is a complete walkthrough: SaaS Subscription, Consumer AI Subscription, AI Chat App, AI Generation App, AI Agent Company, API Platform.
Use reservations for expensive operations. If the work takes seconds or the cost is variable, reserve first, then commit or release. See Reservations.
Set up webhooks for balance-low alerts and subscription lifecycle events. See Webhooks.
Install the AI editor rule so your IDE knows QuotaStack's API patterns. One-click install.