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

# Quickstart

> Set up a catalog, subscribe a customer, and watch credits burn — end to end in minutes.

This quickstart runs the **credit path** end to end: you'll set up a catalog, put a customer on a plan that grants credits, spend some, and watch the balance and ledger update. Every step is a real API call — no card needed. When you're ready to charge cards and issue invoices, see [Billing](/documentation/billing).

<Note>
  You'll need a **secret key** (`upay_sk_…`) from the [dashboard](https://app.useunitpay.com) and the base URL `https://api.useunitpay.com/v1`. See [Authentication](/documentation/authentication).
</Note>

<Steps>
  <Step title="Set up your catalog">
    Your catalog needs a **credit currency**, a **plan** that grants credits, and a **feature** to spend them on. The fastest way is to let [Asterix](/documentation/ai-setup) build it from your pricing page:

    ```bash theme={null}
    curl https://api.useunitpay.com/v1/onboarding \
      -H "x-api-key: $UNITPAY_SECRET_KEY" \
      -H "content-type: application/json" \
      -d '{ "url": "https://yourcompany.com/pricing" }'
    ```

    Or build it by hand — a credit currency (`POST /v1/credit-currencies`) and a **free plan** with a monthly credit grant rule (`POST /v1/plans`). See [Billing](/documentation/billing) for the catalog API and [Credits](/documentation/credits/grants-and-priority) for grant rules.

    <Check>
      For this walkthrough you need a **free plan** (`$0`) that grants credits each cycle and a **feature** (e.g. `ai-generation`) that costs credits — so nothing has to be charged to see credits move.
    </Check>
  </Step>

  <Step title="Create a customer">
    The customer's id is your own user or org id — pass your own `externalId` if you like.

    ```bash theme={null}
    curl https://api.useunitpay.com/v1/customers \
      -H "x-api-key: $UNITPAY_SECRET_KEY" \
      -H "content-type: application/json" \
      -d '{ "name": "Acme", "email": "dev@acme.test" }'
    ```

    ```json Response theme={null}
    { "id": "cus_123", "name": "Acme", "email": "dev@acme.test" }
    ```
  </Step>

  <Step title="Subscribe them to the plan">
    Put the customer on your free plan. Because it's `$0`, the subscription is created with no charge and the plan's credits are granted on activation.

    ```bash theme={null}
    curl https://api.useunitpay.com/v1/subscriptions \
      -H "x-api-key: $UNITPAY_SECRET_KEY" \
      -H "content-type: application/json" \
      -d '{ "customerId": "cus_123", "planId": "pln_free" }'
    ```

    ```json Response theme={null}
    { "kind": "created_no_charge", "subscription": { "id": "sub_123", "status": "active" } }
    ```

    <Note>
      Self-serve subscriptions default to `salesMotion: "self_serve"` and `collectionMethod: "charge_automatically"`. On a **paid** plan the response is `charged_inline` (card charged, first invoice paid) or `requires_form` (collect a card in the browser first) — that's the [Billing](/documentation/billing) flow.
    </Note>
  </Step>

  <Step title="Check the balance">
    Confirm the credits landed. `check` is a read — it never changes state.

    ```bash theme={null}
    curl https://api.useunitpay.com/v1/check \
      -H "x-api-key: $UNITPAY_SECRET_KEY" \
      -H "content-type: application/json" \
      -d '{ "customerId": "cus_123", "featureSlug": "ai-generation", "requestedUsage": 1 }'
    ```

    ```json Response theme={null}
    { "access": true, "remaining": 100, "creditBalance": 100 }
    ```
  </Step>

  <Step title="Track usage — spend credits">
    Report that the customer used the feature. UnitPay resolves the credit cost and deducts it. This is the write that moves credits.

    <CodeGroup>
      ```bash curl theme={null}
      curl https://api.useunitpay.com/v1/usage/track \
        -H "x-api-key: $UNITPAY_SECRET_KEY" \
        -H "content-type: application/json" \
        -d '{ "events": [{ "customerId": "cus_123", "eventName": "ai-generation", "quantity": 10 }] }'
      ```

      ```ts Node theme={null}
      import { UnitPay } from '@unitpay/node';
      const unitpay = new UnitPay({ apiKey: process.env.UNITPAY_SECRET_KEY });

      await unitpay.track({ customerId: 'cus_123', eventName: 'ai-generation', quantity: 10 });
      ```
    </CodeGroup>

    ```json Response theme={null}
    { "accepted": 1, "rejected": 0, "results": [{ "status": "ok", "flow": "credit", "creditsDeducted": "10", "creditBalance": "90" }] }
    ```
  </Step>

  <Step title="See it in the ledger">
    The balance is derived from the [ledger](/documentation/credits/wallets-and-ledger) — an append-only record of every grant and deduction. Read it back:

    ```bash theme={null}
    curl "https://api.useunitpay.com/v1/credit-ledger?customerId=cus_123" \
      -H "x-api-key: $UNITPAY_SECRET_KEY"
    ```

    You'll see the plan grant (`+100`) and your usage deduction (`−10`), with the running balance at `90`. The live per-wallet balance is at `GET /v1/credit-accounts?customerId=cus_123`.

    <Check>
      Credits granted → consumed → recorded. That's the whole credit path working end to end.
    </Check>
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Charge cards & invoices" icon="credit-card" href="/documentation/billing">
    Paid plans, the card-on-file flow, and invoices.
  </Card>

  <Card title="Credits in depth" icon="coins" href="/documentation/credits/overview">
    Denominations, grant priority, wallets, and top-ups.
  </Card>

  <Card title="Build the UI" icon="react" href="/react/introduction">
    Render balances, gates, and checkout with the React hooks.
  </Card>

  <Card title="How it works" icon="diagram-project" href="/documentation/how-it-works">
    The model behind both billing paths.
  </Card>
</CardGroup>