meterbase 0.2.0__tar.gz → 0.3.0__tar.gz

{meterbase-0.2.0 → meterbase-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for the Meterbase engine
 Project-URL: Homepage, https://meterbase.tech
 Project-URL: Documentation, https://meterbase.tech/docs
@@ -363,9 +363,17 @@ Each crossing is delivered as a webhook; see [Webhooks](#webhooks).
 ```python
 meterbase.meters.create(key="api_calls", name="API calls")  # plus optional thresholds
 meters = meterbase.meters.list().data
+meterbase.meters.retrieve("api_calls")  # by key, or by id
 meterbase.meters.archive(meter_id)  # soft delete, idempotent
 ```
 
+A meter's key works wherever its id does: `retrieve`, `update`, `usage` and
+`archive`, `meter_id` on a grant or a plan allowance, and the `meter_id` filter
+on their lists. Code written against a sandbox then runs unchanged in live,
+where the ids differ. A key that names no meter raises `NotFoundError`. A
+canonical UUID is always read as an id, so creating or renaming a meter to a
+key shaped like one raises `InvalidRequestError`.
+
 ### Plans
 
 A plan has one billing period, fixed when the plan is created. Everything it
@@ -387,6 +395,11 @@ meterbase.plans.archive(plan.id)  # stops new assignments, keeps existing ones
 customers were already measured against, so a different cadence is a different
 plan — move a customer with `customers.plan.assign`.
 
+A plan's key works wherever its id does, on the same terms as a meter's:
+`plans.retrieve("pro")`, `plans.allowances.set("pro", ...)`, `plan_id` on
+`customers.plan.assign` and `plan` on each change. A key that names no plan
+raises `NotFoundError`, and a key shaped like a UUID is refused.
+
 ### Plan allowances
 
 What a plan grants, one meter at a time. An allowance says _how much_, never
@@ -416,6 +429,12 @@ versions = meterbase.plans.allowances.list(plan.id).data
 Each `(plan, meter)` pair carries up to two lineages, `recurring` and
 `one_time`, numbering themselves separately. `kind` defaults to `recurring`.
 
+`apply_mode` says when a version reaches customers already on the plan:
+`immediate`, for the whole period they are in, or `next_cycle`, at each one's
+next boundary. Omitted, a meter's first `recurring` version on the plan is
+`immediate`, since there is nothing to phase out, and every later one is
+`next_cycle`. `one_time` is always `immediate`.
+
 **A soft cap** keeps the amount and drops the refusal: included usage, then
 overage.
 
@@ -521,6 +540,26 @@ except CycleChangeRequiresResetError:
     meterbase.customers.plan.restart(customer.id, plan=weekly.id)
 ```
 
+#### From a webhook
+
+A provider may deliver a webhook twice, and a second `restart` would start a
+second fresh period. Pass the event's id as `idempotency_key`, 1–255
+characters, and a retry repeats nothing:
+
+```python
+moved = meterbase.customers.plan.restart(
+    customer.id, plan="pro", idempotency_key=event.id
+)
+moved.replayed  # True when this event had already moved them: nothing was written
+```
+
+`assign`, `change`, `change_now` and `change_at_next_cycle` take one too. The
+same request under the key again answers with the assignment it made, as it is
+now, and writes nothing — so a second delivery of an old event cannot cancel a
+change scheduled since. Another request under the key raises
+`IdempotencyKeyReusedError`. A key is kept for good, per workspace. With a key,
+the SDK retries the call too.
+
 #### Reading where they stand
 
 ```python
@@ -552,6 +591,11 @@ instruction, and writes no new row of its own — so this reads the plan in forc
 and names it back. It returns the assignment still in force, or `None` for a
 customer holding no plan, who can have nothing pending.
 
+It takes no `idempotency_key`: it names whatever plan is in force when it runs,
+so a retry could name a different one and be refused as a different request.
+For a cancel a webhook orders, `assign` the plan the event says they keep, under
+the event's id.
+
 #### How much they have used
 
 ```python
@@ -655,6 +699,37 @@ Revoking withdraws what is left without erasing what was consumed, and is
 idempotent. Grants the engine minted itself from a plan's `one_time` allowance
 appear here with `source="plan"`; they cannot be created through `grant`.
 
+**A grant made from a payment's webhook** takes the payment's id as its
+`idempotency_key`, 1–255 characters: the provider may deliver the webhook
+twice, and a retry under the key cannot grant twice.
+
+```python
+grant = meterbase.customers.allowances.grant(
+    customer.id,
+    meter_id="ai_tokens",
+    amount=500_000,
+    source="purchased",
+    idempotency_key=payment.id,
+)
+grant.replayed  # True when this payment had already granted: nothing was written
+```
+
+The same request under the key again answers with that grant as it is now,
+perhaps spent or revoked since, and writes nothing. Another request under the
+key raises `IdempotencyKeyReusedError`, so build the body the same way every
+time: compute `expires_at` from the payment's own time, not from when the
+handler ran. A key is kept for good, per workspace. With a key, the SDK retries
+the call too.
+
+To find what a payment granted — to take it back on a refund, say — list by its
+key. Once the grant is revoked or has expired, add `include_closed=True`.
+
+```python
+paid = meterbase.customers.allowances.list(customer.id, idempotency_key=payment.id)
+for grant in paid.data:  # the grant the payment made, or none
+    meterbase.customers.allowances.revoke(customer.id, grant.id)
+```
+
 ## Webhooks
 
 Meterbase posts to your endpoints when a customer crosses a usage threshold,
@@ -825,6 +900,7 @@ 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    |
 | `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                                                                                  |
@@ -881,13 +957,15 @@ an attempt already on the wire may still land, but it is never replayed, so a
 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` and
-`customers.ensure`, 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.
+**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.
 
 `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
@@ -916,6 +994,10 @@ 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.3.0** adds an `idempotency_key` on grants and plan changes, which also makes
+them safe to retry, `replayed` on their answers, and `IdempotencyKeyReusedError`.
+Nothing in it breaks code written for 0.2.0.
+
 **0.2.0** adds `customers.ensure` and `idempotency_key()`, and changes two
 behaviours:
 

{meterbase-0.2.0 → meterbase-0.3.0}/README.md

@@ -336,9 +336,17 @@ Each crossing is delivered as a webhook; see [Webhooks](#webhooks).
 ```python
 meterbase.meters.create(key="api_calls", name="API calls")  # plus optional thresholds
 meters = meterbase.meters.list().data
+meterbase.meters.retrieve("api_calls")  # by key, or by id
 meterbase.meters.archive(meter_id)  # soft delete, idempotent
 ```
 
+A meter's key works wherever its id does: `retrieve`, `update`, `usage` and
+`archive`, `meter_id` on a grant or a plan allowance, and the `meter_id` filter
+on their lists. Code written against a sandbox then runs unchanged in live,
+where the ids differ. A key that names no meter raises `NotFoundError`. A
+canonical UUID is always read as an id, so creating or renaming a meter to a
+key shaped like one raises `InvalidRequestError`.
+
 ### Plans
 
 A plan has one billing period, fixed when the plan is created. Everything it
@@ -360,6 +368,11 @@ meterbase.plans.archive(plan.id)  # stops new assignments, keeps existing ones
 customers were already measured against, so a different cadence is a different
 plan — move a customer with `customers.plan.assign`.
 
+A plan's key works wherever its id does, on the same terms as a meter's:
+`plans.retrieve("pro")`, `plans.allowances.set("pro", ...)`, `plan_id` on
+`customers.plan.assign` and `plan` on each change. A key that names no plan
+raises `NotFoundError`, and a key shaped like a UUID is refused.
+
 ### Plan allowances
 
 What a plan grants, one meter at a time. An allowance says _how much_, never
@@ -389,6 +402,12 @@ versions = meterbase.plans.allowances.list(plan.id).data
 Each `(plan, meter)` pair carries up to two lineages, `recurring` and
 `one_time`, numbering themselves separately. `kind` defaults to `recurring`.
 
+`apply_mode` says when a version reaches customers already on the plan:
+`immediate`, for the whole period they are in, or `next_cycle`, at each one's
+next boundary. Omitted, a meter's first `recurring` version on the plan is
+`immediate`, since there is nothing to phase out, and every later one is
+`next_cycle`. `one_time` is always `immediate`.
+
 **A soft cap** keeps the amount and drops the refusal: included usage, then
 overage.
 
@@ -494,6 +513,26 @@ except CycleChangeRequiresResetError:
     meterbase.customers.plan.restart(customer.id, plan=weekly.id)
 ```
 
+#### From a webhook
+
+A provider may deliver a webhook twice, and a second `restart` would start a
+second fresh period. Pass the event's id as `idempotency_key`, 1–255
+characters, and a retry repeats nothing:
+
+```python
+moved = meterbase.customers.plan.restart(
+    customer.id, plan="pro", idempotency_key=event.id
+)
+moved.replayed  # True when this event had already moved them: nothing was written
+```
+
+`assign`, `change`, `change_now` and `change_at_next_cycle` take one too. The
+same request under the key again answers with the assignment it made, as it is
+now, and writes nothing — so a second delivery of an old event cannot cancel a
+change scheduled since. Another request under the key raises
+`IdempotencyKeyReusedError`. A key is kept for good, per workspace. With a key,
+the SDK retries the call too.
+
 #### Reading where they stand
 
 ```python
@@ -525,6 +564,11 @@ instruction, and writes no new row of its own — so this reads the plan in forc
 and names it back. It returns the assignment still in force, or `None` for a
 customer holding no plan, who can have nothing pending.
 
+It takes no `idempotency_key`: it names whatever plan is in force when it runs,
+so a retry could name a different one and be refused as a different request.
+For a cancel a webhook orders, `assign` the plan the event says they keep, under
+the event's id.
+
 #### How much they have used
 
 ```python
@@ -628,6 +672,37 @@ Revoking withdraws what is left without erasing what was consumed, and is
 idempotent. Grants the engine minted itself from a plan's `one_time` allowance
 appear here with `source="plan"`; they cannot be created through `grant`.
 
+**A grant made from a payment's webhook** takes the payment's id as its
+`idempotency_key`, 1–255 characters: the provider may deliver the webhook
+twice, and a retry under the key cannot grant twice.
+
+```python
+grant = meterbase.customers.allowances.grant(
+    customer.id,
+    meter_id="ai_tokens",
+    amount=500_000,
+    source="purchased",
+    idempotency_key=payment.id,
+)
+grant.replayed  # True when this payment had already granted: nothing was written
+```
+
+The same request under the key again answers with that grant as it is now,
+perhaps spent or revoked since, and writes nothing. Another request under the
+key raises `IdempotencyKeyReusedError`, so build the body the same way every
+time: compute `expires_at` from the payment's own time, not from when the
+handler ran. A key is kept for good, per workspace. With a key, the SDK retries
+the call too.
+
+To find what a payment granted — to take it back on a refund, say — list by its
+key. Once the grant is revoked or has expired, add `include_closed=True`.
+
+```python
+paid = meterbase.customers.allowances.list(customer.id, idempotency_key=payment.id)
+for grant in paid.data:  # the grant the payment made, or none
+    meterbase.customers.allowances.revoke(customer.id, grant.id)
+```
+
 ## Webhooks
 
 Meterbase posts to your endpoints when a customer crosses a usage threshold,
@@ -798,6 +873,7 @@ 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    |
 | `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                                                                                  |
@@ -854,13 +930,15 @@ an attempt already on the wire may still land, but it is never replayed, so a
 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` and
-`customers.ensure`, 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.
+**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.
 
 `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
@@ -889,6 +967,10 @@ 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.3.0** adds an `idempotency_key` on grants and plan changes, which also makes
+them safe to retry, `replayed` on their answers, and `IdempotencyKeyReusedError`.
+Nothing in it breaks code written for 0.2.0.
+
 **0.2.0** adds `customers.ensure` and `idempotency_key()`, and changes two
 behaviours:
 

{meterbase-0.2.0 → meterbase-0.3.0}/src/meterbase/__init__.py

@@ -12,6 +12,7 @@ from .errors import (
     AuthenticationError,
     ConflictError,
     CycleChangeRequiresResetError,
+    IdempotencyKeyReusedError,
     InvalidIdempotencyKeyError,
     InvalidRequestError,
     MeterbaseError,
@@ -38,6 +39,7 @@ __all__ = [
     "ConflictError",
     "CycleChangeRequiresResetError",
     "Hold",
+    "IdempotencyKeyReusedError",
     "InvalidIdempotencyKeyError",
     "InvalidRequestError",
     "Meterbase",

{meterbase-0.2.0 → meterbase-0.3.0}/src/meterbase/_async/resources/customer_allowances.py

@@ -3,10 +3,10 @@ from __future__ import annotations
 from collections.abc import Mapping
 from typing import Any
 
-from ..._http import segment
+from ..._http import require_key_filter, segment
 from ..._models import ListResult, list_of
 from ..._not_given import NOT_GIVEN, NotGiven
-from ...types import Allowance, AllowanceSource
+from ...types import Allowance, AllowanceGrantResult, AllowanceSource
 from .._transport import AsyncRequester
 
 
@@ -31,20 +31,30 @@ class AsyncCustomerAllowances:
         metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
         effective_at: str | NotGiven = NOT_GIVEN,
         expires_at: str | NotGiven = NOT_GIVEN,
-    ) -> Allowance:
+        idempotency_key: str | NotGiven = NOT_GIVEN,
+    ) -> AllowanceGrantResult:
         """
-        Give exactly one of `amount` or `no_cap`. Unlike a plan allowance, a
-        grant of 0 is refused: a grant that gives nothing is a no-op, not a
-        state, so `amount` is at least 1.
+        `meter_id` is the meter's id or its key. Give exactly one of `amount`
+        or `no_cap`. Unlike a plan allowance, a grant of 0 is refused: a grant
+        that gives nothing is a no-op, not a state, so `amount` is at least 1.
 
         `source` is required: the engine will not guess why capacity was handed
         out. `effective_at` defaults to now; dated ahead, the grant is inert
         until then.
+
+        `idempotency_key`, 1–255 characters, makes a grant safe to retry. From
+        a webhook the provider may deliver twice, pass your own id for the
+        payment, and a retry cannot grant twice: the same request again
+        answers with that grant and `replayed=True`, and another one under the
+        key raises `IdempotencyKeyReusedError`. Build the body the same way on
+        every retry, with an `expires_at` computed from the payment's own time
+        rather than from when the handler ran. With a key, the SDK retries the
+        call too.
         """
         return await self._api.request(
             "POST",
             f"/v1/customers/{segment(customer_id)}/allowances",
-            Allowance,
+            AllowanceGrantResult,
             body={
                 "meter_id": meter_id,
                 "amount": amount,
@@ -53,7 +63,10 @@ class AsyncCustomerAllowances:
                 "metadata": metadata,
                 "effective_at": effective_at,
                 "expires_at": expires_at,
+                "idempotency_key": idempotency_key,
             },
+            # None goes out as null, which the engine reads as no key at all.
+            idempotent=isinstance(idempotency_key, str),
         )
 
     async def list(
@@ -61,15 +74,29 @@ class AsyncCustomerAllowances:
         customer_id: str,
         *,
         meter_id: str | NotGiven = NOT_GIVEN,
+        idempotency_key: str | NotGiven = NOT_GIVEN,
         include_closed: bool | NotGiven = NOT_GIVEN,
     ) -> ListResult[Allowance]:
-        """Open grants only, unless `include_closed`: revoked, expired and
-        exhausted grants as well."""
+        """
+        Every grant but revoked and expired ones, unless `include_closed`.
+        Exhausted grants and grants not yet open are listed either way.
+        `meter_id` is the meter's id or its key.
+
+        `idempotency_key` narrows it to the grant made under that key, or none:
+        how a refund finds what a payment granted. Once that grant is revoked
+        or has expired, only `include_closed` finds it. `None` raises before
+        sending, rather than listing every grant.
+        """
+        require_key_filter(idempotency_key)
         return await self._api.request(
             "GET",
             f"/v1/customers/{segment(customer_id)}/allowances",
             list_of(Allowance),
-            query={"meter_id": meter_id, "include_closed": include_closed},
+            query={
+                "meter_id": meter_id,
+                "idempotency_key": idempotency_key,
+                "include_closed": include_closed,
+            },
         )
 
     async def retrieve(self, customer_id: str, allowance_id: str) -> Allowance:

{meterbase-0.2.0 → meterbase-0.3.0}/src/meterbase/_async/resources/customer_plan.py

@@ -7,7 +7,7 @@ from ..._models import ListResult, list_of
 from ..._not_given import NOT_GIVEN, NotGiven
 from ..._time import parse_instant
 from ...errors import NotFoundError
-from ...types import ApplyMode, Assignment, Reconciliation
+from ...types import ApplyMode, Assignment, AssignPlanResult, Reconciliation
 from .._io import both
 from .._transport import AsyncRequester
 
@@ -23,7 +23,10 @@ class AsyncCustomerPlan:
     that picking one does not mean knowing what `effective` and
     `reconciliation` do to a half-used period. They name the plan `plan`
     rather than `plan_id`: they sit a layer above the wire, where `assign`
-    still mirrors it field for field.
+    still mirrors it field for field. Either takes the plan's id or its key.
+
+    Every move takes an `idempotency_key`, as `assign` describes, except
+    `cancel_scheduled_change`.
     """
 
     def __init__(self, api: AsyncRequester) -> None:
@@ -37,11 +40,13 @@ class AsyncCustomerPlan:
         effective: ApplyMode | NotGiven = NOT_GIVEN,
         reconciliation: Reconciliation | NotGiven = NOT_GIVEN,
         cycle_anchor: str | NotGiven = NOT_GIVEN,
-    ) -> Assignment:
+        idempotency_key: str | NotGiven = NOT_GIVEN,
+    ) -> AssignPlanResult:
         """
-        Put a customer on a plan. This is the wire call, and the only one that
-        takes `cycle_anchor` — a first assignment's one chance to put their
-        periods on a date they already have.
+        Put a customer on a plan, named by its id or its key. This is the wire
+        call, and the only one that takes `cycle_anchor` — a first
+        assignment's one chance to put their periods on a date they already
+        have.
 
         Returns the instruction as recorded, which is not always as asked: a
         first plan is recorded `immediate` whatever `effective` said.
@@ -52,17 +57,27 @@ class AsyncCustomerPlan:
         `next_cycle`. `cycle_anchor` defaults to the instant the plan lands,
         and is refused beside `reconciliation="reset"`, which anchors at the
         change instant itself.
+
+        `idempotency_key`, 1–255 characters, makes a change safe to retry.
+        From a provider's webhook, which may arrive twice, pass the event's
+        id: a retry then cannot restart a period twice, or cancel a change
+        scheduled after it. The same request again answers with that
+        assignment and `replayed=True`, and another one under the key raises
+        `IdempotencyKeyReusedError`. With a key, the SDK retries the call too.
         """
         return await self._api.request(
             "POST",
             f"/v1/customers/{segment(customer_id)}/plan",
-            Assignment,
+            AssignPlanResult,
             body={
                 "plan_id": plan_id,
                 "effective": effective,
                 "reconciliation": reconciliation,
                 "cycle_anchor": cycle_anchor,
+                "idempotency_key": idempotency_key,
             },
+            # None goes out as null, which the engine reads as no key at all.
+            idempotent=isinstance(idempotency_key, str),
         )
 
     async def change(
@@ -72,12 +87,13 @@ class AsyncCustomerPlan:
         plan: str,
         effective: ApplyMode | NotGiven = NOT_GIVEN,
         reconciliation: Reconciliation | NotGiven = NOT_GIVEN,
-    ) -> Assignment:
+        idempotency_key: str | NotGiven = NOT_GIVEN,
+    ) -> AssignPlanResult:
         """
-        Move a customer to a different plan, named by its Meterbase id, with
+        Move a customer to a different plan, named by its id or its key, with
         both knobs in the open. `effective` defaults to `next_cycle`;
         `reconciliation` applies only to an `immediate` change and defaults to
-        `none`.
+        `none`. `idempotency_key` is as on `assign`.
 
         Reach for `change_at_next_cycle`, `change_now` or `restart` when one of
         them says what you mean — this is the form to fall back to when the two
@@ -88,9 +104,16 @@ class AsyncCustomerPlan:
             plan_id=plan,
             effective=effective,
             reconciliation=reconciliation,
+            idempotency_key=idempotency_key,
         )
 
-    async def change_at_next_cycle(self, customer_id: str, *, plan: str) -> Assignment:
+    async def change_at_next_cycle(
+        self,
+        customer_id: str,
+        *,
+        plan: str,
+        idempotency_key: str | NotGiven = NOT_GIVEN,
+    ) -> AssignPlanResult:
         """
         Schedule the move for the end of the period they are in: they keep the
         plan they are paying for until it runs out, and the new one starts at
@@ -100,7 +123,12 @@ class AsyncCustomerPlan:
         them this raises `CycleChangeRequiresResetError`: use `restart` for
         that move. Other cycles land on the coarser plan's boundary.
         """
-        return await self.change(customer_id, plan=plan, effective="next_cycle")
+        return await self.change(
+            customer_id,
+            plan=plan,
+            effective="next_cycle",
+            idempotency_key=idempotency_key,
+        )
 
     async def change_now(
         self,
@@ -108,7 +136,8 @@ class AsyncCustomerPlan:
         *,
         plan: str,
         reconciliation: Reconciliation | NotGiven = NOT_GIVEN,
-    ) -> Assignment:
+        idempotency_key: str | NotGiven = NOT_GIVEN,
+    ) -> AssignPlanResult:
         """
         Move them now, inside the period already running. Their renewal day
         does not move; what changes is this period's cap, and `reconciliation`
@@ -129,9 +158,16 @@ class AsyncCustomerPlan:
             plan=plan,
             effective="immediate",
             reconciliation=reconciliation,
+            idempotency_key=idempotency_key,
         )
 
-    async def restart(self, customer_id: str, *, plan: str) -> Assignment:
+    async def restart(
+        self,
+        customer_id: str,
+        *,
+        plan: str,
+        idempotency_key: str | NotGiven = NOT_GIVEN,
+    ) -> AssignPlanResult:
         """
         Move them now and start a fresh period today: the period they were in
         closes where the change lands, keeping the usage it had, and the new
@@ -140,13 +176,16 @@ class AsyncCustomerPlan:
         This moves the customer's anchor, so their renewal day becomes today.
         It is the move for a customer starting over — a new contract, a
         re-signup — and the only one that can take a customer between plans
-        whose cycles differ.
+        whose cycles differ. When a provider's webhook orders it, pass the
+        event's id as `idempotency_key`: a second delivery then replays this
+        rather than starting another period.
         """
         return await self.change(
             customer_id,
             plan=plan,
             effective="immediate",
             reconciliation="reset",
+            idempotency_key=idempotency_key,
         )
 
     async def cancel_scheduled_change(self, customer_id: str) -> Assignment | None:
@@ -158,6 +197,11 @@ class AsyncCustomerPlan:
         Returns the assignment still in force, or `None` for a customer holding
         no plan — who can have nothing pending, since a first assignment
         always lands at once.
+
+        It takes no `idempotency_key`: it names whatever plan is in force when
+        it runs, so a retry could name a different one and be refused as a
+        different request. For a cancel a webhook orders, `assign` the plan
+        the event says they keep, under the event's id.
         """
         current = await self.retrieve(customer_id)
         if current is None:

{meterbase-0.2.0 → meterbase-0.3.0}/src/meterbase/_async/resources/meters.py

@@ -24,6 +24,9 @@ class AsyncMeters:
         thresholds: Sequence[int] | NotGiven = NOT_GIVEN,
     ) -> Meter:
         """
+        `key` names the meter wherever its id does, so it must not be shaped
+        like a UUID: the API reads one as an id.
+
         `thresholds` is whole percents, 1–1000, at most 32 of them; a mark over
         100 is an overage alert. Omitted, the meter inherits the workspace's.
         """
@@ -52,6 +55,7 @@ class AsyncMeters:
         )
 
     async def retrieve(self, id: str) -> Meter:
+        """`id` is the meter's id or its key."""
         return await self._api.request("GET", f"/v1/meters/{segment(id)}", Meter)
 
     async def update(
@@ -66,7 +70,9 @@ class AsyncMeters:
         thresholds: Sequence[int] | NotGiven | None = NOT_GIVEN,
     ) -> Meter:
         """
-        An omitted field is left alone; `""` clears an optional one.
+        `id` is the meter's id or its key, and a new `key` must not be shaped
+        like a UUID. An omitted field is left alone; `""` clears an optional
+        one.
 
         `thresholds` is the exception on both counts: `None` is a value there,
         not silence. Omit it to keep the stored list, pass `None` to inherit
@@ -87,8 +93,8 @@ class AsyncMeters:
         )
 
     async def usage(self, id: str, *, days: int) -> MeterUsageHistory:
-        """Every customer's usage of the meter per UTC day: `days` is 1–90 of
-        them, ending today."""
+        """Every customer's usage of the meter, named by its id or its key, per
+        UTC day: `days` is 1–90 of them, ending today."""
         return await self._api.request(
             "GET",
             f"/v1/meters/{segment(id)}/usage",
@@ -97,6 +103,6 @@ class AsyncMeters:
         )
 
     async def archive(self, id: str) -> Meter:
-        """Soft delete: plans and usage keep referencing the meter.
-        Idempotent."""
+        """Soft delete, by id or key: plans and usage keep referencing the
+        meter. Idempotent."""
         return await self._api.request("DELETE", f"/v1/meters/{segment(id)}", Meter)