meterbase 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python SDK for the Meterbase engine
 Project-URL: Homepage, https://meterbase.tech
 Project-URL: Documentation, https://meterbase.tech/docs
@@ -278,7 +278,7 @@ id and gives them a first plan, and running it again changes nothing:
 ensured = meterbase.customers.ensure(
     external_id="acct_1",
     name="Acme",  # applied only when it creates the customer
-    plan="free",  # a plan key
+    plan="free",  # a plan's key or id
 )
 ensured.created, ensured.plan_result, ensured.customer.plan
 ```
@@ -303,7 +303,6 @@ customer = meterbase.customers.create(
 )
 
 found = meterbase.customers.retrieve_by_external_id("acct_1")  # or None
-everyone = meterbase.customers.list(include_deleted=True).data
 
 meterbase.customers.update(customer.id, name="Acme Inc")
 meterbase.customers.delete(customer.id)  # soft delete, idempotent
@@ -328,6 +327,27 @@ embed is which plan, and `customers.plan.retrieve` is where instructions are
 identified. `None` means they hold no plan, which is a default deny — a
 customer with no plan and no grant is denied.
 
+**Lists come a page at a time.** `customers.list` answers one page, newest
+first: `limit` customers, 100 unless you set it and at most 1,000. `list_all`
+follows the pages for you, fetching each one as the loop reaches it:
+
+```python
+page = meterbase.customers.list(plan="pro", limit=1000)
+page.data  #      the newest 1,000 customers on pro
+page.has_more  #  True when another page follows the last of them
+
+for customer in meterbase.customers.list_all(has_plan=False):
+    ...  # every customer holding no plan
+```
+
+On the async client it is `async for customer in meterbase.customers.list_all()`.
+`plan`, a key or an id, and `has_plan` filter on the plan in force now; a
+pending change counts once it lands. `include_deleted=True` adds deleted
+customers. To page by hand, pass the last `id` as `starting_after` while
+`has_more` is `True`. A walk reads no customer twice, and one created while it
+runs is not in it. Both raise before sending when `plan` or `starting_after` is
+`None`, which would otherwise widen the list.
+
 `customers.list` stays lean and does not embed, along with `create`, `update`
 and `delete`; the same read would run per row for an answer most callers of a
 list do not want.
@@ -363,9 +383,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 +415,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 +449,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 +560,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 +611,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 +719,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 +920,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 +977,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 +1014,16 @@ 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.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
+answer every customer. Iterate `list_all` to read them all. The engine pages the
+same way, so 0.3.0 and earlier now read only the newest 100.
+
+**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.4.0}/README.md

@@ -251,7 +251,7 @@ id and gives them a first plan, and running it again changes nothing:
 ensured = meterbase.customers.ensure(
     external_id="acct_1",
     name="Acme",  # applied only when it creates the customer
-    plan="free",  # a plan key
+    plan="free",  # a plan's key or id
 )
 ensured.created, ensured.plan_result, ensured.customer.plan
 ```
@@ -276,7 +276,6 @@ customer = meterbase.customers.create(
 )
 
 found = meterbase.customers.retrieve_by_external_id("acct_1")  # or None
-everyone = meterbase.customers.list(include_deleted=True).data
 
 meterbase.customers.update(customer.id, name="Acme Inc")
 meterbase.customers.delete(customer.id)  # soft delete, idempotent
@@ -301,6 +300,27 @@ embed is which plan, and `customers.plan.retrieve` is where instructions are
 identified. `None` means they hold no plan, which is a default deny — a
 customer with no plan and no grant is denied.
 
+**Lists come a page at a time.** `customers.list` answers one page, newest
+first: `limit` customers, 100 unless you set it and at most 1,000. `list_all`
+follows the pages for you, fetching each one as the loop reaches it:
+
+```python
+page = meterbase.customers.list(plan="pro", limit=1000)
+page.data  #      the newest 1,000 customers on pro
+page.has_more  #  True when another page follows the last of them
+
+for customer in meterbase.customers.list_all(has_plan=False):
+    ...  # every customer holding no plan
+```
+
+On the async client it is `async for customer in meterbase.customers.list_all()`.
+`plan`, a key or an id, and `has_plan` filter on the plan in force now; a
+pending change counts once it lands. `include_deleted=True` adds deleted
+customers. To page by hand, pass the last `id` as `starting_after` while
+`has_more` is `True`. A walk reads no customer twice, and one created while it
+runs is not in it. Both raise before sending when `plan` or `starting_after` is
+`None`, which would otherwise widen the list.
+
 `customers.list` stays lean and does not embed, along with `create`, `update`
 and `delete`; the same read would run per row for an answer most callers of a
 list do not want.
@@ -336,9 +356,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 +388,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 +422,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 +533,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 +584,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 +692,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 +893,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 +950,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 +987,16 @@ 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.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
+answer every customer. Iterate `list_all` to read them all. The engine pages the
+same way, so 0.3.0 and earlier now read only the newest 100.
+
+**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.4.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.4.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: