solvapay-python 0.7.0__tar.gz → 0.7.2__tar.gz

solvapay_python-0.7.2/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## 0.7.2 — 2026-05-18
+
+Bug fixes and documentation update.
+
+### Fixed
+- **`paywall.require_async`**: `AsyncSolvaPay()` instantiated without a caller-supplied `client=` was not closed after the decorated function returned, leaking the underlying `httpx.AsyncClient` connection pool. Wrapped in `try/finally`; `await sv.aclose()` called when the decorator owns the client.
+- **`examples/fastmcp-paywall/pyproject.toml`**: dependency used wrong PyPI dist name (`solvapay`) and a stale `@v0.3.0` pin. Updated to `solvapay-python>=0.7.2`.
+- **`examples/langchain-paywall/pyproject.toml`**: same wrong dist name and stale `@v0.5.0` pin. Updated to `solvapay-python[langchain]>=0.7.2`.
+
+### Docs
+- **README** updated to v0.7.1 surface: `paywall_state.gate()`, error hierarchy, idempotency keys, admin ops table, marketplace example, roadmap entries for v0.7.0 and v0.7.1.
+
+### Internal
+- `tests/test_lifecycle.py` reformatted (ruff format compliance)
+
+## 0.7.1 — 2026-05-17
+
+Payments-grade hardening: structured errors, idempotency keys, py.typed, structured logging.
+
+### Added
+- **Structured error hierarchy** (`exceptions.py`): `APIError` base with `status_code`, `request_id`, `error_code`, `error_message`. Subclasses: `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `RateLimitError` (429, adds `.retry_after`), `InvalidRequestError` (4xx), `APIServerError` (5xx), `APIConnectionError`, `APITimeoutError`. `SolvaPayAPIError` aliased to `APIError` for back-compat.
+- **Idempotency keys** on all mutating ops: `create_checkout_session`, `ensure_customer`, `track_usage`, `cancel_purchase`, `reactivate_purchase`, `create_product`, `clone_product`, `create_plan` all accept `idempotency_key: str | None = None`. Header casing: `Idempotency-Key` (matches TS SDK).
+- **`solvapay.idempotency.from_payload(*parts)`** — SHA256 of stable-serialized payload parts → 32-hex-char deterministic key.
+- **PEP 561 `py.typed` marker** — downstream mypy users no longer see `Any` on `solvapay.*` imports.
+- **Structured logging** at `solvapay.http` logger: INFO on success (method, path, status, request_id, duration_ms), WARNING on 4xx/5xx (adds body_excerpt ≤200 chars). Never calls `logging.basicConfig`. Optional `logger=` injection on `SolvaPay`/`AsyncSolvaPay` constructors for `loguru`/`structlog`.
+- **Secret redaction**: `Authorization` header never appears in logs. Verified by `tests/test_redaction.py`.
+- **pyproject classifiers**: `Development Status :: 4 - Beta`, `Framework :: AsyncIO`, `Topic :: Office/Business :: Financial`, `Typing :: Typed`.
+
+### Internal
+- User-Agent bumped to `solvapay-python/0.7.1`
+- 142 tests (up from 125), `mypy --strict` clean, `ruff` clean
+
+## 0.7.0 — 2026-05-17
+
+Real-API alignment after testing against the SolvaPay sandbox revealed wire-format mismatches.
+
+### Fixed
+- **`Customer.customer_ref`** now accepts `reference` (real API) in addition to `customerRef` via `validation_alias=AliasChoices(...)`.
+- **`ensure_customer()`** reads `reference` from API response; falls back to `customerRef`. Raises if neither present.
+- **`BalanceResponse`** rewritten: `credits`, `display_currency`, `credits_per_minor_unit`, `display_exchange_rate`; `balance` and `currency` kept as computed properties.
+
+### Added
+- **`paywall_state.gate()`** — one-call enrichment helper (limits + checkout URL + plan via `get_customer`).
+- **`paywall.require` / `require_async`**: auto-mints checkout URL when `LimitResponse.checkout_url is None`.
+- **`examples/marketplace/`** — Streamlit demo with 4 paywalled AI agents (Google Gemini) against real SolvaPay sandbox.
+
+### Internal
+- User-Agent `solvapay-python/0.7.0`. 125 tests (up from 121). `mypy --strict` clean.
+
+## 0.6.0
+- Admin endpoints (products, plans, merchant config). GitHub Actions trusted-publish to PyPI.
+
+## 0.5.0
+- `paywall_state` classifier (ACTIVATION_REQUIRED / TOPUP_REQUIRED / UPGRADE_REQUIRED). LangChain `monetize_tool`.
+
+## 0.4.0
+- Full async client. 5 lifecycle operations. 13 typed webhook event classes.
+
+## 0.3.0
+- FastMCP example: AI agent with two paywalled tools.
+
+## 0.2.0
+- `@paywall.require` decorator. FastAPI webhook router.
+
+## 0.1.0
+- Sync client, HMAC-SHA256 webhook verification, Pydantic v2 models, CI on 3 Python versions.

{solvapay_python-0.7.0 → solvapay_python-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvapay-python
-Version: 0.7.0
+Version: 0.7.2
 Summary: Community Python SDK for SolvaPay (agent-native payment rails)
 Project-URL: Homepage, https://github.com/dhruv-sanan/solvapay-python
 Project-URL: Issues, https://github.com/dhruv-sanan/solvapay-python/issues
@@ -9,14 +9,17 @@ Author: Dhruv Sanan
 License: MIT
 License-File: LICENSE
 Keywords: agents,fintech,mcp,payments,solvapay
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.5
@@ -32,12 +35,15 @@ Description-Content-Type: text/markdown
 
 Community Python SDK for [SolvaPay](https://solvapay.com) — payment rails for the agentic economy.
 
-> **Status:** v0.6, community-maintained. Available on PyPI. Pending official adoption.
+> **Status:** v0.7.2, community-maintained. Available on PyPI. Pending official adoption.
 > Mirrors the most-used surface of [@solvapay/core](https://github.com/solvapay/solvapay-sdk).
 
 Python is the dominant language for agent frameworks (LangChain, FastMCP, CrewAI, AutoGen). SolvaPay's official SDK is TypeScript-only. This SDK brings first-class Python support so agent developers can gate tools behind paywalls without switching ecosystems.
 
-> **New in v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
+> **New in v0.7.2:** Async resource leak fix in `@paywall.require_async` — `AsyncSolvaPay` now properly closed when owned by the decorator. Example dep fixes.
+> **v0.7.1:** Full error hierarchy (`AuthenticationError`, `NotFoundError`, `RateLimitError`, `APIConnectionError`, `APITimeoutError`), idempotency keys on all mutating ops, `py.typed` PEP 561 marker, structured HTTP logging.
+> **New in v0.7.0:** Real-API alignment (wire-format fixes), `paywall_state.gate()` enrichment helper, marketplace Streamlit demo.
+> **v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
 > **v0.5:** Paywall state classifier (`paywall_state` module) and LangChain `monetize_tool` decorator — gate any LangChain tool behind a SolvaPay paywall with one line.
 > **v0.4:** Async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events.
 
@@ -147,12 +153,69 @@ if not limits.within_limits:
     print(d.checkout_url)   # "https://solvapay.com/c/..."
 ```
 
+For real-API calls use `gate()` instead — it enriches the bare `/v1/sdk/limits` response (which has no `plan` or `checkout_url`) in one call:
+
+```python
+from solvapay.paywall_state import gate
+
+decision = gate(sv, customer_ref="cus_x", product_ref="prd_y")
+# decision.state        — PaywallState.UPGRADE_REQUIRED (etc)
+# decision.checkout_url — minted via create_checkout_session if needed
+# decision.message      — TS-style copy with URL inlined
+```
+
+## Error handling
+
+v0.7.1 ships a structured exception hierarchy under `SolvaPayError`:
+
+```python
+import time
+from solvapay import (
+    SolvaPayError,        # catch-all
+    APIError,             # base for all HTTP errors — has .status_code, .request_id
+    AuthenticationError,  # 401
+    NotFoundError,        # 404
+    RateLimitError,       # 429 — adds .retry_after
+    APIConnectionError,   # network failure
+    APITimeoutError,      # request timeout
+)
+
+try:
+    sv.get_customer("cus_missing")
+except NotFoundError as e:
+    print(e.status_code, e.request_id)
+except RateLimitError as e:
+    time.sleep(float(e.retry_after or 1))
+except SolvaPayError:
+    raise
+```
+
+Use `except SolvaPayError` as the catch-all. Prefer specific subclasses over checking `.status_code`.
+
+## Idempotency keys
+
+All mutating ops accept an optional `idempotency_key` to make retries safe:
+
+```python
+from solvapay.idempotency import from_payload
+
+key = from_payload("checkout", customer_ref, product_ref)
+session = sv.create_checkout_session(
+    customer_ref=customer_ref,
+    product_ref="prd_xyz",
+    idempotency_key=key,
+)
+```
+
+`from_payload(*parts)` hashes its args to a 32-hex-char deterministic key. Pass the same key on retry — SolvaPay deduplicates server-side.
+
 ## Examples
 
 | Path | What it shows |
 |---|---|
 | [`examples/fastmcp-paywall/`](examples/fastmcp-paywall/) | FastMCP server with two paywalled tools. Demo for `@paywall.require` + MCP. |
 | [`examples/langchain-paywall/`](examples/langchain-paywall/) | LangChain agent with `monetize_tool`. Shows paywall response in agent trace. |
+| [`examples/marketplace/`](examples/marketplace/) | Streamlit demo — paywalled AI-agent marketplace. Real sandbox, real Gemini LLM, two demo customers (one subscribed, one free tier). Shows `paywall_state.gate()` in action. |
 
 ## TS ↔ Python parity
 
@@ -196,6 +259,22 @@ session = sv.create_checkout_session(
 | `cancel_purchase` | `POST /v1/sdk/purchases/{ref}/cancel` | Cancel a subscription |
 | `reactivate_purchase` | `POST /v1/sdk/purchases/{ref}/reactivate` | Reactivate cancelled purchase |
 
+**Admin (new in v0.6):**
+
+| Python | Verb + path | Description |
+|---|---|---|
+| `list_products` | `GET /v1/sdk/products` | List all products |
+| `get_product` | `GET /v1/sdk/products/{ref}` | Fetch product |
+| `create_product` | `POST /v1/sdk/products` | Create product |
+| `delete_product` | `DELETE /v1/sdk/products/{ref}` | Delete product |
+| `clone_product` | `POST /v1/sdk/products/{ref}/clone` | Clone product |
+| `list_plans` | `GET /v1/sdk/products/{ref}/plans` | List plans |
+| `create_plan` | `POST /v1/sdk/products/{ref}/plans` | Create plan |
+| `update_plan` | `PUT /v1/sdk/products/{ref}/plans/{ref}` | Update plan |
+| `delete_plan` | `DELETE /v1/sdk/products/{ref}/plans/{ref}` | Delete plan |
+| `get_merchant` | `GET /v1/sdk/merchant` | Merchant info |
+| `get_platform_config` | `GET /v1/sdk/platform-config` | Platform config |
+
 All methods available on both `SolvaPay` (sync) and `AsyncSolvaPay` (async).
 
 ## Webhook handler (FastAPI)
@@ -258,6 +337,9 @@ async def handle_webhook(request: Request) -> dict:
 - v0.4 — async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events ✅
 - v0.5 — paywall state classifier, LangChain `monetize_tool` decorator ✅
 - v0.6 — admin endpoints (products, plans, merchant, platform config), PyPI publish ✅
+- v0.7.0 — real-API wire-format fixes, `paywall_state.gate()`, marketplace demo ✅
+- v0.7.1 — structured error hierarchy, idempotency keys, `py.typed`, structured logging ✅
+- v0.7.2 — async resource leak fix (`require_async`), example dep fixes ✅
 
 ## Contributing
 

{solvapay_python-0.7.0 → solvapay_python-0.7.2}/README.md

@@ -4,12 +4,15 @@
 
 Community Python SDK for [SolvaPay](https://solvapay.com) — payment rails for the agentic economy.
 
-> **Status:** v0.6, community-maintained. Available on PyPI. Pending official adoption.
+> **Status:** v0.7.2, community-maintained. Available on PyPI. Pending official adoption.
 > Mirrors the most-used surface of [@solvapay/core](https://github.com/solvapay/solvapay-sdk).
 
 Python is the dominant language for agent frameworks (LangChain, FastMCP, CrewAI, AutoGen). SolvaPay's official SDK is TypeScript-only. This SDK brings first-class Python support so agent developers can gate tools behind paywalls without switching ecosystems.
 
-> **New in v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
+> **New in v0.7.2:** Async resource leak fix in `@paywall.require_async` — `AsyncSolvaPay` now properly closed when owned by the decorator. Example dep fixes.
+> **v0.7.1:** Full error hierarchy (`AuthenticationError`, `NotFoundError`, `RateLimitError`, `APIConnectionError`, `APITimeoutError`), idempotency keys on all mutating ops, `py.typed` PEP 561 marker, structured HTTP logging.
+> **New in v0.7.0:** Real-API alignment (wire-format fixes), `paywall_state.gate()` enrichment helper, marketplace Streamlit demo.
+> **v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
 > **v0.5:** Paywall state classifier (`paywall_state` module) and LangChain `monetize_tool` decorator — gate any LangChain tool behind a SolvaPay paywall with one line.
 > **v0.4:** Async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events.
 
@@ -119,12 +122,69 @@ if not limits.within_limits:
     print(d.checkout_url)   # "https://solvapay.com/c/..."
 ```
 
+For real-API calls use `gate()` instead — it enriches the bare `/v1/sdk/limits` response (which has no `plan` or `checkout_url`) in one call:
+
+```python
+from solvapay.paywall_state import gate
+
+decision = gate(sv, customer_ref="cus_x", product_ref="prd_y")
+# decision.state        — PaywallState.UPGRADE_REQUIRED (etc)
+# decision.checkout_url — minted via create_checkout_session if needed
+# decision.message      — TS-style copy with URL inlined
+```
+
+## Error handling
+
+v0.7.1 ships a structured exception hierarchy under `SolvaPayError`:
+
+```python
+import time
+from solvapay import (
+    SolvaPayError,        # catch-all
+    APIError,             # base for all HTTP errors — has .status_code, .request_id
+    AuthenticationError,  # 401
+    NotFoundError,        # 404
+    RateLimitError,       # 429 — adds .retry_after
+    APIConnectionError,   # network failure
+    APITimeoutError,      # request timeout
+)
+
+try:
+    sv.get_customer("cus_missing")
+except NotFoundError as e:
+    print(e.status_code, e.request_id)
+except RateLimitError as e:
+    time.sleep(float(e.retry_after or 1))
+except SolvaPayError:
+    raise
+```
+
+Use `except SolvaPayError` as the catch-all. Prefer specific subclasses over checking `.status_code`.
+
+## Idempotency keys
+
+All mutating ops accept an optional `idempotency_key` to make retries safe:
+
+```python
+from solvapay.idempotency import from_payload
+
+key = from_payload("checkout", customer_ref, product_ref)
+session = sv.create_checkout_session(
+    customer_ref=customer_ref,
+    product_ref="prd_xyz",
+    idempotency_key=key,
+)
+```
+
+`from_payload(*parts)` hashes its args to a 32-hex-char deterministic key. Pass the same key on retry — SolvaPay deduplicates server-side.
+
 ## Examples
 
 | Path | What it shows |
 |---|---|
 | [`examples/fastmcp-paywall/`](examples/fastmcp-paywall/) | FastMCP server with two paywalled tools. Demo for `@paywall.require` + MCP. |
 | [`examples/langchain-paywall/`](examples/langchain-paywall/) | LangChain agent with `monetize_tool`. Shows paywall response in agent trace. |
+| [`examples/marketplace/`](examples/marketplace/) | Streamlit demo — paywalled AI-agent marketplace. Real sandbox, real Gemini LLM, two demo customers (one subscribed, one free tier). Shows `paywall_state.gate()` in action. |
 
 ## TS ↔ Python parity
 
@@ -168,6 +228,22 @@ session = sv.create_checkout_session(
 | `cancel_purchase` | `POST /v1/sdk/purchases/{ref}/cancel` | Cancel a subscription |
 | `reactivate_purchase` | `POST /v1/sdk/purchases/{ref}/reactivate` | Reactivate cancelled purchase |
 
+**Admin (new in v0.6):**
+
+| Python | Verb + path | Description |
+|---|---|---|
+| `list_products` | `GET /v1/sdk/products` | List all products |
+| `get_product` | `GET /v1/sdk/products/{ref}` | Fetch product |
+| `create_product` | `POST /v1/sdk/products` | Create product |
+| `delete_product` | `DELETE /v1/sdk/products/{ref}` | Delete product |
+| `clone_product` | `POST /v1/sdk/products/{ref}/clone` | Clone product |
+| `list_plans` | `GET /v1/sdk/products/{ref}/plans` | List plans |
+| `create_plan` | `POST /v1/sdk/products/{ref}/plans` | Create plan |
+| `update_plan` | `PUT /v1/sdk/products/{ref}/plans/{ref}` | Update plan |
+| `delete_plan` | `DELETE /v1/sdk/products/{ref}/plans/{ref}` | Delete plan |
+| `get_merchant` | `GET /v1/sdk/merchant` | Merchant info |
+| `get_platform_config` | `GET /v1/sdk/platform-config` | Platform config |
+
 All methods available on both `SolvaPay` (sync) and `AsyncSolvaPay` (async).
 
 ## Webhook handler (FastAPI)
@@ -230,6 +306,9 @@ async def handle_webhook(request: Request) -> dict:
 - v0.4 — async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events ✅
 - v0.5 — paywall state classifier, LangChain `monetize_tool` decorator ✅
 - v0.6 — admin endpoints (products, plans, merchant, platform config), PyPI publish ✅
+- v0.7.0 — real-API wire-format fixes, `paywall_state.gate()`, marketplace demo ✅
+- v0.7.1 — structured error hierarchy, idempotency keys, `py.typed`, structured logging ✅
+- v0.7.2 — async resource leak fix (`require_async`), example dep fixes ✅
 
 ## Contributing
 

{solvapay_python-0.7.0 → solvapay_python-0.7.2}/examples/fastmcp-paywall/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "FastMCP server gated by SolvaPay paywall — demo for solvapay-python"
 requires-python = ">=3.10"
 dependencies = [
-    "solvapay @ git+https://github.com/dhruv-sanan/solvapay-python@v0.3.0",
+    "solvapay-python>=0.7.1",
     "fastmcp>=0.4",
     "httpx>=0.27",
     "python-dotenv>=1.0",

{solvapay_python-0.7.0 → solvapay_python-0.7.2}/examples/langchain-paywall/pyproject.toml

@@ -3,7 +3,7 @@ name = "langchain-paywall-example"
 version = "0.1.0"
 requires-python = ">=3.10"
 dependencies = [
-    "solvapay[langchain] @ git+https://github.com/dhruv-sanan/solvapay-python@v0.5.0",
+    "solvapay-python[langchain]>=0.7.1",
     "langchain>=0.3",
     "langchain-openai>=0.2",
     "python-dotenv>=1.0",

{solvapay_python-0.7.0 → solvapay_python-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "solvapay-python"
-version = "0.7.0"
+version = "0.7.2"
 description = "Community Python SDK for SolvaPay (agent-native payment rails)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -12,14 +12,17 @@ authors = [{ name = "Dhruv Sanan" }]
 requires-python = ">=3.10"
 keywords = ["solvapay", "payments", "agents", "mcp", "fintech"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 dependencies = [
     "httpx>=0.27",

{solvapay_python-0.7.0 → solvapay_python-0.7.2}/src/solvapay/__init__.py

@@ -21,24 +21,44 @@ from solvapay.events import (
     PurchaseUpdated,
     WebhookEvent,
 )
-from solvapay.exceptions import SolvaPayAPIError, SolvaPayError
+from solvapay.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIServerError,
+    APITimeoutError,
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    SolvaPayAPIError,
+    SolvaPayError,
+)
 from solvapay.models import BalanceResponse, Merchant, Plan, PlatformConfig, Product
 from solvapay.paywall import PaywallRequired
 from solvapay.webhooks import verify_webhook
 
 __all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIServerError",
+    "APITimeoutError",
     "AsyncSolvaPay",
+    "AuthenticationError",
     "BalanceResponse",
     "CheckoutSessionCreated",
     "CustomerCreated",
     "CustomerDeleted",
     "CustomerUpdated",
+    "InvalidRequestError",
     "Merchant",
+    "NotFoundError",
     "PaymentFailed",
     "PaymentRefundFailed",
     "PaymentRefunded",
     "PaymentSucceeded",
     "PaywallRequired",
+    "PermissionError",
     "Plan",
     "PlatformConfig",
     "Product",
@@ -47,6 +67,7 @@ __all__ = [
     "PurchaseExpired",
     "PurchaseSuspended",
     "PurchaseUpdated",
+    "RateLimitError",
     "SolvaPay",
     "SolvaPayAPIError",
     "SolvaPayError",
@@ -54,4 +75,4 @@ __all__ = [
     "paywall",
     "verify_webhook",
 ]
-__version__ = "0.7.0"
+__version__ = "0.7.2"

{solvapay_python-0.7.0 → solvapay_python-0.7.2}/src/solvapay/_async_client.py

@@ -6,6 +6,7 @@ Use `async with AsyncSolvaPay() as sv: ...` for proper teardown.
 
 from __future__ import annotations
 
+import logging
 import time
 from typing import Any
 
@@ -56,11 +57,13 @@ class AsyncSolvaPay:
         *,
         base_url: str | None = None,
         timeout: float = 30.0,
+        logger: logging.Logger | None = None,
     ) -> None:
         self._http = AsyncHttpClient(
             api_key=resolve_api_key(api_key),
             base_url=resolve_base_url(base_url),
             timeout=timeout,
+            logger=logger,
         )
 
     async def aclose(self) -> None:
@@ -79,6 +82,7 @@ class AsyncSolvaPay:
         product_ref: str,
         plan_ref: str | None = None,
         return_url: str | None = None,
+        idempotency_key: str | None = None,
     ) -> CheckoutSession:
         req = CheckoutSessionRequest(
             customer_ref=customer_ref,
@@ -91,6 +95,7 @@ class AsyncSolvaPay:
                 "POST",
                 "/v1/sdk/checkout-sessions",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return CheckoutSession.model_validate(data)
@@ -102,6 +107,7 @@ class AsyncSolvaPay:
         *,
         email: str | None = None,
         name: str | None = None,
+        idempotency_key: str | None = None,
     ) -> str:
         lookup_ref = external_ref or customer_ref
         try:
@@ -122,7 +128,10 @@ class AsyncSolvaPay:
         )
         created = await self._http.send(
             _RequestSpec(
-                "POST", "/v1/sdk/customers", json=req.model_dump(by_alias=True, exclude_none=True)
+                "POST",
+                "/v1/sdk/customers",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         ref = created.get("reference") or created.get("customerRef")
@@ -226,7 +235,11 @@ class AsyncSolvaPay:
         return BalanceResponse.model_validate(data)
 
     async def cancel_purchase(
-        self, purchase_ref: str, *, reason: str | None = None
+        self,
+        purchase_ref: str,
+        *,
+        reason: str | None = None,
+        idempotency_key: str | None = None,
     ) -> dict[str, Any]:
         """Cancel a purchase. Maps to POST /v1/sdk/purchases/{ref}/cancel."""
         req = CancelPurchaseRequest(reason=reason)
@@ -235,13 +248,20 @@ class AsyncSolvaPay:
                 "POST",
                 f"/v1/sdk/purchases/{purchase_ref}/cancel",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
 
-    async def reactivate_purchase(self, purchase_ref: str) -> dict[str, Any]:
+    async def reactivate_purchase(
+        self, purchase_ref: str, *, idempotency_key: str | None = None
+    ) -> dict[str, Any]:
         """Reactivate a cancelled purchase. Maps to POST /v1/sdk/purchases/{ref}/reactivate."""
         return await self._http.send(
-            _RequestSpec("POST", f"/v1/sdk/purchases/{purchase_ref}/reactivate")
+            _RequestSpec(
+                "POST",
+                f"/v1/sdk/purchases/{purchase_ref}/reactivate",
+                idempotency_key=idempotency_key,
+            )
         )
 
     # --- Admin: Products ---
@@ -257,7 +277,9 @@ class AsyncSolvaPay:
         data = await self._http.send(_RequestSpec("GET", f"/v1/sdk/products/{product_ref}"))
         return Product.model_validate(data)
 
-    async def create_product(self, *, name: str, type: str, default_currency: str) -> Product:
+    async def create_product(
+        self, *, name: str, type: str, default_currency: str, idempotency_key: str | None = None
+    ) -> Product:
         """Create a product. Maps to POST /v1/sdk/products."""
         req = CreateProductRequest(name=name, type=type, default_currency=default_currency)
         data = await self._http.send(
@@ -265,6 +287,7 @@ class AsyncSolvaPay:
                 "POST",
                 "/v1/sdk/products",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return Product.model_validate(data)
@@ -273,7 +296,9 @@ class AsyncSolvaPay:
         """Delete a product. Maps to DELETE /v1/sdk/products/{ref}."""
         return await self._http.send(_RequestSpec("DELETE", f"/v1/sdk/products/{product_ref}"))
 
-    async def clone_product(self, product_ref: str, *, new_name: str) -> Product:
+    async def clone_product(
+        self, product_ref: str, *, new_name: str, idempotency_key: str | None = None
+    ) -> Product:
         """Clone a product with a new name. Maps to POST /v1/sdk/products/{ref}/clone."""
         req = CloneProductRequest(new_name=new_name)
         data = await self._http.send(
@@ -281,6 +306,7 @@ class AsyncSolvaPay:
                 "POST",
                 f"/v1/sdk/products/{product_ref}/clone",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return Product.model_validate(data)
@@ -302,6 +328,7 @@ class AsyncSolvaPay:
         price: float | None = None,
         currency: str | None = None,
         interval: str | None = None,
+        idempotency_key: str | None = None,
     ) -> Plan:
         """Create a plan for a product. Maps to POST /v1/sdk/products/{ref}/plans."""
         req = CreatePlanRequest(
@@ -312,6 +339,7 @@ class AsyncSolvaPay:
                 "POST",
                 f"/v1/sdk/products/{product_ref}/plans",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return Plan.model_validate(data)