Authdog Billing adds a subscription catalog to your environment: define plans and the features they grant, sell them through Stripe, and gate your application on the plan or feature a signed-in user holds. Subscriptions and entitlements live next to your users, so checking a plan is a local read, not a round trip to Stripe.

Billing runs on the environment's existing Stripe connection and supports one active subscription per subject.

## Prerequisites

Connect Stripe first, under **Authentication > Add-ons** in the [Authdog console](https://console.authdog.com). Billing reuses that connection — its secret key creates Products and Prices, and your checkout page initializes Stripe.js with its publishable key. There is no separate Billing credential.

Connect a Stripe test account to your development environment and the live account to production. Plans, features, and subscriptions never cross environments.

## Model

| Object | Meaning |
| --- | --- |
| **Feature** | A gateable capability, identified by a slug such as `advanced_reports`. |
| **Plan** | A purchasable bundle of features with a monthly price and an optional annual price. |
| **Subscription** | One subject's current plan, its period, and its Stripe status. |

A plan targets either a user or an organization (`forResource`), and slugs are unique within an environment. A feature's slug is what your application checks against, so treat it as frozen once it ships — renaming it revokes access for everyone holding it.

## Define plans

In the console, open **Billing > Plans** for the selected environment:

1. Add the features you want to gate on.
2. Create a plan: name, slug, description, and whether it is for a user or an organization.
3. Set the currency and the monthly amount, in cents. Add an annual amount only if you sell one — a plan can be month-only.
4. Attach the features the plan grants.
5. Choose whether the plan is publicly visible, whether it is the default, and its sort order in the pricing table.
6. Select **Sync to Stripe**.

Syncing creates or refreshes the plan's Stripe Product and its monthly and annual Prices. Stripe Prices are immutable, so changing an amount mints a new Price and leaves the old one in place — Stripe does not allow deleting a Price that has been used — and existing subscribers stay on the Price they bought until they change plans.

An unsynced plan has no Stripe Price and cannot be checked out.

## Client endpoints

Your application calls these on the Authdog identity origin, `https://identity.authdog.com`, or on your [custom domain](/docs/custom-domains) when one is configured.

| Endpoint | Auth | Purpose |
| --- | --- | --- |
| `GET /billing/:environmentId/plans` | None | Publicly visible plans, their features, and the Stripe publishable key. |
| `GET /billing/:environmentId/subscription` | Session | The caller's current subscription. |
| `POST /billing/:environmentId/subscriptions` | Session | Start a subscription; returns a client secret for payment confirmation. |
| `POST /billing/:environmentId/subscriptions/cancel` | Session | Cancel the caller's subscription. |

The plans endpoint is deliberately unauthenticated — a pricing page has to render before sign-in. It returns only plans marked publicly visible, and the publishable key, never a secret. Pass `?for=org` to list organization plans; the default is `user`.

Creating a subscription takes a `planId` and an optional `planPeriod` of `month` or `annual` (default `month`). The response carries a `clientSecret` your page confirms with Stripe Elements, so card details never touch Authdog.

```bash
curl -X POST "https://identity.authdog.com/billing/$ENVIRONMENT_ID/subscriptions" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "planId": "pln_123", "planPeriod": "annual" }'
```

## Gate your application

The React SDK ships the pieces for a pricing page and for gating:

- `PricingTable` renders plans with a month/annual toggle and a per-plan call to action.
- `CheckoutButton` starts checkout for a plan and period.
- `Protect` renders its children only when the caller holds the given plan or feature.
- `hasBillingAccess` exposes the same check as a plain function, for use outside JSX.

```tsx
import { Protect } from "@authdog/react-elements"

<Protect
  subscription={subscription}
  activeFeatures={features}
  feature="advanced_reports"
  fallback={<UpgradePrompt />}
>
  <AdvancedReports />
</Protect>
```

`Protect` is a pure conditional render over state you already fetched — it makes no network call of its own. And like every client-side gate, it decides what the interface shows, not what the API allows: enforce entitlements again on your server before doing the paid work.

## Staying in sync with Stripe

Stripe's webhook is the source of truth for subscription state: it updates the stored status, current period end, and cancellation flag, and refreshes the entitlement cache for the plan's features. Feature slugs double as Stripe entitlement lookup keys, so a feature check reads the same cache that backs entitlement claims.

A subscription starts as `incomplete` and turns `active` once payment succeeds. Never grant access on the checkout response alone — wait for the subscription to report an active status.

Configure the Stripe webhook for the same account you connected, and verify a full purchase in a test environment before enabling live payments.

## Limits

- One active subscription per subject, per environment.
- Checkout accepts user plans only. Organization plans can be defined and listed with `?for=org`, but a subscription request for one is rejected.
- Amounts are integer cents in the plan's currency. A plan has a single currency.

## Related

- [Integrations](/docs/integrations)
- [Organizations](/docs/organizations)
- [Users](/docs/users)
- [JWT claims](/docs/jwt-claims)