> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quotamint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a test project and make your first usage decision

This guide uses the QuotaMint dashboard and runtime API together. It ends with one `consume` request that is safe to retry.

## Before you begin

You need:

* A QuotaMint workspace and project
* A test API key (`qm_test_...`)
* A customer with an active plan
* A feature entitled by that plan
* The runtime base URL from **Developers** in the dashboard

## 1. Create a project

Create a project in the dashboard. Keep separate projects when test and live balances must never mix. A project owns its customers, plans, features, API keys, and usage.

Open **Settings → Projects** to confirm the project slug and default environment.

## 2. Add a plan and feature

Create a plan such as `pro` and give it a monthly credit allocation. Then create a metered feature:

* Key: `generate_image`
* Type: `CREDIT`
* Credit cost: `10`

Add the feature to the `pro` entitlement matrix. A customer can only consume an active feature on an active plan.

## 3. Create a customer and assign the plan

Customers are identified by your own stable ID. Create the customer in the dashboard and assign the `pro` plan. Example IDs are opaque strings such as `user_123` or `org_acme`.

## 4. Create a test key

Open **API keys**, choose **Test**, and create a key. Copy the secret immediately; QuotaMint returns it once and does not store the plaintext.

```bash theme={null}
export QUOTAMINT_URL="https://runtime.example.com"
export QUOTAMINT_TEST_KEY="qm_test_replace_me"
```

Never ship a test or live key to a browser bundle. Send runtime requests from your server.

## 5. Check without changing anything

`check` is useful for previews and UI hints. It does not reserve or consume credits.

```bash theme={null}
curl -sS -X POST "$QUOTAMINT_URL/v1/check" \
  -H "Authorization: Bearer $QUOTAMINT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"user_123","feature":"generate_image","quantity":1}'
```

```json theme={null}
{
  "allowed": true,
  "customerId": "user_123",
  "feature": "generate_image",
  "quantity": 1,
  "requiredCredits": 10,
  "creditsRemaining": 500
}
```

## 6. Consume atomically

Call `consume` immediately before the billable work. The idempotency key should identify the business operation, not the HTTP attempt.

```bash theme={null}
curl -sS -X POST "$QUOTAMINT_URL/v1/consume" \
  -H "Authorization: Bearer $QUOTAMINT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId":"user_123",
    "feature":"generate_image",
    "quantity":1,
    "idempotencyKey":"image_job_8472",
    "metadata":{"requestId":"req_123"}
  }'
```

```json theme={null}
{
  "allowed": true,
  "customerId": "user_123",
  "feature": "generate_image",
  "quantity": 1,
  "creditsUsed": 10,
  "creditsRemaining": 490
}
```

If the call is retried with the same key and payload, QuotaMint returns the original response without charging again. Read [idempotency](/guides/idempotency) before adding retry middleware.

<Note>
  QuotaMint exposes a plain REST API — there is no SDK to install. See
  [calling QuotaMint from any language](/guides/rest-api-any-language) for copyable request patterns
  in eight backend languages.
</Note>

<Warning>
  Do not use `check` followed by `consume` as an authorization transaction. Another request can spend the balance between the two calls. `consume` is the authoritative decision.
</Warning>

## Next steps

<CardGroup cols={3}>
  <Card title="Integrate from any language" href="/guides/rest-api-any-language">
    Node.js, Python, Go, Java, PHP, Ruby, C#, and Rust working against the same REST contract.
  </Card>

  <Card title="Sync billing changes" href="/guides/customers-plans">
    Keep Stripe, Razorpay, or another billing provider as the source of payment truth.
  </Card>

  <Card title="Handle retries" href="/guides/idempotency">
    Choose stable keys and understand replay and conflict behavior.
  </Card>

  <Card title="Track non-credit usage" href="/api/events">
    Record tokens, seconds, documents, or other project-defined metrics.
  </Card>

  <Card title="Go live safely" href="/production/security">
    Separate keys, add a denial path to your product.
  </Card>
</CardGroup>