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

# How UnitPay works

> One model behind both billing paths — and the two verbs your app calls at runtime.

UnitPay is the billing engine where **dollars and credits are both first-class**. You model **what you sell** once — a catalog of products, plans, and (optionally) credit currencies — attach customers to it, and report usage. From there, everything comes down to two ideas: the **path** value takes when it moves out, and the **two verbs** your app calls at runtime.

## The two paths

Usage flows down one of two paths. The difference is *when* money settles.

```mermaid actions={false} theme={null}
flowchart LR
    USE["**Usage** — you report what happened"]:::core
    USE --> DOLLAR["**Dollar billing** (invoice-time)<br/>aggregate → invoice → auto-charge → PSP"]:::dollar
    USE --> CREDIT["**Credit billing** (track-time)<br/>resolve charge → deduct FIFO → ledger"]:::credit

    classDef core fill:#7c3aed10,stroke:#7c3aed
    classDef dollar fill:#ec489920,stroke:#ec4899
    classDef credit fill:#22c55e20,stroke:#22c55e
```

|                 | **Dollar billing**                              | **Credit billing**                                   |
| --------------- | ----------------------------------------------- | ---------------------------------------------------- |
| When you charge | At invoice time — usage adds up, you bill later | At usage time — credits come off a balance instantly |
| The result      | An **invoice**, auto-charged to a card          | A **balance** that goes down and refills or tops up  |
| Feels like      | A monthly bill                                  | A prepaid wallet or an allowance                     |
| Classic for     | API metering                                    | AI products, packs, plan allowances                  |

You don't pick one for your whole business. You choose per plan, and a single plan can do both — a dollar price for the subscription *and* a credit grant that refills every cycle.

## The two verbs

At runtime your app only ever does two things: it **checks** whether a customer is allowed to do something, and it **tracks** that they did it.

```mermaid actions={false} theme={null}
flowchart LR
    C["**check** — is the customer allowed?<br/>(before the action)"]:::v --> ACT["your app does the work"]:::a
    ACT --> T["**track** — record what happened<br/>(after the action)"]:::v
    T --> SETTLE["credits deduct · usage meters · invoice accrues"]:::s
    classDef v fill:#22c55e15,stroke:#22c55e
    classDef a fill:#00302408,stroke:#003024
    classDef s fill:#ec489915,stroke:#ec4899
```

<Steps>
  <Step title="check — before the action">
    Ask UnitPay whether the customer has access before you do the work.

    ```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": 42, "creditBalance": 42, "feature": { "slug": "ai-generation", "type": "credit" } }
    ```

    `access` is `false` when the customer is out of balance or the feature isn't in their plan. In your UI, the React SDK does the same check synchronously — see [React SDK](/react/introduction).
  </Step>

  <Step title="track — after the action">
    Report what happened. UnitPay routes the event by how the plan is priced: it **deducts credits**, meters usage for a dollar invoice, or both.

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

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

<Note>
  `check` never changes state — it's a read. `track` is the write that moves money or credits. Track from your **server** with a secret key so usage can't be spoofed from the browser.
</Note>

## The objects you'll use

<CardGroup cols={2}>
  <Card title="Customer" icon="user">
    Whoever you bill. Their id is your own user or org id — no extra id to store.
  </Card>

  <Card title="Plan" icon="layer-group">
    What a customer subscribes to: a price, entitlements, and credit grants.
  </Card>

  <Card title="Entitlement / feature" icon="shield-halved">
    What a plan grants access to — what `check` reads.
  </Card>

  <Card title="Credit account & ledger" icon="wallet">
    A customer's wallet and the append-only record behind its balance.
  </Card>

  <Card title="Grant" icon="gift">
    One deposit of credits — from a plan, a drip, a promo, or a package.
  </Card>

  <Card title="Invoice" icon="file-invoice-dollar">
    The dollar bill, auto-charged to a card at settlement.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/documentation/getting-started/setup">
    Set up a catalog, subscribe a customer, and watch credits burn — end to end.
  </Card>

  <Card title="Credits" icon="coins" href="/documentation/credits/overview">
    The credit path in depth: grants, denominations, wallets, and top-ups.
  </Card>

  <Card title="Authentication" icon="key" href="/documentation/authentication">
    API keys, and the difference between sandbox and live.
  </Card>

  <Card title="Billing" icon="file-invoice-dollar" href="/documentation/billing">
    Plans, subscriptions, payments, and invoices on the dollar side.
  </Card>
</CardGroup>