vatly-api-python 0.1.0a2__py3-none-any.whl

vatly/models.py

@@ -0,0 +1,3009 @@
+# generated by datamodel-codegen:
+#   filename:  schema.json
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from datetime import date
+from typing import Annotated, Any, Literal
+
+from pydantic import AwareDatetime, ConfigDict, Field, RootModel
+
+from vatly._model import VatlyModel
+
+
+class Model(RootModel[Any]):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    root: Any
+
+
+class Money1(VatlyModel):
+    """
+    Monetary value with currency
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    value: Annotated[
+        str,
+        Field(
+            description='The amount as a decimal string. Sent and returned as a string to\npreserve precision for financial calculations.\n\nThe number of required decimal places is **currency-dependent**: it\nequals the currency\'s ISO 4217 minor-unit count — the same rule the\nserver enforces via [moneyphp/money](https://github.com/moneyphp/money)\'s\n`DecimalMoneyParser`. The `(value, currency)` pair is validated\ntogether (see the `oneOf` below); mixing precisions is rejected:\n\n- 2 decimals — EUR, USD (and most currencies): `"10.00"` ✓, `"10"` ✗, `"10.0"` ✗, `"10.000"` ✗\n- 0 decimals — e.g. JPY: `"1000"` ✓, `"1000.00"` ✗   *(not yet enabled)*\n- 3 decimals — e.g. BHD, KWD, OMR, TND: `"1.000"` ✓, `"1.00"` ✗   *(not yet enabled)*\n\nBecause the value is a decimal amount (not minor units), `"1000"`\nmeans one thousand units — valid only for a 0-decimal currency; for\nEUR/USD you must write `"1000.00"`.\n',
+            examples=["99.99"],
+            pattern="^\\d+\\.\\d{2}$",
+        ),
+    ]
+    currency: Annotated[
+        Literal["EUR", "USD"],
+        Field(
+            description="ISO 4217 currency code. Vatly aligns its supported currency set\nwith its payment provider's; currencies are enabled as PSP support and\ndownstream tax/FX coverage are in place. More currencies may be added\nlater.\n",
+            examples=["EUR"],
+        ),
+    ]
+
+
+class Money(RootModel[Money1]):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    root: Annotated[Money1, Field(description="Monetary value with currency")]
+
+
+class EurMoney(VatlyModel):
+    """
+    Monetary value in EUR. Used where the API currently accepts EUR prices
+    only: catalog prices and checkout price overrides. The `value` takes
+    exactly two decimals.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    value: Annotated[
+        str,
+        Field(
+            description="The amount as a decimal string with exactly two decimals.",
+            examples=["99.99"],
+            pattern="^\\d+\\.\\d{2}$",
+        ),
+    ]
+    currency: Annotated[
+        Literal["EUR"],
+        Field(
+            description="ISO 4217 currency code. Only `EUR` is accepted.",
+            examples=["EUR"],
+        ),
+    ]
+
+
+class Link(VatlyModel):
+    """
+    HATEOAS link to a related resource
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    href: Annotated[
+        str,
+        Field(
+            description="URL of the linked resource",
+            examples=["https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP"],
+        ),
+    ]
+    type: Annotated[
+        Literal["application/json", "text/html"],
+        Field(
+            description="Content type of the linked resource.\n- `application/json` for API resources\n- `text/html` for hosted pages\n",
+            examples=["application/json"],
+        ),
+    ]
+
+
+class BillingAddress(VatlyModel):
+    """
+    Customer or merchant billing address
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    full_name: Annotated[
+        str | None,
+        Field(
+            alias="fullName",
+            description="Full name of the person or contact",
+            examples=["John Doe"],
+        ),
+    ] = None
+    company_name: Annotated[
+        str | None,
+        Field(
+            alias="companyName",
+            description="Company or organization name",
+            examples=["Acme Corp"],
+        ),
+    ] = None
+    tax_id: Annotated[
+        str | None,
+        Field(
+            alias="taxId",
+            description="Tax identification number for tax purposes",
+            examples=["NL123456789B01"],
+        ),
+    ] = None
+    street_and_number: Annotated[
+        str | None,
+        Field(
+            alias="streetAndNumber",
+            description="Street address including building number",
+            examples=["123 Main Street"],
+        ),
+    ] = None
+    street_additional: Annotated[
+        str | None,
+        Field(
+            alias="streetAdditional",
+            description="Additional address information (apartment, suite, etc.)",
+            examples=["Suite 456"],
+        ),
+    ] = None
+    city: Annotated[str | None, Field(description="City name", examples=["Amsterdam"])] = None
+    region: Annotated[
+        str | None,
+        Field(description="State, province, or region", examples=["North Holland"]),
+    ] = None
+    postal_code: Annotated[
+        str | None,
+        Field(alias="postalCode", description="Postal or ZIP code", examples=["1012 AB"]),
+    ] = None
+    country: Annotated[
+        str | None,
+        Field(
+            description="ISO 3166-1 alpha-2 country code",
+            examples=["NL"],
+            max_length=2,
+            min_length=2,
+        ),
+    ] = None
+
+
+class BillingDetails(VatlyModel):
+    """
+    Complete billing details including address and contact information
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    full_name: Annotated[
+        str | None,
+        Field(
+            alias="fullName",
+            description="Full name of the person or contact",
+            examples=["John Doe"],
+        ),
+    ] = None
+    company_name: Annotated[
+        str | None,
+        Field(
+            alias="companyName",
+            description="Company or organization name",
+            examples=["Acme Corp"],
+        ),
+    ] = None
+    tax_id: Annotated[
+        str | None,
+        Field(
+            alias="taxId",
+            description="Tax identification number",
+            examples=["NL123456789B01"],
+        ),
+    ] = None
+    street_and_number: Annotated[
+        str | None,
+        Field(
+            alias="streetAndNumber",
+            description="Street address including building number",
+            examples=["123 Main Street"],
+        ),
+    ] = None
+    street_additional: Annotated[
+        str | None,
+        Field(
+            alias="streetAdditional",
+            description="Additional address information",
+            examples=["Suite 456"],
+        ),
+    ] = None
+    city: Annotated[str | None, Field(description="City name", examples=["Amsterdam"])] = None
+    region: Annotated[
+        str | None,
+        Field(description="State, province, or region", examples=["North Holland"]),
+    ] = None
+    postal_code: Annotated[
+        str | None,
+        Field(alias="postalCode", description="Postal or ZIP code", examples=["1012 AB"]),
+    ] = None
+    country: Annotated[
+        str | None,
+        Field(description="ISO 3166-1 alpha-2 country code", examples=["NL"]),
+    ] = None
+    email: Annotated[
+        str | None,
+        Field(
+            description="Email address.\nInternationalized domains must use their Punycode (ASCII) form\nper RFC 3492 — e.g. `billing@xn--mller-kva.de`.\n",
+            examples=["billing@acme.com"],
+        ),
+    ] = None
+
+
+class Metadata(RootModel[Mapping[str, Any] | None]):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    root: Annotated[
+        Mapping[str, Any] | None,
+        Field(
+            description="Arbitrary key-value metadata for your application.\nUp to 50 keys, with key names up to 40 characters and values up to 500 characters.\n",
+            examples=[{"orderId": "internal-12345", "campaign": "summer-sale"}],
+        ),
+    ]
+
+
+class PaginationLinks(VatlyModel):
+    """
+    Pagination links for navigating list results
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to the current page")]
+    next: Annotated[
+        Link | None,
+        Field(description="Link to the next page (null if on the last page)"),
+    ] = None
+    prev: Annotated[
+        Link | None,
+        Field(description="Link to the previous page (null if on the first page)"),
+    ] = None
+
+
+class Error(VatlyModel):
+    """
+    Standard error response.
+
+    Every non-validation error path returns this shape — `message` is
+    always present, and `details` (if present) is an object carrying
+    structured context attached by the originating exception. HTTP
+    status code is the primary programmatic discriminator.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    message: Annotated[
+        str,
+        Field(
+            description="Human-readable error message",
+            examples=["The requested resource was not found."],
+        ),
+    ]
+    details: Annotated[
+        Mapping[str, Any] | None,
+        Field(
+            description="Optional structured context attached by the originating exception.\nShape depends on the specific error case; clients should treat\nunknown keys as forward-compatible additions and rely on the HTTP\nstatus code for branching logic.\n",
+            examples=[{"resource_type": "checkout", "resource_id": "checkout_abc123"}],
+        ),
+    ] = None
+
+
+class ValidationError(VatlyModel):
+    """
+    Validation error response with field-specific errors
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    message: Annotated[
+        str,
+        Field(
+            description="General validation error message",
+            examples=["The given data was invalid."],
+        ),
+    ]
+    errors: Annotated[
+        Mapping[str, Sequence[str]],
+        Field(
+            description="Field-specific validation errors.\nKeys are field names (using dot notation for nested fields).\nValues are arrays of error messages.\n",
+            examples=[
+                {
+                    "email": ["The email field is required."],
+                    "products.0.id": ["The selected products.0.id is invalid."],
+                }
+            ],
+        ),
+    ]
+
+
+class Links(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    checkout_url: Annotated[
+        Link,
+        Field(alias="checkoutUrl", description="Hosted checkout page URL (text/html)"),
+    ]
+    self: Annotated[Link, Field(description="Link to this checkout resource")]
+    order: Annotated[
+        Link | None,
+        Field(
+            description="Link to the created order. Always present; `null` until the checkout completes."
+        ),
+    ] = None
+
+
+class Checkout(VatlyModel):
+    """
+    A checkout session represents a hosted payment flow.
+    Customers are redirected to the checkout URL to complete their purchase.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the checkout",
+            examples=["checkout_QdEpFhdSrG4Y3DnfsdqsH"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["checkout"],
+        Field(description="Resource type identifier", examples=["checkout"]),
+    ]
+    customer_id: Annotated[
+        str | None,
+        Field(
+            alias="customerId",
+            description="ID of the customer associated with this checkout.\nNull until a customer has been associated (for an anonymous\ncheckout this happens when the buyer completes payment).\n",
+            examples=["customer_7kBmRtPvXw2NjLhYcZaE"],
+        ),
+    ] = None
+    order_id: Annotated[
+        str | None,
+        Field(
+            alias="orderId",
+            description="ID of the order created from this checkout. Always present in the\npayload; `null` until the checkout completes, then set to the created\norder id.\n",
+            examples=["order_Tk7mNvBxKw2RjTgYcZaE"],
+        ),
+    ] = None
+    testmode: Annotated[
+        bool,
+        Field(description="Whether this checkout is in test mode", examples=[False]),
+    ]
+    redirect_url_success: Annotated[
+        str,
+        Field(
+            alias="redirectUrlSuccess",
+            description="URL to redirect customers after successful payment",
+            examples=["https://example.com/success"],
+        ),
+    ]
+    redirect_url_canceled: Annotated[
+        str,
+        Field(
+            alias="redirectUrlCanceled",
+            description="URL to redirect customers if they cancel the checkout",
+            examples=["https://example.com/canceled"],
+        ),
+    ]
+    metadata: Metadata | None = None
+    locale: Annotated[
+        Literal["en", "de", "fr", "nl", "es", "it", "pt", "pl"] | None,
+        Field(
+            description="The language you asked the hosted checkout to be presented in, as sent on\ncreation. `null` means you did not specify one, and the checkout picks a\nlanguage from the shopper's browser.\n",
+            examples=["de"],
+        ),
+    ]
+    status: Annotated[
+        Literal["created", "paid", "canceled", "failed", "expired"],
+        Field(
+            description="Current status of the checkout:\n- `created` - Checkout is active and awaiting payment\n- `paid` - Payment successful, order created\n- `canceled` - Checkout was canceled by the customer\n- `failed` - Payment failed\n- `expired` - Checkout expired without completion\n",
+            examples=["created"],
+        ),
+    ]
+    expires_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="expiresAt",
+            description="When this checkout will expire (ISO 8601 format)",
+            examples=["2024-01-15T14:30:00Z"],
+        ),
+    ] = None
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this checkout was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    links: Annotated[Links, Field(description="HATEOAS links to related resources")]
+
+
+class CheckoutProduct(VatlyModel):
+    """
+    A product to add to the checkout
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Product identifier. Must be either:\n- A one-off product ID (starts with `one_off_product_`)\n- A subscription plan ID (starts with `subscription_plan_`)\n",
+            examples=["one_off_product_Vr8kQdFhSrG4Y3DnfsdqH"],
+            pattern="^(one_off_product_|subscription_plan_)",
+        ),
+    ]
+    quantity: Annotated[
+        int | None, Field(description="Number of units to purchase", examples=[2], ge=1)
+    ] = 1
+    price: Annotated[
+        EurMoney | None,
+        Field(
+            description="Custom price override for this product, in EUR. If not provided, the\nproduct's default price is used.\n\nCurrently only EUR is accepted; any other currency returns a `422`.\nWhen the customer pays in another currency, the amount is converted\nfrom this EUR price at checkout. For a subscription, the converted\namount and currency are then fixed, so renewals charge the same amount.\n"
+        ),
+    ] = None
+    trial_days: Annotated[
+        int | None,
+        Field(
+            alias="trialDays",
+            description="Trial period in days for subscription plans.\nOnly applicable when `id` references a subscription plan.\n",
+            examples=[14],
+            ge=0,
+        ),
+    ] = None
+    metadata: Metadata | None = None
+
+
+class CreateCheckoutRequest(VatlyModel):
+    """
+    Request body for creating a new checkout
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    redirect_url_success: Annotated[
+        str,
+        Field(
+            alias="redirectUrlSuccess",
+            description="URL to redirect customers after successful payment.\n\nYou may include the literal `{CHECKOUT_ID}` placeholder anywhere in the\nURL (e.g. `https://example.com/return?checkout_id={CHECKOUT_ID}`). Vatly\nsubstitutes it with this checkout's id at creation time, so the host can\nlearn the checkout id on the redirect back without any server-side token\nstore. Only `{CHECKOUT_ID}` is supported.\n",
+            examples=["https://example.com/return?checkout_id={CHECKOUT_ID}"],
+        ),
+    ]
+    redirect_url_canceled: Annotated[
+        str,
+        Field(
+            alias="redirectUrlCanceled",
+            description="URL to redirect customers if they cancel the checkout.\n\nSupports the same `{CHECKOUT_ID}` placeholder as `redirectUrlSuccess`.\n",
+            examples=["https://example.com/canceled?checkout_id={CHECKOUT_ID}"],
+        ),
+    ]
+    customer_id: Annotated[
+        str | None,
+        Field(
+            alias="customerId",
+            description="Existing customer ID to associate with this checkout.\nIf provided, the customer's email will be pre-filled.\nMust match the testmode of the API token.\n",
+            examples=["customer_7kBmRtPvXw2NjLhYcZaE"],
+        ),
+    ] = None
+    billing_address: Annotated[
+        BillingAddress | None,
+        Field(
+            alias="billingAddress",
+            description="Optional editable prefill for the billing address fields on the hosted\ncheckout. When `country` is supplied, it takes precedence over the\nshopper's IP address for determining their country. A supplied `taxId`\nis only a prefill; it is not registered until the buyer submits the\ncheckout.\n",
+        ),
+    ] = None
+    metadata: Metadata | None = None
+    locale: Annotated[
+        str | None,
+        Field(
+            description="Language to present the hosted checkout in, including its validation and\nerror messages. Set this when you already know the customer's language —\nit is a better signal than their browser's.\n\nSend a bare language code (`de`), a BCP 47 tag (`de-AT`), or a POSIX /\nISO 15897 locale (`de_DE`) — whichever your stack already stores. All\nthree are folded to the language, so `de`, `de-AT` and `de_DE` are the\nsame request. There are no region-specific variants: an Austrian and a\nGerman customer are both served `de`.\n\nThe language also carries through to the payment provider's own hosted\npage, in whatever format that provider expects.\n\nSupported languages: `en`, `de`, `fr`, `nl`, `es`, `it`, `pt`, `pl`.\nAnything else is a `422` naming the supported set.\n\nOmit it (or send `null`) to detect the language from the shopper's\n`Accept-Language` header, falling back to English. A shopper can always\noverride your choice with the checkout's own language switcher.\n\nThe response echoes back the folded language, not the string you sent.\n",
+            examples=["de"],
+        ),
+    ] = None
+    products: Annotated[
+        Sequence[CheckoutProduct],
+        Field(
+            description="Products to include in this checkout",
+            examples=[
+                [
+                    {"id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH", "quantity": 1},
+                    {"id": "subscription_plan_Rk5pQrSvWm8NjLhYbUcP", "trialDays": 14},
+                ]
+            ],
+            min_length=1,
+        ),
+    ]
+
+
+class Links1(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this customer resource")]
+
+
+class Customer(VatlyModel):
+    """
+    A customer represents a person or organization that can make purchases.
+    Email addresses are scoped to a storefront and testmode, so the same
+    address exists as separate customers in test and live mode.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the customer",
+            examples=["customer_7kBmRtPvXw2NjLhYcZaE"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["customer"],
+        Field(description="Resource type identifier", examples=["customer"]),
+    ]
+    testmode: Annotated[
+        bool,
+        Field(description="Whether this customer is in test mode", examples=[False]),
+    ]
+    email: Annotated[
+        str,
+        Field(
+            description="Customer's email address.\nInternationalized domains are stored and returned in their\nPunycode (ASCII) form per UTS #46 — e.g. `user@xn--mller-kva.de`.\nConvert back to Unicode for display in your own UI.\n",
+            examples=["customer@example.com"],
+        ),
+    ]
+    name: Annotated[
+        str | None,
+        Field(
+            description="Customer's display / account-holder name. This is an identity field\nfor communication (dunning emails, dashboard) — it is distinct from,\nand does not affect, the billing name on invoices.\n",
+            examples=["John Doe"],
+        ),
+    ] = None
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this customer was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    metadata: Metadata | None = None
+    links: Annotated[Links1, Field(description="HATEOAS links to related resources")]
+
+
+class CreateCustomerRequest(VatlyModel):
+    """
+    Request body for creating a new customer
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    email: Annotated[
+        str,
+        Field(
+            description="Customer's email address. Submit it in any form: the local part is\nlower-cased and an internationalized domain is converted to its\nPunycode (ASCII) form per UTS #46, so `User@Müller.de` is stored and\nreturned as `user@xn--mller-kva.de`.\n\nAn address another customer in this storefront and testmode already\nholds is not an error — that customer is returned with `200`.\n",
+            examples=["customer@example.com"],
+        ),
+    ]
+    name: Annotated[
+        str | None,
+        Field(
+            description="Customer's display / account-holder name.",
+            examples=["John Doe"],
+            max_length=255,
+        ),
+    ] = None
+    metadata: Metadata | None = None
+
+
+class PendingUpdates(VatlyModel):
+    """
+    The changes that will take effect once a submitted update is approved, or
+    `null` when there is no pending update. Only the fields that actually
+    differ from the live product are present.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[str | None, Field(examples=["Premium License v2"])] = None
+    description: Annotated[str | None, Field(examples=["Now with more premium"])] = None
+    base_price: Annotated[Money | None, Field(alias="basePrice")] = None
+    product_type: Annotated[Literal["saas", "ebook"] | None, Field(alias="productType")] = None
+
+
+class Links2(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this product resource")]
+
+
+class OneOffProduct(VatlyModel):
+    """
+    A one-off product represents a single-purchase item.
+    Products are configured in the Vatly dashboard and can be added to checkouts.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the product (always starts with `one_off_product_`)",
+            examples=["one_off_product_Vr8kQdFhSrG4Y3DnfsdqH"],
+            pattern="^one_off_product_",
+        ),
+    ]
+    resource: Annotated[
+        Literal["one_off_product"],
+        Field(description="Resource type identifier", examples=["one_off_product"]),
+    ]
+    testmode: Annotated[
+        bool,
+        Field(description="Whether this product is in test mode", examples=[False]),
+    ]
+    name: Annotated[
+        str,
+        Field(description="Display name of the product", examples=["Premium License"]),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="Detailed description of the product",
+            examples=["Lifetime access to all premium features"],
+        ),
+    ]
+    base_price: Annotated[
+        Money,
+        Field(
+            alias="basePrice",
+            description="Default price of the product (can be overridden in checkout).\nInterpretation depends on `taxBehavior`:\n- `exclusive` → `basePrice` is the net amount; tax is added at checkout.\n- `inclusive` → `basePrice` already includes tax; net is back-computed from the buyer's jurisdiction.\n",
+        ),
+    ]
+    tax_behavior: Annotated[
+        Literal["exclusive", "inclusive"],
+        Field(
+            alias="taxBehavior",
+            description="Whether `basePrice` is tax-exclusive (B2B convention; tax added on top at checkout)\nor tax-inclusive (B2C convention; price already includes tax).\nImmutable after product creation. A checkout may not mix products with different\n`taxBehavior` values; doing so returns `422 Unprocessable Entity`.\n",
+            examples=["exclusive"],
+        ),
+    ]
+    product_type: Annotated[
+        str,
+        Field(
+            alias="productType",
+            description="What kind of product this is:\n- `saas` — software supplied as a service (hosted, licensed or otherwise\n  delivered online)\n- `ebook` — an electronic publication supplied as a download or stream\n\nSet when the product is created. Subscription plans accept `saas` only;\nan e-book is a one-time purchase, so sell it as a one-off product.\n",
+            examples=["saas"],
+        ),
+    ]
+    status: Annotated[
+        Literal["active", "pending", "rejected"],
+        Field(
+            description="Current status of the product:\n- `active` - Product is active and can be purchased\n- `pending` - Product is awaiting approval\n- `rejected` - Product has been rejected\n",
+            examples=["active"],
+        ),
+    ]
+    archived_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="archivedAt",
+            description="When this product was archived (ISO 8601), or `null` while it is on\nsale. Always present. An archived product is hidden from\n`GET /v1/one-off-products` and refused by `POST /v1/checkouts`; restore\nit with `DELETE /v1/one-off-products/{oneOffProductId}/archive`.\n",
+            examples=[None],
+        ),
+    ] = None
+    pending_updates: Annotated[
+        PendingUpdates | None,
+        Field(
+            alias="pendingUpdates",
+            description="The changes that will take effect once a submitted update is approved, or\n`null` when there is no pending update. Only the fields that actually\ndiffer from the live product are present.\n",
+            examples=[{"basePrice": {"currency": "EUR", "value": "349.00"}}],
+        ),
+    ] = None
+    update_status: Annotated[
+        Literal["pending", "reviewing"] | None,
+        Field(
+            alias="updateStatus",
+            description="Lifecycle of a pending update, or `null` when there is none:\n- `pending` - An update was submitted and is awaiting review\n- `reviewing` - The update is being reviewed\n",
+            examples=[None],
+        ),
+    ] = None
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this product was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    links: Annotated[Links2, Field(description="HATEOAS links to related resources")]
+
+
+class CreateOneOffProductRequest(VatlyModel):
+    """
+    Request body for creating a one-off product.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[
+        str,
+        Field(
+            description="Display name of the product.",
+            examples=["Premium License"],
+            max_length=255,
+            min_length=3,
+        ),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="Detailed description of the product.",
+            examples=["Lifetime access to all premium features"],
+        ),
+    ]
+    base_price: Annotated[
+        EurMoney, Field(alias="basePrice", description="Price of the product, in EUR.")
+    ]
+    product_type: Annotated[
+        Literal["saas", "ebook"],
+        Field(
+            alias="productType",
+            description="What kind of product this is:\n- `saas` — software supplied as a service (hosted, licensed or otherwise\n  delivered online)\n- `ebook` — an electronic publication supplied as a download or stream\n\nSet when the product is created. Subscription plans accept `saas` only;\nan e-book is a one-time purchase, so sell it as a one-off product.\n",
+            examples=["saas"],
+        ),
+    ]
+    tax_behavior: Annotated[
+        Literal["exclusive", "inclusive"] | None,
+        Field(
+            alias="taxBehavior",
+            description="Whether `basePrice` is tax-exclusive (B2B convention) or tax-inclusive\n(B2C convention). Optional; defaults to `exclusive`. Immutable after\nproduct creation.\n",
+            examples=["exclusive"],
+        ),
+    ] = "exclusive"
+
+
+class PendingUpdates1(VatlyModel):
+    """
+    The changes that will take effect once a submitted update is approved, or
+    `null` when there is no pending update. Only the fields that actually
+    differ from the live plan are present.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[str | None, Field(examples=["Pro Weekly"])] = None
+    description: Annotated[str | None, Field(examples=["Billed weekly"])] = None
+    base_price: Annotated[Money | None, Field(alias="basePrice")] = None
+    interval: Literal["day", "week", "month", "year"] | None = None
+    interval_count: Annotated[int | None, Field(alias="intervalCount", ge=1)] = None
+    product_type: Annotated[Literal["saas"] | None, Field(alias="productType")] = None
+
+
+class Links3(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this plan resource")]
+
+
+class SubscriptionPlan(VatlyModel):
+    """
+    A subscription plan defines recurring billing terms.
+    Plans are configured in the Vatly dashboard and can be added to checkouts.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the plan (always starts with `subscription_plan_`)",
+            examples=["subscription_plan_Wt5mNvBxKw7YcZaEjLhR"],
+            pattern="^subscription_plan_",
+        ),
+    ]
+    resource: Annotated[
+        Literal["subscription_plan"],
+        Field(description="Resource type identifier", examples=["subscription_plan"]),
+    ]
+    testmode: Annotated[
+        bool, Field(description="Whether this plan is in test mode", examples=[False])
+    ]
+    name: Annotated[str, Field(description="Display name of the plan", examples=["Pro Monthly"])]
+    description: Annotated[
+        str,
+        Field(
+            description="Detailed description of the plan",
+            examples=["Full access to all Pro features, billed monthly"],
+        ),
+    ]
+    base_price: Annotated[
+        Money,
+        Field(
+            alias="basePrice",
+            description="Price per billing interval.\nInterpretation depends on `taxBehavior`:\n- `exclusive` → `basePrice` is the net amount; tax is added at checkout.\n- `inclusive` → `basePrice` already includes tax; net is back-computed from the buyer's jurisdiction.\n",
+        ),
+    ]
+    tax_behavior: Annotated[
+        Literal["exclusive", "inclusive"],
+        Field(
+            alias="taxBehavior",
+            description="Whether `basePrice` is tax-exclusive (B2B convention) or tax-inclusive (B2C convention).\nImmutable after plan creation — create a new plan for the other mode. A checkout may not\nmix products with different `taxBehavior` values; doing so returns\n`422 Unprocessable Entity`.\n",
+            examples=["exclusive"],
+        ),
+    ]
+    interval: Annotated[
+        Literal["day", "week", "month", "year"],
+        Field(
+            description="Billing interval unit:\n- `day` - Daily billing\n- `week` - Weekly billing\n- `month` - Monthly billing\n- `year` - Yearly billing\n",
+            examples=["month"],
+        ),
+    ]
+    interval_count: Annotated[
+        int,
+        Field(
+            alias="intervalCount",
+            description="Number of interval units between billing cycles.\nFor example, `interval: month` with `intervalCount: 3` bills every 3 months.\n",
+            examples=[1],
+            ge=1,
+        ),
+    ]
+    product_type: Annotated[
+        Literal["saas"],
+        Field(
+            alias="productType",
+            description="What kind of product this plan sells. Only `saas` is available on a\nsubscription plan — an e-book is a one-time purchase, so sell it as a\none-off product instead.\n\nSet when the plan is created.\n",
+            examples=["saas"],
+        ),
+    ]
+    status: Annotated[
+        Literal["active", "pending", "rejected"],
+        Field(
+            description="Current status of the plan:\n- `active` - Plan is active and can be subscribed to\n- `pending` - Plan is awaiting approval\n- `rejected` - Plan has been rejected\n",
+            examples=["active"],
+        ),
+    ]
+    archived_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="archivedAt",
+            description="When this plan was archived (ISO 8601), or `null` while it is open to\nnew business. Always present. An archived plan is hidden from\n`GET /v1/subscription-plans`, refused by `POST /v1/checkouts`, and\ncannot be switched to from `PATCH /v1/subscriptions/{subscriptionId}`.\nSubscribers already on the plan keep billing unchanged. Restore it with\n`DELETE /v1/subscription-plans/{subscriptionPlanId}/archive`.\n",
+            examples=[None],
+        ),
+    ] = None
+    pending_updates: Annotated[
+        PendingUpdates1 | None,
+        Field(
+            alias="pendingUpdates",
+            description="The changes that will take effect once a submitted update is approved, or\n`null` when there is no pending update. Only the fields that actually\ndiffer from the live plan are present.\n",
+            examples=[{"interval": "week", "intervalCount": 1}],
+        ),
+    ] = None
+    update_status: Annotated[
+        Literal["pending", "reviewing"] | None,
+        Field(
+            alias="updateStatus",
+            description="Lifecycle of a pending update, or `null` when there is none:\n- `pending` - An update was submitted and is awaiting review\n- `reviewing` - The update is being reviewed\n",
+            examples=[None],
+        ),
+    ] = None
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this plan was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    links: Annotated[Links3, Field(description="HATEOAS links to related resources")]
+
+
+class CreateSubscriptionPlanRequest(VatlyModel):
+    """
+    Request body for creating a subscription plan.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[
+        str,
+        Field(
+            description="Display name of the plan.",
+            examples=["Pro Monthly"],
+            max_length=255,
+            min_length=3,
+        ),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="Detailed description of the plan.",
+            examples=["Full access to all Pro features, billed monthly"],
+        ),
+    ]
+    base_price: Annotated[
+        EurMoney,
+        Field(alias="basePrice", description="Price per billing interval, in EUR."),
+    ]
+    product_type: Annotated[
+        Literal["saas"],
+        Field(
+            alias="productType",
+            description="What kind of product this plan sells. Only `saas` is available on a\nsubscription plan — an e-book is a one-time purchase, so sell it as a\none-off product instead.\n\nSet when the plan is created.\n",
+            examples=["saas"],
+        ),
+    ]
+    tax_behavior: Annotated[
+        Literal["exclusive", "inclusive"] | None,
+        Field(
+            alias="taxBehavior",
+            description="Whether `basePrice` is tax-exclusive (B2B convention) or tax-inclusive\n(B2C convention). Optional; defaults to `exclusive`. Immutable after\nplan creation — create a new plan for the other mode.\n",
+            examples=["exclusive"],
+        ),
+    ] = "exclusive"
+    interval: Annotated[
+        Literal["day", "week", "month", "year"],
+        Field(
+            description="Billing interval unit. `day` is sandbox-only (test mode); live plans\nsupport `week`, `month`, and `year`.\n",
+            examples=["month"],
+        ),
+    ]
+    interval_count: Annotated[
+        int,
+        Field(
+            alias="intervalCount",
+            description="Number of interval units between billing cycles. Bounded per unit:\nup to 365 days, 52 weeks, or 12 months. For `year`, billing is always\nannual and this value is ignored.\n",
+            examples=[1],
+            ge=1,
+        ),
+    ]
+
+
+class Links4(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this order resource")]
+    customer: Annotated[
+        Link | None,
+        Field(
+            description="Link to the customer who made this purchase. Null for orders with no associated customer."
+        ),
+    ] = None
+    customer_invoice: Annotated[
+        Link,
+        Field(
+            alias="customerInvoice",
+            description="Link to the customer-facing invoice page in the customer portal (text/html).\nOn a refund or chargeback order this page is the credit note. The link is signed\nand expires after 72 hours; an expired link lets the customer request a fresh one by email.\n",
+        ),
+    ]
+
+
+class InvoiceUpdateLink(VatlyModel):
+    """
+    A signed URL for the customer to update invoice details (billing address, VAT number, company name)
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    href: Annotated[
+        str,
+        Field(
+            description="Signed URL to the address update page.\nValid for a limited time (typically 24 hours).\n",
+            examples=[
+                "https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP/edit?signature=abc123..."
+            ],
+        ),
+    ]
+    type: Annotated[
+        Literal["text/html"],
+        Field(description="Content type of the linked page", examples=["text/html"]),
+    ]
+
+
+class Links5(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this refund resource")]
+    original_order: Annotated[
+        Link, Field(alias="originalOrder", description="Link to the original order")
+    ]
+    order: Annotated[
+        Link | None,
+        Field(
+            description="Link to the credit note order. Always present; `null` until the credit-note order is created."
+        ),
+    ] = None
+    customer_invoice: Annotated[
+        Link | None,
+        Field(
+            alias="customerInvoice",
+            description="Link to this refund's credit note in the customer portal (text/html). This is the\nsame page as the credit-note order's `customerInvoice` link, not the original order's invoice.\nAlways present; `null` until the refund is processed. The link is signed and\nexpires after 72 hours; an expired link lets the customer request a fresh one by email.\n",
+        ),
+    ] = None
+
+
+class CreateFullRefundRequest(VatlyModel):
+    """
+    Request body for creating a full refund
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    metadata: Metadata | None = None
+
+
+class Links6(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this chargeback resource")]
+    original_order: Annotated[
+        Link, Field(alias="originalOrder", description="Link to the original order")
+    ]
+    order: Annotated[
+        Link | None,
+        Field(
+            description="Link to the credit note order. Always present; `null` until the credit-note order is created."
+        ),
+    ] = None
+    customer_invoice: Annotated[
+        Link | None,
+        Field(
+            alias="customerInvoice",
+            description="Link to this chargeback's credit note in the customer portal (text/html). This is the\nsame page as the credit-note order's `customerInvoice` link, not the original order's invoice.\nAlways present; `null` until the lost chargeback is processed. The link is signed and\nexpires after 72 hours; an expired link lets the customer request a fresh one by email.\n",
+        ),
+    ] = None
+
+
+class Links7(VatlyModel):
+    """
+    HATEOAS links to related resources. Always present on the persisted event.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this webhook event resource")]
+
+
+class Links8(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this webhook endpoint resource")]
+
+
+class WebhookEndpoint(VatlyModel):
+    """
+    A registered webhook endpoint. Vatly POSTs event deliveries to its `url`
+    and signs each one with the secret you set (see the `Vatly-Signature`
+    header).
+
+    A storefront can have up to five endpoints in each mode. URLs must be
+    unique within the storefront and mode. Each endpoint receives only the
+    public event names in `enabledEvents`; an empty list makes it dormant.
+
+    The signing secret is write-only: you provide it on creation (and may rotate
+    it via update) but it is never returned in any response. Store the value you
+    send; the API will not give it back.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the webhook endpoint",
+            examples=["webhook_QdEpFhdSrG4Y3DnfsdqsH"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["webhook_endpoint"],
+        Field(description="Resource type identifier", examples=["webhook_endpoint"]),
+    ]
+    testmode: Annotated[
+        bool,
+        Field(
+            description="Whether this endpoint receives test-mode events",
+            examples=[False],
+        ),
+    ]
+    url: Annotated[
+        str,
+        Field(
+            description="The HTTPS URL deliveries are POSTed to",
+            examples=["https://merchant.example/webhooks/vatly"],
+        ),
+    ]
+    enabled_events: Annotated[
+        Sequence[str],
+        Field(
+            alias="enabledEvents",
+            description="The endpoint's persisted subscription names. Current names in this list\nare delivered; a retired public name can remain visible for stable\nreadback but is inert. New event names are not added automatically;\nupdate this list to opt in. An empty list means no domain events are\ndelivered, although `webhook.setup` is still sent whenever Vatly\nverifies the endpoint configuration.\n",
+            examples=[["order.paid", "refund.completed"]],
+        ),
+    ]
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this endpoint was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    links: Annotated[Links8, Field(description="HATEOAS links to related resources")]
+
+
+class Links9(VatlyModel):
+    """
+    HATEOAS links to related resources
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this subscription resource")]
+    customer: Annotated[Link, Field(description="Link to the customer who owns this subscription")]
+
+
+class ScheduledUpdate(VatlyModel):
+    """
+    The target values for a change scheduled to take effect at the subscription's next
+    billing cycle — set by `PATCH /subscriptions/{subscriptionId}` with
+    `applyImmediately: false`. The rest of the object is the subscription's *current*
+    state; `scheduledUpdate` is what it will become.
+
+    Null when nothing is pending. Always present on both the REST resource and webhook
+    deliveries, so this is the authoritative way to reconcile a pending change — do not
+    depend on having received the `subscription.update_scheduled` webhook, which is
+    delivered once.
+
+    Cleared when the change is applied at renewal, and when it is discarded because the
+    subscription was canceled before that renewal happened.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    subscription_plan_id: Annotated[
+        str,
+        Field(
+            alias="subscriptionPlanId",
+            description="ID of the plan the subscription will switch to",
+            examples=["subscription_plan_Wt5mNvBxKw7YcZaEjLhR"],
+        ),
+    ]
+    name: Annotated[str, Field(description="Name of the scheduled plan", examples=["Pro Annual"])]
+    description: Annotated[str, Field(description="Description of the scheduled plan")]
+    base_price: Annotated[
+        Money,
+        Field(
+            alias="basePrice",
+            description="Scheduled price per billing cycle before taxes",
+        ),
+    ]
+    quantity: Annotated[int, Field(description="Scheduled quantity", examples=[1], ge=1)]
+    interval: Annotated[
+        Literal["day", "week", "month", "year"],
+        Field(description="Scheduled billing interval unit", examples=["month"]),
+    ]
+    interval_count: Annotated[
+        int,
+        Field(
+            alias="intervalCount",
+            description="Scheduled number of interval units between billing cycles",
+            examples=[1],
+            ge=1,
+        ),
+    ]
+    effective_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="effectiveAt",
+            description="When the change takes effect — the subscription's next renewal date. Null if the\nsubscription has no scheduled renewal.\n",
+            examples=["2024-03-15T10:30:00Z"],
+        ),
+    ] = None
+
+
+class Price(VatlyModel):
+    """
+    Change the recurring price, keeping the current plan. Provide
+    `price` without a `subscriptionPlanId` to change the price in place;
+    combine it with `subscriptionPlanId` to switch plans at a custom
+    price. The currency must match the subscription's currency. The
+    `prorate`, `applyImmediately`, `invoiceImmediately` and anchor
+    options apply exactly as they do for a plan or quantity change.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    value: Annotated[
+        str,
+        Field(
+            description="Price amount as a decimal string, with the exact number of decimals for the currency.",
+            examples=["99.99"],
+        ),
+    ]
+    currency: Annotated[
+        Literal["EUR", "USD"],
+        Field(
+            description="Must match the subscription's own currency (a subscription's\ncurrency is fixed at checkout and cannot be changed via an update).\n",
+            examples=["EUR"],
+        ),
+    ]
+
+
+class UpdateSubscriptionRequest(VatlyModel):
+    """
+    Request body for updating a subscription.
+    At least one of `subscriptionPlanId`, `quantity`, or `price` must be provided.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    subscription_plan_id: Annotated[
+        str | None,
+        Field(
+            alias="subscriptionPlanId",
+            description="ID of the new subscription plan.\nMust match the testmode of the current subscription.\n",
+            examples=["subscription_plan_Wt5mNvBxKw7YcZaEjLhR"],
+            pattern="^subscription_plan_",
+        ),
+    ] = None
+    quantity: Annotated[
+        int | None,
+        Field(
+            description="The new total quantity (e.g. number of seats). This sets the\nquantity to the given value — it is not added to the current\nquantity. Omit it to leave the quantity unchanged.\n",
+            examples=[5],
+            ge=1,
+        ),
+    ] = None
+    price: Annotated[
+        Price | None,
+        Field(
+            description="Change the recurring price, keeping the current plan. Provide\n`price` without a `subscriptionPlanId` to change the price in place;\ncombine it with `subscriptionPlanId` to switch plans at a custom\nprice. The currency must match the subscription's currency. The\n`prorate`, `applyImmediately`, `invoiceImmediately` and anchor\noptions apply exactly as they do for a plan or quantity change.\n"
+        ),
+    ] = None
+    prorate: Annotated[
+        bool | None,
+        Field(
+            description="How an immediate change is priced.\n- `true`: the new price for the time left on the cycle, minus a credit\n  for the old price over that same time\n- `false`: the full new price for the current cycle, on top of what was\n  already paid. This does not skip the charge; use\n  `prorationCharge: false` for that\n\nIgnored when `prorationCharge` is `false`.\n",
+            examples=[True],
+        ),
+    ] = True
+    proration_charge: Annotated[
+        bool | None,
+        Field(
+            alias="prorationCharge",
+            description="Whether an immediate change is charged at all.\n- `true`: charged as set by `prorate` and `invoiceImmediately`\n- `false`: the change applies now and nothing is charged for it. The\n  next renewal bills the new price, unless a change is already\n  scheduled for that renewal: that change still applies. A downgrade\n  gets no credit. During a trial the trial keeps running and its end\n  bills the new plan\n\nWith `false`, `invoiceImmediately: true`, `anchor`, `resetAnchor`,\n`trialUntil` and a change to a plan with a different interval are\nrejected with `422`: each would start or bill a new cycle now.\n",
+            examples=[False],
+        ),
+    ] = True
+    apply_immediately: Annotated[
+        bool | None,
+        Field(
+            alias="applyImmediately",
+            description="Whether to apply changes immediately or at the end of the current billing period.\n- `true`: Changes take effect immediately (with proration if enabled)\n- `false`: Changes apply when the current period ends\n\nDuring a trial, `true` ends the trial and starts the first paid cycle,\ncharged right away. Without `anchor` the cycle starts that day at the\nfull new price; with `anchor` it runs to that date, priced per\n`prorate`. A subscription that is `on_grace_period` starts no paid\ncycle and still ends on its communicated date.\n",
+            examples=[True],
+        ),
+    ] = False
+    invoice_immediately: Annotated[
+        bool | None,
+        Field(
+            alias="invoiceImmediately",
+            description="Whether to generate and charge an invoice immediately for proration.\nOnly applies when `applyImmediately` and `prorate` are both true.\n\nWhen `false` (the default) the proration delta is parked on the current\ncycle and billed as a line on the next renewal invoice — the customer\ngets one invoice and one payment covering both. If the subscription is\ncancelled before that renewal there is no next invoice and the parked\namount is waived, so a customer is never charged at the moment they\ncancel.\n\n**Set this to `true` on yearly and other long-interval plans.** The\ndefault suits monthly billing, where the delta is collected within\nweeks. On a yearly plan an upgrade in month 2 is not billed until\nmonth 12, and is waived entirely if the customer cancels at any point\nin between — so the longer the interval, the more the deferral costs\nyou. Charging immediately trades that for a separate invoice and\npayment (and its transaction fee) per change.\n\nAn immediate update during a trial is always charged right away,\nwhatever this is set to, because it starts the first paid cycle. This\ndoes not apply to a subscription that is `on_grace_period`.\n",
+            examples=[False],
+        ),
+    ] = False
+    anchor: Annotated[
+        date | None,
+        Field(
+            description="Set the billing anchor to a specific calendar date (YYYY-MM-DD,\ninterpreted in UTC). The new billing cycle is recalculated around\nthis anchor. Date-only by design — the anchor identifies a day,\nnot an instant, so daylight-saving transitions don't shift it.\nCannot be combined with `resetAnchor`.\n",
+            examples=["2024-02-01"],
+        ),
+    ] = None
+    reset_anchor: Annotated[
+        bool | None,
+        Field(
+            alias="resetAnchor",
+            description='Reset the billing anchor to "now" — the moment the update\nis processed becomes the new cycle anchor, and future\nrenewals align to it. Useful when a customer upgrades\nmid-cycle and you want the new plan\'s billing period to\nstart fresh from today.\nCannot be combined with `anchor`.\n',
+            examples=[True],
+        ),
+    ] = False
+    trial_until: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="trialUntil",
+            description="Extend or set a trial period until this date (ISO 8601 format).\nCannot be combined with `anchor`.\n",
+            examples=["2024-02-15T00:00:00Z"],
+        ),
+    ] = None
+
+
+class UpdateSubscriptionBillingRequest(VatlyModel):
+    """
+    Request body for updating subscription billing details via hosted flow
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    redirect_url_success: Annotated[
+        str,
+        Field(
+            alias="redirectUrlSuccess",
+            description="URL to redirect after successful billing update",
+            examples=["https://example.com/billing-updated"],
+        ),
+    ]
+    redirect_url_canceled: Annotated[
+        str,
+        Field(
+            alias="redirectUrlCanceled",
+            description="URL to redirect if customer cancels the update",
+            examples=["https://example.com/billing-canceled"],
+        ),
+    ]
+    billing_address: Annotated[
+        BillingAddress | None,
+        Field(
+            alias="billingAddress",
+            description="Optional editable prefill for the hosted billing update form. When\nsupplied, it replaces the subscription's stored billing details as the\nprefill, so send every field you want shown; empty strings give a blank\nform. Omit it, or send `null` or `{}`, to prefill the stored details.\n`country` must be an ISO 3166-1 alpha-2 code. A supplied `taxId` is\nonly a prefill; it is not registered until the customer submits the\nform.\n",
+        ),
+    ] = None
+
+
+class Mandate(VatlyModel):
+    """
+    A mandate represents an authorization to charge a customer's payment method
+    on a recurring basis (cards, SEPA Direct Debit, PayPal, Bacs).
+
+    This shape is the inline summary exposed on subscriptions — enough to
+    render "Visa ending in 4242" in a billing portal without an extra round
+    trip. A dedicated `/v1/mandates/{id}` endpoint with richer detail (status,
+    validity timestamps, billing snapshot) is on the roadmap; fields here are
+    forward-compatible additions to that future schema.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    method: Annotated[
+        Literal["card", "sepa_debit", "paypal", "bacs_debit"],
+        Field(
+            description="Normalized payment method category, provider-agnostic:\n- `card` — credit/debit card (incl. Apple Pay, Google Pay wallets)\n- `sepa_debit` — SEPA Direct Debit (incl. iDEAL, Bancontact, KBC and\n  other rail aliases that settle into a directdebit mandate)\n- `paypal` — PayPal billing agreement\n- `bacs_debit` — UK Bacs Direct Debit\n",
+            examples=["card"],
+        ),
+    ]
+    masked_identifier: Annotated[
+        str | None,
+        Field(
+            alias="maskedIdentifier",
+            description='Customer-facing masked identifier for the payment method on file:\nthe last 4 of a card (`"4242"`), a masked IBAN (`"NL91****4300"`),\na masked PayPal email (`"j***@example.com"`), or last 4 of a Bacs\naccount (`"****5678"`).\n\nMay briefly be `null` for freshly-subscribed customers when the\nunderlying authorization event doesn\'t carry the masked identifier\ninline — in that case it lands on a follow-up sync (runs at most\nevery 5 minutes) and the field updates from `null` to the resolved\nvalue once the sync completes.\n',
+            examples=["4242"],
+        ),
+    ] = None
+
+
+class UpdateCustomerRequest(VatlyModel):
+    """
+    Request body for updating a customer's identity fields. Only `name` and
+    `email` may be changed here — both are optional (send either or both).
+
+    Billing-address fields (company name, tax ID, street, city, country, etc.)
+    are not supported by this endpoint and are ignored; amend those through the
+    hosted billing-update flow, which validates tax-relevant data centrally.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[
+        str | None,
+        Field(
+            description="Customer's display / account-holder name.",
+            examples=["John Doe"],
+            max_length=255,
+        ),
+    ] = None
+    email: Annotated[
+        str | None,
+        Field(
+            description="Customer's email address, canonicalized on the way in exactly as on\ncreate (lower-cased local part, Punycode domain per UTS #46).\n\nUnlike create, a collision is rejected here: moving this customer onto\nan address another customer in the same storefront and testmode holds\nreturns `422`. Creating with a known address is a recovery; moving one\ncustomer onto another's address is a conflict.\n",
+            examples=["new.email@example.com"],
+        ),
+    ] = None
+
+
+class CreatePortalSessionRequest(VatlyModel):
+    """
+    Optional settings for a short-lived hosted customer portal session. The body
+    may be omitted or sent as `{}`. `returnUrl` must be sent here in the JSON
+    body; query-string input is rejected.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    return_url: Annotated[
+        str | None,
+        Field(
+            alias="returnUrl",
+            description="Absolute HTTPS URL without embedded credentials, rendered as a return\nlink in the hosted portal. The runtime limit is 2,048 UTF-8 bytes.\nVatly never fetches or automatically redirects to this URL.\n",
+            examples=["https://merchant.example/account/billing"],
+            max_length=2048,
+            pattern="^[Hh][Tt][Tt][Pp][Ss]://",
+        ),
+    ] = None
+
+
+class PortalSession(VatlyModel):
+    """
+    A short-lived, single-use entry link to the hosted customer portal. Redirect
+    the customer's browser to `url`; do not store it as a long-lived account
+    link.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    url: Annotated[
+        str,
+        Field(
+            description="Single-use HTTPS URL to redirect the customer to.",
+            examples=["https://billing.vatly.com/authenticate?credential=..."],
+        ),
+    ]
+    expires_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="expiresAt",
+            description="Expiry of the one-time entry link, not of the resulting browser session.",
+            examples=["2026-09-01T12:15:00Z"],
+        ),
+    ]
+    return_url: Annotated[
+        str | None,
+        Field(
+            alias="returnUrl",
+            description="The validated absolute HTTPS return URL supplied in the request, or\nnull. It contains no embedded credentials and is limited to 2,048\nUTF-8 bytes.\n",
+            examples=["https://merchant.example/account/billing"],
+            max_length=2048,
+            pattern="^[Hh][Tt][Tt][Pp][Ss]://",
+        ),
+    ] = None
+
+
+class UpdateOneOffProductRequest(VatlyModel):
+    """
+    Request body for submitting an update to a live one-off product. Each request
+    is the **complete set of changes** relative to the current live product, and
+    must contain at least one field. A field submitted equal to the live value is
+    ignored; a submission that nets to no change clears any pending update. The
+    update enters review (`updateStatus: pending`) before it takes effect (in test
+    mode it is approved automatically).
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[
+        str | None,
+        Field(
+            description="New display name of the product.",
+            examples=["Premium License v2"],
+            max_length=255,
+            min_length=3,
+        ),
+    ] = None
+    description: Annotated[
+        str | None,
+        Field(
+            description="New description of the product.",
+            examples=["Now with more premium"],
+        ),
+    ] = None
+    base_price: Annotated[
+        EurMoney | None,
+        Field(alias="basePrice", description="New price of the product, in EUR."),
+    ] = None
+    product_type: Annotated[
+        Literal["saas", "ebook"] | None,
+        Field(
+            alias="productType",
+            description="What kind of product this is:\n- `saas` — software supplied as a service (hosted, licensed or otherwise\n  delivered online)\n- `ebook` — an electronic publication supplied as a download or stream\n\nSet when the product is created. Subscription plans accept `saas` only;\nan e-book is a one-time purchase, so sell it as a one-off product.\n",
+            examples=["saas"],
+        ),
+    ] = None
+
+
+class UpdateSubscriptionPlanRequest(VatlyModel):
+    """
+    Request body for submitting an update to a live subscription plan. Each
+    request is the **complete set of changes** relative to the current live plan,
+    and must contain at least one field. A field submitted equal to the live value
+    is ignored; a submission that nets to no change clears any pending update. The
+    update enters review (`updateStatus: pending`) before it takes effect (in test
+    mode it is approved automatically).
+
+    The interval cannot be changed once the plan has ever been used by a
+    subscription, active or not. The price stays changeable.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[
+        str | None,
+        Field(
+            description="New display name of the plan.",
+            examples=["Pro Weekly"],
+            max_length=255,
+            min_length=3,
+        ),
+    ] = None
+    description: Annotated[
+        str | None,
+        Field(description="New description of the plan.", examples=["Billed weekly"]),
+    ] = None
+    base_price: Annotated[
+        EurMoney | None,
+        Field(alias="basePrice", description="New price per billing interval, in EUR."),
+    ] = None
+    product_type: Annotated[
+        Literal["saas"] | None, Field(alias="productType", examples=["saas"])
+    ] = None
+    interval: Annotated[
+        Literal["day", "week", "month", "year"] | None, Field(examples=["week"])
+    ] = None
+    interval_count: Annotated[
+        int | None,
+        Field(
+            alias="intervalCount",
+            description="Required when `interval` is provided.",
+            examples=[1],
+            ge=1,
+        ),
+    ] = None
+
+
+class TaxSummaryRate(VatlyModel):
+    """
+    Simplified tax rate information
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    name: Annotated[str, Field(description="Human-readable name of the tax rate", examples=["VAT"])]
+    percentage: Annotated[float, Field(description="Tax rate percentage", examples=[21])]
+    taxable_percentage: Annotated[
+        float,
+        Field(
+            alias="taxablePercentage",
+            description="Percentage of the amount that is taxable",
+            examples=[100],
+        ),
+    ]
+
+
+class TaxSummaryItem(VatlyModel):
+    """
+    A single tax rate entry with its calculated amount
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    tax_rate: Annotated[TaxSummaryRate, Field(alias="taxRate")]
+    amount: Annotated[Money, Field(description="Tax amount for this rate")]
+
+
+class RefundItem(VatlyModel):
+    """
+    An item to refund from an order
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    item_id: Annotated[
+        str,
+        Field(
+            alias="itemId",
+            description="ID of the order line item to refund",
+            examples=["order_item_Jk4pQrSvWm8NjLhYbUcP"],
+        ),
+    ]
+    amount: Annotated[
+        Money,
+        Field(
+            description="Amount to refund for this item (before taxes).\nCannot exceed the remaining refundable amount for the item.\n"
+        ),
+    ]
+    description: Annotated[
+        str | None,
+        Field(
+            description="Custom description for this refund line",
+            examples=["Partial refund for service issue"],
+        ),
+    ] = None
+    description_additional_line: Annotated[
+        str | None,
+        Field(
+            alias="descriptionAdditionalLine",
+            description="Additional description line for the refund",
+            examples=["Ticket #12345"],
+        ),
+    ] = None
+
+
+class WebhookSubscriptionEventName(
+    RootModel[
+        Literal[
+            "checkout.canceled",
+            "checkout.expired",
+            "checkout.failed",
+            "checkout.paid",
+            "one_off_product.archived",
+            "one_off_product.unarchived",
+            "one_off_product.update_approved",
+            "one_off_product.update_rejected",
+            "one_off_product.update_submitted",
+            "order.canceled",
+            "order.chargeback_received",
+            "order.chargeback_reversed",
+            "order.paid",
+            "order.payment_failed",
+            "refund.canceled",
+            "refund.completed",
+            "refund.failed",
+            "subscription.billing_updated",
+            "subscription.canceled_for_nonpayment",
+            "subscription.canceled_immediately",
+            "subscription.canceled_with_grace_period",
+            "subscription.cancellation_grace_period_completed",
+            "subscription.resumed",
+            "subscription.started",
+            "subscription.update_scheduled",
+            "subscription.updated",
+            "subscription_plan.archived",
+            "subscription_plan.unarchived",
+            "subscription_plan.update_approved",
+            "subscription_plan.update_rejected",
+            "subscription_plan.update_submitted",
+        ]
+    ]
+):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    root: Annotated[
+        Literal[
+            "checkout.canceled",
+            "checkout.expired",
+            "checkout.failed",
+            "checkout.paid",
+            "one_off_product.archived",
+            "one_off_product.unarchived",
+            "one_off_product.update_approved",
+            "one_off_product.update_rejected",
+            "one_off_product.update_submitted",
+            "order.canceled",
+            "order.chargeback_received",
+            "order.chargeback_reversed",
+            "order.paid",
+            "order.payment_failed",
+            "refund.canceled",
+            "refund.completed",
+            "refund.failed",
+            "subscription.billing_updated",
+            "subscription.canceled_for_nonpayment",
+            "subscription.canceled_immediately",
+            "subscription.canceled_with_grace_period",
+            "subscription.cancellation_grace_period_completed",
+            "subscription.resumed",
+            "subscription.started",
+            "subscription.update_scheduled",
+            "subscription.updated",
+            "subscription_plan.archived",
+            "subscription_plan.unarchived",
+            "subscription_plan.update_approved",
+            "subscription_plan.update_rejected",
+            "subscription_plan.update_submitted",
+        ],
+        Field(
+            description="A public event name that can be enabled for a webhook endpoint. The\n`webhook.setup` verification event is deliberately excluded: Vatly sends\nthat event whenever it verifies endpoint configuration, regardless of the\nendpoint's subscriptions.\n",
+            examples=["order.paid"],
+        ),
+    ]
+
+
+class FastForwardSubscriptionRenewalRequest(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    payment_status: Annotated[
+        Literal["paid", "failed"] | None,
+        Field(
+            alias="paymentStatus",
+            description="Deterministic outcome to simulate for the test-mode renewal payment. The\nhelper uses a local payment and does not submit a charge to the provider\nsandbox, so a provider response cannot override this requested status.\n\nOmit it to advance the billing cycle and leave that local payment\npending, which is this endpoint's original behaviour.\n\n`failed` declines the payment and starts a payment recovery for the\nrenewal order, so `order.payment_failed` is delivered to your webhook\nendpoint. `paid` settles it.\n",
+            examples=["failed"],
+        ),
+    ] = None
+    failure_reason: Annotated[
+        Literal[
+            "insufficient_funds",
+            "temporary_decline",
+            "general_failure",
+            "invalid_mandate",
+            "mandate_canceled",
+            "account_closed",
+            "card_expired",
+            "card_lost_or_stolen",
+            "invalid_card_details",
+            "authentication_failed",
+            "fraud_suspected",
+        ]
+        | None,
+        Field(
+            alias="failureReason",
+            description="Which decline to simulate. Only valid alongside `paymentStatus: failed`;\nsending it with `paid` is rejected.\n\nThe reason decides how the payment recovery proceeds. A soft decline\n(`insufficient_funds`, `temporary_decline`, `general_failure`) means the\npayment method is still good, so recovery retries on a multi-week\ntimeline. Every other value is a hard decline: the payment method is\ndead, retrying is pointless, and recovery instead drives the customer to\nsupply a new one on a short timeline.\n\nDefaults to `general_failure`, which is soft.\n",
+            examples=["card_expired"],
+        ),
+    ] = "general_failure"
+
+
+class SimulateOrderPaymentRequest(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    payment_status: Annotated[
+        Literal["paid", "failed"],
+        Field(
+            alias="paymentStatus",
+            description="Outcome to force on the order's pending payment.\n\n`paid` settles it, so `order.paid` is delivered to your webhook endpoint.\n`failed` declines it and starts a payment recovery, so\n`order.payment_failed` is delivered.\n",
+            examples=["paid"],
+        ),
+    ]
+    failure_reason: Annotated[
+        Literal[
+            "insufficient_funds",
+            "temporary_decline",
+            "general_failure",
+            "invalid_mandate",
+            "mandate_canceled",
+            "account_closed",
+            "card_expired",
+            "card_lost_or_stolen",
+            "invalid_card_details",
+            "authentication_failed",
+            "fraud_suspected",
+        ]
+        | None,
+        Field(
+            alias="failureReason",
+            description="Which decline to simulate. Only valid alongside `paymentStatus: failed`;\nsending it with `paid` is rejected.\n\nThe reason decides how the payment recovery proceeds. A soft decline\n(`insufficient_funds`, `temporary_decline`, `general_failure`) means the\npayment method is still good, so recovery retries on a multi-week\ntimeline. Every other value is a hard decline: the payment method is\ndead, retrying is pointless, and recovery instead drives the customer to\nsupply a new one on a short timeline.\n\nDefaults to `general_failure`, which is soft.\n",
+            examples=["card_expired"],
+        ),
+    ] = "general_failure"
+
+
+class Webhook(VatlyModel):
+    """
+    A registered webhook endpoint configuration — the subject of a `webhook.setup`
+    verification call. Never includes the signing secret.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    resource: Annotated[Literal["webhook"], Field(examples=["webhook"])]
+    id: Annotated[
+        str,
+        Field(
+            description="The webhook endpoint identifier.",
+            examples=["webhook_QdEpFhdSrG4Y3DnfsdqsH"],
+        ),
+    ]
+    url: Annotated[
+        str,
+        Field(
+            description="The endpoint the verification call was sent to.",
+            examples=["https://merchant.example/webhooks/vatly"],
+        ),
+    ]
+    testmode: Annotated[bool, Field(examples=[True])]
+
+
+class Links10(VatlyModel):
+    """
+    HATEOAS links to related resources. Present on event deliveries; omitted on
+    the `webhook.setup` verification call, which is not a persisted resource.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    self: Annotated[Link, Field(description="Link to this webhook event resource")]
+
+
+class ListCheckoutsParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListCustomersParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    email: str | None = None
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListCustomerSubscriptionsParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListOneOffProductsParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+    include_archived: Annotated[bool | None, Field(alias="includeArchived")] = False
+
+
+class ListSubscriptionPlansParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+    include_archived: Annotated[bool | None, Field(alias="includeArchived")] = False
+
+
+class ListOrdersParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListOrderRefundsParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListOrderChargebacksParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListRefundsParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListChargebacksParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListWebhookEndpointsParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class ListSubscriptionsParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    limit: Annotated[int | None, Field(ge=1, le=100)] = 10
+    starting_after: Annotated[str | None, Field(alias="startingAfter")] = None
+    ending_before: Annotated[str | None, Field(alias="endingBefore")] = None
+
+
+class CancelSubscriptionParams(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    immediately: bool | None = False
+
+
+class CreateSubscriptionBillingUpdateLinkResponse(VatlyModel):
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    href: Annotated[
+        str,
+        Field(
+            description="URL to redirect customer for billing update",
+            examples=[
+                "https://vatly.com/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE/billing?token=xyz..."
+            ],
+        ),
+    ]
+    type: Annotated[Literal["text/html"], Field(examples=["text/html"])]
+
+
+class OrderLine(VatlyModel):
+    """
+    A line item in an order
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for this line item",
+            examples=["order_item_Jk4pQrSvWm8NjLhYbUcP"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["orderline"],
+        Field(description="Resource type identifier", examples=["orderline"]),
+    ]
+    description: Annotated[
+        str,
+        Field(description="Description of the item", examples=["Pro Monthly Subscription"]),
+    ]
+    quantity: Annotated[int, Field(description="Number of units", examples=[1], ge=1)]
+    base_price: Annotated[
+        Money, Field(alias="basePrice", description="Price per unit before taxes")
+    ]
+    total: Annotated[
+        Money,
+        Field(description="Total price including taxes (basePrice * quantity + taxes)"),
+    ]
+    subtotal: Annotated[Money, Field(description="Subtotal before taxes (basePrice * quantity)")]
+    taxes: Annotated[
+        Sequence[TaxSummaryItem],
+        Field(description="Tax breakdown by rate for this line"),
+    ]
+    product_type: Annotated[
+        Literal[
+            "one_off_product",
+            "subscription_plan",
+            "subscription",
+            "billing_details_verification",
+            "auth_request_product",
+        ]
+        | None,
+        Field(
+            alias="productType",
+            description="The product type this line links to; null when the line has no product link.",
+            examples=["subscription"],
+        ),
+    ] = None
+    product_id: Annotated[
+        str | None,
+        Field(
+            alias="productId",
+            description="The linked product's id; for a `subscription` line this is the public `subscription_…` id.",
+            examples=["subscription_Hn5xWqVfKm8RjTgYbUcP"],
+        ),
+    ] = None
+
+
+class RefundLine(VatlyModel):
+    """
+    A line item in a refund
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for this refund line",
+            examples=["refund_item_Tk7mNvBxKw2RjTgYcZaE"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["refundline"],
+        Field(description="Resource type identifier", examples=["refundline"]),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="Description of the refunded item",
+            examples=["Pro Monthly Subscription (Refund)"],
+        ),
+    ]
+    quantity: Annotated[
+        int, Field(description="Number of units being refunded", examples=[1], ge=1)
+    ]
+    base_price: Annotated[
+        Money,
+        Field(alias="basePrice", description="Refund amount per unit before taxes"),
+    ]
+    total: Annotated[Money, Field(description="Total refund amount including taxes")]
+    subtotal: Annotated[Money, Field(description="Refund subtotal before taxes")]
+    taxes: Annotated[
+        Sequence[TaxSummaryItem],
+        Field(description="Tax breakdown by rate being refunded"),
+    ]
+
+
+class CreateRefundRequest(VatlyModel):
+    """
+    Request body for creating a partial refund
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    items: Annotated[
+        Sequence[RefundItem],
+        Field(
+            description="Items to refund",
+            examples=[
+                [
+                    {
+                        "itemId": "order_item_Jk4pQrSvWm8NjLhYbUcP",
+                        "amount": {"value": "15.00", "currency": "EUR"},
+                        "description": "Partial refund",
+                    }
+                ]
+            ],
+            min_length=1,
+        ),
+    ]
+    metadata: Metadata | None = None
+
+
+class Chargeback(VatlyModel):
+    """
+    A chargeback represents a payment dispute initiated by a customer through their bank or card issuer.
+    Chargebacks are created automatically when the payment provider notifies Vatly of a dispute.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the chargeback",
+            examples=["chargeback_Mn6xBtPvKw2RjTgYcZaE"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["chargeback"],
+        Field(description="Resource type identifier", examples=["chargeback"]),
+    ]
+    customer_id: Annotated[
+        str,
+        Field(
+            alias="customerId",
+            description="ID of the customer the chargeback was raised against",
+            examples=["customer_Lp3mNvBxKw7RjTgYcZaE"],
+        ),
+    ]
+    testmode: Annotated[
+        bool,
+        Field(description="Whether this chargeback is in test mode", examples=[False]),
+    ]
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this chargeback was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    status: Annotated[
+        Literal[
+            "pending",
+            "requires_amount_review",
+            "accepted",
+            "rejected",
+            "evidence_submitted",
+            "won",
+            "lost",
+        ],
+        Field(
+            description="Current status of the chargeback dispute:\n- `pending` - Dispute received, awaiting action\n- `requires_amount_review` - Provider amount exceeds the original order; financial completion is quarantined pending review\n- `accepted` - Merchant accepted the dispute\n- `rejected` - Dispute rejected\n- `evidence_submitted` - Evidence submitted, awaiting decision\n- `won` - Dispute resolved in the merchant's favor\n- `lost` - Dispute resolved in the customer's favor\n",
+            examples=["pending"],
+        ),
+    ]
+    amount: Annotated[Money, Field(description="Amount of the chargeback")]
+    settlement_amount: Annotated[
+        Money,
+        Field(
+            alias="settlementAmount",
+            description="Amount that was deducted from the merchant's settlement.\nMay differ from `amount` due to currency conversion or fees.\n",
+        ),
+    ]
+    total: Annotated[Money, Field(description="Total chargeback amount including taxes")]
+    subtotal: Annotated[Money, Field(description="Chargeback subtotal before taxes")]
+    tax_summary: Annotated[
+        Sequence[TaxSummaryItem],
+        Field(alias="taxSummary", description="Tax breakdown by rate for the chargeback"),
+    ]
+    reason: Annotated[
+        str,
+        Field(
+            description="Reason code or description for the chargeback.\nCommon reasons include:\n- `fraud` - Unauthorized transaction\n- `product_not_received` - Customer claims non-delivery\n- `product_unacceptable` - Customer claims product was defective\n- `duplicate` - Customer claims duplicate charge\n- `subscription_canceled` - Customer claims subscription was canceled\n",
+            examples=["fraud"],
+        ),
+    ]
+    original_order_id: Annotated[
+        str,
+        Field(
+            alias="originalOrderId",
+            description="ID of the original order that was charged back",
+            examples=["order_Fp2kQrSvWm8NjLhYbUcP"],
+        ),
+    ]
+    order_id: Annotated[
+        str | None,
+        Field(
+            alias="orderId",
+            description="ID of the credit note order created for this chargeback. Always present\nin the payload; `null` until the chargeback is processed, then set to the\ncredit-note order id.\n",
+            examples=["order_Rk5pQrSvWm8NjLhYbUcP"],
+        ),
+    ] = None
+    links: Annotated[Links6, Field(description="HATEOAS links to related resources")]
+
+
+class CreateWebhookEndpointRequest(VatlyModel):
+    """
+    Request body for registering a new webhook endpoint
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    url: Annotated[
+        str,
+        Field(
+            description="The HTTPS URL deliveries are POSTed to. Must be publicly reachable and\npresent a valid SSL certificate — Vatly sends a `webhook.setup`\nverification ping on registration and rejects the request if it fails.\n`localhost` and loopback addresses are not allowed.\n",
+            examples=["https://merchant.example/webhooks/vatly"],
+        ),
+    ]
+    secret: Annotated[
+        str,
+        Field(
+            description="Signing secret for this endpoint, used to compute the `Vatly-Signature`\nHMAC on every delivery. You choose it (e.g. pinned from an environment\nvariable) and use it to verify inbound webhooks. It is write-only — keep\nthis value, as the API never returns it.\n",
+            examples=["whsec_3f9a1c7e2d4f7b9c5a2c1d5b7e9f3a8d"],
+            min_length=10,
+        ),
+    ]
+    enabled_events: Annotated[
+        Sequence[WebhookSubscriptionEventName] | None,
+        Field(
+            alias="enabledEvents",
+            description="The explicit events delivered to this endpoint. If omitted, Vatly\nstores all event names available at registration time. New event names\nadded later are not enabled automatically. Send an empty list to create\na dormant endpoint. `webhook.setup` cannot be selected and remains an\nunconditional configuration-verification event.\n",
+            examples=[["order.paid", "refund.completed"]],
+        ),
+    ] = None
+
+
+class UpdateWebhookEndpointRequest(VatlyModel):
+    """
+    Request body for updating a webhook endpoint. Send `url` to repoint the
+    endpoint, `secret` to rotate the signing secret, and/or `enabledEvents` to
+    replace its full subscription set. Omitting all three is a no-op that
+    returns the current endpoint.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    url: Annotated[
+        str | None,
+        Field(
+            description="New HTTPS delivery URL. Revalidated for reachability and SSL the same\nway as on creation.\n",
+            examples=["https://merchant.example/webhooks/vatly-v2"],
+        ),
+    ] = None
+    secret: Annotated[
+        str | None,
+        Field(
+            description="New signing secret for this endpoint. Write-only — keep the value, as\nthe API never returns it.\n",
+            examples=["whsec_a1b2c3d4e5f60718293a4b5c6d7e8f90"],
+            min_length=10,
+        ),
+    ] = None
+    enabled_events: Annotated[
+        Sequence[WebhookSubscriptionEventName] | None,
+        Field(
+            alias="enabledEvents",
+            description="Replaces the endpoint's complete event subscription set. Omit this\nfield to preserve the current subscriptions; send an empty list to make\nthe endpoint dormant. New event names are never added automatically.\n`webhook.setup` is not subscribable.\n",
+            examples=[["checkout.paid", "order.paid"]],
+        ),
+    ] = None
+
+
+class Subscription(VatlyModel):
+    """
+    A subscription represents a recurring billing relationship with a customer.
+    Subscriptions automatically renew according to their billing interval.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the subscription",
+            examples=["subscription_Lp3mNvBxKw7RjTgYcZaE"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["subscription"],
+        Field(description="Resource type identifier", examples=["subscription"]),
+    ]
+    customer_id: Annotated[
+        str,
+        Field(
+            alias="customerId",
+            description="ID of the customer who owns this subscription",
+            examples=["customer_Lp3mNvBxKw7RjTgYcZaE"],
+        ),
+    ]
+    subscription_plan_id: Annotated[
+        str,
+        Field(
+            alias="subscriptionPlanId",
+            description="ID of the subscription plan this subscription is based on",
+            examples=["subscription_plan_Wt5mNvBxKw7YcZaEjLhR"],
+        ),
+    ]
+    testmode: Annotated[
+        bool,
+        Field(description="Whether this subscription is in test mode", examples=[False]),
+    ]
+    name: Annotated[
+        str,
+        Field(
+            description="Name of the subscription (from the plan)",
+            examples=["Pro Monthly"],
+        ),
+    ]
+    description: Annotated[
+        str,
+        Field(
+            description="Description of the subscription",
+            examples=["Full access to all Pro features"],
+        ),
+    ]
+    billing_address: Annotated[
+        BillingAddress,
+        Field(
+            alias="billingAddress",
+            description="Customer's billing address for this subscription",
+        ),
+    ]
+    base_price: Annotated[
+        Money,
+        Field(alias="basePrice", description="Price per billing cycle before taxes"),
+    ]
+    quantity: Annotated[
+        int,
+        Field(description="Number of subscription units (e.g., seats)", examples=[1], ge=1),
+    ]
+    interval: Annotated[
+        Literal["day", "week", "month", "year"],
+        Field(description="Billing interval unit", examples=["month"]),
+    ]
+    interval_count: Annotated[
+        int,
+        Field(
+            alias="intervalCount",
+            description="Number of interval units between billing cycles",
+            examples=[1],
+            ge=1,
+        ),
+    ]
+    status: Annotated[
+        Literal["active", "created", "trial", "on_grace_period", "paused", "canceled"],
+        Field(
+            description="Current status of the subscription:\n- `active` - Subscription is active and will renew\n- `created` - Subscription has been created but not yet started\n- `trial` - Subscription is in trial period\n- `on_grace_period` - Subscription is canceled but still active until period ends\n- `paused` - Subscription is temporarily paused\n- `canceled` - Subscription has been canceled\n",
+            examples=["active"],
+        ),
+    ]
+    cancellation_reason: Annotated[
+        Literal["payment_failure", "merchant_request", "customer_request"] | None,
+        Field(
+            alias="cancellationReason",
+            description="Why the subscription was canceled. Null unless a cancellation has been\nrequested. Public values are intentionally decoupled from internal domain\nreason names:\n- `payment_failure` - Payment recovery was exhausted after failed renewals\n- `merchant_request` - The merchant explicitly canceled the subscription\n- `customer_request` - The customer canceled from the self-service portal\n",
+            examples=[None],
+        ),
+    ]
+    mandate: Annotated[
+        Mandate | None,
+        Field(
+            description='Payment method on file for this subscription, as an inline summary\nintended for billing-portal rendering ("Visa ending in 4242"). May\nbe `null` when the subscription has no mandate yet (e.g. ended /\ncanceled-before-payment states).\n'
+        ),
+    ] = None
+    started_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="startedAt",
+            description="When the subscription started (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ] = None
+    ended_at: Annotated[
+        AwareDatetime | None,
+        Field(alias="endedAt", description="When the subscription ended (ISO 8601 format)"),
+    ] = None
+    canceled_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="canceledAt",
+            description="When the subscription was canceled (ISO 8601 format)",
+        ),
+    ] = None
+    renewed_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="renewedAt",
+            description="When the subscription was last renewed (ISO 8601 format)",
+            examples=["2024-02-15T10:30:00Z"],
+        ),
+    ] = None
+    renewed_until: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="renewedUntil",
+            description="Current billing period end date (ISO 8601 format)",
+            examples=["2024-03-15T10:30:00Z"],
+        ),
+    ] = None
+    next_renewal_at: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="nextRenewalAt",
+            description="When the next renewal will be attempted (ISO 8601 format).\nNull if subscription is canceled or ended.\n",
+            examples=["2024-03-15T10:30:00Z"],
+        ),
+    ] = None
+    trial_until: Annotated[
+        AwareDatetime | None,
+        Field(
+            alias="trialUntil",
+            description="When the trial period ends (ISO 8601 format).\nNull if not in trial or trial has ended.\n",
+        ),
+    ] = None
+    links: Annotated[Links9, Field(description="HATEOAS links to related resources")]
+    scheduled_update: Annotated[
+        ScheduledUpdate | None,
+        Field(
+            alias="scheduledUpdate",
+            description="The target values for a change scheduled to take effect at the subscription's next\nbilling cycle — set by `PATCH /subscriptions/{subscriptionId}` with\n`applyImmediately: false`. The rest of the object is the subscription's *current*\nstate; `scheduledUpdate` is what it will become.\n\nNull when nothing is pending. Always present on both the REST resource and webhook\ndeliveries, so this is the authoritative way to reconcile a pending change — do not\ndepend on having received the `subscription.update_scheduled` webhook, which is\ndelivered once.\n\nCleared when the change is applied at renewal, and when it is discarded because the\nsubscription was canceled before that renewal happened.\n",
+        ),
+    ] = None
+
+
+class Order(VatlyModel):
+    """
+    An order represents a completed purchase.
+    Orders are created when checkouts complete or subscriptions renew.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the order",
+            examples=["order_Hn5xWqVfKm8RjTgYbUcP"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["order"],
+        Field(description="Resource type identifier", examples=["order"]),
+    ]
+    customer_id: Annotated[
+        str | None,
+        Field(
+            alias="customerId",
+            description="ID of the customer who made this purchase. Always present; `null` for orders with no associated customer.",
+            examples=["customer_Lp3mNvBxKw7RjTgYcZaE"],
+        ),
+    ] = None
+    testmode: Annotated[
+        bool, Field(description="Whether this order is in test mode", examples=[False])
+    ]
+    metadata: Metadata | None = None
+    payment_method: Annotated[
+        str | None,
+        Field(
+            alias="paymentMethod",
+            description="Payment method used for this order.\nExamples: `ideal`, `creditcard`, `bancontact`, `paypal`\n",
+            examples=["ideal"],
+        ),
+    ] = None
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this order was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    status: Annotated[
+        Literal["created", "pending", "paid", "canceled", "expired"],
+        Field(
+            description="Current status of the order:\n- `created` - Order has just been created\n- `pending` - Payment is being processed\n- `paid` - Payment successful\n- `canceled` - Order has been canceled\n- `expired` - Order has expired\n",
+            examples=["paid"],
+        ),
+    ]
+    cancellation_reason: Annotated[
+        Literal["payment_failure"] | None,
+        Field(
+            alias="cancellationReason",
+            description="Why the order was canceled. Null unless the status is `canceled`, and null\nfor orders canceled before this field existed.\n- `payment_failure` - Payment recovery for this unpaid order was exhausted\n",
+            examples=[None],
+        ),
+    ]
+    invoice_number: Annotated[
+        str | None,
+        Field(
+            alias="invoiceNumber",
+            description="Invoice number for this order (assigned after payment)",
+            examples=["INV-2024-0001"],
+        ),
+    ] = None
+    total: Annotated[Money, Field(description="Total amount including taxes")]
+    subtotal: Annotated[Money, Field(description="Subtotal amount before taxes")]
+    reversed_subtotal: Annotated[
+        Money,
+        Field(
+            alias="reversedSubtotal",
+            description="Amount of the captured payment returned to the customer, before taxes, via refund or chargeback (settled)",
+        ),
+    ]
+    refundable_subtotal: Annotated[
+        Money,
+        Field(
+            alias="refundableSubtotal",
+            description="Remaining amount that can still be refunded, before taxes.",
+        ),
+    ]
+    tax_summary: Annotated[
+        Sequence[TaxSummaryItem],
+        Field(alias="taxSummary", description="Tax breakdown by rate"),
+    ]
+    lines: Annotated[Sequence[OrderLine], Field(description="Line items in this order")]
+    customer_details: Annotated[
+        BillingDetails,
+        Field(alias="customerDetails", description="Customer billing details (buyer)"),
+    ]
+    links: Annotated[Links4, Field(description="HATEOAS links to related resources")]
+
+
+class Refund(VatlyModel):
+    """
+    A refund represents a partial or full reversal of an order payment.
+    Refunds are processed through the original payment provider.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the refund",
+            examples=["refund_Xk9pQrSvWm4NjLhYbUcP"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["refund"],
+        Field(description="Resource type identifier", examples=["refund"]),
+    ]
+    order_id: Annotated[
+        str | None,
+        Field(
+            alias="orderId",
+            description="ID of the credit note order created for this refund. Always present in\nthe payload; `null` until the refund is processed, then set to the\ncredit-note order id.\n",
+            examples=["order_Vr8kQdFhSrG4Y3DnfsdqH"],
+        ),
+    ] = None
+    customer_id: Annotated[
+        str,
+        Field(
+            alias="customerId",
+            description="ID of the customer receiving the refund",
+            examples=["customer_Lp3mNvBxKw7RjTgYcZaE"],
+        ),
+    ]
+    testmode: Annotated[
+        bool, Field(description="Whether this refund is in test mode", examples=[False])
+    ]
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="When this refund was created (ISO 8601 format)",
+            examples=["2024-01-15T10:30:00Z"],
+        ),
+    ]
+    status: Annotated[
+        Literal["pending", "queued", "processing", "refunded", "failed", "canceled"],
+        Field(
+            description="Current status of the refund:\n- `pending` - Refund is ready to be sent to the bank\n- `queued` - Refund is queued due to a lack of balance\n- `processing` - Refund is being processed (cancellation no longer possible)\n- `refunded` - Refund has been processed successfully\n- `failed` - Refund has failed after processing\n- `canceled` - Refund was canceled\n",
+            examples=["refunded"],
+        ),
+    ]
+    original_order_id: Annotated[
+        str,
+        Field(
+            alias="originalOrderId",
+            description="ID of the original order being refunded",
+            examples=["order_Fp2kQrSvWm8NjLhYbUcP"],
+        ),
+    ]
+    total: Annotated[Money, Field(description="Total refund amount including taxes")]
+    subtotal: Annotated[Money, Field(description="Refund subtotal before taxes")]
+    tax_summary: Annotated[
+        Sequence[TaxSummaryItem],
+        Field(alias="taxSummary", description="Tax breakdown by rate being refunded"),
+    ]
+    lines: Annotated[Sequence[RefundLine], Field(description="Refund line items")]
+    links: Annotated[Links5, Field(description="HATEOAS links to related resources")]
+
+
+class WebhookEvent(VatlyModel):
+    """
+    A persisted webhook event — the record returned by `GET /webhook-events/{eventId}`.
+    It captures a domain event that was delivered to your endpoint, including the full
+    resource payload at the time the event occurred.
+
+    This is the *stored* resource. For the shape Vatly POSTs to your endpoint on each
+    live delivery (which additionally includes the `webhook.setup` verification call),
+    see `WebhookDelivery`.
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the webhook event",
+            examples=["webhook_event_Qk8pRtSvWm2NjLhYcZaE"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["webhook_event"],
+        Field(description="Resource type identifier", examples=["webhook_event"]),
+    ]
+    event_name: Annotated[
+        Literal[
+            "order.paid",
+            "order.canceled",
+            "order.chargeback_received",
+            "order.chargeback_reversed",
+            "order.payment_failed",
+            "refund.completed",
+            "refund.failed",
+            "refund.canceled",
+            "subscription.started",
+            "subscription.canceled_immediately",
+            "subscription.canceled_for_nonpayment",
+            "subscription.canceled_with_grace_period",
+            "subscription.cancellation_grace_period_completed",
+            "subscription.resumed",
+            "subscription.billing_updated",
+            "subscription.updated",
+            "subscription.update_scheduled",
+            "checkout.paid",
+            "checkout.failed",
+            "checkout.canceled",
+            "checkout.expired",
+            "one_off_product.update_submitted",
+            "one_off_product.update_approved",
+            "one_off_product.update_rejected",
+            "one_off_product.archived",
+            "one_off_product.unarchived",
+            "subscription_plan.update_submitted",
+            "subscription_plan.update_approved",
+            "subscription_plan.update_rejected",
+            "subscription_plan.archived",
+            "subscription_plan.unarchived",
+        ],
+        Field(
+            alias="eventName",
+            description="Name of the event that triggered this webhook:\n- `order.paid` - Order payment was successful\n- `order.canceled` - Order was canceled\n- `order.chargeback_received` - Chargeback was received for an order\n- `order.chargeback_reversed` - Chargeback was reversed\n- `order.payment_failed` - A payment failed and the order entered payment recovery (dunning); sent once per failed order\n- `refund.completed` - Refund was processed successfully\n- `refund.failed` - Refund processing failed\n- `refund.canceled` - Refund was canceled\n- `subscription.started` - Subscription was started\n- `subscription.canceled_immediately` - Subscription was canceled immediately\n- `subscription.canceled_for_nonpayment` - Subscription was canceled because payment recovery was exhausted\n- `subscription.canceled_with_grace_period` - Subscription was canceled with a grace period\n- `subscription.cancellation_grace_period_completed` - Subscription grace period ended\n- `subscription.resumed` - A canceled subscription was resumed during its grace period\n- `subscription.billing_updated` - A subscription's billing details changed; in practice today the mandate (payment method on file), e.g. to refresh the masked payment method identifier shown to the customer\n- `subscription.updated` - A subscription changed: on an immediate change, when a scheduled change takes effect at renewal, or when a renewal payment is confirmed; see `reason`\n- `subscription.update_scheduled` - A plan/price/quantity change was scheduled for the next billing cycle; the target values are in `object.scheduledUpdate`\n- `checkout.paid` - Checkout was paid successfully\n- `checkout.failed` - Checkout payment failed\n- `checkout.canceled` - Checkout was canceled\n- `checkout.expired` - Checkout session expired\n\n`webhook.setup` is intentionally absent: the verification handshake is not\npersisted and so never appears on this resource (see `WebhookDelivery`).\n\nThis list is kept in sync with the webhook transformer registry by\n`php artisan openapi:audit-webhook-drift`.\n",
+            examples=["order.paid"],
+        ),
+    ]
+    reason: Annotated[
+        str | None,
+        Field(
+            description="Why the event fired, for events that have more than one cause. Always\npresent; `null` for every event other than `subscription.updated`.\n\nFor `subscription.updated`:\n- `updated_immediately` - A plan, price, interval or quantity change took effect immediately\n- `updated_on_renewal` - A scheduled plan, price, interval or quantity change took effect at a renewal\n- `renewed` - A renewal payment was confirmed; `renewedAt` and `renewedUntil` moved\n\nNew values may be added; treat an unknown value as a generic change.\n",
+            examples=["renewed"],
+        ),
+    ] = None
+    entity_type: Annotated[
+        str,
+        Field(
+            alias="entityType",
+            description="Type of the resource this event relates to",
+            examples=["order"],
+        ),
+    ]
+    entity_id: Annotated[
+        str,
+        Field(
+            alias="entityId",
+            description="ID of the resource this event relates to",
+            examples=["order_Hn5xWqVfKm8RjTgYbUcP"],
+        ),
+    ]
+    object: Annotated[
+        Order | Chargeback | Refund | Subscription | Checkout | OneOffProduct | SubscriptionPlan,
+        Field(
+            description="The full resource payload at the time of the event, serialized identically\nto the corresponding REST resource. The concrete shape is selected by the\npayload's own `resource` field (the discriminator):\n  - `order.paid`, `order.canceled`, `order.payment_failed` → Order\n  - `order.chargeback_received`, `order.chargeback_reversed` → Chargeback\n  - `refund.*` → Refund\n  - `subscription.*` → Subscription\n  - `checkout.*` → Checkout\n  - `one_off_product.*` → OneOffProduct\n  - `subscription_plan.*` → SubscriptionPlan\n\nNote `object.resource` may differ from `entityType`: chargeback events carry\n`entityType: order` (the order the chargeback belongs to) but a Chargeback object.\n",
+            discriminator="resource",
+        ),
+    ]
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="ISO 8601 timestamp of when the webhook event was created.",
+            examples=["2026-05-21T14:32:08+00:00"],
+        ),
+    ]
+    testmode: Annotated[
+        bool,
+        Field(
+            description="Whether the event originated from a test-mode resource.\n`true` for events created with a `test_` prefixed token, `false` for live events.\n",
+            examples=[False],
+        ),
+    ]
+    links: Annotated[
+        Links7,
+        Field(
+            description="HATEOAS links to related resources. Always present on the persisted event."
+        ),
+    ]
+
+
+class WebhookDelivery(VatlyModel):
+    """
+    The envelope Vatly POSTs to your configured webhook endpoint for each delivery.
+
+    Identical to the persisted `WebhookEvent`, with two differences that exist only on
+    the wire:
+      - it additionally covers the `webhook.setup` verification call (`entityType`
+        `webhook`, `object` is the secret-free endpoint config), and
+      - that setup call is not persisted and omits `links`, so `links` is not required
+        on a delivery.
+
+    Every delivery is signed: the `Vatly-Signature` header carries an HMAC-SHA256 of
+    the raw body and `Vatly-Event-Id` carries a retry-stable dedup key (see the
+    operation parameters).
+
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+    id: Annotated[
+        str,
+        Field(
+            description="Unique identifier for the webhook event",
+            examples=["webhook_event_Qk8pRtSvWm2NjLhYcZaE"],
+        ),
+    ]
+    resource: Annotated[
+        Literal["webhook_event"],
+        Field(description="Resource type identifier", examples=["webhook_event"]),
+    ]
+    event_name: Annotated[
+        Literal[
+            "order.paid",
+            "order.canceled",
+            "order.chargeback_received",
+            "order.chargeback_reversed",
+            "order.payment_failed",
+            "refund.completed",
+            "refund.failed",
+            "refund.canceled",
+            "subscription.started",
+            "subscription.canceled_immediately",
+            "subscription.canceled_for_nonpayment",
+            "subscription.canceled_with_grace_period",
+            "subscription.cancellation_grace_period_completed",
+            "subscription.resumed",
+            "subscription.billing_updated",
+            "subscription.updated",
+            "subscription.update_scheduled",
+            "checkout.paid",
+            "checkout.failed",
+            "checkout.canceled",
+            "checkout.expired",
+            "one_off_product.update_submitted",
+            "one_off_product.update_approved",
+            "one_off_product.update_rejected",
+            "one_off_product.archived",
+            "one_off_product.unarchived",
+            "subscription_plan.update_submitted",
+            "subscription_plan.update_approved",
+            "subscription_plan.update_rejected",
+            "subscription_plan.archived",
+            "subscription_plan.unarchived",
+            "webhook.setup",
+        ],
+        Field(
+            alias="eventName",
+            description="Name of the event that triggered this webhook:\n- `order.paid` - Order payment was successful\n- `order.canceled` - Order was canceled\n- `order.chargeback_received` - Chargeback was received for an order\n- `order.chargeback_reversed` - Chargeback was reversed\n- `order.payment_failed` - A payment failed and the order entered payment recovery (dunning); sent once per failed order\n- `refund.completed` - Refund was processed successfully\n- `refund.failed` - Refund processing failed\n- `refund.canceled` - Refund was canceled\n- `subscription.started` - Subscription was started\n- `subscription.canceled_immediately` - Subscription was canceled immediately\n- `subscription.canceled_for_nonpayment` - Subscription was canceled because payment recovery was exhausted\n- `subscription.canceled_with_grace_period` - Subscription was canceled with a grace period\n- `subscription.cancellation_grace_period_completed` - Subscription grace period ended\n- `subscription.resumed` - A canceled subscription was resumed during its grace period\n- `subscription.billing_updated` - A subscription's billing details changed; in practice today the mandate (payment method on file), e.g. to refresh the masked payment method identifier shown to the customer\n- `subscription.updated` - A subscription changed: on an immediate change, when a scheduled change takes effect at renewal, or when a renewal payment is confirmed; see `reason`\n- `subscription.update_scheduled` - A plan/price/quantity change was scheduled for the next billing cycle; the target values are in `object.scheduledUpdate`\n- `checkout.paid` - Checkout was paid successfully\n- `checkout.failed` - Checkout payment failed\n- `checkout.canceled` - Checkout was canceled\n- `checkout.expired` - Checkout session expired\n- `webhook.setup` - Verification call sent when an endpoint is registered or its URL changes (`entityType` is `webhook`)\n\nThis list is the single source of truth for SDK generators and is kept in\nsync with the webhook transformer registry by `php artisan openapi:audit-webhook-drift`.\n",
+            examples=["order.paid"],
+        ),
+    ]
+    reason: Annotated[
+        str | None,
+        Field(
+            description="Why the event fired, for events that have more than one cause. Always\npresent; `null` for every event other than `subscription.updated`.\n\nFor `subscription.updated`:\n- `updated_immediately` - A plan, price, interval or quantity change took effect immediately\n- `updated_on_renewal` - A scheduled plan, price, interval or quantity change took effect at a renewal\n- `renewed` - A renewal payment was confirmed; `renewedAt` and `renewedUntil` moved\n\nNew values may be added; treat an unknown value as a generic change.\n",
+            examples=["renewed"],
+        ),
+    ] = None
+    entity_type: Annotated[
+        str,
+        Field(
+            alias="entityType",
+            description="Type of the resource this event relates to",
+            examples=["order"],
+        ),
+    ]
+    entity_id: Annotated[
+        str,
+        Field(
+            alias="entityId",
+            description="ID of the resource this event relates to",
+            examples=["order_Hn5xWqVfKm8RjTgYbUcP"],
+        ),
+    ]
+    object: Annotated[
+        Order
+        | Chargeback
+        | Refund
+        | Subscription
+        | Checkout
+        | OneOffProduct
+        | SubscriptionPlan
+        | Webhook,
+        Field(
+            description="The full resource payload at the time of the event, serialized identically\nto the corresponding REST resource. The concrete shape is selected by the\npayload's own `resource` field (the discriminator):\n  - `order.paid`, `order.canceled`, `order.payment_failed` → Order\n  - `order.chargeback_received`, `order.chargeback_reversed` → Chargeback\n  - `refund.*` → Refund\n  - `subscription.*` → Subscription\n  - `checkout.*` → Checkout\n  - `webhook.setup` → Webhook (the endpoint config; verification handshake)\n  - `one_off_product.*` → OneOffProduct\n  - `subscription_plan.*` → SubscriptionPlan\n\nNote `object.resource` may differ from `entityType`: chargeback events carry\n`entityType: order` (the order the chargeback belongs to) but a Chargeback object.\n",
+            discriminator="resource",
+        ),
+    ]
+    created_at: Annotated[
+        AwareDatetime,
+        Field(
+            alias="createdAt",
+            description="ISO 8601 timestamp of when the webhook event was created.",
+            examples=["2026-05-21T14:32:08+00:00"],
+        ),
+    ]
+    testmode: Annotated[
+        bool,
+        Field(
+            description="Whether the event originated from a test-mode resource.\n`true` for events created with a `test_` prefixed token, `false` for live events.\n",
+            examples=[False],
+        ),
+    ]
+    links: Annotated[
+        Links10 | None,
+        Field(
+            description="HATEOAS links to related resources. Present on event deliveries; omitted on\nthe `webhook.setup` verification call, which is not a persisted resource.\n"
+        ),
+    ] = None