meterbase 0.4.1__tar.gz → 0.5.0__tar.gz

{meterbase-0.4.1 → meterbase-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.4.1
+Version: 0.5.0
 Summary: Python SDK for the Meterbase engine
 Project-URL: Homepage, https://meterbase.tech
 Project-URL: Documentation, https://meterbase.tech/docs
@@ -750,6 +750,213 @@ for grant in paid.data:  # the grant the payment made, or none
     meterbase.customers.allowances.revoke(customer.id, grant.id)
 ```
 
+## Billing
+
+Once the workspace has connected Stripe or Dodo Payments under **Payments** in
+the dashboard, and bound its plans and packs to Stripe prices or Dodo products,
+Meterbase sells them: it opens the checkout, receives the provider's webhooks,
+and moves the customer's plan or grants the pack. There is no webhook handler of
+yours in between. These calls go to the service at
+`https://service.meterbase.tech` rather than the engine, with the same API key;
+see [Options](#options). There each API key has three limits, whichever
+customers the calls are for: `billing.checkout` and `billing.state` have 30
+requests per 10 s each, and `purchases` has 120 per 10 s. All calls from one IP
+address share 300 per 10 s on top. A 429 there raises `RateLimitError` with
+`retry_after`, once the retries a `GET` or a keyed checkout gets have run out;
+`purchases.wait` keeps waiting instead.
+
+A Dodo Payments subscription made outside Meterbase's checkout, from a buy link
+or your own server, is held until you link it to its customer once under
+**Payments**: anyone with a buy link can name a customer, so Meterbase trusts
+only a name its own checkout signed. Give each Dodo subscription product a
+Subscription Period longer than its billing period, such as 10 years: with the
+two equal, Dodo Payments ends the subscription after one charge.
+
+### Checkout
+
+```python
+session = meterbase.billing.checkout(
+    "acct_1",  # the tenant's own id
+    plan="pro",  # the plan's key; or pack="tokens_200k", quantity=2
+    success_url="https://app.example.com/billing/done",
+    cancel_url="https://app.example.com/pricing",
+)
+redirect(session.url)
+```
+
+Give exactly one of `plan` or `pack`, and `quantity` only with a pack. A pack is
+named as the pack offers from [`billing.state`](#a-customers-billing) name it:
+by its price's lookup key, or by the price id when it has none. Dodo Payments
+has no lookup keys, so there it is the product id, which differs between test
+and live mode: take it from the offer, chosen by
+[what it grants](#a-customers-billing). A plan bound at more than one interval
+sells its first bound price, unless `price` names another: a plan offer's
+`price.id` or `price.lookup_key`. `checkout` reuses the provider's customer
+already linked to the customer, and a customer Meterbase has not seen yet is
+created when their purchase is applied. `success_url` is https, or http on
+localhost; Meterbase adds `session_id`, its own opaque id for the checkout, to
+it. The session expires at `session.expires_at`: an hour after it opens on
+Stripe, and 24 hours on Dodo Payments.
+
+A plan's checkout opens a new subscription, so it is for a customer without a
+paying one. For a customer whose subscription pays and is not cancelling
+(`billing.status` is `active`, `trialing` or `past_due` in their
+[state](#a-customers-billing), and `cancel_at_period_end` is false), it raises
+`ConflictError` with `code == "already_subscribed"`. There is no plan-change
+call yet: a customer who already pays changes plan or interval in the provider's
+customer portal, so link there for their `upgrade`, `downgrade` and
+`switch_interval` offers. A customer whose subscription is cancelling can check
+out a new one, which takes over when the old one ends; its purchase reads `held`
+until then.
+
+Set the portal up once per mode, on the provider's side, and give it only the
+prices or products you bound: a subscription moved onto any other is held for
+review under **Payments**.
+
+- **Stripe:** under Settings → Billing → Customer portal, turn on **Switch
+  plan**, add the bound products and prices, and save. Then **Activate link**,
+  and link to the login link it gives (`https://billing.stripe.com/p/login/…`),
+  where the customer signs in with the email they paid with. In test mode,
+  open a customer's portal from their page in the Stripe Dashboard.
+- **Dodo Payments:** put the bound subscription products in one Product
+  Collection, since the portal changes plans only within one, and turn on
+  **Allow Subscription Updates** under Settings → Subscriptions. Link to
+  `https://customer.dodopayments.com/login/{business_id}`, where the customer
+  asks for a sign-in link by the email they paid with. Test mode sends no
+  sign-in emails, so there your server makes a session with your Dodo key:
+  `POST /customers/{customer_id}/customer-portal/session`, with the
+  `customer.customer_id` of `GET /subscriptions/{id}`, for the
+  `billing.subscription_id` in their [state](#a-customers-billing).
+
+A checkout is never retried unless it is given an `idempotency_key`, 1 to 200
+printable ASCII characters with no spaces. Until the session expires, a repeat
+with the same key answers that session rather than opening another when it
+names the same customer, plan or pack, price and quantity, and raises
+`IdempotencyKeyReusedError` (409 `idempotency_key_reused`) otherwise. The return
+URLs stay the first request's. Once the session expires, the key opens a new
+one. What each call can raise is under [Billing errors](#billing-errors).
+
+### The return page
+
+The provider can send the customer back before its webhook has arrived, so the
+return page waits for the purchase to land. Dodo Payments adds query parameters
+of its own, such as `status`; they prove nothing about payment, so read the
+purchase by `session_id`:
+
+```python
+purchase = meterbase.purchases.wait(request.args["session_id"], timeout=15)
+
+if purchase is None:
+    ...  # no checkout has that session_id
+elif purchase.state in ("waiting", "settling"):
+    ...  # still on its way: show "Confirming your payment"
+elif purchase.state in ("fulfilled", "late", "held"):
+    ...  # paid; only "fulfilled" means the plan or the pack is in place
+else:
+    ...  # "failed" or "expired": nothing was bought
+```
+
+| `state`     | Meaning                                                                   |
+| ----------- | ------------------------------------------------------------------------- |
+| `waiting`   | the checkout is open, or it was paid and is not applied yet               |
+| `settling`  | paid by a method that clears later, such as a bank debit                  |
+| `fulfilled` | the plan or the pack is in place                                          |
+| `late`      | paid over 90 s ago and still not applied: the customer can close the page |
+| `held`      | paid, and held for review under **Payments** in the dashboard             |
+| `failed`    | the payment failed                                                        |
+| `expired`   | the checkout closed unpaid                                                |
+
+`wait` reads the purchase every `interval` seconds, 2 unless set, for up to
+`timeout` seconds, 90 unless set, and returns as soon as the state is anything
+but `waiting` or `settling`. Running out of time is not an error: it returns
+the last read, so show a purchase still pending as pending, and read it again
+from the page. Many hosts cut a request off before 90 s, so a wait inside the
+page's request passes a shorter `timeout`, as above. It returns `None` when the
+purchase was never found, which means no checkout has that id, as with an
+edited link. A 404 reads as waiting, in case the provider does not show a new
+session yet. A `RateLimitError` reads as waiting too, with the next read after
+its `retry_after` when that is longer than `interval`, since every return page
+on one key shares the 120 reads per 10 s.
+`timeout` bounds the polling, not each read, which keeps the client's own
+timeout and retries. A negative or NaN `timeout`, an `interval` that is not
+above 0, or an empty session id raises `MeterbaseError` and sends nothing.
+`purchases.retrieve` reads it once.
+
+### A customer's billing
+
+```python
+state = meterbase.billing.state("acct_1")
+
+state.plan  # BillingPlan(key="pro", name="Pro"), or None
+if state.billing and state.billing.status == "past_due":
+    print("Payment failing, next retry:", state.billing.next_retry_at)  # None on Dodo
+for offer in state.offers:
+    print(offer.action, offer.plan or offer.pack, offer.price.unit_amount)
+```
+
+One read for a pricing or account page: the plan and its `period`, a change
+waiting to land (`pending_change`), each meter the plan meters (`allowances`),
+the open grants beside it, purchased packs included (`grants`), the provider's
+subscription the plan follows (`billing`, `None` when there is none), and every
+bound price on offer. A customer Meterbase has not seen yet reads as one with no
+plan, every plan offer an `upgrade`, so a pricing page can show a new visitor
+what to buy before they buy. A customer that was deleted raises `NotFoundError`
+(404 `customer_not_found`).
+
+`billing.status` reads the same on both providers, with a cancelled or expired
+subscription `ended`. Dodo Payments has no `trialing`, since a trial reads
+`active`, and its `on_hold` reads as `unpaid`; `next_retry_at` and `lookup_key`
+are always `None` there.
+
+An offer's `action` is `current`, `switch_interval` for the same plan billed
+over another interval, `upgrade` or `downgrade` by price per month against the
+current plan, or `purchase` for a pack. A plan offer is sold to a customer
+without a paying subscription with `checkout(..., plan=offer.plan,
+price=offer.price.id)`, and a pack offer with `pack=offer.pack`. New actions can
+be added; treat one you do not know as unavailable. `price.unit_amount` is the
+price as listed, in the currency's minor unit, cents for USD. Dodo Payments adds
+tax at checkout, by the buyer's location, unless the product's price is tax
+inclusive, so a Dodo Payments buyer can pay more than the offer shows.
+
+A pack offer's `grant` is what one pack gives: `amount` on the meter whose key
+is `meter`, twice that for `quantity=2`, expiring `expires_days` after the
+payment, or never when that is `None`. A plan offer's `grant` is `None`. Choose
+a pack by its grant rather than by name, telling two packs on one meter apart
+by `amount`: Dodo Payments has no lookup keys, and its product ids differ
+between test and live mode.
+
+```python
+top_up = next(
+    (o for o in state.offers if o.grant and o.grant.meter == "ai_tokens"), None
+)
+# top_up.grant == {"meter": "ai_tokens", "amount": 200_000, "expires_days": 90}
+
+if top_up and top_up.pack:
+    session = meterbase.billing.checkout(
+        "acct_1",
+        pack=top_up.pack,
+        success_url="https://app.example.com/billing/done",
+    )
+```
+
+### Billing errors
+
+| `code`                   | Raises                           | Calls               | When                                                                     |
+| ------------------------ | -------------------------------- | ------------------- | ------------------------------------------------------------------------ |
+| `unauthenticated`        | `AuthenticationError`, 401       | all                 | unknown, revoked or malformed key                                        |
+| `payments_not_connected` | `ConflictError`, 409             | all                 | the workspace has no payment provider connected                          |
+| `already_subscribed`     | `ConflictError`, 409             | `checkout`          | a plan checkout for a customer who already pays                          |
+| `customer_deleted`       | `ConflictError`, 409             | `checkout`          | the customer was deleted                                                 |
+| `idempotency_key_reused` | `IdempotencyKeyReusedError`, 409 | `checkout`          | the `idempotency_key` was used for a different checkout                  |
+| `customer_not_found`     | `NotFoundError`, 404             | `state`             | the customer was deleted                                                 |
+| `purchase_not_found`     | `NotFoundError`, 404             | `purchases`         | no checkout has that session id; `wait` reads it as waiting              |
+| `price_not_bound`        | `InvalidRequestError`, 422       | `checkout`          | the plan or pack has nothing bound, or `price` is not bound to the plan  |
+| `invalid_request`        | `InvalidRequestError`, 422       | `checkout`, `state` | a field failed validation; the message names it                          |
+| `rate_limited`           | `RateLimitError`, 429            | all                 | past a [limit](#billing), with `retry_after`; `wait` keeps waiting       |
+| `provider_error`         | `ServerError`, 502               | all                 | the provider refused or failed; the message says which                   |
+| `unavailable`            | `ServerError`, 503               | all                 | the connected key could not be opened: disconnect, then connect it again |
+| `engine_unavailable`     | `ServerError`, 503               | all                 | Meterbase could not be reached                                           |
+
 ## Webhooks
 
 Meterbase posts to your endpoints when a customer crosses a usage threshold,
@@ -920,13 +1127,13 @@ except RateLimitError as error:
 | `NotFoundError`                          | 404                                                                                                                                       |
 | `ConflictError`                          | 409 — a key or external id is taken                                                                                                       |
 | `PeriodSettlingError`                    | 409 — a `ConflictError`: the period ended under a minute ago, so read it again after `retry_after` seconds                                |
-| `IdempotencyKeyReusedError`              | 409 — a `ConflictError`: the `idempotency_key` on a grant or plan change was already used for a different request. Nothing was written    |
+| `IdempotencyKeyReusedError`              | 409 — a `ConflictError`: the `idempotency_key` on a grant, a plan change or a `billing.checkout` was already used for a different request. No grant or plan change was written, and no checkout opened |
 | `InvalidRequestError`                    | 422 — a field failed validation; or `400 invalid_query`, a query parameter that did                                                       |
 | `CycleChangeRequiresResetError`          | 422 — an `InvalidRequestError`: the two plans' cycles differ, so use `restart`                                                            |
 | `InvalidIdempotencyKeyError`             | 422 — an `InvalidRequestError`: the key was not a UUIDv7                                                                                  |
 | `TooLateError`                           | 422 — an `InvalidRequestError`: the key is over an hour from the engine's clock, which it carries on `server_time`. Nothing was recorded |
 | `ReservationMismatchError`               | 422 — an `InvalidRequestError`: the reservation was made for a different customer or meter                                                |
-| `RateLimitError`                         | 429 — `check` or `reserve` past the workspace's fair-use rate, `code == "rate_limited"`, with `retry_after` in seconds. `reserve` retries it for you; `check` raises at once, so fail open or closed |
+| `RateLimitError`                         | 429 — `check` or `reserve` past the workspace's fair-use rate, `code == "rate_limited"`, with `retry_after` in seconds. `reserve` retries it for you; `check` raises at once, so fail open or closed. Also a billing call past its [per-key limit](#billing), once a `GET` or a keyed checkout has retried it; `purchases.wait` keeps waiting |
 | `ServerError`                            | 5xx                                                                                                                                       |
 | `APIConnectionError` / `APITimeoutError` | the request never got an answer                                                                                                           |
 | `WebhookVerificationError`               | `verify_webhook`: not a delivery Meterbase signed in the last five minutes                                                                |
@@ -945,7 +1152,8 @@ SDK would raise for a response, for realistic errors in your own tests.
 ```python
 Meterbase(
     api_key="mb_sk_live_…",
-    base_url="https://api.meterbase.dev",
+    base_url="https://api.meterbase.tech",
+    billing_base_url="https://service.meterbase.tech",  # billing and purchases
     timeout=10.0,  # seconds, per attempt, on every call; unset, 35, and 3 for check
     max_retries=2,
     http_client=httpx.Client(proxy="http://localhost:8030"),  # yours to close
@@ -959,7 +1167,9 @@ milliseconds when the engine is well. Decide what an `APITimeoutError` means
 there — failing open or failing closed — rather than leaving the user waiting
 out the 35 s the writes get. Pass an `http_client` for proxies,
 limits or a transport of your own: an `httpx.Client` for `Meterbase`, an
-`httpx.AsyncClient` for `AsyncMeterbase`.
+`httpx.AsyncClient` for `AsyncMeterbase`. `billing` and `purchases` go to
+`billing_base_url`, `https://service.meterbase.tech` unless set, and every other
+call to `base_url`, over the same connections.
 
 For other settings on some calls, derive a client with them. It shares the
 original's connections, and its clock:
@@ -978,14 +1188,15 @@ cancelled `track` cannot record usage twice. A sync call cannot be cancelled;
 bound it with `timeout` and `max_retries` instead.
 
 **Retries** apply to `GET`, `DELETE`, `track`, `reserve`, `customers.ensure`,
-and a grant or plan change given an `idempotency_key`, on connection failures,
-timeouts, 408, 429 and 5xx, with exponential backoff and full jitter.
-`Retry-After` is honoured when the engine sends it, up to eight seconds. Every
-other `POST` and `PATCH` is never replayed, because a retried create could
-produce a second row. An `ensure` can be, because running it twice changes
-nothing: one whose first attempt landed answers `created` false. So can a keyed
-grant or plan change, which the engine answers with what the first attempt
-wrote: one whose first attempt landed answers `replayed` true.
+and a grant, plan change or `billing.checkout` given an `idempotency_key`, on
+connection failures, timeouts, 408, 429 and 5xx, with exponential backoff and
+full jitter. `Retry-After` is honoured when Meterbase sends it, up to eight
+seconds. Every other `POST` and `PATCH` is never replayed, because a retried
+create could produce a second row. An `ensure` can be, because running it twice
+changes nothing: one whose first attempt landed answers `created` false. So can
+a keyed grant or plan change, which the engine answers with what the first
+attempt wrote: one whose first attempt landed answers `replayed` true. A keyed
+checkout is answered by Meterbase with the session its first attempt opened.
 
 `track` and `reserve` are the exception because they carry an idempotency key,
 and because the SDK fixes that key **before** the retry loop starts: every
@@ -1014,6 +1225,12 @@ Pre-1.0, the minor version is where breaking changes land — deliberately, so a
 change that will not run against your code cannot arrive as a patch. The SDK
 follows the engine's API, as the TypeScript SDK (`mbase-sdk`) does.
 
+**0.5.0** adds `billing` and `purchases`, for a workspace that sells through
+Stripe or Dodo Payments: `billing.checkout`, `billing.state`,
+`purchases.retrieve` and `purchases.wait`, with the `billing_base_url` option.
+They go to the service at `https://service.meterbase.tech` rather than the
+engine. Nothing in it breaks code written for 0.4.0.
+
 **0.4.0** pages the customer list, and adds `customers.list_all` and the
 `limit`, `starting_after`, `plan` and `has_plan` parameters. One change can break
 code: `customers.list()` answers one page of 100, newest first, where it used to

{meterbase-0.4.1 → meterbase-0.5.0}/README.md

@@ -723,6 +723,213 @@ for grant in paid.data:  # the grant the payment made, or none
     meterbase.customers.allowances.revoke(customer.id, grant.id)
 ```
 
+## Billing
+
+Once the workspace has connected Stripe or Dodo Payments under **Payments** in
+the dashboard, and bound its plans and packs to Stripe prices or Dodo products,
+Meterbase sells them: it opens the checkout, receives the provider's webhooks,
+and moves the customer's plan or grants the pack. There is no webhook handler of
+yours in between. These calls go to the service at
+`https://service.meterbase.tech` rather than the engine, with the same API key;
+see [Options](#options). There each API key has three limits, whichever
+customers the calls are for: `billing.checkout` and `billing.state` have 30
+requests per 10 s each, and `purchases` has 120 per 10 s. All calls from one IP
+address share 300 per 10 s on top. A 429 there raises `RateLimitError` with
+`retry_after`, once the retries a `GET` or a keyed checkout gets have run out;
+`purchases.wait` keeps waiting instead.
+
+A Dodo Payments subscription made outside Meterbase's checkout, from a buy link
+or your own server, is held until you link it to its customer once under
+**Payments**: anyone with a buy link can name a customer, so Meterbase trusts
+only a name its own checkout signed. Give each Dodo subscription product a
+Subscription Period longer than its billing period, such as 10 years: with the
+two equal, Dodo Payments ends the subscription after one charge.
+
+### Checkout
+
+```python
+session = meterbase.billing.checkout(
+    "acct_1",  # the tenant's own id
+    plan="pro",  # the plan's key; or pack="tokens_200k", quantity=2
+    success_url="https://app.example.com/billing/done",
+    cancel_url="https://app.example.com/pricing",
+)
+redirect(session.url)
+```
+
+Give exactly one of `plan` or `pack`, and `quantity` only with a pack. A pack is
+named as the pack offers from [`billing.state`](#a-customers-billing) name it:
+by its price's lookup key, or by the price id when it has none. Dodo Payments
+has no lookup keys, so there it is the product id, which differs between test
+and live mode: take it from the offer, chosen by
+[what it grants](#a-customers-billing). A plan bound at more than one interval
+sells its first bound price, unless `price` names another: a plan offer's
+`price.id` or `price.lookup_key`. `checkout` reuses the provider's customer
+already linked to the customer, and a customer Meterbase has not seen yet is
+created when their purchase is applied. `success_url` is https, or http on
+localhost; Meterbase adds `session_id`, its own opaque id for the checkout, to
+it. The session expires at `session.expires_at`: an hour after it opens on
+Stripe, and 24 hours on Dodo Payments.
+
+A plan's checkout opens a new subscription, so it is for a customer without a
+paying one. For a customer whose subscription pays and is not cancelling
+(`billing.status` is `active`, `trialing` or `past_due` in their
+[state](#a-customers-billing), and `cancel_at_period_end` is false), it raises
+`ConflictError` with `code == "already_subscribed"`. There is no plan-change
+call yet: a customer who already pays changes plan or interval in the provider's
+customer portal, so link there for their `upgrade`, `downgrade` and
+`switch_interval` offers. A customer whose subscription is cancelling can check
+out a new one, which takes over when the old one ends; its purchase reads `held`
+until then.
+
+Set the portal up once per mode, on the provider's side, and give it only the
+prices or products you bound: a subscription moved onto any other is held for
+review under **Payments**.
+
+- **Stripe:** under Settings → Billing → Customer portal, turn on **Switch
+  plan**, add the bound products and prices, and save. Then **Activate link**,
+  and link to the login link it gives (`https://billing.stripe.com/p/login/…`),
+  where the customer signs in with the email they paid with. In test mode,
+  open a customer's portal from their page in the Stripe Dashboard.
+- **Dodo Payments:** put the bound subscription products in one Product
+  Collection, since the portal changes plans only within one, and turn on
+  **Allow Subscription Updates** under Settings → Subscriptions. Link to
+  `https://customer.dodopayments.com/login/{business_id}`, where the customer
+  asks for a sign-in link by the email they paid with. Test mode sends no
+  sign-in emails, so there your server makes a session with your Dodo key:
+  `POST /customers/{customer_id}/customer-portal/session`, with the
+  `customer.customer_id` of `GET /subscriptions/{id}`, for the
+  `billing.subscription_id` in their [state](#a-customers-billing).
+
+A checkout is never retried unless it is given an `idempotency_key`, 1 to 200
+printable ASCII characters with no spaces. Until the session expires, a repeat
+with the same key answers that session rather than opening another when it
+names the same customer, plan or pack, price and quantity, and raises
+`IdempotencyKeyReusedError` (409 `idempotency_key_reused`) otherwise. The return
+URLs stay the first request's. Once the session expires, the key opens a new
+one. What each call can raise is under [Billing errors](#billing-errors).
+
+### The return page
+
+The provider can send the customer back before its webhook has arrived, so the
+return page waits for the purchase to land. Dodo Payments adds query parameters
+of its own, such as `status`; they prove nothing about payment, so read the
+purchase by `session_id`:
+
+```python
+purchase = meterbase.purchases.wait(request.args["session_id"], timeout=15)
+
+if purchase is None:
+    ...  # no checkout has that session_id
+elif purchase.state in ("waiting", "settling"):
+    ...  # still on its way: show "Confirming your payment"
+elif purchase.state in ("fulfilled", "late", "held"):
+    ...  # paid; only "fulfilled" means the plan or the pack is in place
+else:
+    ...  # "failed" or "expired": nothing was bought
+```
+
+| `state`     | Meaning                                                                   |
+| ----------- | ------------------------------------------------------------------------- |
+| `waiting`   | the checkout is open, or it was paid and is not applied yet               |
+| `settling`  | paid by a method that clears later, such as a bank debit                  |
+| `fulfilled` | the plan or the pack is in place                                          |
+| `late`      | paid over 90 s ago and still not applied: the customer can close the page |
+| `held`      | paid, and held for review under **Payments** in the dashboard             |
+| `failed`    | the payment failed                                                        |
+| `expired`   | the checkout closed unpaid                                                |
+
+`wait` reads the purchase every `interval` seconds, 2 unless set, for up to
+`timeout` seconds, 90 unless set, and returns as soon as the state is anything
+but `waiting` or `settling`. Running out of time is not an error: it returns
+the last read, so show a purchase still pending as pending, and read it again
+from the page. Many hosts cut a request off before 90 s, so a wait inside the
+page's request passes a shorter `timeout`, as above. It returns `None` when the
+purchase was never found, which means no checkout has that id, as with an
+edited link. A 404 reads as waiting, in case the provider does not show a new
+session yet. A `RateLimitError` reads as waiting too, with the next read after
+its `retry_after` when that is longer than `interval`, since every return page
+on one key shares the 120 reads per 10 s.
+`timeout` bounds the polling, not each read, which keeps the client's own
+timeout and retries. A negative or NaN `timeout`, an `interval` that is not
+above 0, or an empty session id raises `MeterbaseError` and sends nothing.
+`purchases.retrieve` reads it once.
+
+### A customer's billing
+
+```python
+state = meterbase.billing.state("acct_1")
+
+state.plan  # BillingPlan(key="pro", name="Pro"), or None
+if state.billing and state.billing.status == "past_due":
+    print("Payment failing, next retry:", state.billing.next_retry_at)  # None on Dodo
+for offer in state.offers:
+    print(offer.action, offer.plan or offer.pack, offer.price.unit_amount)
+```
+
+One read for a pricing or account page: the plan and its `period`, a change
+waiting to land (`pending_change`), each meter the plan meters (`allowances`),
+the open grants beside it, purchased packs included (`grants`), the provider's
+subscription the plan follows (`billing`, `None` when there is none), and every
+bound price on offer. A customer Meterbase has not seen yet reads as one with no
+plan, every plan offer an `upgrade`, so a pricing page can show a new visitor
+what to buy before they buy. A customer that was deleted raises `NotFoundError`
+(404 `customer_not_found`).
+
+`billing.status` reads the same on both providers, with a cancelled or expired
+subscription `ended`. Dodo Payments has no `trialing`, since a trial reads
+`active`, and its `on_hold` reads as `unpaid`; `next_retry_at` and `lookup_key`
+are always `None` there.
+
+An offer's `action` is `current`, `switch_interval` for the same plan billed
+over another interval, `upgrade` or `downgrade` by price per month against the
+current plan, or `purchase` for a pack. A plan offer is sold to a customer
+without a paying subscription with `checkout(..., plan=offer.plan,
+price=offer.price.id)`, and a pack offer with `pack=offer.pack`. New actions can
+be added; treat one you do not know as unavailable. `price.unit_amount` is the
+price as listed, in the currency's minor unit, cents for USD. Dodo Payments adds
+tax at checkout, by the buyer's location, unless the product's price is tax
+inclusive, so a Dodo Payments buyer can pay more than the offer shows.
+
+A pack offer's `grant` is what one pack gives: `amount` on the meter whose key
+is `meter`, twice that for `quantity=2`, expiring `expires_days` after the
+payment, or never when that is `None`. A plan offer's `grant` is `None`. Choose
+a pack by its grant rather than by name, telling two packs on one meter apart
+by `amount`: Dodo Payments has no lookup keys, and its product ids differ
+between test and live mode.
+
+```python
+top_up = next(
+    (o for o in state.offers if o.grant and o.grant.meter == "ai_tokens"), None
+)
+# top_up.grant == {"meter": "ai_tokens", "amount": 200_000, "expires_days": 90}
+
+if top_up and top_up.pack:
+    session = meterbase.billing.checkout(
+        "acct_1",
+        pack=top_up.pack,
+        success_url="https://app.example.com/billing/done",
+    )
+```
+
+### Billing errors
+
+| `code`                   | Raises                           | Calls               | When                                                                     |
+| ------------------------ | -------------------------------- | ------------------- | ------------------------------------------------------------------------ |
+| `unauthenticated`        | `AuthenticationError`, 401       | all                 | unknown, revoked or malformed key                                        |
+| `payments_not_connected` | `ConflictError`, 409             | all                 | the workspace has no payment provider connected                          |
+| `already_subscribed`     | `ConflictError`, 409             | `checkout`          | a plan checkout for a customer who already pays                          |
+| `customer_deleted`       | `ConflictError`, 409             | `checkout`          | the customer was deleted                                                 |
+| `idempotency_key_reused` | `IdempotencyKeyReusedError`, 409 | `checkout`          | the `idempotency_key` was used for a different checkout                  |
+| `customer_not_found`     | `NotFoundError`, 404             | `state`             | the customer was deleted                                                 |
+| `purchase_not_found`     | `NotFoundError`, 404             | `purchases`         | no checkout has that session id; `wait` reads it as waiting              |
+| `price_not_bound`        | `InvalidRequestError`, 422       | `checkout`          | the plan or pack has nothing bound, or `price` is not bound to the plan  |
+| `invalid_request`        | `InvalidRequestError`, 422       | `checkout`, `state` | a field failed validation; the message names it                          |
+| `rate_limited`           | `RateLimitError`, 429            | all                 | past a [limit](#billing), with `retry_after`; `wait` keeps waiting       |
+| `provider_error`         | `ServerError`, 502               | all                 | the provider refused or failed; the message says which                   |
+| `unavailable`            | `ServerError`, 503               | all                 | the connected key could not be opened: disconnect, then connect it again |
+| `engine_unavailable`     | `ServerError`, 503               | all                 | Meterbase could not be reached                                           |
+
 ## Webhooks
 
 Meterbase posts to your endpoints when a customer crosses a usage threshold,
@@ -893,13 +1100,13 @@ except RateLimitError as error:
 | `NotFoundError`                          | 404                                                                                                                                       |
 | `ConflictError`                          | 409 — a key or external id is taken                                                                                                       |
 | `PeriodSettlingError`                    | 409 — a `ConflictError`: the period ended under a minute ago, so read it again after `retry_after` seconds                                |
-| `IdempotencyKeyReusedError`              | 409 — a `ConflictError`: the `idempotency_key` on a grant or plan change was already used for a different request. Nothing was written    |
+| `IdempotencyKeyReusedError`              | 409 — a `ConflictError`: the `idempotency_key` on a grant, a plan change or a `billing.checkout` was already used for a different request. No grant or plan change was written, and no checkout opened |
 | `InvalidRequestError`                    | 422 — a field failed validation; or `400 invalid_query`, a query parameter that did                                                       |
 | `CycleChangeRequiresResetError`          | 422 — an `InvalidRequestError`: the two plans' cycles differ, so use `restart`                                                            |
 | `InvalidIdempotencyKeyError`             | 422 — an `InvalidRequestError`: the key was not a UUIDv7                                                                                  |
 | `TooLateError`                           | 422 — an `InvalidRequestError`: the key is over an hour from the engine's clock, which it carries on `server_time`. Nothing was recorded |
 | `ReservationMismatchError`               | 422 — an `InvalidRequestError`: the reservation was made for a different customer or meter                                                |
-| `RateLimitError`                         | 429 — `check` or `reserve` past the workspace's fair-use rate, `code == "rate_limited"`, with `retry_after` in seconds. `reserve` retries it for you; `check` raises at once, so fail open or closed |
+| `RateLimitError`                         | 429 — `check` or `reserve` past the workspace's fair-use rate, `code == "rate_limited"`, with `retry_after` in seconds. `reserve` retries it for you; `check` raises at once, so fail open or closed. Also a billing call past its [per-key limit](#billing), once a `GET` or a keyed checkout has retried it; `purchases.wait` keeps waiting |
 | `ServerError`                            | 5xx                                                                                                                                       |
 | `APIConnectionError` / `APITimeoutError` | the request never got an answer                                                                                                           |
 | `WebhookVerificationError`               | `verify_webhook`: not a delivery Meterbase signed in the last five minutes                                                                |
@@ -918,7 +1125,8 @@ SDK would raise for a response, for realistic errors in your own tests.
 ```python
 Meterbase(
     api_key="mb_sk_live_…",
-    base_url="https://api.meterbase.dev",
+    base_url="https://api.meterbase.tech",
+    billing_base_url="https://service.meterbase.tech",  # billing and purchases
     timeout=10.0,  # seconds, per attempt, on every call; unset, 35, and 3 for check
     max_retries=2,
     http_client=httpx.Client(proxy="http://localhost:8030"),  # yours to close
@@ -932,7 +1140,9 @@ milliseconds when the engine is well. Decide what an `APITimeoutError` means
 there — failing open or failing closed — rather than leaving the user waiting
 out the 35 s the writes get. Pass an `http_client` for proxies,
 limits or a transport of your own: an `httpx.Client` for `Meterbase`, an
-`httpx.AsyncClient` for `AsyncMeterbase`.
+`httpx.AsyncClient` for `AsyncMeterbase`. `billing` and `purchases` go to
+`billing_base_url`, `https://service.meterbase.tech` unless set, and every other
+call to `base_url`, over the same connections.
 
 For other settings on some calls, derive a client with them. It shares the
 original's connections, and its clock:
@@ -951,14 +1161,15 @@ cancelled `track` cannot record usage twice. A sync call cannot be cancelled;
 bound it with `timeout` and `max_retries` instead.
 
 **Retries** apply to `GET`, `DELETE`, `track`, `reserve`, `customers.ensure`,
-and a grant or plan change given an `idempotency_key`, on connection failures,
-timeouts, 408, 429 and 5xx, with exponential backoff and full jitter.
-`Retry-After` is honoured when the engine sends it, up to eight seconds. Every
-other `POST` and `PATCH` is never replayed, because a retried create could
-produce a second row. An `ensure` can be, because running it twice changes
-nothing: one whose first attempt landed answers `created` false. So can a keyed
-grant or plan change, which the engine answers with what the first attempt
-wrote: one whose first attempt landed answers `replayed` true.
+and a grant, plan change or `billing.checkout` given an `idempotency_key`, on
+connection failures, timeouts, 408, 429 and 5xx, with exponential backoff and
+full jitter. `Retry-After` is honoured when Meterbase sends it, up to eight
+seconds. Every other `POST` and `PATCH` is never replayed, because a retried
+create could produce a second row. An `ensure` can be, because running it twice
+changes nothing: one whose first attempt landed answers `created` false. So can
+a keyed grant or plan change, which the engine answers with what the first
+attempt wrote: one whose first attempt landed answers `replayed` true. A keyed
+checkout is answered by Meterbase with the session its first attempt opened.
 
 `track` and `reserve` are the exception because they carry an idempotency key,
 and because the SDK fixes that key **before** the retry loop starts: every
@@ -987,6 +1198,12 @@ Pre-1.0, the minor version is where breaking changes land — deliberately, so a
 change that will not run against your code cannot arrive as a patch. The SDK
 follows the engine's API, as the TypeScript SDK (`mbase-sdk`) does.
 
+**0.5.0** adds `billing` and `purchases`, for a workspace that sells through
+Stripe or Dodo Payments: `billing.checkout`, `billing.state`,
+`purchases.retrieve` and `purchases.wait`, with the `billing_base_url` option.
+They go to the service at `https://service.meterbase.tech` rather than the
+engine. Nothing in it breaks code written for 0.4.0.
+
 **0.4.0** pages the customer list, and adds `customers.list_all` and the
 `limit`, `starting_after`, `plan` and `has_plan` parameters. One change can break
 code: `customers.list()` answers one page of 100, newest first, where it used to