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

# Usage-based and per-seat pricing

> Charge subscribers per team member or per unit of usage (API calls, exports, credits). Pocketsflow bills the overage at the end of every billing period.

Selling software? Price a subscription **per seat**, **per unit of usage**, or
both. Buyers pick their seats at checkout, your app reports usage through the
API, and at the end of each billing period Pocketsflow charges what was used
above the included amount, once, to the card the subscription already pays
with.

<Note>
  Usage-based pricing is part of the **Pro** plan and above. Below Pro the
  editor shows the section locked, and the API answers `403 FEATURE_LOCKED`.
</Note>

<Steps>
  <Step title="Set it up on the subscription">
    In the subscription editor, open **Usage & seats**. Turn on **Charge per
    seat** and/or **Charge for usage**, then add a meter (for example
    `api_calls`).
  </Step>

  <Step title="Sell">
    Buyers choose their seats on the checkout page. The subscription price is
    charged for those seats every period, like any subscription.
  </Step>

  <Step title="Report usage from your app">
    Call `POST /subscriptions/{id}/usage` with an API key whenever a
    subscriber uses something billable. Send an `idempotencyKey` so retries
    never count twice.
  </Step>

  <Step title="We bill the overage">
    When the period ends we total each meter, take off the included units,
    price the rest and charge it with one payment. You get a
    `usage.period_closed` webhook with the totals and the charge status.
  </Step>
</Steps>

## Per-seat pricing

* **Price** is the price of one seat. A buyer with 5 seats pays price × 5 every
  period.
* **Minimum / maximum seats** bound what buyers can pick at checkout and in
  their portal. Leave the maximum blank for no maximum (up to 10,000).
* **Adding seats** (from the buyer's portal, your dashboard or
  `POST /subscriptions/{id}/seats`) takes effect at once. Seats above the
  number bought at checkout are billed at the end of the period, **prorated**
  by the time they were held: two extra $12 seats added with 24 of 30 days
  left cost 2 × $12 × 24/30 = \$19.20.
* **Removing seats** works down to the number bought at checkout. The
  subscription price already covers those every period, so going lower means
  cancelling and subscribing again with fewer seats.
* **License keys.** Turn on **Issue a license key per subscriber** and each
  subscriber gets one [license key](/api-reference/license-keys) whose
  activation limit is their seat count. When seats change, the limit follows.
  When the subscription is canceled or expires the key stops validating, and
  it turns back on if the subscription resumes (a key you switched off
  yourself stays off).
  Your app validates the key with the usual license endpoints (the
  `productId` is the subscription offer id).

## Metered usage

A meter has:

| Setting | What it does |
| - | - |
| **Name** and **API key** | `API calls` / `api_calls`. The API key is what you send as `meter`. |
| **Unit** | What buyers see: `call`, `export`, `credit`. |
| **Price applies to** | Units per price. `1000` with a price of $1.00 means $1 per 1,000 calls, so sub-cent prices stay exact. |
| **Included each period** | Free units before any charge. |
| **Pricing** | **Per unit**, **Graduated tiers** or **Volume tiers** (below). |

All amounts are computed in integer cents and each line is rounded half up to
the cent once.

### Tiers

Tiers count **billable** units — what is left after the included units.

* **Graduated:** each tier prices the units that fall inside it. With tiers
  "up to 100,000 at $1 / 1,000" and "above at $0.50 / 1,000", 150,000 billable
  calls cost $100 + $25 = \$125.
* **Volume:** every unit is priced at the tier the period's total reaches. The
  same 150,000 calls cost 150 × $0.50 = $75.
* A tier's **flat fee** is added once when any unit lands in it.

<Note>
  Prices are copied onto each billing period when it opens, so a price change
  applies from the next period, never to usage already being counted.
</Note>

## Billing periods

Usage periods follow the subscription's renewal date (weekly 7 days, monthly
30 days, yearly 365 days). A report belongs to the period its `timestamp`
falls in; a period's end is exclusive. Once a period has closed, reports for it
are refused with `409 PERIOD_CLOSED`, so send usage promptly (or without a
`timestamp` to use the current time).

## How the overage is charged

* One off-session charge per period, to the card the subscription pays with,
  with the same platform fee as your other sales.
* Exactly once: a period can only close once, and the charge carries a fixed
  idempotency key, so a retry is always the same payment.
* A paid overage is a normal order: it appears in **Orders** and on the
  subscriber's payment history as **Usage** (`billingReason: "usage"`), the
  buyer gets a receipt, and it counts in your analytics. The platform fee is
  stored on the order like on any other sale. Integrations (webhooks, Zapier)
  get the same `invoice.payment_succeeded` event as a renewal, with
  `billingReason: "usage"`.
* If the card can't be charged the period shows **Failed**; if there is no
  saved card, payments are paused or the payouts account is missing it shows
  **Due**. Both are retried automatically **1, 3, 5 and 7 days** after the
  first failure — the same schedule as a failed renewal — each retry once.
  After the last one fails the overage is **Uncollectible**: we stop trying
  and email you. Unpaid amounts appear on the subscriber page as
  **Outstanding**, and the `usage.period_closed` webhook tells you the status
  so you can follow up (for example limit the account in your app).

## Where to see it

* **Subscriber page:** usage this period (a daily chart per meter), the line
  items with the upcoming overage, the seat changer and past periods with
  their charge status.
* **Buyer portal:** the subscriber sees usage this period, can add or remove
  seats (from the signed portal link) and sees their license key.
* **API / MCP:** `GET /subscriptions/{id}/usage` and the
  `get_subscription_usage` MCP tool return the same data.

## API

See [Usage billing API](/api-reference/usage-billing) for every endpoint with
curl and SDK examples, and [Webhook events](/api-webhooks/events#usage-billing-events)
for `usage.recorded` and `usage.period_closed`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.