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

# Billing

> Plans, subscriptions, taking a card payment, and invoices — the dollar path for self-serve products.

The [Quickstart](/documentation/getting-started/setup) ran the credit path with no card. This page covers the **dollar path**: what a plan is, how a customer subscribes and pays, and where the invoice lands. It's written for self-serve (PLG) products — subscriptions a customer starts themselves and pays by card.

## The catalog

You sell **plans**, which live under a **product**. A plan carries:

* **Charges** — the price (a `$20/month` recurring charge, a usage charge, a one-off).
* **Entitlements** — the features the plan unlocks, read by [`check`](/documentation/how-it-works#the-two-verbs).
* **Grant rules** — optional [credit grants](/documentation/credits/grants-and-priority) that refill each cycle.

Create them with the catalog API (`POST /v1/products`, `POST /v1/plans`) or let [Asterix](/documentation/ai-setup) build the whole catalog from your pricing page.

## Subscribing and paying

You always subscribe the same way — `POST /v1/subscriptions` — and the response tells you how money moved. It's a single **outcome** object discriminated by `kind`:

| `kind`              | When                                        | What you do                                                       |
| ------------------- | ------------------------------------------- | ----------------------------------------------------------------- |
| `created_no_charge` | Free/\$0 plan, or trial with no card        | Nothing — the subscription is active.                             |
| `charged_inline`    | Paid plan **and** a card already on file    | Nothing — the card was charged and the first invoice is **paid**. |
| `requires_form`     | Paid plan, **no card yet**                  | Collect a card in the browser, then it settles.                   |
| `deferred`          | Change scheduled for later (e.g. downgrade) | Applies at the next cycle.                                        |

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

### Collecting the first card

The first card-on-file is collected in the **browser** with Stripe Elements — a card number can't be sent to the API directly. When `POST /v1/subscriptions` returns `requires_form`, it includes a client secret; mount the React SDK's payment form with it, and the subscription settles once the card is confirmed (a webhook provisions the subscription, invoice, and any credits).

```tsx theme={null}
import { useCreateSubscription } from '@unitpay/react';

const { createSubscription } = useCreateSubscription({
  onChargedInline: () => alert('Subscribed and paid ✓'),
  onRequiresForm: (r) => setFormClient(r.client), // render <PaymentForm> with this
  onCreated: () => alert('Subscription active.'),
});

createSubscription({ planId: 'pln_pro' });
```

Once a card is saved, later charges — renewals, plan changes, and [credit top-ups](/documentation/credits/top-ups) — are `charged_inline` automatically, no form needed. See the [React SDK](/react/introduction) for the full checkout UI.

<Note>
  In sandbox, use Stripe's test card `4242 4242 4242 4242` with any future expiry and any CVC.
</Note>

## Invoices

When a paid subscription settles, UnitPay creates an **invoice** and auto-charges the card (`collectionMethod: "charge_automatically"`). Read a customer's invoices, filtered by status:

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

Fetch one for its line items and payments:

```bash theme={null}
curl https://api.useunitpay.com/v1/invoices/inv_123 \
  -H "x-api-key: $UNITPAY_SECRET_KEY"
```

Renewals bill automatically each cycle. If a renewal charge fails, the subscription goes `past_due` and the open invoice can be paid with `POST /v1/invoices/:id/pay`.

## Next steps

<CardGroup cols={2}>
  <Card title="Credits & top-ups" icon="coins" href="/documentation/credits/top-ups">
    Sell credit packages and refill balances — same card-on-file flow.
  </Card>

  <Card title="React SDK" icon="react" href="/react/introduction">
    Pricing table, checkout, and the payment form.
  </Card>

  <Card title="How it works" icon="diagram-project" href="/documentation/how-it-works">
    The two paths and the two verbs.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/documentation/getting-started/setup">
    The credit path, end to end.
  </Card>
</CardGroup>