threecommon 0.1.0__tar.gz → 0.2.0__tar.gz

{threecommon-0.1.0 → threecommon-0.2.0}/CHANGELOG.md

@@ -5,6 +5,19 @@ versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## 0.1.0
+
+### Added
+
+- Subscriptions resource. The new `client.subscriptions` surface covers the
+  full subscription lifecycle: `list`, `retrieve`, `create`, `update`
+  (mid-cycle change with proration), `activate`, `cancel`,
+  `cancel_immediately`, `mark_unpaid`, `bill`, `renew`,
+  `preview_upcoming_invoice`, and `list_auto_paginate`. Types and typed
+  errors match the events / invoices resources. Both sync and async surfaces.
+
+## 0.0.0
+
 ### Added
 
 - Initial scaffolding.

{threecommon-0.1.0 → threecommon-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threecommon
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official Python client for the 3Common Public API.
 Project-URL: Homepage, https://github.com/3-Common/sdk/tree/main/sdk-python
 Project-URL: Issues, https://github.com/3-Common/sdk/issues

{threecommon-0.1.0 → threecommon-0.2.0}/pyproject.toml

@@ -10,7 +10,7 @@ license = { text = "MIT" }
 authors = [{ name = "3Common", email = "support@3common.com" }]
 keywords = ["3common", "sdk", "api-client", "events", "invoices"]
 requires-python = ">=3.10"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
     "httpx>=0.27,<1.0",
     "pydantic>=2.7,<3.0",

{threecommon-0.1.0 → threecommon-0.2.0}/src/threecommon/client.py

@@ -20,6 +20,7 @@ from threecommon._core.telemetry import Telemetry
 from threecommon.config import RetryDelay, resolve_config
 from threecommon.events.service import AsyncEventsService, EventsService
 from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
+from threecommon.subscriptions.service import AsyncSubscriptionsService, SubscriptionsService
 
 if TYPE_CHECKING:  # pragma: no cover
     import logging
@@ -51,6 +52,9 @@ class ThreeCommon:
     invoices: InvoicesService
     """Invoices resource — list, retrieve, create, update, finalize, void, record_payment."""
 
+    subscriptions: SubscriptionsService
+    """Subscriptions resource — list, retrieve, create, update, activate, cancel, bill, renew."""
+
     _http: HTTPClient
     _telemetry: Telemetry
 
@@ -93,6 +97,7 @@ class ThreeCommon:
         )
         self.events = EventsService(self._http)
         self.invoices = InvoicesService(self._http)
+        self.subscriptions = SubscriptionsService(self._http)
 
     def close(self) -> None:
         """Close the underlying httpx client (no-op if you supplied your own)."""
@@ -120,6 +125,7 @@ class AsyncThreeCommon:
 
     events: AsyncEventsService
     invoices: AsyncInvoicesService
+    subscriptions: AsyncSubscriptionsService
 
     _http: AsyncHTTPClient
     _telemetry: Telemetry
@@ -163,6 +169,7 @@ class AsyncThreeCommon:
         )
         self.events = AsyncEventsService(self._http)
         self.invoices = AsyncInvoicesService(self._http)
+        self.subscriptions = AsyncSubscriptionsService(self._http)
 
     async def aclose(self) -> None:
         """Close the underlying async httpx client."""

threecommon-0.2.0/src/threecommon/subscriptions/__init__.py

@@ -0,0 +1,57 @@
+"""Subscriptions resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.subscriptions][threecommon.ThreeCommon] /
+[AsyncThreeCommon.subscriptions][threecommon.AsyncThreeCommon]; importing the
+service classes directly is supported for advanced wiring.
+"""
+
+from threecommon.subscriptions.service import (
+    AsyncSubscriptionsService,
+    SubscriptionsService,
+)
+from threecommon.subscriptions.types import (
+    BillSubscriptionResult,
+    CancelBody,
+    CancelImmediatelyBody,
+    CreateBody,
+    CreateBodyItem,
+    ListParams,
+    ListSubscriptionsResponse,
+    RenewSubscriptionResult,
+    RetrieveParams,
+    Subscription,
+    SubscriptionInvoicePreview,
+    SubscriptionInvoicePreviewLineItem,
+    SubscriptionInvoiceRef,
+    SubscriptionItem,
+    SubscriptionProration,
+    SubscriptionStatus,
+    SubscriptionTaxId,
+    UpdateBody,
+    UpdateSubscriptionResult,
+)
+
+__all__ = (
+    "AsyncSubscriptionsService",
+    "BillSubscriptionResult",
+    "CancelBody",
+    "CancelImmediatelyBody",
+    "CreateBody",
+    "CreateBodyItem",
+    "ListParams",
+    "ListSubscriptionsResponse",
+    "RenewSubscriptionResult",
+    "RetrieveParams",
+    "Subscription",
+    "SubscriptionInvoicePreview",
+    "SubscriptionInvoicePreviewLineItem",
+    "SubscriptionInvoiceRef",
+    "SubscriptionItem",
+    "SubscriptionProration",
+    "SubscriptionStatus",
+    "SubscriptionTaxId",
+    "SubscriptionsService",
+    "UpdateBody",
+    "UpdateSubscriptionResult",
+)

threecommon-0.2.0/src/threecommon/subscriptions/service.py

@@ -0,0 +1,376 @@
+"""Sync and async subscriptions services.
+
+Both services share the same wire shape and validation logic; the only
+difference is which HTTP client they call.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+from threecommon._core.http_client import Request
+from threecommon.errors.classes import ValidationError
+from threecommon.pagination import AsyncIter, Iter
+from threecommon.subscriptions.types import (
+    BillSubscriptionResult,
+    CancelBody,
+    CancelImmediatelyBody,
+    CreateBody,
+    ListParams,
+    ListSubscriptionsResponse,
+    RenewSubscriptionResult,
+    RetrieveParams,
+    Subscription,
+    SubscriptionInvoicePreview,
+    UpdateBody,
+    UpdateSubscriptionResult,
+)
+
+if TYPE_CHECKING:
+    from threecommon._core.http_client import AsyncHTTPClient, HTTPClient
+
+
+def _encode_list_params(params: ListParams | None) -> dict[str, str] | None:
+    if params is None:
+        return None
+    raw = params.model_dump(by_alias=True, exclude_none=True)
+    if not raw:
+        return None
+    return {k: str(v) for k, v in raw.items()}
+
+
+def _encode_retrieve_params(params: RetrieveParams | None) -> dict[str, str] | None:
+    if params is None or params.fields is None:
+        return None
+    return {"fields": params.fields}
+
+
+def _require_id(method: str, subscription_id: str) -> None:
+    if not subscription_id:
+        msg = f"subscriptions.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _path_for(subscription_id: str) -> str:
+    return f"/subscriptions/{quote(subscription_id, safe='')}"
+
+
+def _action_path(subscription_id: str, action: str) -> str:
+    return f"{_path_for(subscription_id)}/{action}"
+
+
+def _build_update_result(response: dict[str, Any]) -> UpdateSubscriptionResult:
+    payload: dict[str, Any] = {
+        "subscription": response["data"],
+        "proration": response["proration"],
+    }
+    if response.get("invoice") is not None:
+        payload["invoice"] = response["invoice"]
+    return UpdateSubscriptionResult.model_validate(payload)
+
+
+def _build_bill_result(response: dict[str, Any]) -> BillSubscriptionResult:
+    return BillSubscriptionResult.model_validate(
+        {"subscription": response["data"], "invoice": response["invoice"]}
+    )
+
+
+def _build_renew_result(response: dict[str, Any]) -> RenewSubscriptionResult:
+    payload: dict[str, Any] = {"subscription": response["data"]}
+    if response.get("invoice") is not None:
+        payload["invoice"] = response["invoice"]
+    return RenewSubscriptionResult.model_validate(payload)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class SubscriptionsService:
+    """Sync subscriptions service — bound as ``client.subscriptions`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListSubscriptionsResponse:
+        """List the host's subscriptions (one page).
+
+        For full iteration use
+        [list_auto_paginate][SubscriptionsService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/subscriptions", query=_encode_list_params(params))
+        )
+        return ListSubscriptionsResponse.model_validate(body)
+
+    def retrieve(self, subscription_id: str, params: RetrieveParams | None = None) -> Subscription:
+        """Retrieve a single subscription by id."""
+        _require_id("retrieve", subscription_id)
+        body = self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(subscription_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Subscription.model_validate(body["data"])
+
+    def create(self, body: CreateBody) -> Subscription:
+        """Create a new subscription against an active recurring Price."""
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(Request(method="POST", path="/subscriptions", body=payload))
+        return Subscription.model_validate(response["data"])
+
+    def update(self, subscription_id: str, body: UpdateBody) -> UpdateSubscriptionResult:
+        """Apply a mid-cycle price/quantity change with Stripe-style daily proration."""
+        _require_id("update", subscription_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(
+            Request(method="PATCH", path=_path_for(subscription_id), body=payload)
+        )
+        return _build_update_result(response)
+
+    def activate(self, subscription_id: str) -> Subscription:
+        """Transition an incomplete or trialing subscription to ``active``."""
+        _require_id("activate", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "activate"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    def cancel(self, subscription_id: str, body: CancelBody | None = None) -> Subscription:
+        """Schedule cancellation at the end of the current period. Idempotent."""
+        _require_id("cancel", subscription_id)
+        payload = body.model_dump(by_alias=True, exclude_none=True) if body is not None else {}
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "cancel"), body=payload)
+        )
+        return Subscription.model_validate(response["data"])
+
+    def cancel_immediately(
+        self, subscription_id: str, body: CancelImmediatelyBody | None = None
+    ) -> Subscription:
+        """Admin override — terminate the subscription immediately."""
+        _require_id("cancel_immediately", subscription_id)
+        payload = body.model_dump(by_alias=True, exclude_none=True) if body is not None else {}
+        response = self._http.request(
+            Request(
+                method="POST",
+                path=_action_path(subscription_id, "cancel-immediately"),
+                body=payload,
+            )
+        )
+        return Subscription.model_validate(response["data"])
+
+    def mark_unpaid(self, subscription_id: str) -> Subscription:
+        """Admin override — mark a subscription ``unpaid`` (terminal)."""
+        _require_id("mark_unpaid", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "mark-unpaid"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    def bill(self, subscription_id: str) -> BillSubscriptionResult:
+        """Generate a draft invoice for the current period without advancing it."""
+        _require_id("bill", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "bill"), body={})
+        )
+        return _build_bill_result(response)
+
+    def renew(self, subscription_id: str) -> RenewSubscriptionResult:
+        """Advance the subscription to its next billing period and generate an invoice."""
+        _require_id("renew", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "renew"), body={})
+        )
+        return _build_renew_result(response)
+
+    def preview_upcoming_invoice(self, subscription_id: str) -> SubscriptionInvoicePreview | None:
+        """Preview the invoice the next renewal will generate.
+
+        Returns ``None`` when the subscription is set to cancel at period end.
+        """
+        _require_id("preview_upcoming_invoice", subscription_id)
+        response = self._http.request(
+            Request(method="GET", path=_action_path(subscription_id, "upcoming"))
+        )
+        invoice = response["data"].get("invoice")
+        if invoice is None:
+            return None
+        return SubscriptionInvoicePreview.model_validate(invoice)
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Subscription]:
+        """Iterate every subscription matching ``params``, paging automatically."""
+        start_page = params.page if params is not None and params.page is not None else 0
+
+        def fetch(page: int) -> tuple[list[Subscription], bool]:
+            page_params = (
+                params.model_copy(update={"page": page})
+                if params is not None
+                else ListParams(page=page)
+            )
+            body = self._http.request(
+                Request(
+                    method="GET",
+                    path="/subscriptions",
+                    query=_encode_list_params(page_params),
+                )
+            )
+            response = ListSubscriptionsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncSubscriptionsService:
+    """Async subscriptions service — bound as ``client.subscriptions`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListSubscriptionsResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/subscriptions", query=_encode_list_params(params))
+        )
+        return ListSubscriptionsResponse.model_validate(body)
+
+    async def retrieve(
+        self, subscription_id: str, params: RetrieveParams | None = None
+    ) -> Subscription:
+        _require_id("retrieve", subscription_id)
+        body = await self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(subscription_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Subscription.model_validate(body["data"])
+
+    async def create(self, body: CreateBody) -> Subscription:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(
+            Request(method="POST", path="/subscriptions", body=payload)
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def update(self, subscription_id: str, body: UpdateBody) -> UpdateSubscriptionResult:
+        _require_id("update", subscription_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(
+            Request(method="PATCH", path=_path_for(subscription_id), body=payload)
+        )
+        return _build_update_result(response)
+
+    async def activate(self, subscription_id: str) -> Subscription:
+        _require_id("activate", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "activate"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def cancel(self, subscription_id: str, body: CancelBody | None = None) -> Subscription:
+        _require_id("cancel", subscription_id)
+        payload = body.model_dump(by_alias=True, exclude_none=True) if body is not None else {}
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "cancel"), body=payload)
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def cancel_immediately(
+        self, subscription_id: str, body: CancelImmediatelyBody | None = None
+    ) -> Subscription:
+        _require_id("cancel_immediately", subscription_id)
+        payload = body.model_dump(by_alias=True, exclude_none=True) if body is not None else {}
+        response = await self._http.request(
+            Request(
+                method="POST",
+                path=_action_path(subscription_id, "cancel-immediately"),
+                body=payload,
+            )
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def mark_unpaid(self, subscription_id: str) -> Subscription:
+        _require_id("mark_unpaid", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "mark-unpaid"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def bill(self, subscription_id: str) -> BillSubscriptionResult:
+        _require_id("bill", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "bill"), body={})
+        )
+        return _build_bill_result(response)
+
+    async def renew(self, subscription_id: str) -> RenewSubscriptionResult:
+        _require_id("renew", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "renew"), body={})
+        )
+        return _build_renew_result(response)
+
+    async def preview_upcoming_invoice(
+        self, subscription_id: str
+    ) -> SubscriptionInvoicePreview | None:
+        _require_id("preview_upcoming_invoice", subscription_id)
+        response = await self._http.request(
+            Request(method="GET", path=_action_path(subscription_id, "upcoming"))
+        )
+        invoice = response["data"].get("invoice")
+        if invoice is None:
+            return None
+        return SubscriptionInvoicePreview.model_validate(invoice)
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Subscription]:
+        """Async iterate every subscription matching ``params``."""
+        start_page = params.page if params is not None and params.page is not None else 0
+        http = self._http
+
+        async def fetch(page: int) -> tuple[list[Subscription], bool]:
+            page_params = (
+                params.model_copy(update={"page": page})
+                if params is not None
+                else ListParams(page=page)
+            )
+            body = await http.request(
+                Request(
+                    method="GET",
+                    path="/subscriptions",
+                    query=_encode_list_params(page_params),
+                )
+            )
+            response = ListSubscriptionsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon-0.2.0/src/threecommon/subscriptions/types.py

@@ -0,0 +1,359 @@
+"""Public types for the subscriptions resource.
+
+Hand-curated Pydantic models that mirror the wire shape (camelCase aliases
+preserved). All response models use ``extra="ignore"`` so newer server-side
+fields don't break older SDK versions.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Lifecycle status of a subscription. Future server-side values will arrive
+#: as raw strings until the SDK is updated.
+SubscriptionStatus = Literal[
+    "incomplete",
+    "trialing",
+    "active",
+    "past_due",
+    "canceled",
+    "unpaid",
+]
+
+
+class _BaseModel(BaseModel):
+    """Shared config: accept snake_case or camelCase, ignore unknown fields."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore",
+        str_strip_whitespace=False,
+    )
+
+
+class SubscriptionItem(_BaseModel):
+    """One billed item on a subscription."""
+
+    id: str
+    price_id: str = Field(serialization_alias="priceId", validation_alias="priceId")
+    quantity: int
+
+
+class SubscriptionTaxId(_BaseModel):
+    """Host tax-ID snapshot carried onto each renewal invoice."""
+
+    type: str
+    value: str
+
+
+class Subscription(_BaseModel):
+    """One subscription as returned by the API.
+
+    Optional fields are populated only when the server returned them — list
+    responses with a ``fields`` filter omit unrequested values.
+    """
+
+    id: str
+    host_id: str | None = Field(
+        default=None, serialization_alias="hostId", validation_alias="hostId"
+    )
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contactId", validation_alias="contactId"
+    )
+    customer_email: str | None = Field(
+        default=None, serialization_alias="customerEmail", validation_alias="customerEmail"
+    )
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    quantity: int | None = None
+    items: list[SubscriptionItem] | None = None
+    status: SubscriptionStatus | None = None
+    current_period_start: str | None = Field(
+        default=None,
+        serialization_alias="currentPeriodStart",
+        validation_alias="currentPeriodStart",
+    )
+    current_period_end: str | None = Field(
+        default=None,
+        serialization_alias="currentPeriodEnd",
+        validation_alias="currentPeriodEnd",
+    )
+    trial_start: str | None = Field(
+        default=None, serialization_alias="trialStart", validation_alias="trialStart"
+    )
+    trial_end: str | None = Field(
+        default=None, serialization_alias="trialEnd", validation_alias="trialEnd"
+    )
+    billing_cycle_anchor: str | None = Field(
+        default=None,
+        serialization_alias="billingCycleAnchor",
+        validation_alias="billingCycleAnchor",
+    )
+    cancel_at: str | None = Field(
+        default=None, serialization_alias="cancelAt", validation_alias="cancelAt"
+    )
+    cancel_at_period_end: bool | None = Field(
+        default=None,
+        serialization_alias="cancelAtPeriodEnd",
+        validation_alias="cancelAtPeriodEnd",
+    )
+    canceled_at: str | None = Field(
+        default=None, serialization_alias="canceledAt", validation_alias="canceledAt"
+    )
+    cancel_reason: str | None = Field(
+        default=None, serialization_alias="cancelReason", validation_alias="cancelReason"
+    )
+    ended_at: str | None = Field(
+        default=None, serialization_alias="endedAt", validation_alias="endedAt"
+    )
+    started_at: str | None = Field(
+        default=None, serialization_alias="startedAt", validation_alias="startedAt"
+    )
+    dunning_enabled: bool | None = Field(
+        default=None,
+        serialization_alias="dunningEnabled",
+        validation_alias="dunningEnabled",
+    )
+    first_failure_at: str | None = Field(
+        default=None,
+        serialization_alias="firstFailureAt",
+        validation_alias="firstFailureAt",
+    )
+    next_retry_at: str | None = Field(
+        default=None,
+        serialization_alias="nextRetryAt",
+        validation_alias="nextRetryAt",
+    )
+    retry_count: int | None = Field(
+        default=None, serialization_alias="retryCount", validation_alias="retryCount"
+    )
+    notes: str | None = None
+    tax_ids: list[SubscriptionTaxId] | None = Field(
+        default=None, serialization_alias="taxIds", validation_alias="taxIds"
+    )
+    auto_charge: bool | None = Field(
+        default=None, serialization_alias="autoCharge", validation_alias="autoCharge"
+    )
+    payment_due_days: int | None = Field(
+        default=None,
+        serialization_alias="paymentDueDays",
+        validation_alias="paymentDueDays",
+    )
+    tax_rate: float | None = Field(
+        default=None, serialization_alias="taxRate", validation_alias="taxRate"
+    )
+    metadata: dict[str, str] | None = None
+    created_at: str | None = Field(
+        default=None, serialization_alias="createdAt", validation_alias="createdAt"
+    )
+    updated_at: str | None = Field(
+        default=None, serialization_alias="updatedAt", validation_alias="updatedAt"
+    )
+
+
+class SubscriptionInvoiceRef(_BaseModel):
+    """Slim invoice reference returned alongside renew/bill/update responses."""
+
+    id: str
+    status: str
+    total: int
+    currency: str
+
+
+class SubscriptionProration(_BaseModel):
+    """Proration summary returned by ``PATCH /v1/subscriptions/{id}``."""
+
+    net_amount_minor: int = Field(
+        serialization_alias="netAmountMinor", validation_alias="netAmountMinor"
+    )
+    days_remaining: int = Field(
+        serialization_alias="daysRemaining", validation_alias="daysRemaining"
+    )
+    days_in_cycle: int = Field(serialization_alias="daysInCycle", validation_alias="daysInCycle")
+
+
+class SubscriptionInvoicePreviewLineItem(_BaseModel):
+    """One line item on a subscription invoice preview."""
+
+    description: str
+    quantity: int
+    unit_amount: int = Field(serialization_alias="unitAmount", validation_alias="unitAmount")
+    product_id: str | None = Field(
+        default=None, serialization_alias="productId", validation_alias="productId"
+    )
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+
+
+class SubscriptionInvoicePreview(_BaseModel):
+    """Non-persisted projection of the invoice the next renewal will generate."""
+
+    customer_id: str = Field(serialization_alias="customerId", validation_alias="customerId")
+    subscription_id: str = Field(
+        serialization_alias="subscriptionId", validation_alias="subscriptionId"
+    )
+    currency: str
+    line_items: list[SubscriptionInvoicePreviewLineItem] = Field(
+        serialization_alias="lineItems", validation_alias="lineItems"
+    )
+    subtotal: int
+    total: int
+    period_start: str = Field(serialization_alias="periodStart", validation_alias="periodStart")
+    period_end: str = Field(serialization_alias="periodEnd", validation_alias="periodEnd")
+
+
+class ListSubscriptionsResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/subscriptions``."""
+
+    data: list[Subscription]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+
+
+class UpdateSubscriptionResult(_BaseModel):
+    """Successful response shape from ``PATCH /v1/subscriptions/{id}``."""
+
+    subscription: Subscription
+    invoice: SubscriptionInvoiceRef | None = None
+    proration: SubscriptionProration
+
+
+class BillSubscriptionResult(_BaseModel):
+    """Successful response shape from ``POST /v1/subscriptions/{id}/bill``."""
+
+    subscription: Subscription
+    invoice: SubscriptionInvoiceRef
+
+
+class RenewSubscriptionResult(_BaseModel):
+    """Successful response shape from ``POST /v1/subscriptions/{id}/renew``."""
+
+    subscription: Subscription
+    invoice: SubscriptionInvoiceRef | None = None
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/subscriptions``."""
+
+    page: int | None = None
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    status: SubscriptionStatus | None = None
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contactId", validation_alias="contactId"
+    )
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    fields: str | None = None
+
+
+class RetrieveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/subscriptions/{id}``."""
+
+    fields: str | None = None
+
+
+class CreateBodyItem(_BaseModel):
+    """One item on a multi-item subscription create body."""
+
+    price_id: str = Field(serialization_alias="priceId", validation_alias="priceId")
+    quantity: int | None = None
+
+
+class CreateBody(_BaseModel):
+    """Body accepted by ``POST /v1/subscriptions``."""
+
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    quantity: int | None = None
+    items: list[CreateBodyItem] | None = None
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contactId", validation_alias="contactId"
+    )
+    customer_email: str | None = Field(
+        default=None,
+        serialization_alias="customerEmail",
+        validation_alias="customerEmail",
+    )
+    trial_days: int | None = Field(
+        default=None, serialization_alias="trialDays", validation_alias="trialDays"
+    )
+    billing_cycle_anchor: str | None = Field(
+        default=None,
+        serialization_alias="billingCycleAnchor",
+        validation_alias="billingCycleAnchor",
+    )
+    cancel_at: str | None = Field(
+        default=None, serialization_alias="cancelAt", validation_alias="cancelAt"
+    )
+    dunning_enabled: bool | None = Field(
+        default=None,
+        serialization_alias="dunningEnabled",
+        validation_alias="dunningEnabled",
+    )
+    notes: str | None = None
+    tax_ids: list[SubscriptionTaxId] | None = Field(
+        default=None, serialization_alias="taxIds", validation_alias="taxIds"
+    )
+    auto_charge: bool | None = Field(
+        default=None, serialization_alias="autoCharge", validation_alias="autoCharge"
+    )
+    payment_due_days: int | None = Field(
+        default=None,
+        serialization_alias="paymentDueDays",
+        validation_alias="paymentDueDays",
+    )
+    tax_rate: float | None = Field(
+        default=None, serialization_alias="taxRate", validation_alias="taxRate"
+    )
+    metadata: dict[str, str] | None = None
+
+
+class UpdateBody(_BaseModel):
+    """Body accepted by ``PATCH /v1/subscriptions/{id}``.
+
+    Only fields you provide are changed.
+    """
+
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    quantity: int | None = None
+    notes: str | None = None
+    tax_ids: list[SubscriptionTaxId] | None = Field(
+        default=None, serialization_alias="taxIds", validation_alias="taxIds"
+    )
+    tax_rate: float | None = Field(
+        default=None, serialization_alias="taxRate", validation_alias="taxRate"
+    )
+    auto_charge: bool | None = Field(
+        default=None, serialization_alias="autoCharge", validation_alias="autoCharge"
+    )
+    dunning_enabled: bool | None = Field(
+        default=None,
+        serialization_alias="dunningEnabled",
+        validation_alias="dunningEnabled",
+    )
+    payment_due_days: int | None = Field(
+        default=None,
+        serialization_alias="paymentDueDays",
+        validation_alias="paymentDueDays",
+    )
+
+
+class CancelBody(_BaseModel):
+    """Body accepted by ``POST /v1/subscriptions/{id}/cancel``."""
+
+    reason: str | None = None
+
+
+class CancelImmediatelyBody(_BaseModel):
+    """Body accepted by ``POST /v1/subscriptions/{id}/cancel-immediately``."""
+
+    reason: str | None = None