---
title: Quickstart
description: Go from zero to a working credit-based billing flow in seven API calls.
---

# 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 at https://quotastack.io 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:

```bash
export QS_KEY="qs_test_your_key_here"
```

## 1. Create a customer

Register a customer using your own ID. QuotaStack creates a credit account automatically.

```bash
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.

```bash
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 — each `api_call` costs 1 credit (1,000 millicredits):

```bash
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 grant creates an immutable credit block.

```bash
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?" Read-only, Redis-backed (~50 ms P99).

```bash
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.

```bash
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"
  }'
```

Response: `202 Accepted`. 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):

```bash
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

- **Idempotency:** Derive keys from business events (payment IDs, request IDs), not random UUIDs. See [Idempotency](/docs/concepts/idempotency.md).
- **Pick your use case:** [SaaS Subscription](/docs/use-cases/saas-subscription.md), [Consumer AI Subscription](/docs/use-cases/consumer-ai-subscription.md), [AI Chat App](/docs/use-cases/ai-chat-app.md), [AI Generation App](/docs/use-cases/ai-generation-app.md), [AI Agent Company](/docs/use-cases/ai-agent-company.md), [API Platform](/docs/use-cases/api-platform.md).
- **Reservations:** For expensive or variable-cost operations, reserve first, then commit or release. See [Reservations](/docs/concepts/reservations.md).
- **Webhooks:** Balance-low alerts and subscription lifecycle events. See [Webhooks](/docs/concepts/webhooks.md).
- **OpenAPI spec:** Full type-correct spec at https://quotastack.io/openapi.yaml (76 endpoints).