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

solvapay_python-0.7.1/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvapay-python
-Version: 0.7.0
+Version: 0.7.1
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "solvapay-python"
-version = "0.7.0"
+version = "0.7.1"
 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.1}/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.1"

{solvapay_python-0.7.0 → solvapay_python-0.7.1}/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)

solvapay_python-0.7.1/src/solvapay/_http.py

@@ -0,0 +1,220 @@
+"""Internal HTTP transport. Not part of public API."""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from solvapay.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIServerError,
+    APITimeoutError,
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+)
+
+_logger = logging.getLogger("solvapay.http")
+
+
+@dataclass(frozen=True)
+class _RequestSpec:
+    method: str
+    path: str
+    json: dict[str, Any] | None = None
+    params: dict[str, Any] | None = None
+    idempotency_key: str | None = None
+
+    def headers(self) -> dict[str, str]:
+        return {"Idempotency-Key": self.idempotency_key} if self.idempotency_key else {}
+
+
+def _parse_error(response: httpx.Response) -> APIError:
+    request_id = response.headers.get("x-request-id") or response.headers.get("x-correlation-id")
+    error_code: str | None = None
+    error_message: str | None = None
+    try:
+        payload = response.json()
+        if isinstance(payload, dict):
+            err = payload.get("error", payload)
+            if isinstance(err, dict):
+                code = err.get("code")
+                msg = err.get("message")
+                if isinstance(code, str):
+                    error_code = code
+                if isinstance(msg, str):
+                    error_message = msg
+    except Exception:
+        pass
+
+    status = response.status_code
+    body = response.text
+
+    if status == 401:
+        return AuthenticationError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    if status == 403:
+        return PermissionError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    if status == 404:
+        return NotFoundError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    if status == 429:
+        return RateLimitError(
+            status,
+            body,
+            request_id=request_id,
+            error_code=error_code,
+            error_message=error_message,
+            retry_after=response.headers.get("Retry-After"),
+        )
+    if 400 <= status < 500:
+        return InvalidRequestError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    return APIServerError(
+        status, body, request_id=request_id, error_code=error_code, error_message=error_message
+    )
+
+
+def _handle(response: httpx.Response) -> dict[str, Any]:
+    if not response.is_success:
+        raise _parse_error(response)
+    if response.status_code == 204 or not response.content:
+        return {}
+    return response.json()  # type: ignore[no-any-return]
+
+
+def _log_response(
+    logger: logging.Logger,
+    spec: _RequestSpec,
+    response: httpx.Response,
+    duration_ms: int,
+) -> None:
+    request_id = response.headers.get("x-request-id") or response.headers.get("x-correlation-id")
+    extra: dict[str, object] = {"request_id": request_id, "duration_ms": duration_ms}
+    if response.is_success:
+        logger.info(
+            "%s %s → %d (%dms)",
+            spec.method,
+            spec.path,
+            response.status_code,
+            duration_ms,
+            extra=extra,
+        )
+    else:
+        logger.warning(
+            "%s %s → %d (%dms)",
+            spec.method,
+            spec.path,
+            response.status_code,
+            duration_ms,
+            extra={**extra, "body_excerpt": response.text[:200]},
+        )
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float = 30.0,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._logger = logger or _logger
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "solvapay-python/0.7.1",
+            },
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def send(self, spec: _RequestSpec) -> dict[str, Any]:
+        t0 = time.perf_counter()
+        try:
+            response = self._client.request(
+                spec.method, spec.path, json=spec.json, params=spec.params, headers=spec.headers()
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(str(exc)) from exc
+        except (httpx.ConnectError, httpx.ReadError) as exc:
+            raise APIConnectionError(str(exc)) from exc
+        _log_response(self._logger, spec, response, int((time.perf_counter() - t0) * 1000))
+        return _handle(response)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        return self.send(_RequestSpec(method, path, json, params, idempotency_key))
+
+
+class AsyncHttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float = 30.0,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._logger = logger or _logger
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "solvapay-python/0.7.1",
+            },
+            timeout=timeout,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def send(self, spec: _RequestSpec) -> dict[str, Any]:
+        t0 = time.perf_counter()
+        try:
+            response = await self._client.request(
+                spec.method, spec.path, json=spec.json, params=spec.params, headers=spec.headers()
+            )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(str(exc)) from exc
+        except (httpx.ConnectError, httpx.ReadError) as exc:
+            raise APIConnectionError(str(exc)) from exc
+        _log_response(self._logger, spec, response, int((time.perf_counter() - t0) * 1000))
+        return _handle(response)

{solvapay_python-0.7.0 → solvapay_python-0.7.1}/src/solvapay/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import time
 from typing import Any
 
@@ -54,11 +55,13 @@ class SolvaPay:
         *,
         base_url: str | None = None,
         timeout: float = 30.0,
+        logger: logging.Logger | None = None,
     ) -> None:
         self._http = HttpClient(
             api_key=resolve_api_key(api_key),
             base_url=resolve_base_url(base_url),
             timeout=timeout,
+            logger=logger,
         )
 
     def close(self) -> None:
@@ -77,6 +80,7 @@ class SolvaPay:
         product_ref: str,
         plan_ref: str | None = None,
         return_url: str | None = None,
+        idempotency_key: str | None = None,
     ) -> CheckoutSession:
         """Create a hosted checkout session.
 
@@ -101,6 +105,7 @@ class SolvaPay:
             "POST",
             "/v1/sdk/checkout-sessions",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
         return CheckoutSession.model_validate(data)
 
@@ -111,6 +116,7 @@ class SolvaPay:
         *,
         email: str | None = None,
         name: str | None = None,
+        idempotency_key: str | None = None,
     ) -> str:
         """Idempotently create or look up a customer.
 
@@ -140,6 +146,7 @@ class SolvaPay:
             "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")
         if not ref:
@@ -238,18 +245,27 @@ class SolvaPay:
         data = self._http.request("GET", f"/v1/sdk/customers/{customer_ref}/balance")
         return BalanceResponse.model_validate(data)
 
-    def cancel_purchase(self, purchase_ref: str, *, reason: str | None = None) -> dict[str, Any]:
+    def cancel_purchase(
+        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)
         return self._http.request(
             "POST",
             f"/v1/sdk/purchases/{purchase_ref}/cancel",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
 
-    def reactivate_purchase(self, purchase_ref: str) -> dict[str, Any]:
+    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 self._http.request("POST", f"/v1/sdk/purchases/{purchase_ref}/reactivate")
+        return self._http.request(
+            "POST",
+            f"/v1/sdk/purchases/{purchase_ref}/reactivate",
+            idempotency_key=idempotency_key,
+        )
 
     # --- Admin: Products ---
 
@@ -264,13 +280,16 @@ class SolvaPay:
         data = self._http.request("GET", f"/v1/sdk/products/{product_ref}")
         return Product.model_validate(data)
 
-    def create_product(self, *, name: str, type: str, default_currency: str) -> Product:
+    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 = self._http.request(
             "POST",
             "/v1/sdk/products",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
         return Product.model_validate(data)
 
@@ -278,13 +297,16 @@ class SolvaPay:
         """Delete a product. Maps to DELETE /v1/sdk/products/{ref}."""
         return self._http.request("DELETE", f"/v1/sdk/products/{product_ref}")
 
-    def clone_product(self, product_ref: str, *, new_name: str) -> Product:
+    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 = self._http.request(
             "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)
 
@@ -305,6 +327,7 @@ class SolvaPay:
         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(
@@ -314,6 +337,7 @@ class SolvaPay:
             "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)