openapi.yaml

openapi: 3.1.0
info:
  title: Vatly API
  version: '1.0'
  x-generated-at: '2026-05-28'
  description: |
    Vatly is a Merchant of Record billing platform for European SaaS companies.
    This API enables you to manage checkouts, customers, orders, subscriptions, refunds, and more.

    ## Authentication

    The Vatly API uses Bearer token authentication. All API requests must include an `Authorization` header:

    ```
    Authorization: Bearer {your_api_token}
    ```

    ### Live vs Test Mode

    API tokens determine the environment mode:
    - Tokens prefixed with `live_` access **production** data
    - Tokens prefixed with `test_` access **sandbox** data

    Resources created in one mode cannot be accessed or referenced from the other mode.
    For example, a checkout created with a test token cannot reference a customer created with a live token.

    #### Payment methods in test mode

    A few payment methods work in live mode but cannot be completed in test mode,
    because the payment provider cannot settle them there. A test-mode checkout
    still lists them, greyed out and labelled as unavailable, so you can see they
    exist without being able to select one:

    | Method | Test mode | Reason |
    |--------|-----------|--------|
    | `banktransfer` | Not selectable | The provider cannot settle bank transfers in test mode |
    | `paybybank` | Not selectable | The provider cannot settle Pay by Bank in test mode |

    Every other method behaves identically in both modes. Test a checkout with any
    selectable method — `creditcard` and `ideal` cover the one-off and mandate flows —
    and the resulting orders, invoices and webhooks are the same ones live mode produces.

    ## Pagination

    List endpoints use cursor-based pagination with the following query parameters:

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `limit` | integer | Number of results per page (default: 10, max: 100) |
    | `startingAfter` | string | Cursor ID to fetch results after |
    | `endingBefore` | string | Cursor ID to fetch results before |

    `startingAfter` and `endingBefore` are mutually exclusive.

    All list responses are wrapped in a pagination envelope:

    ```json
    {
      "data": [ ... ],
      "count": 2,
      "links": {
        "self": { "href": "https://api.vatly.com/v1/orders", "type": "application/json" },
        "next": { "href": "https://api.vatly.com/v1/orders?startingAfter=order_abc", "type": "application/json" },
        "prev": null
      }
    }
    ```

    ## Money Format

    All monetary values are represented as objects with `value` (string) and `currency` (ISO 4217 code):

    ```json
    {
      "value": "99.99",
      "currency": "EUR"
    }
    ```

    Values are strings to preserve decimal precision.

    ## Email Format

    Vatly canonicalizes every email address it accepts, and stores and returns
    that canonical form:

    - the local part is lower-cased;
    - the domain is lower-cased and converted to its **Punycode (ASCII)** form
      per [UTS #46](https://www.unicode.org/reports/tr46/).

    So `User@Müller.de`, `USER@MÜLLER.DE` and `user@xn--mller-kva.de` are all
    accepted and all describe the same address. **Responses return the canonical
    form, which may therefore differ in spelling from what you submitted** —
    compare addresses after canonicalizing, or key off the resource `id`.

    Submitting an internationalized domain directly is fine; you do not need to
    encode it yourself. A domain that cannot be canonicalized at all — an empty
    label (`user@..com`), a malformed Punycode label (`user@xn--0.com`), a label
    over 63 characters — is rejected with `422`.

    Beyond that canonicalization the comparison is exact: `büyer@example.com`
    and `straße@example.com` are different addresses from `buyer@example.com`
    and `strasse@example.com`, and get their own customers.

    For human-friendly display in your own UI, decode the domain back to
    Unicode. Most languages provide this in the standard library — for
    example, PHP's `idn_to_utf8()`, Python's `idna.decode()`, or Node's
    [`url.domainToUnicode()`](https://nodejs.org/api/url.html#urldomaintounicodedomain).

    Local-part Unicode (EAI / SMTPUTF8) is not supported for delivery, but a
    non-ASCII local part is stored and compared verbatim (after lower-casing).

    ## Idempotency

    All mutating requests (`POST`, `PATCH`, `PUT`, `DELETE`) accept an
    optional `Idempotency-Key` header. When present, Vatly records the
    first response keyed by `(token, endpoint, key)` and returns it
    verbatim on subsequent requests with the same key, marking the
    replay with an `Idempotent-Replayed: true` response header.

    - **Use a fresh key per logical operation.** Generate one client-side
      (UUIDv4 is recommended) and retry transparently with the same key
      on network errors.
    - **Keys are bound to the exact parameters of the first request.**
      The method, public endpoint, concrete path, query, body, normalized
      `Content-Type` media type, and normalized ordered `Content-Encoding` are
      contract-significant. Replaying with a different value returns
      `409 Conflict` without executing again. Either retry with the original
      parameters or generate a new key.
    - **Keys expire after 24 hours.** After that the key is reusable as
      a fresh idempotency boundary.
    - **Scope is per public route URI template.** The same key value on a
      different endpoint is treated as a new key. Internal route-name or
      controller refactors do not change replay identity.
    - **The first HTTP response is final for that key.** This includes a
      rendered `4xx` or `5xx` response after request processing started.
      Retry the exact request with the same key to retrieve that response;
      use a fresh key for corrected parameters only after reconciling whether
      the original mutation took effect.
    - **Exact replays still consume rate-limit budget.** API and per-merchant
      write throttles run before the idempotency lookup. An otherwise valid
      replay can therefore return `429 Too Many Requests` instead of the stored
      response. Wait for its `Retry-After` interval, then resend the exact same
      request and key.
    - **A `409` with `details.idempotency_outcome = in_progress` is
      retryable.** Wait the number of seconds in `Retry-After`, then resend the
      exact same request and key.
    - **A `409` with `details.idempotency_outcome = unknown` is not
      retryable.** The mutation may have completed but its response is not
      replayable. Read and reconcile the affected resource before taking any
      further mutating action; never automatically retry with either the same
      or a fresh key.

    Sending an `Idempotency-Key` on a `GET` or `HEAD` request is ignored.

    ## Handling failed subscription payments

    When a subscription renewal payment fails, Vatly runs an automated
    **payment recovery** process (dunning) on your behalf. You never have to
    schedule your own retries — but you do decide when to restrict access.

    **What happens, and what you receive:**

    1. The renewal payment fails and recovery begins. You receive a single
       **`order.payment_failed`** webhook for the renewal order (sent once, when
       recovery starts — not on each retry). The subscription's `status` stays
       `active` throughout recovery: it does **not** move to a "past due" state,
       and `on_grace_period` is never used for payment failure — that status
       means a *voluntary* cancellation that keeps access until the period ends.
    2. Vatly attempts to recover the payment, and how it does so depends on why
       the charge failed:
       - **Soft decline** (e.g. insufficient funds, a temporary decline): the
         payment method is still valid, so Vatly automatically re-attempts the
         charge over a multi-week window, emailing the customer along the way.
       - **Hard decline** (e.g. an expired, canceled or invalid payment method):
         retrying cannot succeed, so Vatly instead prompts the customer to
         supply a new payment method, on a shorter window.
    3. **If recovery succeeds**, the original renewal order is paid and you
       receive **`order.paid`** for that same order. Because the subscription was
       never interrupted, access simply continues — nothing else is needed.
    4. **If recovery is exhausted** (the customer never resolves it), Vatly
       cancels the subscription: you receive **`subscription.canceled_for_nonpayment`**
       and the subscription `status` becomes `canceled` with
       `cancellationReason: payment_failure`.

    **Recommended integration** — gate access on the events, not on a timer you
    keep in sync with ours:

    - On `order.payment_failed`: keep access on, and start your own grace period
      if your product has one.
    - On `order.paid` for the same order: recovery succeeded — clear that grace
      period.
    - If your grace period elapses with no matching `order.paid`: restrict access
      on your side if you wish. Vatly's recovery keeps running underneath, so a
      later `order.paid` lets you restore access automatically.
    - On the subscription's cancellation: remove access permanently.

    The number of retry attempts and the exact retry cadence are operational
    details that Vatly tunes over time. Integrate against these webhook events
    rather than against specific durations or attempt counts.

    ## Errors

    The API returns standard HTTP status codes and JSON error responses:

    | Status | Description |
    |--------|-------------|
    | 400 | Bad Request - Invalid request format |
    | 401 | Unauthorized - Missing or invalid token |
    | 403 | Forbidden - Token invalid or insufficient permissions |
    | 404 | Not Found - Resource doesn't exist |
    | 409 | Conflict - idempotency mismatch, request still in progress, outcome unknown, or concurrent write |
    | 422 | Unprocessable Entity - Validation failed |
    | 429 | Too Many Requests - Rate limit exceeded |
    | 500 | Internal Server Error |
  contact:
    name: Vatly Support
    url: https://vatly.com
    email: support@vatly.com
  license:
    name: Proprietary
    url: https://vatly.com/terms
servers:
  - url: https://api.vatly.com/v1
    description: Production API
  - url: https://api.staging.vatly.com/v1
    description: Staging API
security:
  - BearerAuth: []
tags:
  - name: Checkouts
    description: |
      Create and manage hosted checkout sessions.
      Checkouts allow customers to purchase one-off products and subscription plans through a hosted payment page.
  - name: Customers
    description: |
      Manage customer records.
      Customers are identified by email and can have multiple subscriptions and orders.
  - name: One-Off Products
    description: |
      Create and view one-off products.
      Products can be created in the Vatly dashboard or through the API. Live
      products are reviewed and approved by Vatly before they can be added to
      checkouts.
  - name: Subscription Plans
    description: |
      Create and view subscription plans.
      Plans define recurring billing intervals and pricing, and can be created
      in the Vatly dashboard or through the API. Live plans are reviewed and
      approved by Vatly before they can be added to checkouts.
  - name: Orders
    description: |
      View orders and request invoice address updates.
      Orders are created when checkouts complete or subscriptions renew.
  - name: Refunds
    description: |
      Create and manage refunds for paid orders.
      Supports both partial (per-item) and full refunds.
  - name: Chargebacks
    description: |
      View chargebacks initiated by the payment provider.
      Chargebacks are created automatically when a customer disputes a payment.
  - name: Subscriptions
    description: |
      Manage customer subscriptions.
      Update plans, quantities, billing details, or cancel subscriptions.
  - name: Webhook Events
    description: |
      View webhook events that were sent to your webhook endpoints.
      Each event contains the full resource payload at the time the event occurred.
  - name: Webhook Endpoints
    description: |
      Register and manage the endpoints Vatly delivers webhook events to.
      Create, list, update, and delete endpoints programmatically — useful for
      CI, infrastructure-as-code, and ephemeral preview environments. The
      signing secret is write-only: you supply it and it is never returned.
  - name: Test Helpers
    description: |
      Sandbox-only endpoints for simulating billing events.
      These endpoints require a `test_` prefixed API token.
paths:
  /checkouts:
    get:
      operationId: listCheckouts
      summary: List all checkouts
      description: |
        Returns a paginated list of checkouts for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.
      tags:
        - Checkouts
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of checkouts
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Checkout'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: checkout_QdEpFhdSrG4Y3DnfsdqsH
                    resource: checkout
                    customerId: null
                    orderId: null
                    testmode: false
                    redirectUrlSuccess: https://example.com/success
                    redirectUrlCanceled: https://example.com/canceled
                    metadata: {}
                    locale: null
                    status: created
                    expiresAt: '2024-01-16T10:30:00Z'
                    createdAt: '2024-01-15T10:30:00Z'
                    links:
                      checkoutUrl:
                        href: https://checkout.vatly.com/checkout_QdEpFhdSrG4Y3DnfsdqsH
                        type: text/html
                      self:
                        href: https://api.vatly.com/v1/checkouts/checkout_QdEpFhdSrG4Y3DnfsdqsH
                        type: application/json
                      order: null
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/checkouts
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: createCheckout
      summary: Create a checkout
      description: |
        Creates a new hosted checkout session.

        The checkout URL in the response can be used to redirect customers to complete their purchase.
        Checkouts expire after a configurable period (default: 24 hours).

        **Products:**
        - Include one or more products using their `one_off_product_` or `subscription_plan_` IDs
        - Mix one-off products and subscription plans in the same checkout
        - Override prices for specific products using the `price` field
        - Add trial periods to subscription plans using `trialDays`

        **Customer association:**
        - Optionally link to an existing customer using `customerId`
        - If not provided, a new customer is created based on checkout form input
      tags:
        - Checkouts
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutRequest'
            examples:
              oneOffProduct:
                summary: Checkout with one-off product (with {CHECKOUT_ID} placeholder)
                value:
                  redirectUrlSuccess: https://example.com/return?checkout_id={CHECKOUT_ID}
                  redirectUrlCanceled: https://example.com/canceled?checkout_id={CHECKOUT_ID}
                  products:
                    - id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                      quantity: 1
              subscriptionWithTrial:
                summary: Subscription plan with trial
                value:
                  redirectUrlSuccess: https://example.com/success
                  redirectUrlCanceled: https://example.com/canceled
                  customerId: customer_Fp2kQrSvWm8NjLhYbUcP
                  locale: de
                  products:
                    - id: subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                      trialDays: 14
              customPrice:
                summary: Product with custom price
                value:
                  redirectUrlSuccess: https://example.com/success
                  redirectUrlCanceled: https://example.com/canceled
                  products:
                    - id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                      quantity: 2
                      price:
                        value: '49.99'
                        currency: EUR
                  metadata:
                    campaign: summer-sale
      responses:
        '201':
          description: Checkout created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
              example:
                id: checkout_Bm7xNvPwKr3YjTgHcZaE
                resource: checkout
                customerId: null
                orderId: null
                testmode: false
                redirectUrlSuccess: https://example.com/success
                redirectUrlCanceled: https://example.com/canceled
                metadata:
                  campaign: summer-sale
                locale: de
                status: created
                expiresAt: '2024-01-16T10:30:00Z'
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  checkoutUrl:
                    href: https://checkout.vatly.com/checkout_Bm7xNvPwKr3YjTgHcZaE
                    type: text/html
                  self:
                    href: https://api.vatly.com/v1/checkouts/checkout_Bm7xNvPwKr3YjTgHcZaE
                    type: application/json
                  order: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: |
            Unprocessable Entity - The request was well-formed but contained validation errors.
            This includes the case where a referenced resource (e.g. `customerId`) exists but
            was created in a different mode — switch between live/test API tokens to access it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                validationFailed:
                  summary: Field validation failed
                  value:
                    message: The given data was invalid.
                    errors:
                      products.0.id:
                        - The selected products.0.id is invalid.
                testmodeMismatch:
                  summary: Referenced resource exists but in the wrong mode
                  value:
                    message: The given data was invalid.
                    errors:
                      customerId:
                        - Customer exists, but the wrong mode is used. Try switching live / test API keys.
        default:
          $ref: '#/components/responses/UnexpectedError'
  /checkouts/{checkoutId}:
    get:
      operationId: getCheckout
      summary: Get a checkout
      description: |
        Retrieves a specific checkout by its ID.
        Use this to check the status of a checkout or get the order ID after completion.
      tags:
        - Checkouts
      parameters:
        - $ref: '#/components/parameters/checkoutId'
      responses:
        '200':
          description: Checkout details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout'
              example:
                id: checkout_QdEpFhdSrG4Y3DnfsdqsH
                resource: checkout
                customerId: customer_7kBmRtPvXw2NjLhYcZaE
                orderId: order_Jk4pQrSvWm8NjLhYbUcP
                testmode: false
                redirectUrlSuccess: https://example.com/return?checkout_id=checkout_QdEpFhdSrG4Y3DnfsdqsH
                redirectUrlCanceled: https://example.com/canceled
                metadata:
                  campaign: summer-sale
                locale: null
                status: paid
                expiresAt: '2024-01-16T10:30:00Z'
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  checkoutUrl:
                    href: https://checkout.vatly.com/checkout_QdEpFhdSrG4Y3DnfsdqsH
                    type: text/html
                  self:
                    href: https://api.vatly.com/v1/checkouts/checkout_QdEpFhdSrG4Y3DnfsdqsH
                    type: application/json
                  order:
                    href: https://api.vatly.com/v1/orders/order_Jk4pQrSvWm8NjLhYbUcP
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /customers:
    get:
      operationId: listCustomers
      summary: List all customers
      description: |
        Returns a paginated list of customers for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.

        Pass `email` to filter the list down to the customers holding an address —
        the way back to a customer id you no longer have.
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/customerEmailFilter'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 2
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: customer_7kBmRtPvXw2NjLhYcZaE
                    resource: customer
                    testmode: false
                    email: john.doe@example.com
                    name: John Doe
                    createdAt: '2024-01-15T10:30:00Z'
                    metadata:
                      userId: user_Qp8kNvBxKw7RjTgYcZaE
                    links:
                      self:
                        href: https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE
                        type: application/json
                  - id: customer_Lp3mNvBxKw7RjTgYcZaE
                    resource: customer
                    testmode: false
                    email: jane.smith@acme.com
                    name: Jane Smith
                    createdAt: '2024-01-10T08:15:00Z'
                    metadata: {}
                    links:
                      self:
                        href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                        type: application/json
                count: 2
                links:
                  self:
                    href: https://api.vatly.com/v1/customers
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: createCustomer
      summary: Create a customer
      description: |
        Creates a customer, or returns the one that already holds the address.

        Customers are uniquely identified by email within a storefront and
        testmode, and this endpoint is get-or-create on that key: posting an
        address that already exists returns the existing customer rather than a
        validation error, so an integration that lost its Vatly customer id can
        always get back to it. The status code says which happened:

        | Status | Meaning |
        | --- | --- |
        | `201` | The customer was created by this request. |
        | `200` | A customer with this email already existed and is returned unchanged. |

        A `200` response never modifies the customer — `name` and `metadata` in
        the request body are ignored for an existing customer. Use
        `PATCH /v1/customers/{customerId}` to change one.

        A `201` can also complete a create that was interrupted before it
        finished, in which case the customer keeps the `id` and `createdAt` of
        that earlier attempt — so `createdAt` may predate the request. Treat it as
        when the customer came into being, not as when this call happened.

        Addresses are canonicalized before they are compared, so `User@MÜLLER.de`
        and `user@xn--mller-kva.de` are the same customer. Beyond that the
        comparison is exact — `büyer@example.com` is a different mailbox and gets
        its own customer.

        **Use cases:**
        - Pre-create customers before checkout
        - Link existing users from your system to Vatly
        - Recover the customer id for a known email after a re-sync or reset
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            example:
              email: customer@example.com
              metadata:
                userId: user_Qp8kNvBxKw7RjTgYcZaE
      responses:
        '200':
          description: |
            A customer with this email already existed. It is returned unchanged —
            nothing in the request body was applied.
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                id: customer_7kBmRtPvXw2NjLhYcZaE
                resource: customer
                testmode: false
                email: customer@example.com
                name: John Doe
                createdAt: '2024-01-15T10:30:00Z'
                metadata:
                  userId: user_Qp8kNvBxKw7RjTgYcZaE
                links:
                  self:
                    href: https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE
                    type: application/json
        '201':
          description: Customer created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                id: customer_7kBmRtPvXw2NjLhYcZaE
                resource: customer
                testmode: false
                email: customer@example.com
                name: John Doe
                createdAt: '2024-01-15T10:30:00Z'
                metadata:
                  userId: user_Qp8kNvBxKw7RjTgYcZaE
                links:
                  self:
                    href: https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerId}:
    get:
      operationId: getCustomer
      summary: Get a customer
      description: Retrieves a specific customer by their ID.
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                id: customer_7kBmRtPvXw2NjLhYcZaE
                resource: customer
                testmode: false
                email: john.doe@example.com
                name: John Doe
                createdAt: '2024-01-15T10:30:00Z'
                metadata:
                  userId: user_Qp8kNvBxKw7RjTgYcZaE
                links:
                  self:
                    href: https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
    patch:
      operationId: updateCustomer
      summary: Update a customer
      description: |
        Updates a customer's identity fields. Only `name` and `email` may be
        changed here, and both are optional — send whichever you want to update.

        Billing-address details (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 so invoices stay accurate.

        An `email` is canonicalized before it is stored, so the address you read
        back may differ in spelling from the one you sent. Moving a customer onto
        an address another customer in the same storefront and mode already holds
        returns `422`.
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
            example:
              name: John Doe
              email: new.email@example.com
      responses:
        '200':
          description: Customer updated successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
              example:
                id: customer_7kBmRtPvXw2NjLhYcZaE
                resource: customer
                testmode: false
                email: new.email@example.com
                name: John Doe
                createdAt: '2024-01-15T10:30:00Z'
                metadata:
                  userId: user_Qp8kNvBxKw7RjTgYcZaE
                links:
                  self:
                    href: https://api.vatly.com/v1/customers/customer_7kBmRtPvXw2NjLhYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerId}/portal-sessions:
    post:
      operationId: createCustomerPortalSession
      summary: Create a hosted customer portal session
      description: |
        Creates a short-lived, single-use link that sends an authenticated
        customer directly to this API token's storefront in Vatly's hosted
        portal. The session is locked to the customer, storefront, merchant, and
        live/test mode represented by the token; it never exposes a storefront
        picker or other stores associated with the same email address.

        Redirect the customer's browser to `url`. The link expires after roughly
        15 minutes by default and can be consumed once. If an idempotency key
        replays a response after its URL has already been used, request a
        replacement with a fresh key.
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePortalSessionRequest'
            example:
              returnUrl: https://merchant.example/account/billing
      responses:
        '201':
          description: Hosted customer portal session created
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
            Cache-Control:
              description: Prevents storage of the credential-bearing response.
              schema:
                type: string
                example: no-store, private
            Pragma:
              description: Legacy proxy fallback preventing storage of the credential-bearing response.
              schema:
                type: string
                example: no-cache
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalSession'
              example:
                url: https://billing.vatly.com/authenticate?credential=...
                expiresAt: '2026-09-01T12:15:00Z'
                returnUrl: https://merchant.example/account/billing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerId}/subscriptions:
    get:
      operationId: listCustomerSubscriptions
      summary: List customer subscriptions
      description: |
        Returns a paginated list of subscriptions for a specific customer.
        Includes subscriptions in all states (active, canceled, etc.).
      tags:
        - Customers
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of customer's subscriptions
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: subscription_Lp3mNvBxKw7RjTgYcZaE
                    resource: subscription
                    customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                    subscriptionPlanId: subscription_plan_Rk5pQrSvWm8NjLhYbUcP
                    testmode: false
                    name: Pro Monthly
                    description: Full access to all Pro features
                    billingAddress:
                      fullName: John Doe
                      companyName: Acme Corp
                      streetAndNumber: 123 Main Street
                      city: Berlin
                      postalCode: '10115'
                      country: DE
                    basePrice:
                      value: '29.00'
                      currency: EUR
                    quantity: 1
                    interval: month
                    intervalCount: 1
                    status: active
                    cancellationReason: null
                    mandate:
                      method: card
                      maskedIdentifier: '4242'
                    startedAt: '2024-01-15T10:30:00Z'
                    endedAt: null
                    canceledAt: null
                    renewedAt: '2024-02-15T10:30:00Z'
                    renewedUntil: '2024-03-15T10:30:00Z'
                    nextRenewalAt: '2024-03-15T10:30:00Z'
                    trialUntil: null
                    scheduledUpdate: null
                    links:
                      self:
                        href: https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE
                        type: application/json
                      customer:
                        href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                        type: application/json
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE/subscriptions
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /customers/{customerId}/subscriptions/{subscriptionId}:
    get:
      operationId: getCustomerSubscription
      summary: Get a customer subscription
      description: |
        Retrieves a specific subscription for a customer.
        The subscription must belong to the specified customer.
      tags:
        - Customers
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              example:
                id: subscription_Lp3mNvBxKw7RjTgYcZaE
                resource: subscription
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                subscriptionPlanId: subscription_plan_Rk5pQrSvWm8NjLhYbUcP
                testmode: false
                name: Pro Monthly
                description: Full access to all Pro features
                billingAddress:
                  fullName: John Doe
                  companyName: Acme Corp
                  streetAndNumber: 123 Main Street
                  city: Berlin
                  postalCode: '10115'
                  country: DE
                basePrice:
                  value: '29.00'
                  currency: EUR
                quantity: 1
                interval: month
                intervalCount: 1
                status: active
                cancellationReason: null
                mandate:
                  method: card
                  maskedIdentifier: '4242'
                startedAt: '2024-01-15T10:30:00Z'
                endedAt: null
                canceledAt: null
                renewedAt: '2024-02-15T10:30:00Z'
                renewedUntil: '2024-03-15T10:30:00Z'
                nextRenewalAt: '2024-03-15T10:30:00Z'
                trialUntil: null
                scheduledUpdate: null
                links:
                  self:
                    href: https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
                  customer:
                    href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /one-off-products:
    get:
      operationId: listOneOffProducts
      summary: List all one-off products
      description: |
        Returns a paginated list of one-off products for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.

        Only products with `active` status can be used in checkouts.

        Archived products are excluded unless `includeArchived=true` is passed.
      tags:
        - One-Off Products
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
        - $ref: '#/components/parameters/includeArchived'
      responses:
        '200':
          description: List of one-off products
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OneOffProduct'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                    resource: one_off_product
                    testmode: false
                    name: Premium License
                    description: Lifetime access to all premium features
                    basePrice:
                      value: '299.00'
                      currency: EUR
                    taxBehavior: exclusive
                    productType: saas
                    status: active
                    archivedAt: null
                    createdAt: '2024-01-15T10:30:00Z'
                    links:
                      self:
                        href: https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                        type: application/json
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/one-off-products
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: createOneOffProduct
      summary: Create a one-off product
      description: |
        Creates a new one-off product for the authenticated merchant, in the
        testmode determined from the API token.

        A product created with a `live_` token starts in `pending` status and
        must be approved by Vatly before it can be used in checkouts — the same
        review that applies to products created in the dashboard. A product
        created with a `test_` token is auto-approved (`active`) so you can trial
        checkout immediately.
      tags:
        - One-Off Products
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOneOffProductRequest'
            example:
              name: Premium License
              description: Lifetime access to all premium features
              basePrice:
                value: '299.00'
                currency: EUR
              productType: saas
      responses:
        '201':
          description: One-off product created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneOffProduct'
              example:
                id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                resource: one_off_product
                testmode: false
                name: Premium License
                description: Lifetime access to all premium features
                basePrice:
                  value: '299.00'
                  currency: EUR
                taxBehavior: exclusive
                productType: saas
                status: pending
                archivedAt: null
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /one-off-products/{oneOffProductId}:
    get:
      operationId: getOneOffProduct
      summary: Get a one-off product
      description: Retrieves a specific one-off product by its ID.
      tags:
        - One-Off Products
      parameters:
        - $ref: '#/components/parameters/oneOffProductId'
      responses:
        '200':
          description: One-off product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneOffProduct'
              example:
                id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                resource: one_off_product
                testmode: false
                name: Premium License
                description: Lifetime access to all premium features
                basePrice:
                  value: '299.00'
                  currency: EUR
                taxBehavior: exclusive
                productType: saas
                status: active
                archivedAt: null
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
    patch:
      operationId: updateOneOffProduct
      summary: Request an update to a one-off product
      description: |
        Submits an update to a live one-off product. Because products drive
        VAT-bearing sales, the change is held as a pending update and reviewed by
        Vatly before it takes effect (`updateStatus` moves `pending` → `reviewing`
        → applied). In test mode the update is approved automatically.

        Each request is the **complete set of changes** relative to the current
        live product. Fields equal to the live value are ignored, and a request
        that nets to no change clears any pending update. A new request replaces
        the not-yet-reviewed one; while an update is being reviewed, further
        requests return `409`.
      tags:
        - One-Off Products
      parameters:
        - $ref: '#/components/parameters/oneOffProductId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOneOffProductRequest'
            example:
              name: Premium License v2
              basePrice:
                value: '349.00'
                currency: EUR
      responses:
        '200':
          description: Update submitted; the product now carries a pending update.
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneOffProduct'
              example:
                id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                resource: one_off_product
                testmode: false
                name: Premium License
                description: Lifetime access to all premium features
                basePrice:
                  value: '299.00'
                  currency: EUR
                taxBehavior: exclusive
                productType: saas
                status: active
                archivedAt: null
                pendingUpdates:
                  name: Premium License v2
                  basePrice:
                    value: '349.00'
                    currency: EUR
                updateStatus: pending
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /one-off-products/{oneOffProductId}/archive:
    post:
      operationId: archiveOneOffProduct
      summary: Archive a one-off product
      description: |
        Takes the product out of your sellable catalogue. It is hidden from
        `GET /v1/one-off-products` (unless `includeArchived=true`) and refused by
        `POST /v1/checkouts`; existing orders and refunds are untouched.

        Archiving applies to *new* checkouts only. A checkout created before the
        product was archived snapshots its product data at creation time and can
        still be completed — the same window that applies when a product is
        rejected after a checkout was opened.

        Nothing is deleted — the product remains readable by id, now carrying a
        non-null `archivedAt`. Archiving is not queued behind Vatly's product
        review, and leaves any pending update in place. Repeating the request is
        a no-op that returns `204` and does not move `archivedAt`.
        Reverse it with `DELETE /v1/one-off-products/{oneOffProductId}/archive`.
      tags:
        - One-Off Products
      parameters:
        - $ref: '#/components/parameters/oneOffProductId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '204':
          description: Product archived (or already archived).
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: unarchiveOneOffProduct
      summary: Unarchive a one-off product
      description: |
        Puts an archived product back on sale: it reappears in
        `GET /v1/one-off-products` and can be added to checkouts again. Calling
        it on a product that is not archived is a no-op.
      tags:
        - One-Off Products
      parameters:
        - $ref: '#/components/parameters/oneOffProductId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '200':
          description: The product, now on sale again.
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneOffProduct'
              example:
                id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                resource: one_off_product
                testmode: false
                name: Premium License
                description: Lifetime access to all premium features
                basePrice:
                  value: '299.00'
                  currency: EUR
                taxBehavior: exclusive
                productType: saas
                status: active
                archivedAt: null
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /subscription-plans:
    get:
      operationId: listSubscriptionPlans
      summary: List all subscription plans
      description: |
        Returns a paginated list of subscription plans for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.

        Only plans with `active` status can be used in checkouts.

        Archived plans are excluded unless `includeArchived=true` is passed.
      tags:
        - Subscription Plans
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
        - $ref: '#/components/parameters/includeArchived'
      responses:
        '200':
          description: List of subscription plans
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubscriptionPlan'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 2
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                    resource: subscription_plan
                    testmode: false
                    name: Pro Monthly
                    description: Full access to all Pro features, billed monthly
                    basePrice:
                      value: '29.00'
                      currency: EUR
                    taxBehavior: exclusive
                    interval: month
                    intervalCount: 1
                    productType: saas
                    status: active
                    archivedAt: null
                    createdAt: '2024-01-15T10:30:00Z'
                    links:
                      self:
                        href: https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                        type: application/json
                  - id: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
                    resource: subscription_plan
                    testmode: false
                    name: Pro Yearly
                    description: Full access to all Pro features, billed yearly
                    basePrice:
                      value: '290.00'
                      currency: EUR
                    taxBehavior: exclusive
                    interval: year
                    intervalCount: 1
                    productType: saas
                    status: active
                    archivedAt: null
                    createdAt: '2024-01-15T10:30:00Z'
                    links:
                      self:
                        href: https://api.vatly.com/v1/subscription-plans/subscription_plan_Wt5mNvBxKw7YcZaEjLhR
                        type: application/json
                count: 2
                links:
                  self:
                    href: https://api.vatly.com/v1/subscription-plans
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: createSubscriptionPlan
      summary: Create a subscription plan
      description: |
        Creates a new subscription plan for the authenticated merchant, in the
        testmode determined from the API token.

        A plan created with a `live_` token starts in `pending` status and must be
        approved by Vatly before it can be used in checkouts — the same review
        that applies to plans created in the dashboard. A plan created with a
        `test_` token is auto-approved (`active`) so you can trial checkout
        immediately.

        Constraints:
        - `productType` must be `saas` (e-books are one-off purchases and cannot
          be sold on a recurring basis).
        - The `day` interval is sandbox-only; live plans support `week`, `month`,
          and `year`.
        - `intervalCount` is bounded per unit: up to 365 days, 52 weeks, or 12
          months. `year` always bills once per year (`intervalCount` is ignored).
      tags:
        - Subscription Plans
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionPlanRequest'
            example:
              name: Pro Monthly
              description: Full access to all Pro features, billed monthly
              basePrice:
                value: '29.00'
                currency: EUR
              productType: saas
              interval: month
              intervalCount: 1
      responses:
        '201':
          description: Subscription plan created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlan'
              example:
                id: subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                resource: subscription_plan
                testmode: false
                name: Pro Monthly
                description: Full access to all Pro features, billed monthly
                basePrice:
                  value: '29.00'
                  currency: EUR
                taxBehavior: exclusive
                interval: month
                intervalCount: 1
                productType: saas
                status: pending
                archivedAt: null
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /subscription-plans/{subscriptionPlanId}:
    get:
      operationId: getSubscriptionPlan
      summary: Get a subscription plan
      description: Retrieves a specific subscription plan by its ID.
      tags:
        - Subscription Plans
      parameters:
        - $ref: '#/components/parameters/subscriptionPlanId'
      responses:
        '200':
          description: Subscription plan details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlan'
              example:
                id: subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                resource: subscription_plan
                testmode: false
                name: Pro Monthly
                description: Full access to all Pro features, billed monthly
                basePrice:
                  value: '29.00'
                  currency: EUR
                taxBehavior: exclusive
                interval: month
                intervalCount: 1
                productType: saas
                status: active
                archivedAt: null
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
    patch:
      operationId: updateSubscriptionPlan
      summary: Request an update to a subscription plan
      description: |
        Submits an update to a live subscription plan. Because plans drive
        VAT-bearing recurring sales, the change is held as a pending update and
        reviewed by Vatly before it takes effect (`updateStatus` moves `pending` →
        `reviewing` → applied). In test mode the update is approved automatically.

        Each request is the **complete set of changes** relative to the current
        live plan. Fields equal to the live value are ignored, and a request that
        nets to no change clears any pending update. A new request replaces the
        not-yet-reviewed one; while an update is being reviewed, further requests
        return `409`. Changing the interval on a plan that has ever been used by a
        subscription — active or not — also returns `409`. The price stays
        changeable.
      tags:
        - Subscription Plans
      parameters:
        - $ref: '#/components/parameters/subscriptionPlanId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionPlanRequest'
            example:
              name: Pro Weekly
              basePrice:
                value: '9.00'
                currency: EUR
              interval: week
              intervalCount: 1
      responses:
        '200':
          description: Update submitted; the plan now carries a pending update.
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlan'
              example:
                id: subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                resource: subscription_plan
                testmode: false
                name: Pro Monthly
                description: Full access to all Pro features, billed monthly
                basePrice:
                  value: '29.00'
                  currency: EUR
                taxBehavior: exclusive
                interval: month
                intervalCount: 1
                productType: saas
                status: active
                archivedAt: null
                pendingUpdates:
                  name: Pro Weekly
                  basePrice:
                    value: '9.00'
                    currency: EUR
                  interval: week
                  intervalCount: 1
                updateStatus: pending
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /subscription-plans/{subscriptionPlanId}/archive:
    post:
      operationId: archiveSubscriptionPlan
      summary: Archive a subscription plan
      description: |
        Closes the plan to new business. It is hidden from
        `GET /v1/subscription-plans` (unless `includeArchived=true`), refused by
        `POST /v1/checkouts`, and can no longer be switched to from
        `PATCH /v1/subscriptions/{subscriptionId}`.

        Subscribers already on the plan are deliberately untouched: a
        subscription snapshots its plan at signup and renews off that snapshot,
        so archiving never cancels anyone or changes what they are billed. To end
        a subscription, cancel it with `DELETE /v1/subscriptions/{subscriptionId}`.

        Likewise a checkout created before the plan was archived snapshots its
        product data at creation time and can still be completed. Archiving
        applies to *new* checkouts only.

        Nothing is deleted — the plan remains readable by id, now carrying a
        non-null `archivedAt`. Repeating the request is a no-op that returns
        `204` and does not move `archivedAt`.

        Reverse it with `DELETE /v1/subscription-plans/{subscriptionPlanId}/archive`.
      tags:
        - Subscription Plans
      parameters:
        - $ref: '#/components/parameters/subscriptionPlanId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '204':
          description: Plan archived (or already archived).
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: unarchiveSubscriptionPlan
      summary: Unarchive a subscription plan
      description: |
        Re-opens an archived plan to new business: it reappears in
        `GET /v1/subscription-plans` and can be added to checkouts and switched
        to again. Calling it on a plan that is not archived is a no-op.
      tags:
        - Subscription Plans
      parameters:
        - $ref: '#/components/parameters/subscriptionPlanId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '200':
          description: The plan, now open to new business again.
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlan'
              example:
                id: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
                resource: subscription_plan
                testmode: false
                name: Pro Monthly
                description: Full access to all Pro features, billed monthly
                basePrice:
                  value: '29.00'
                  currency: EUR
                taxBehavior: exclusive
                interval: month
                intervalCount: 1
                productType: saas
                status: active
                archivedAt: null
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/subscription-plans/subscription_plan_Wt5mNvBxKw7YcZaEjLhR
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders:
    get:
      operationId: listOrders
      summary: List all orders
      description: |
        Returns a paginated list of orders for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: order_Hn5xWqVfKm8RjTgYbUcP
                    resource: order
                    customerId: customer_Xk9pQrSvWm4NjLhYbUcP
                    testmode: false
                    metadata: {}
                    paymentMethod: ideal
                    createdAt: '2024-01-15T10:30:00Z'
                    status: paid
                    invoiceNumber: INV-2024-0001
                    total:
                      value: '35.09'
                      currency: EUR
                    subtotal:
                      value: '29.00'
                      currency: EUR
                    reversedSubtotal:
                      value: '0.00'
                      currency: EUR
                    refundableSubtotal:
                      value: '29.00'
                      currency: EUR
                    taxSummary:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '6.09'
                          currency: EUR
                    lines:
                      - id: order_item_Mn6xBtPvKw2RjTgYcZaE
                        resource: orderline
                        description: Pro Monthly Subscription
                        quantity: 1
                        basePrice:
                          value: '29.00'
                          currency: EUR
                        total:
                          value: '35.09'
                          currency: EUR
                        subtotal:
                          value: '29.00'
                          currency: EUR
                        taxes:
                          - taxRate:
                              name: VAT
                              percentage: 21
                              taxablePercentage: 100
                            amount:
                              value: '6.09'
                              currency: EUR
                        productType: subscription
                        productId: subscription_Hn5xWqVfKm8RjTgYbUcP
                    customerDetails:
                      fullName: John Doe
                      companyName: Acme Corp
                      streetAndNumber: 123 Main Street
                      city: Berlin
                      postalCode: '10115'
                      country: DE
                      email: john@acme.com
                    links:
                      self:
                        href: https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP
                        type: application/json
                      customer:
                        href: https://api.vatly.com/v1/customers/customer_Xk9pQrSvWm4NjLhYbUcP
                        type: application/json
                      customerInvoice:
                        href: https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP
                        type: text/html
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/orders
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get an order
      description: |
        Retrieves a specific order by its ID.
        Includes full order details with line items, totals, and billing information.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              example:
                id: order_Hn5xWqVfKm8RjTgYbUcP
                resource: order
                customerId: customer_Xk9pQrSvWm4NjLhYbUcP
                testmode: false
                metadata: {}
                paymentMethod: ideal
                createdAt: '2024-01-15T10:30:00Z'
                status: paid
                invoiceNumber: INV-2024-0001
                total:
                  value: '35.09'
                  currency: EUR
                subtotal:
                  value: '29.00'
                  currency: EUR
                reversedSubtotal:
                  value: '0.00'
                  currency: EUR
                refundableSubtotal:
                  value: '29.00'
                  currency: EUR
                taxSummary:
                  - taxRate:
                      name: VAT
                      percentage: 21
                      taxablePercentage: 100
                    amount:
                      value: '6.09'
                      currency: EUR
                lines:
                  - id: order_item_Jk4pQrSvWm8NjLhYbUcP
                    resource: orderline
                    description: Pro Monthly Subscription
                    quantity: 1
                    basePrice:
                      value: '29.00'
                      currency: EUR
                    total:
                      value: '35.09'
                      currency: EUR
                    subtotal:
                      value: '29.00'
                      currency: EUR
                    taxes:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '6.09'
                          currency: EUR
                    productType: subscription
                    productId: subscription_Hn5xWqVfKm8RjTgYbUcP
                customerDetails:
                  fullName: John Doe
                  companyName: Acme Corp
                  streetAndNumber: 123 Main Street
                  city: Berlin
                  postalCode: '10115'
                  country: DE
                  email: john@acme.com
                links:
                  self:
                    href: https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP
                    type: application/json
                  customer:
                    href: https://api.vatly.com/v1/customers/customer_Xk9pQrSvWm4NjLhYbUcP
                    type: application/json
                  customerInvoice:
                    href: https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP
                    type: text/html
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders/{orderId}/invoice-update-link:
    post:
      operationId: createOrderInvoiceUpdateLink
      summary: Create invoice update link
      description: |
        Generates a signed URL that allows the customer to update the invoice details for this order
        (billing address, VAT number, company name).

        The link is valid for a limited time (typically 24 hours) and can be sent to the customer
        to self-service update their invoice.

        **Use cases:**
        - Customer needs to add/update VAT number
        - Customer needs to correct billing address
        - Customer needs to change company name on invoice
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '200':
          description: Invoice update link generated
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceUpdateLink'
              example:
                href: https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP/edit?signature=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                type: text/html
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders/{orderId}/refunds:
    get:
      operationId: listOrderRefunds
      summary: List order refunds
      description: |
        Returns a paginated list of refunds for a specific order.
        Includes both pending and completed refunds.
      tags:
        - Orders
        - Refunds
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of order refunds
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Refund'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: refund_Bm7xNvPwKr3YjTgHcZaE
                    resource: refund
                    orderId: null
                    customerId: customer_Wt5mNvBxKw7YcZaEjLhR
                    testmode: false
                    createdAt: '2024-01-20T14:00:00Z'
                    status: pending
                    originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                    total:
                      value: '12.10'
                      currency: EUR
                    subtotal:
                      value: '10.00'
                      currency: EUR
                    taxSummary:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '2.10'
                          currency: EUR
                    lines:
                      - id: refund_item_Jk4pQrSvWm8NjLhYbUcP
                        resource: refundline
                        description: Partial refund for service issue
                        quantity: 1
                        basePrice:
                          value: '10.00'
                          currency: EUR
                        total:
                          value: '12.10'
                          currency: EUR
                        subtotal:
                          value: '10.00'
                          currency: EUR
                        taxes:
                          - taxRate:
                              name: VAT
                              percentage: 21
                              taxablePercentage: 100
                            amount:
                              value: '2.10'
                              currency: EUR
                    links:
                      self:
                        href: https://api.vatly.com/v1/refunds/refund_Bm7xNvPwKr3YjTgHcZaE
                        type: application/json
                      originalOrder:
                        href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                        type: application/json
                      order: null
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP/refunds
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: createOrderRefund
      summary: Create a partial refund
      description: |
        Creates a partial refund for specific items in an order.

        **Requirements:**
        - Order must have `paid` status
        - Order's payment provider must support refunds
        - Refund amount per item cannot exceed remaining refundable amount

        **Notes:**
        - Amounts are specified before taxes; taxes are calculated automatically
        - Multiple partial refunds can be created for the same order
        - Refunds are processed asynchronously through the payment provider
      tags:
        - Orders
        - Refunds
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefundRequest'
            examples:
              partialRefund:
                summary: Partial refund for one item
                value:
                  items:
                    - itemId: order_item_Jk4pQrSvWm8NjLhYbUcP
                      amount:
                        value: '15.00'
                        currency: EUR
                      description: 50% refund for service issue
              multipleItems:
                summary: Refund multiple items
                value:
                  items:
                    - itemId: order_item_Jk4pQrSvWm8NjLhYbUcP
                      amount:
                        value: '29.00'
                        currency: EUR
                    - itemId: order_item_Tk7mNvBxKw2RjTgYcZaE
                      amount:
                        value: '10.00'
                        currency: EUR
                  metadata:
                    ticketId: SUPPORT-12345
      responses:
        '201':
          description: Refund created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
              example:
                id: refund_Mn6xBtPvKw2RjTgYcZaE
                resource: refund
                orderId: null
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                testmode: false
                createdAt: '2024-01-15T10:30:00Z'
                status: pending
                originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                total:
                  value: '18.15'
                  currency: EUR
                subtotal:
                  value: '15.00'
                  currency: EUR
                taxSummary:
                  - taxRate:
                      name: VAT
                      percentage: 21
                      taxablePercentage: 100
                    amount:
                      value: '3.15'
                      currency: EUR
                lines:
                  - id: refund_item_Tk7mNvBxKw2RjTgYcZaE
                    resource: refundline
                    description: 50% refund for service issue
                    quantity: 1
                    basePrice:
                      value: '15.00'
                      currency: EUR
                    total:
                      value: '18.15'
                      currency: EUR
                    subtotal:
                      value: '15.00'
                      currency: EUR
                    taxes:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '3.15'
                          currency: EUR
                links:
                  self:
                    href: https://api.vatly.com/v1/refunds/refund_Mn6xBtPvKw2RjTgYcZaE
                    type: application/json
                  originalOrder:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                    type: application/json
                  order: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: |
            Validation failed. Common errors:
            - Order is not in `paid` status
            - Order's payment provider does not support refunds
            - Refund amount exceeds remaining refundable amount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                notPaid:
                  summary: Order not paid
                  value:
                    message: The given data was invalid.
                    errors:
                      orderId:
                        - Order must be in paid status to create a refund.
                overRefund:
                  summary: Over-refunding
                  value:
                    message: The given data was invalid.
                    errors:
                      items.0.amount:
                        - 'Refund amount exceeds remaining refundable amount. Maximum: 15.00 EUR'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders/{orderId}/refunds/full:
    post:
      operationId: createFullOrderRefund
      summary: Create a full refund
      description: |
        Creates a full refund for an order, refunding all items.

        **Requirements:**
        - Order must have `paid` status
        - Order's payment provider must support refunds
        - Order must not be already fully refunded

        **Notes:**
        - This is a convenience endpoint; it automatically calculates the full refundable amount
        - If partial refunds have already been issued, only the remaining amount is refunded
      tags:
        - Orders
        - Refunds
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFullRefundRequest'
            example:
              metadata:
                reason: Customer requested cancellation
      responses:
        '201':
          description: Full refund created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
              example:
                id: refund_Rk5pQrSvWm8NjLhYbUcP
                resource: refund
                orderId: null
                customerId: customer_Wt5mNvBxKw7YcZaEjLhR
                testmode: false
                createdAt: '2024-01-21T09:00:00Z'
                status: pending
                originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                total:
                  value: '35.09'
                  currency: EUR
                subtotal:
                  value: '29.00'
                  currency: EUR
                taxSummary:
                  - taxRate:
                      name: VAT
                      percentage: 21
                      taxablePercentage: 100
                    amount:
                      value: '6.09'
                      currency: EUR
                lines:
                  - id: refund_item_Bm7xNvPwKr3YjTgHcZaE
                    resource: refundline
                    description: Pro Monthly Subscription (Full Refund)
                    quantity: 1
                    basePrice:
                      value: '29.00'
                      currency: EUR
                    total:
                      value: '35.09'
                      currency: EUR
                    subtotal:
                      value: '29.00'
                      currency: EUR
                    taxes:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '6.09'
                          currency: EUR
                links:
                  self:
                    href: https://api.vatly.com/v1/refunds/refund_Rk5pQrSvWm8NjLhYbUcP
                    type: application/json
                  originalOrder:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                    type: application/json
                  order: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders/{orderId}/refunds/{refundId}:
    get:
      operationId: getOrderRefund
      summary: Get an order refund
      description: |
        Retrieves a specific refund for an order.
        The refund must belong to the specified order.
      tags:
        - Orders
        - Refunds
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/refundId'
      responses:
        '200':
          description: Refund details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
              example:
                id: refund_Xk9pQrSvWm4NjLhYbUcP
                resource: refund
                orderId: order_Bm7xNvPwKr3YjTgHcZaE
                customerId: customer_Wt5mNvBxKw7YcZaEjLhR
                testmode: false
                createdAt: '2024-01-20T14:00:00Z'
                status: refunded
                originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                total:
                  value: '18.15'
                  currency: EUR
                subtotal:
                  value: '15.00'
                  currency: EUR
                taxSummary:
                  - taxRate:
                      name: VAT
                      percentage: 21
                      taxablePercentage: 100
                    amount:
                      value: '3.15'
                      currency: EUR
                lines:
                  - id: refund_item_Mn6xBtPvKw2RjTgYcZaE
                    resource: refundline
                    description: Pro Monthly Subscription (Refund)
                    quantity: 1
                    basePrice:
                      value: '15.00'
                      currency: EUR
                    total:
                      value: '18.15'
                      currency: EUR
                    subtotal:
                      value: '15.00'
                      currency: EUR
                    taxes:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '3.15'
                          currency: EUR
                links:
                  self:
                    href: https://api.vatly.com/v1/refunds/refund_Xk9pQrSvWm4NjLhYbUcP
                    type: application/json
                  originalOrder:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                    type: application/json
                  order:
                    href: https://api.vatly.com/v1/orders/order_Bm7xNvPwKr3YjTgHcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: cancelOrderRefund
      summary: Cancel a refund
      description: |
        Cancels a pending refund.

        **Requirements:**
        - Refund must be in `pending` status
        - Cannot cancel refunds that have already been processed

        **Notes:**
        - Once canceled, the refund cannot be restored
        - To refund again, create a new refund request
      tags:
        - Orders
        - Refunds
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/refundId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '204':
          description: Refund canceled successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: Cannot cancel refund (not in pending status)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Only pending refunds can be canceled.
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders/{orderId}/chargebacks:
    get:
      operationId: listOrderChargebacks
      summary: List order chargebacks
      description: |
        Returns a paginated list of chargebacks for a specific order.
        Most orders have at most one chargeback.
      tags:
        - Orders
        - Chargebacks
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of order chargebacks
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Chargeback'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: chargeback_Fp2kQrSvWm8NjLhYbUcP
                    resource: chargeback
                    testmode: false
                    createdAt: '2024-01-25T16:45:00Z'
                    amount:
                      value: '35.09'
                      currency: EUR
                    settlementAmount:
                      value: '35.09'
                      currency: EUR
                    customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                    status: lost
                    total:
                      value: '35.09'
                      currency: EUR
                    subtotal:
                      value: '29.00'
                      currency: EUR
                    taxSummary:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '6.09'
                          currency: EUR
                    reason: product_not_received
                    originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                    orderId: order_Rk5pQrSvWm8NjLhYbUcP
                    links:
                      self:
                        href: https://api.vatly.com/v1/chargebacks/chargeback_Fp2kQrSvWm8NjLhYbUcP
                        type: application/json
                      originalOrder:
                        href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                        type: application/json
                      order:
                        href: https://api.vatly.com/v1/orders/order_Rk5pQrSvWm8NjLhYbUcP
                        type: application/json
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP/chargebacks
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /orders/{orderId}/chargebacks/{chargebackId}:
    get:
      operationId: getOrderChargeback
      summary: Get an order chargeback
      description: |
        Retrieves a specific chargeback for an order.
        The chargeback must belong to the specified order.
      tags:
        - Orders
        - Chargebacks
      parameters:
        - $ref: '#/components/parameters/orderId'
        - $ref: '#/components/parameters/chargebackId'
      responses:
        '200':
          description: Chargeback details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
              example:
                id: chargeback_Mn6xBtPvKw2RjTgYcZaE
                resource: chargeback
                testmode: false
                createdAt: '2024-01-25T16:45:00Z'
                amount:
                  value: '35.09'
                  currency: EUR
                settlementAmount:
                  value: '35.09'
                  currency: EUR
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                status: lost
                total:
                  value: '35.09'
                  currency: EUR
                subtotal:
                  value: '29.00'
                  currency: EUR
                taxSummary:
                  - taxRate:
                      name: VAT
                      percentage: 21
                      taxablePercentage: 100
                    amount:
                      value: '6.09'
                      currency: EUR
                reason: fraud
                originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                orderId: order_Rk5pQrSvWm8NjLhYbUcP
                links:
                  self:
                    href: https://api.vatly.com/v1/chargebacks/chargeback_Mn6xBtPvKw2RjTgYcZaE
                    type: application/json
                  originalOrder:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                    type: application/json
                  order:
                    href: https://api.vatly.com/v1/orders/order_Rk5pQrSvWm8NjLhYbUcP
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /refunds:
    get:
      operationId: listRefunds
      summary: List all refunds
      description: |
        Returns a paginated list of all refunds for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.
      tags:
        - Refunds
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of refunds
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Refund'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: refund_Xk9pQrSvWm4NjLhYbUcP
                    resource: refund
                    orderId: order_Bm7xNvPwKr3YjTgHcZaE
                    customerId: customer_Wt5mNvBxKw7YcZaEjLhR
                    testmode: false
                    createdAt: '2024-01-20T14:00:00Z'
                    status: refunded
                    originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                    total:
                      value: '18.15'
                      currency: EUR
                    subtotal:
                      value: '15.00'
                      currency: EUR
                    taxSummary:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '3.15'
                          currency: EUR
                    lines:
                      - id: refund_item_Mn6xBtPvKw2RjTgYcZaE
                        resource: refundline
                        description: Pro Monthly Subscription (Refund)
                        quantity: 1
                        basePrice:
                          value: '15.00'
                          currency: EUR
                        total:
                          value: '18.15'
                          currency: EUR
                        subtotal:
                          value: '15.00'
                          currency: EUR
                        taxes:
                          - taxRate:
                              name: VAT
                              percentage: 21
                              taxablePercentage: 100
                            amount:
                              value: '3.15'
                              currency: EUR
                    links:
                      self:
                        href: https://api.vatly.com/v1/refunds/refund_Xk9pQrSvWm4NjLhYbUcP
                        type: application/json
                      originalOrder:
                        href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                        type: application/json
                      order:
                        href: https://api.vatly.com/v1/orders/order_Bm7xNvPwKr3YjTgHcZaE
                        type: application/json
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/refunds
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /refunds/{refundId}:
    get:
      operationId: getRefund
      summary: Get a refund
      description: Retrieves a specific refund by its ID.
      tags:
        - Refunds
      parameters:
        - $ref: '#/components/parameters/refundId'
      responses:
        '200':
          description: Refund details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
              example:
                id: refund_Xk9pQrSvWm4NjLhYbUcP
                resource: refund
                orderId: order_Bm7xNvPwKr3YjTgHcZaE
                customerId: customer_Wt5mNvBxKw7YcZaEjLhR
                testmode: false
                createdAt: '2024-01-20T14:00:00Z'
                status: refunded
                originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                total:
                  value: '18.15'
                  currency: EUR
                subtotal:
                  value: '15.00'
                  currency: EUR
                taxSummary:
                  - taxRate:
                      name: VAT
                      percentage: 21
                      taxablePercentage: 100
                    amount:
                      value: '3.15'
                      currency: EUR
                lines:
                  - id: refund_item_Mn6xBtPvKw2RjTgYcZaE
                    resource: refundline
                    description: Pro Monthly Subscription (Refund)
                    quantity: 1
                    basePrice:
                      value: '15.00'
                      currency: EUR
                    total:
                      value: '18.15'
                      currency: EUR
                    subtotal:
                      value: '15.00'
                      currency: EUR
                    taxes:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '3.15'
                          currency: EUR
                links:
                  self:
                    href: https://api.vatly.com/v1/refunds/refund_Xk9pQrSvWm4NjLhYbUcP
                    type: application/json
                  originalOrder:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                    type: application/json
                  order:
                    href: https://api.vatly.com/v1/orders/order_Bm7xNvPwKr3YjTgHcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /chargebacks:
    get:
      operationId: listChargebacks
      summary: List all chargebacks
      description: |
        Returns a paginated list of all chargebacks for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.

        **Notes:**
        - Chargebacks are created automatically by payment provider webhooks
        - They cannot be created manually through the API
      tags:
        - Chargebacks
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of chargebacks
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Chargeback'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: chargeback_Mn6xBtPvKw2RjTgYcZaE
                    resource: chargeback
                    testmode: false
                    createdAt: '2024-01-15T10:30:00Z'
                    amount:
                      value: '35.09'
                      currency: EUR
                    settlementAmount:
                      value: '35.09'
                      currency: EUR
                    customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                    status: lost
                    total:
                      value: '35.09'
                      currency: EUR
                    subtotal:
                      value: '29.00'
                      currency: EUR
                    taxSummary:
                      - taxRate:
                          name: VAT
                          percentage: 21
                          taxablePercentage: 100
                        amount:
                          value: '6.09'
                          currency: EUR
                    reason: fraud
                    originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                    orderId: order_Rk5pQrSvWm8NjLhYbUcP
                    links:
                      self:
                        href: https://api.vatly.com/v1/chargebacks/chargeback_Mn6xBtPvKw2RjTgYcZaE
                        type: application/json
                      originalOrder:
                        href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                        type: application/json
                      order:
                        href: https://api.vatly.com/v1/orders/order_Rk5pQrSvWm8NjLhYbUcP
                        type: application/json
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/chargebacks
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /chargebacks/{chargebackId}:
    get:
      operationId: getChargeback
      summary: Get a chargeback
      description: Retrieves a specific chargeback by its ID.
      tags:
        - Chargebacks
      parameters:
        - $ref: '#/components/parameters/chargebackId'
      responses:
        '200':
          description: Chargeback details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chargeback'
              example:
                id: chargeback_Mn6xBtPvKw2RjTgYcZaE
                resource: chargeback
                testmode: false
                createdAt: '2024-01-25T16:45:00Z'
                amount:
                  value: '35.09'
                  currency: EUR
                settlementAmount:
                  value: '35.09'
                  currency: EUR
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                status: lost
                total:
                  value: '35.09'
                  currency: EUR
                subtotal:
                  value: '29.00'
                  currency: EUR
                taxSummary:
                  - taxRate:
                      name: VAT
                      percentage: 21
                      taxablePercentage: 100
                    amount:
                      value: '6.09'
                      currency: EUR
                reason: fraud
                originalOrderId: order_Fp2kQrSvWm8NjLhYbUcP
                orderId: order_Rk5pQrSvWm8NjLhYbUcP
                links:
                  self:
                    href: https://api.vatly.com/v1/chargebacks/chargeback_Mn6xBtPvKw2RjTgYcZaE
                    type: application/json
                  originalOrder:
                    href: https://api.vatly.com/v1/orders/order_Fp2kQrSvWm8NjLhYbUcP
                    type: application/json
                  order:
                    href: https://api.vatly.com/v1/orders/order_Rk5pQrSvWm8NjLhYbUcP
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /webhook-events/{eventId}:
    get:
      operationId: getWebhookEvent
      summary: Get webhook event
      description: |
        Retrieves a specific webhook event by its ID.
        Returns the full event payload including the resource data at the time the event occurred.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: Webhook event details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEvent'
              example:
                id: webhook_event_Qk8pRtSvWm2NjLhYcZaE
                resource: webhook_event
                eventName: order.paid
                entityType: order
                entityId: order_Hn5xWqVfKm8RjTgYbUcP
                object:
                  id: order_Hn5xWqVfKm8RjTgYbUcP
                  resource: order
                  customerId: customer_Xk9pQrSvWm4NjLhYbUcP
                  testmode: false
                  metadata: {}
                  paymentMethod: ideal
                  createdAt: '2026-05-21T14:32:08+00:00'
                  status: paid
                  invoiceNumber: INV-2026-0001
                  total:
                    value: '29.99'
                    currency: EUR
                  subtotal:
                    value: '24.79'
                    currency: EUR
                  reversedSubtotal:
                    value: '0.00'
                    currency: EUR
                  refundableSubtotal:
                    value: '24.79'
                    currency: EUR
                  taxSummary:
                    - taxRate:
                        name: VAT
                        percentage: 21
                        taxablePercentage: 100
                      amount:
                        value: '5.20'
                        currency: EUR
                  lines:
                    - id: order_item_Mn6xBtPvKw2RjTgYcZaE
                      resource: orderline
                      description: Pro Monthly Subscription
                      quantity: 1
                      basePrice:
                        value: '24.79'
                        currency: EUR
                      total:
                        value: '29.99'
                        currency: EUR
                      subtotal:
                        value: '24.79'
                        currency: EUR
                      taxes:
                        - taxRate:
                            name: VAT
                            percentage: 21
                            taxablePercentage: 100
                          amount:
                            value: '5.20'
                            currency: EUR
                      productType: subscription
                      productId: subscription_Hn5xWqVfKm8RjTgYbUcP
                  customerDetails:
                    fullName: John Doe
                    companyName: Acme Corp
                    streetAndNumber: 123 Main Street
                    city: Berlin
                    postalCode: '10115'
                    country: DE
                    email: john@acme.com
                  links:
                    self:
                      href: https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP
                      type: application/json
                    customer:
                      href: https://api.vatly.com/v1/customers/customer_Xk9pQrSvWm4NjLhYbUcP
                      type: application/json
                    customerInvoice:
                      href: https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP
                      type: text/html
                createdAt: '2026-05-21T14:32:08+00:00'
                testmode: false
                links:
                  self:
                    href: https://api.vatly.com/v1/webhook-events/webhook_event_Qk8pRtSvWm2NjLhYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /webhook-endpoints:
    get:
      operationId: listWebhookEndpoints
      summary: List webhook endpoints
      description: |
        Returns the webhook endpoints for the authenticated merchant, filtered by
        the testmode determined from the API token. A storefront may have up to
        five endpoints per mode, so this returns up to five endpoints. The signing
        secret is never included.
      tags:
        - Webhook Endpoints
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of webhook endpoints
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 1
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: webhook_QdEpFhdSrG4Y3DnfsdqsH
                    resource: webhook_endpoint
                    testmode: false
                    url: https://merchant.example/webhooks/vatly
                    enabledEvents:
                      - order.paid
                      - refund.completed
                    createdAt: '2024-01-15T10:30:00Z'
                    links:
                      self:
                        href: https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH
                        type: application/json
                count: 1
                links:
                  self:
                    href: https://api.vatly.com/v1/webhook-endpoints
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    post:
      operationId: createWebhookEndpoint
      summary: Register a webhook endpoint
      description: |
        Registers a webhook endpoint for the mode determined by the API token.

        You supply the signing `secret`; it is write-only and never returned, so
        keep the value you send — you use it to verify the `Vatly-Signature` HMAC
        on deliveries.

        Vatly sends a `webhook.setup` verification ping to the URL and validates
        its SSL certificate; if either fails the request is rejected with `422`.

        Optionally pass `enabledEvents` to choose the endpoint's subscription set.
        Omit it and Vatly subscribes the endpoint to every event available at
        registration time (not updated automatically afterwards); send an empty
        list to create a dormant endpoint.

        A storefront may have up to five endpoints per mode, and URLs must be
        unique within the storefront and mode. A duplicate URL or a sixth endpoint
        returns `422`.

        **Use cases:**
        - Provision an endpoint from CI / infrastructure-as-code
        - Point an ephemeral preview environment at its own public URL
      tags:
        - Webhook Endpoints
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointRequest'
            example:
              url: https://merchant.example/webhooks/vatly
              secret: whsec_3f9a1c7e2d4f7b9c5a2c1d5b7e9f3a8d
      responses:
        '201':
          description: Webhook endpoint registered successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
              example:
                id: webhook_QdEpFhdSrG4Y3DnfsdqsH
                resource: webhook_endpoint
                testmode: false
                url: https://merchant.example/webhooks/vatly
                enabledEvents:
                  - order.paid
                  - refund.completed
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /webhook-endpoints/{webhookEndpointId}:
    get:
      operationId: getWebhookEndpoint
      summary: Get a webhook endpoint
      description: Retrieves a webhook endpoint by ID. The signing secret is never included.
      tags:
        - Webhook Endpoints
      parameters:
        - $ref: '#/components/parameters/webhookEndpointId'
      responses:
        '200':
          description: Webhook endpoint details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
              example:
                id: webhook_QdEpFhdSrG4Y3DnfsdqsH
                resource: webhook_endpoint
                testmode: false
                url: https://merchant.example/webhooks/vatly
                enabledEvents:
                  - order.paid
                  - refund.completed
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
    patch:
      operationId: updateWebhookEndpoint
      summary: Update a webhook endpoint
      description: |
        Updates a webhook endpoint's `url`, its signing `secret`, or both. A new
        URL is revalidated for reachability and a valid SSL certificate just like
        on creation. The secret is write-only and is never returned. Sending an
        empty body is a no-op that returns the current endpoint.

        Repointing the URL is the supported way to follow an ephemeral
        environment whose public URL changes between runs, without rotating the
        signing secret.
      tags:
        - Webhook Endpoints
      parameters:
        - $ref: '#/components/parameters/webhookEndpointId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookEndpointRequest'
            example:
              url: https://merchant.example/webhooks/vatly-v2
      responses:
        '200':
          description: Webhook endpoint updated successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
              example:
                id: webhook_QdEpFhdSrG4Y3DnfsdqsH
                resource: webhook_endpoint
                testmode: false
                url: https://merchant.example/webhooks/vatly-v2
                enabledEvents:
                  - order.paid
                  - refund.completed
                createdAt: '2024-01-15T10:30:00Z'
                links:
                  self:
                    href: https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: deleteWebhookEndpoint
      summary: Delete a webhook endpoint
      description: |
        Deletes a webhook endpoint. Vatly stops sending deliveries to it
        immediately. To receive events again, register a new endpoint.
      tags:
        - Webhook Endpoints
      parameters:
        - $ref: '#/components/parameters/webhookEndpointId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '204':
          description: Webhook endpoint deleted successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /subscriptions:
    get:
      operationId: listSubscriptions
      summary: List all subscriptions
      description: |
        Returns a paginated list of all subscriptions for the authenticated merchant.
        Results are filtered by the testmode determined from the API token.
        Includes subscriptions in all states (active, canceled, etc.).
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/startingAfter'
        - $ref: '#/components/parameters/endingBefore'
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - links
                additionalProperties: false
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  count:
                    type: integer
                    description: Number of items in the current page
                    example: 2
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              example:
                data:
                  - id: subscription_Lp3mNvBxKw7RjTgYcZaE
                    resource: subscription
                    customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                    subscriptionPlanId: subscription_plan_Rk5pQrSvWm8NjLhYbUcP
                    testmode: false
                    name: Pro Monthly
                    description: Full access to all Pro features
                    billingAddress:
                      fullName: John Doe
                      companyName: Acme Corp
                      streetAndNumber: 123 Main Street
                      city: Berlin
                      postalCode: '10115'
                      country: DE
                    basePrice:
                      value: '29.00'
                      currency: EUR
                    quantity: 1
                    interval: month
                    intervalCount: 1
                    status: active
                    cancellationReason: null
                    mandate:
                      method: card
                      maskedIdentifier: '4242'
                    startedAt: '2024-01-15T10:30:00Z'
                    endedAt: null
                    canceledAt: null
                    renewedAt: '2024-02-15T10:30:00Z'
                    renewedUntil: '2024-03-15T10:30:00Z'
                    nextRenewalAt: '2024-03-15T10:30:00Z'
                    trialUntil: null
                    scheduledUpdate: null
                    links:
                      self:
                        href: https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE
                        type: application/json
                      customer:
                        href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                        type: application/json
                  - id: subscription_Wt5mNvBxKw7YcZaEjLhR
                    resource: subscription
                    customerId: customer_Mn6xBtPvKw2RjTgYcZaE
                    subscriptionPlanId: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
                    testmode: false
                    name: Enterprise Yearly
                    description: Enterprise features with priority support
                    billingAddress:
                      fullName: Jane Smith
                      companyName: TechCorp Ltd
                      taxId: GB123456789
                      streetAndNumber: 456 Tech Lane
                      city: London
                      postalCode: EC1A 1BB
                      country: GB
                    basePrice:
                      value: '990.00'
                      currency: EUR
                    quantity: 5
                    interval: year
                    intervalCount: 1
                    status: active
                    cancellationReason: null
                    mandate:
                      method: card
                      maskedIdentifier: '4242'
                    startedAt: '2024-01-01T00:00:00Z'
                    endedAt: null
                    canceledAt: null
                    renewedAt: '2024-01-01T00:00:00Z'
                    renewedUntil: '2025-01-01T00:00:00Z'
                    nextRenewalAt: '2025-01-01T00:00:00Z'
                    trialUntil: null
                    scheduledUpdate: null
                    links:
                      self:
                        href: https://api.vatly.com/v1/subscriptions/subscription_Wt5mNvBxKw7YcZaEjLhR
                        type: application/json
                      customer:
                        href: https://api.vatly.com/v1/customers/customer_Mn6xBtPvKw2RjTgYcZaE
                        type: application/json
                count: 2
                links:
                  self:
                    href: https://api.vatly.com/v1/subscriptions
                    type: application/json
                  next: null
                  prev: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /subscriptions/{subscriptionId}:
    get:
      operationId: getSubscription
      summary: Get a subscription
      description: Retrieves a specific subscription by its ID.
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              example:
                id: subscription_Lp3mNvBxKw7RjTgYcZaE
                resource: subscription
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                subscriptionPlanId: subscription_plan_Rk5pQrSvWm8NjLhYbUcP
                testmode: false
                name: Pro Monthly
                description: Full access to all Pro features
                billingAddress:
                  fullName: John Doe
                  companyName: Acme Corp
                  streetAndNumber: 123 Main Street
                  city: Berlin
                  postalCode: '10115'
                  country: DE
                basePrice:
                  value: '29.00'
                  currency: EUR
                quantity: 1
                interval: month
                intervalCount: 1
                status: active
                cancellationReason: null
                mandate:
                  method: card
                  maskedIdentifier: '4242'
                startedAt: '2024-01-15T10:30:00Z'
                endedAt: null
                canceledAt: null
                renewedAt: '2024-02-15T10:30:00Z'
                renewedUntil: '2024-03-15T10:30:00Z'
                nextRenewalAt: '2024-03-15T10:30:00Z'
                trialUntil: null
                scheduledUpdate: null
                links:
                  self:
                    href: https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
                  customer:
                    href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/UnexpectedError'
    patch:
      operationId: updateSubscription
      summary: Update a subscription
      description: |
        Updates a subscription's plan, quantity, price, or billing schedule.

        **Plan updates:**
        - Specify `subscriptionPlanId` to switch to a different plan
        - New plan must match the subscription's testmode

        **Quantity updates:**
        - Specify `quantity` to set the number of units (e.g., seats). It is
          the new total, not an amount to add.

        **Price updates:**
        - Specify `price` to set a new recurring price while keeping the
          current plan. Its currency must match the subscription's currency.
        - A `price` sent alongside a `subscriptionPlanId` overrides the new
          plan's default price.

        **Proration:**
        - By default, updates are prorated
        - Set `prorate: false` to disable proration
        - Proration credits unused time and charges for the new plan

        **Timing:**
        - By default, updates apply at the end of the current billing period
        - Set `applyImmediately: true` to apply immediately
        - A subscription whose `status` is `on_grace_period` has no next billing
          period — it ends when the current one does. Scheduling an update for it
          returns `422`; resume the subscription first, or set
          `applyImmediately: true` to apply the change to the remaining period
        - An immediate update on an `on_grace_period` subscription may change the
          plan, price or quantity for the remaining period, but not when that
          period ends. `anchor`, `resetAnchor`, and a plan whose interval differs
          from the current one all return `422`, because each would move the
          already-communicated end date
        - Set `invoiceImmediately: true` to charge proration immediately.
          Otherwise the delta is billed as a line on the next renewal invoice,
          and is waived if the subscription is cancelled before that renewal
        - On yearly and other long-interval plans, prefer
          `invoiceImmediately: true` — the default defers the delta until the
          next renewal, which can be many months away, and waives it if the
          customer cancels first

        **Trial/Anchor:**
        - Use `trialUntil` to extend or set a trial period
        - Use `anchor` to set the billing anchor to a specific date, or
          `resetAnchor: true` to reset it to the current date
        - `anchor` and `resetAnchor` are mutually exclusive
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/subscriptionId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
            examples:
              plan:
                summary: Switch to the yearly plan
                value:
                  subscriptionPlanId: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
                  prorate: true
                  applyImmediately: true
              quantity:
                summary: Set the number of seats to 10
                value:
                  quantity: 10
                  applyImmediately: true
                  invoiceImmediately: true
              price:
                summary: Set a new price, keeping the current plan
                value:
                  price:
                    value: '29.00'
                    currency: EUR
                  applyImmediately: true
              scheduleForNextCycle:
                summary: Apply a new plan or price at the next cycle
                value:
                  subscriptionPlanId: subscription_plan_Fp2kQrSvWm8NjLhYbUcP
                  applyImmediately: false
              extendTrial:
                summary: Extend trial period
                description: |
                  `trialUntil` cannot be sent on its own — at least one of
                  `subscriptionPlanId`, `quantity`, or `price` is required.
                value:
                  quantity: 1
                  trialUntil: '2024-02-28T00:00:00Z'
      responses:
        '200':
          description: Subscription updated successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              example:
                id: subscription_Lp3mNvBxKw7RjTgYcZaE
                resource: subscription
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                subscriptionPlanId: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
                testmode: false
                name: Pro Yearly
                description: Full access to all Pro features, billed yearly
                billingAddress:
                  fullName: John Doe
                  companyName: Acme Corp
                  streetAndNumber: 123 Main Street
                  city: Berlin
                  postalCode: '10115'
                  country: DE
                basePrice:
                  value: '290.00'
                  currency: EUR
                quantity: 1
                interval: year
                intervalCount: 1
                status: active
                cancellationReason: null
                mandate:
                  method: card
                  maskedIdentifier: '4242'
                startedAt: '2024-01-15T10:30:00Z'
                endedAt: null
                canceledAt: null
                renewedAt: '2024-02-15T10:30:00Z'
                renewedUntil: '2025-02-15T10:30:00Z'
                nextRenewalAt: '2025-02-15T10:30:00Z'
                trialUntil: null
                scheduledUpdate: null
                links:
                  self:
                    href: https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
                  customer:
                    href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: |
            Validation failed. Common errors:
            - None of subscriptionPlanId, quantity or price provided
            - Plan does not exist or is in wrong testmode
            - Price currency does not match the subscription currency
            - Both anchor and resetAnchor specified
            - Update scheduled for the next cycle of a subscription that is on its
              cancellation grace period
            - Anchor, resetAnchor or interval change on a subscription that is on
              its cancellation grace period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                validationFailed:
                  summary: Field validation failed
                  value:
                    message: The given data was invalid.
                    errors:
                      subscriptionPlanId:
                        - At least one of subscriptionPlanId, quantity, or price is required.
                testmodeMismatch:
                  summary: Plan exists but in the wrong mode
                  value:
                    message: The given data was invalid.
                    errors:
                      subscriptionPlanId:
                        - Subscription plan exists, but the wrong mode is used. Try switching live / test API keys.
                noNextBillingCycle:
                  summary: Subscription is on its cancellation grace period
                  value:
                    message: The given data was invalid.
                    errors:
                      applyImmediately:
                        - Unable to schedule an update for the next billing cycle of subscription_Lp3mNvBxKw7RjTgYcZaE. The subscription is canceled and ends when the current billing cycle does, so there is no next billing cycle to apply the update to. Resume the subscription first, or set applyImmediately to true to apply the update to the remaining cycle.
                wouldMoveTheEndDate:
                  summary: Immediate update would move a terminating subscription's end date
                  value:
                    message: The given data was invalid.
                    errors:
                      subscriptionId:
                        - Unable to move the billing anchor of subscription_Lp3mNvBxKw7RjTgYcZaE. The subscription is canceled and ends on the date already communicated for the current cycle; changing the anchor, resetting it, or switching to a different interval would move that end date. Resume the subscription first, or apply an update that keeps the current interval and anchor.
        default:
          $ref: '#/components/responses/UnexpectedError'
    delete:
      operationId: cancelSubscription
      summary: Cancel a subscription
      description: |
        Cancels a subscription.

        **Cancellation modes:**
        - **Default (grace period):** Subscription remains active until the end of the current billing period, then ends
        - **Immediate:** Subscription ends immediately when `immediately=true` is specified

        **Notes:**
        - A subscription that was canceled with a grace period (the default) can be resumed via
          `POST /subscriptions/{subscriptionId}/resume` while its `status` is `on_grace_period`
        - A subscription that was canceled immediately cannot be reactivated; create a new subscription instead
        - Customers retain access until `renewedUntil` date (unless canceled immediately)
        - No refunds are issued automatically; use the Refunds API if needed
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/subscriptionId'
        - $ref: '#/components/parameters/idempotencyKey'
        - name: immediately
          in: query
          description: |
            Cancel immediately instead of at period end.
            - `false` (default): Cancel at end of current billing period
            - `true`: Cancel immediately
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: Subscription canceled successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: Subscription cannot be canceled (already canceled or ended)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /subscriptions/{subscriptionId}/billing-update-link:
    post:
      operationId: createSubscriptionBillingUpdateLink
      summary: Create billing update link
      description: |
        Generates a signed URL that allows the customer to update the billing details for this
        subscription (billing address, VAT number, company name) via a hosted flow.

        **Flow:**
        1. Call this endpoint with redirect URLs
        2. Redirect customer to the returned URL
        3. Customer updates their details on the hosted page
        4. Customer is redirected to your success/canceled URL

        **Use cases:**
        - Customer needs to update billing address
        - Customer needs to add/update VAT number
        - Self-service invoice detail management
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/subscriptionId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionBillingRequest'
            example:
              redirectUrlSuccess: https://example.com/billing-updated
              redirectUrlCanceled: https://example.com/account/billing
              billingAddress:
                companyName: Acme Corp
                taxId: DE123456789
      responses:
        '200':
          description: Billing update link generated
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                type: object
                required:
                  - href
                  - type
                additionalProperties: false
                properties:
                  href:
                    type: string
                    format: uri
                    description: URL to redirect customer for billing update
                    example: https://vatly.com/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE/billing?token=xyz...
                  type:
                    type: string
                    const: text/html
                    example: text/html
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /subscriptions/{subscriptionId}/resume:
    post:
      operationId: resumeSubscription
      summary: Resume a canceled subscription
      description: |
        Resumes a subscription that was previously canceled with a grace period, while it is still
        within that grace period.

        **When this works:**
        - The subscription's `status` is `on_grace_period`

          (`endedAt` stays `null` throughout the grace period — it is only set once the
          subscription has actually ended, so resumability is keyed off `status`, not `endedAt`.)

        **Result:**
        - Status returns to `active`
        - The existing billing cycle and renewal schedule are preserved (no new charge fires immediately)
        - The original payment mandate remains in effect
        - A `subscription.resumed` webhook is delivered to your configured endpoint
        - `canceledAt` is cleared (`endedAt` was already `null` during the grace period)
        - The refreshed subscription is returned in the response body

        **When this does NOT work:**
        - Subscription was canceled immediately (`status` is `canceled`) — create a new subscription instead
        - Grace period has already lapsed (`status` is now `canceled` and `endedAt` is set) — create a new subscription instead
        - Subscription is already active (no-op rejected for clarity, not silently ignored)
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/subscriptionId'
        - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '200':
          description: Subscription resumed successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              example:
                id: subscription_Lp3mNvBxKw7RjTgYcZaE
                resource: subscription
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                subscriptionPlanId: subscription_plan_Rk5pQrSvWm8NjLhYbUcP
                testmode: false
                name: Pro Monthly
                description: Full access to all Pro features
                billingAddress:
                  fullName: John Doe
                  companyName: Acme Corp
                  streetAndNumber: 123 Main Street
                  city: Berlin
                  postalCode: '10115'
                  country: DE
                basePrice:
                  value: '29.00'
                  currency: EUR
                quantity: 1
                interval: month
                intervalCount: 1
                status: active
                cancellationReason: null
                mandate:
                  method: card
                  maskedIdentifier: '4242'
                startedAt: '2024-01-15T10:30:00Z'
                endedAt: null
                canceledAt: null
                renewedAt: '2024-02-15T10:30:00Z'
                renewedUntil: '2024-03-15T10:30:00Z'
                nextRenewalAt: '2024-03-15T10:30:00Z'
                trialUntil: null
                scheduledUpdate: null
                links:
                  self:
                    href: https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
                  customer:
                    href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: |
            Subscription is not within an active grace period. Common causes:
            - Subscription was canceled immediately (status `canceled`)
            - Grace period has already lapsed (`status` is now `canceled`)
            - Subscription is already active (was not canceled, or already resumed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        default:
          $ref: '#/components/responses/UnexpectedError'
  /test-helpers/subscriptions/{subscriptionId}/fast-forward-renewal:
    post:
      operationId: fastForwardSubscriptionRenewal
      summary: Fast-forward subscription renewal
      description: |
        Simulates a subscription renewal cycle for testing purposes.

        **Requirements:**
        - Only available in test mode (requires `test_` prefixed API token)
        - Subscription must belong to the authenticated merchant

        **Use cases:**
        - Test renewal billing flows without waiting for the actual billing cycle
        - Verify subscription lifecycle events and webhooks
        - Exercise your payment-recovery handling by forcing the renewal payment to
          fail (`paymentStatus: failed`)
        - Reach both recovery timelines by naming the decline: a soft one retries
          over weeks, a hard one asks the customer for a new payment method

        Requesting an outcome for a renewal that produced no payable order, or whose
        payment has already settled, is an error rather than a silent no-op.
      tags:
        - Test Helpers
      parameters:
        - $ref: '#/components/parameters/subscriptionId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FastForwardSubscriptionRenewalRequest'
            examples:
              advanceOnly:
                summary: Advance the cycle and leave the payment pending
                value: {}
              failed:
                summary: Decline the renewal payment and start a recovery
                value:
                  paymentStatus: failed
              hardDecline:
                summary: Decline it as a dead payment method
                value:
                  paymentStatus: failed
                  failureReason: card_expired
              paid:
                summary: Settle the renewal payment
                value:
                  paymentStatus: paid
      responses:
        '200':
          description: Subscription renewed successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              example:
                id: subscription_Lp3mNvBxKw7RjTgYcZaE
                resource: subscription
                customerId: customer_Lp3mNvBxKw7RjTgYcZaE
                subscriptionPlanId: subscription_plan_Rk5pQrSvWm8NjLhYbUcP
                testmode: true
                name: Pro Monthly
                description: Full access to all Pro features
                billingAddress:
                  fullName: John Doe
                  companyName: Acme Corp
                  streetAndNumber: 123 Main Street
                  city: Berlin
                  postalCode: '10115'
                  country: DE
                basePrice:
                  value: '29.00'
                  currency: EUR
                quantity: 1
                interval: month
                intervalCount: 1
                status: active
                cancellationReason: null
                mandate:
                  method: card
                  maskedIdentifier: '4242'
                startedAt: '2024-01-15T10:30:00Z'
                endedAt: null
                canceledAt: null
                renewedAt: '2024-03-15T10:30:00Z'
                renewedUntil: '2024-04-15T10:30:00Z'
                nextRenewalAt: '2024-04-15T10:30:00Z'
                trialUntil: null
                scheduledUpdate: null
                links:
                  self:
                    href: https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
                  customer:
                    href: https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE
                    type: application/json
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/UnexpectedError'
webhooks:
  order.paid:
    post:
      operationId: onOrderPaid
      summary: Order paid
      description: An order's payment was successful. `object` is the Order.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  order.canceled:
    post:
      operationId: onOrderCanceled
      summary: Order canceled
      description: An order was canceled. `object` is the Order.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  order.chargeback_received:
    post:
      operationId: onOrderChargebackReceived
      summary: Chargeback received
      description: |
        A chargeback was received for an order. `entityType` is `order`, but
        `object` is the Chargeback.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  order.chargeback_reversed:
    post:
      operationId: onOrderChargebackReversed
      summary: Chargeback reversed
      description: |
        A previously received chargeback was reversed. `entityType` is `order`, but
        `object` is the Chargeback.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  order.payment_failed:
    post:
      operationId: onOrderPaymentFailed
      summary: Order payment failed
      description: |
        A payment for this order failed and Vatly's automated payment recovery
        (dunning) has started. Delivered once, when recovery begins — not on each
        retry attempt. If recovery succeeds you receive `order.paid` for the same
        order; if it is exhausted the related subscription is canceled. See
        "Handling failed subscription payments" in the API overview for the full
        recovery flow and the recommended way to gate access.
        `entityType` is `order` and `object` is the Order.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  refund.completed:
    post:
      operationId: onRefundCompleted
      summary: Refund completed
      description: A refund was processed successfully. `object` is the Refund.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  refund.failed:
    post:
      operationId: onRefundFailed
      summary: Refund failed
      description: A refund failed to process. `object` is the Refund.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  refund.canceled:
    post:
      operationId: onRefundCanceled
      summary: Refund canceled
      description: A refund was canceled before completing. `object` is the Refund.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.started:
    post:
      operationId: onSubscriptionStarted
      summary: Subscription started
      description: A subscription was started. `object` is the Subscription.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.canceled_immediately:
    post:
      operationId: onSubscriptionCanceledImmediately
      summary: Subscription canceled immediately
      description: |
        A subscription was canceled with immediate effect at the merchant's
        request. `object` is the Subscription and carries
        `cancellationReason: merchant_request`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.canceled_for_nonpayment:
    post:
      operationId: onSubscriptionCanceledForNonpayment
      summary: Subscription canceled for nonpayment
      description: |
        Payment recovery for a failed subscription renewal was exhausted, so the
        subscription was canceled with immediate effect. `object` is the
        Subscription and carries `cancellationReason: payment_failure`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.canceled_with_grace_period:
    post:
      operationId: onSubscriptionCanceledWithGracePeriod
      summary: Subscription canceled with grace period
      description: |
        A subscription was canceled and will remain active until the end of its
        grace period. `object` is the Subscription.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.cancellation_grace_period_completed:
    post:
      operationId: onSubscriptionCancellationGracePeriodCompleted
      summary: Subscription grace period completed
      description: |
        A canceled subscription's grace period ended and the subscription is now
        fully canceled. `object` is the Subscription.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.resumed:
    post:
      operationId: onSubscriptionResumed
      summary: Subscription resumed
      description: |
        A canceled subscription was resumed during its grace period. `object` is
        the Subscription.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.billing_updated:
    post:
      operationId: onSubscriptionBillingUpdated
      summary: Subscription billing updated
      description: |
        A subscription's billing details changed server-side. In practice today
        this is the mandate (payment method on file) — e.g. the customer completed
        the hosted billing-update flow or the mandate was replaced
        customer-service-side. `object` is the Subscription, enriched with the
        current mandate (`object.mandate.method` and `object.mandate.maskedIdentifier`).
        Use this to refresh the masked payment method identifier you display to the
        customer without polling or a follow-up `GET /v1/subscriptions/{id}`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.updated:
    post:
      operationId: onSubscriptionUpdated
      summary: Subscription updated
      description: |
        A subscription changed immediately (effective now, not at the next billing
        cycle) — a plan/price/interval change or a quantity change. `object` is the
        Subscription reflecting the new values.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription.update_scheduled:
    post:
      operationId: onSubscriptionUpdateScheduled
      summary: Subscription update scheduled
      description: |
        A plan/price/quantity change was scheduled to take effect at the
        subscription's next billing cycle. `object` is the Subscription as it is
        *today* (the change has not applied yet); the scheduled target values are
        carried in `object.scheduledUpdate` (`subscriptionPlanId`, `name`,
        `description`, `basePrice`, `quantity`, `interval`, `intervalCount`, `effectiveAt`).
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  checkout.paid:
    post:
      operationId: onCheckoutPaid
      summary: Checkout paid
      description: A checkout was paid successfully. `object` is the Checkout.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  checkout.failed:
    post:
      operationId: onCheckoutFailed
      summary: Checkout payment failed
      description: A checkout payment failed. `object` is the Checkout.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  checkout.canceled:
    post:
      operationId: onCheckoutCanceled
      summary: Checkout canceled
      description: A checkout was canceled. `object` is the Checkout.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  checkout.expired:
    post:
      operationId: onCheckoutExpired
      summary: Checkout expired
      description: A checkout session expired before being paid. `object` is the Checkout.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  webhook.setup:
    post:
      operationId: onWebhookSetup
      summary: Webhook setup
      description: |
        Verification call sent when a webhook endpoint is registered or its URL is
        changed, to confirm the endpoint is reachable. `entityType` is `webhook` and
        `object` is the (secret-free) endpoint config. Acknowledge with any 2xx; no
        other action is required. This call is not persisted and is not retried, and
        therefore omits the `links` field carried by regular event deliveries.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/SetupAcknowledged'
  one_off_product.update_submitted:
    post:
      operationId: onOneOffProductUpdateSubmitted
      summary: One-off product update submitted
      description: |
        A merchant submitted an update to a one-off product; it is awaiting review.
        `object` is the OneOffProduct, with the requested changes in
        `object.pendingUpdates` and `object.updateStatus: pending`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  one_off_product.update_approved:
    post:
      operationId: onOneOffProductUpdateApproved
      summary: One-off product update approved
      description: |
        A submitted update to a one-off product was approved and is now live.
        `object` is the OneOffProduct with the new values applied and
        `object.pendingUpdates: null`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  one_off_product.update_rejected:
    post:
      operationId: onOneOffProductUpdateRejected
      summary: One-off product update rejected
      description: |
        A submitted update to a one-off product was rejected. `object` is the
        unchanged OneOffProduct with `object.pendingUpdates: null`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  one_off_product.archived:
    post:
      operationId: onOneOffProductArchived
      summary: One-off product archived
      description: |
        A one-off product was taken out of the sellable catalogue. `object` is
        the OneOffProduct with a non-null `object.archivedAt`. It is now hidden
        from `GET /v1/one-off-products` and refused by `POST /v1/checkouts`;
        checkouts opened before this point are unaffected.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  one_off_product.unarchived:
    post:
      operationId: onOneOffProductUnarchived
      summary: One-off product unarchived
      description: |
        An archived one-off product was put back on sale. `object` is the
        OneOffProduct with `object.archivedAt: null`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription_plan.update_submitted:
    post:
      operationId: onSubscriptionPlanUpdateSubmitted
      summary: Subscription plan update submitted
      description: |
        A merchant submitted an update to a subscription plan; it is awaiting
        review. `object` is the SubscriptionPlan, with the requested changes in
        `object.pendingUpdates` and `object.updateStatus: pending`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription_plan.update_approved:
    post:
      operationId: onSubscriptionPlanUpdateApproved
      summary: Subscription plan update approved
      description: |
        A submitted update to a subscription plan was approved and is now live.
        `object` is the SubscriptionPlan with the new values applied and
        `object.pendingUpdates: null`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription_plan.update_rejected:
    post:
      operationId: onSubscriptionPlanUpdateRejected
      summary: Subscription plan update rejected
      description: |
        A submitted update to a subscription plan was rejected. `object` is the
        unchanged SubscriptionPlan with `object.pendingUpdates: null`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription_plan.archived:
    post:
      operationId: onSubscriptionPlanArchived
      summary: Subscription plan archived
      description: |
        A subscription plan was closed to new business. `object` is the
        SubscriptionPlan with a non-null `object.archivedAt`. It is now hidden
        from `GET /v1/subscription-plans`, refused by `POST /v1/checkouts`, and
        can no longer be switched to from `PATCH /v1/subscriptions/{subscriptionId}`.
        Subscribers already on the plan keep billing unchanged.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
  subscription_plan.unarchived:
    post:
      operationId: onSubscriptionPlanUnarchived
      summary: Subscription plan unarchived
      description: |
        An archived subscription plan was re-opened to new business. `object` is
        the SubscriptionPlan with `object.archivedAt: null`.
      tags:
        - Webhook Events
      parameters:
        - $ref: '#/components/parameters/VatlySignature'
        - $ref: '#/components/parameters/VatlyEventId'
      requestBody:
        $ref: '#/components/requestBodies/WebhookDelivery'
      responses:
        2XX:
          $ref: '#/components/responses/Acknowledged'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API token authentication using Bearer scheme.

        Tokens are prefixed to indicate the environment mode:
        - `live_` - Production mode, accesses real data
        - `test_` - Sandbox mode, accesses test data

        Obtain API tokens from the Vatly dashboard under Settings > API Keys.

        **Example:**
        ```
        Authorization: Bearer test_abc123xyz...
        ```

        **Important:** Resources are isolated by mode. A checkout created with a test token
        cannot reference customers or products created with a live token, and vice versa.
      bearerFormat: '{mode}_{token}'
  parameters:
    limit:
      name: limit
      in: query
      description: Maximum number of results to return per page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
      example: 25
    startingAfter:
      name: startingAfter
      in: query
      description: |
        Cursor for forward pagination.
        Returns results after this resource ID.
        Mutually exclusive with `endingBefore`.
      required: false
      schema:
        type: string
      example: checkout_QdEpFhdSrG4Y3DnfsdqsH
    endingBefore:
      name: endingBefore
      in: query
      description: |
        Cursor for backward pagination.
        Returns results before this resource ID.
        Mutually exclusive with `startingAfter`.
      required: false
      schema:
        type: string
      example: checkout_Rk5pQrSvWm8NjLhYbUcP
    idempotencyKey:
      name: Idempotency-Key
      in: header
      description: |
        A unique key the client generates per logical mutating operation to
        make retries safe. Vatly stores the first response keyed by
        `(token, endpoint, key)` and returns it verbatim on subsequent
        requests with the same key, setting `Idempotent-Replayed: true` on
        the replayed response.

        Keys bind to the HTTP method, public endpoint, concrete path, query,
        request body, normalized `Content-Type` media type, and normalized
        ordered `Content-Encoding`. Media type and content encoding are
        contract-significant: changing either on a replay returns `409 Conflict`
        without executing the operation again. Keys are scoped per public route
        URI template and retained for 24 hours; internal route-name changes do
        not affect replay identity.

        Recommended format: UUIDv4. Send on every mutating request
        (POST, PATCH, PUT, DELETE) where retry safety matters.
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: 9f6a3b1c-7e2d-4f7b-9c5a-2c1d5b7e9f3a
    checkoutId:
      name: checkoutId
      in: path
      description: Unique identifier of the checkout
      required: true
      schema:
        type: string
      example: checkout_QdEpFhdSrG4Y3DnfsdqsH
    customerEmailFilter:
      name: email
      in: query
      description: |
        Return customers with this email address, within the storefront and mode
        the API token is scoped to.

        Canonicalized before matching, exactly as on write — see the `email`
        field of the customer schema. Beyond that the comparison is exact, so
        `büyer@example.com` does not match `buyer@example.com`.

        An address can be held by more than one customer, in which case all of
        them are returned. A value that is not a valid email address returns
        `422`.
      required: false
      schema:
        type: string
        format: email
      example: john.doe@example.com
    customerId:
      name: customerId
      in: path
      description: Unique identifier of the customer
      required: true
      schema:
        type: string
      example: customer_7kBmRtPvXw2NjLhYcZaE
    subscriptionId:
      name: subscriptionId
      in: path
      description: Unique identifier of the subscription
      required: true
      schema:
        type: string
      example: subscription_Lp3mNvBxKw7RjTgYcZaE
    includeArchived:
      name: includeArchived
      in: query
      description: |
        Include archived entries in the catalogue listing. Archived entries are
        hidden by default because they cannot be sold; set this to `true` to see
        them alongside the live ones (tell them apart by the non-null
        `archivedAt`).
      required: false
      schema:
        type: boolean
        default: false
      example: true
    oneOffProductId:
      name: oneOffProductId
      in: path
      description: Unique identifier of the one-off product
      required: true
      schema:
        type: string
        pattern: ^one_off_product_
      example: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
    subscriptionPlanId:
      name: subscriptionPlanId
      in: path
      description: Unique identifier of the subscription plan
      required: true
      schema:
        type: string
        pattern: ^subscription_plan_
      example: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
    orderId:
      name: orderId
      in: path
      description: Unique identifier of the order
      required: true
      schema:
        type: string
      example: order_Hn5xWqVfKm8RjTgYbUcP
    refundId:
      name: refundId
      in: path
      description: Unique identifier of the refund
      required: true
      schema:
        type: string
      example: refund_Xk9pQrSvWm4NjLhYbUcP
    chargebackId:
      name: chargebackId
      in: path
      description: Unique identifier of the chargeback
      required: true
      schema:
        type: string
      example: chargeback_Mn6xBtPvKw2RjTgYcZaE
    eventId:
      name: eventId
      in: path
      description: Unique identifier of the webhook event
      required: true
      schema:
        type: string
      example: webhook_event_Qk8pRtSvWm2NjLhYcZaE
    webhookEndpointId:
      name: webhookEndpointId
      in: path
      description: Unique identifier of the webhook endpoint
      required: true
      schema:
        type: string
        pattern: ^webhook_
      example: webhook_QdEpFhdSrG4Y3DnfsdqsH
    VatlySignature:
      name: Vatly-Signature
      in: header
      required: true
      description: |
        HMAC-SHA256 signature of the raw request body, formatted `t=<unix-timestamp>,v1=<hex>`.
        Recompute it over the exact bytes received and compare before trusting the payload.
        A fresh signature is sent on every delivery attempt (initial and retries).
      schema:
        type: string
      example: t=1716301928,v1=5f3cbe2a9d1e4c7b8a0f6d2e1c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a
    VatlyEventId:
      name: Vatly-Event-Id
      in: header
      required: true
      description: |
        Stable identifier for this event, constant across delivery retries. Use it as an
        idempotency / dedup key so a retried delivery is not processed twice.
      schema:
        type: string
      example: webhook_event_Qk8pRtSvWm2NjLhYcZaE
  headers:
    IdempotentReplayed:
      description: |
        Present and set to `true` when the response was replayed from a
        previously stored result keyed by `Idempotency-Key`. Absent (or
        `false`) for first-time requests.
      schema:
        type: boolean
      example: true
  responses:
    UnexpectedError:
      description: |
        Catch-all for any status not explicitly enumerated on the operation.
        Branch on the HTTP status code:
        - `400` Bad Request — malformed request (e.g. invalid JSON body)
        - `429` Too Many Requests — rate limit exceeded; the `Retry-After`
          header gives the number of seconds to wait before retrying
        - `500` Internal Server Error — an unexpected error occurred; the
          request can typically be retried

        The body is always the standard `Error` shape.
      headers:
        Retry-After:
          description: Present on `429` responses — seconds to wait before retrying.
          required: false
          schema:
            type: integer
          example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: An unexpected error occurred. Please try again later.
    Unauthorized:
      description: Unauthorized - Authentication credentials were missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Unauthenticated.
    Forbidden:
      description: |
        Forbidden - The API token is invalid or does not have permission for this operation.
        Common causes:
        - Token does not start with `live_` or `test_`
        - Token has been revoked
        - Attempting live operations on a non-live merchant account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Auth token must start with live_ or test_.
    ValidationFailed:
      description: |
        Unprocessable Entity - The request was well-formed but contained validation errors.
        The `errors` object contains field-specific error messages.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            message: The given data was invalid.
            errors:
              email:
                - The email field is required.
                - The email must be a valid email address.
              products.0.id:
                - The selected products.0.id is invalid.
    Conflict:
      description: |
        Conflict — The request could not be completed because of one of
        the following:

        - **Idempotency replay mismatch** (`Idempotency-Key` reused with
          different request parameters). Retry with the original parameters
          or generate a new key.
        - **Idempotency request in progress**
          (`details.idempotency_outcome = in_progress`). Wait the
          `Retry-After` interval, then retry the exact request with the same key.
        - **Idempotency outcome unknown**
          (`details.idempotency_outcome = unknown`). This is not retryable: read
          and reconcile resource/provider state before another mutation.
        - **Optimistic concurrency conflict** (two writers modifying the
          same resource at the same version). Reload the latest state
          and retry — the conflict resolves itself unless contention is
          sustained.

        The HTTP status (`409`) is shared by all cases; the `message`
        distinguishes them.
      headers:
        Retry-After:
          description: Present only for `in_progress`; seconds before retrying the exact request and key.
          required: false
          schema:
            type: integer
            minimum: 1
          example: 2
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            idempotency_replay_mismatch:
              summary: Idempotency-Key reused with a different payload
              value:
                message: Idempotency-Key has already been used with different request parameters.
                details:
                  idempotency_key: 9f6a3b1c-7e2d-4f7b-9c5a-2c1d5b7e9f3a
            idempotency_in_progress:
              summary: Another caller is still processing this exact request
              value:
                message: A request with this Idempotency-Key is still being processed. Retry the same request shortly.
                details:
                  idempotency_outcome: in_progress
                  retryable: true
                  retry_after_seconds: 2
            idempotency_outcome_unknown:
              summary: The request may have completed but cannot be replayed safely
              value:
                message: The prior request may have completed, but its response could not be recorded. Reconcile the resource state before attempting another mutation.
                details:
                  idempotency_outcome: unknown
                  retryable: false
                  recovery_action: reconcile_resource_state
            concurrency_conflict:
              summary: Concurrent write on the same resource
              value:
                message: The resource was modified concurrently. Reload the latest state and retry.
    NotFound:
      description: Not Found - The requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Checkout not found.
    Acknowledged:
      description: |
        Acknowledged. Return any 2xx status to confirm receipt. A non-2xx response
        or a timeout causes Vatly to retry the delivery with backoff.
    SetupAcknowledged:
      description: |
        Endpoint reachable. Return any 2xx status to confirm. Unlike event
        deliveries, the setup call is a synchronous verification check: a non-2xx
        response or timeout fails endpoint registration/verification and is NOT
        retried.
  schemas:
    Money:
      type: object
      description: Monetary value with currency
      required:
        - value
        - currency
      additionalProperties: false
      properties:
        value:
          type: string
          description: |
            The amount as a decimal string. Sent and returned as a string to
            preserve precision for financial calculations.

            The number of required decimal places is **currency-dependent**: it
            equals the currency's ISO 4217 minor-unit count — the same rule the
            server enforces via [moneyphp/money](https://github.com/moneyphp/money)'s
            `DecimalMoneyParser`. The `(value, currency)` pair is validated
            together (see the `oneOf` below); mixing precisions is rejected:

            - 2 decimals — EUR, USD (and most currencies): `"10.00"` ✓, `"10"` ✗, `"10.0"` ✗, `"10.000"` ✗
            - 0 decimals — e.g. JPY: `"1000"` ✓, `"1000.00"` ✗   *(not yet enabled)*
            - 3 decimals — e.g. BHD, KWD, OMR, TND: `"1.000"` ✓, `"1.00"` ✗   *(not yet enabled)*

            Because the value is a decimal amount (not minor units), `"1000"`
            means one thousand units — valid only for a 0-decimal currency; for
            EUR/USD you must write `"1000.00"`.
          example: '99.99'
        currency:
          type: string
          description: |
            ISO 4217 currency code. Vatly aligns its supported currency set
            with its payment provider's; currencies are enabled as PSP support and
            downstream tax/FX coverage are in place. Expansion beyond this
            list is tracked in issue #1404.
          enum:
            - EUR
            - USD
          example: EUR
      oneOf:
        - title: Two-decimal currencies (default)
          properties:
            currency:
              not:
                enum:
                  - BIF
                  - CLP
                  - DJF
                  - GNF
                  - ISK
                  - JPY
                  - KMF
                  - KRW
                  - PYG
                  - RWF
                  - UGX
                  - VND
                  - VUV
                  - XAF
                  - XOF
                  - XPF
                  - BHD
                  - IQD
                  - JOD
                  - KWD
                  - LYD
                  - OMR
                  - TND
            value:
              pattern: ^\d+\.\d{2}$
        - title: Zero-decimal currencies
          properties:
            currency:
              enum:
                - BIF
                - CLP
                - DJF
                - GNF
                - ISK
                - JPY
                - KMF
                - KRW
                - PYG
                - RWF
                - UGX
                - VND
                - VUV
                - XAF
                - XOF
                - XPF
            value:
              pattern: ^\d+$
        - title: Three-decimal currencies
          properties:
            currency:
              enum:
                - BHD
                - IQD
                - JOD
                - KWD
                - LYD
                - OMR
                - TND
            value:
              pattern: ^\d+\.\d{3}$
    Link:
      type: object
      description: HATEOAS link to a related resource
      required:
        - href
        - type
      properties:
        href:
          type: string
          format: uri
          description: URL of the linked resource
          example: https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP
        type:
          type: string
          description: |
            Content type of the linked resource.
            - `application/json` for API resources
            - `text/html` for hosted pages
          enum:
            - application/json
            - text/html
          example: application/json
    BillingAddress:
      type: object
      description: Customer or merchant billing address
      properties:
        fullName:
          type:
            - string
            - 'null'
          description: Full name of the person or contact
          example: John Doe
        companyName:
          type:
            - string
            - 'null'
          description: Company or organization name
          example: Acme Corp
        taxId:
          type:
            - string
            - 'null'
          description: Tax identification number for tax purposes
          example: NL123456789B01
        streetAndNumber:
          type:
            - string
            - 'null'
          description: Street address including building number
          example: 123 Main Street
        streetAdditional:
          type:
            - string
            - 'null'
          description: Additional address information (apartment, suite, etc.)
          example: Suite 456
        city:
          type:
            - string
            - 'null'
          description: City name
          example: Amsterdam
        region:
          type:
            - string
            - 'null'
          description: State, province, or region
          example: North Holland
        postalCode:
          type:
            - string
            - 'null'
          description: Postal or ZIP code
          example: 1012 AB
        country:
          type:
            - string
            - 'null'
          description: ISO 3166-1 alpha-2 country code
          example: NL
          minLength: 2
          maxLength: 2
    BillingDetails:
      type: object
      description: Complete billing details including address and contact information
      properties:
        fullName:
          type:
            - string
            - 'null'
          description: Full name of the person or contact
          example: John Doe
        companyName:
          type:
            - string
            - 'null'
          description: Company or organization name
          example: Acme Corp
        taxId:
          type:
            - string
            - 'null'
          description: Tax identification number
          example: NL123456789B01
        streetAndNumber:
          type:
            - string
            - 'null'
          description: Street address including building number
          example: 123 Main Street
        streetAdditional:
          type:
            - string
            - 'null'
          description: Additional address information
          example: Suite 456
        city:
          type:
            - string
            - 'null'
          description: City name
          example: Amsterdam
        region:
          type:
            - string
            - 'null'
          description: State, province, or region
          example: North Holland
        postalCode:
          type:
            - string
            - 'null'
          description: Postal or ZIP code
          example: 1012 AB
        country:
          type:
            - string
            - 'null'
          description: ISO 3166-1 alpha-2 country code
          example: NL
        email:
          type:
            - string
            - 'null'
          format: email
          description: |
            Email address.
            Internationalized domains must use their Punycode (ASCII) form
            per RFC 3492 — e.g. `billing@xn--mller-kva.de`.
          example: billing@acme.com
    Metadata:
      type:
        - object
        - 'null'
      description: |
        Arbitrary key-value metadata for your application.
        Up to 50 keys, with key names up to 40 characters and values up to 500 characters.
      additionalProperties:
        type: string
        maxLength: 500
      maxProperties: 50
      example:
        orderId: internal-12345
        campaign: summer-sale
    PaginationLinks:
      type: object
      description: Pagination links for navigating list results
      required:
        - self
      properties:
        self:
          allOf:
            - $ref: '#/components/schemas/Link'
          description: Link to the current page
        next:
          oneOf:
            - $ref: '#/components/schemas/Link'
            - type: 'null'
          description: Link to the next page (null if on the last page)
        prev:
          oneOf:
            - $ref: '#/components/schemas/Link'
            - type: 'null'
          description: Link to the previous page (null if on the first page)
    Error:
      type: object
      description: |
        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.
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message
          example: The requested resource was not found.
        details:
          type: object
          description: |
            Optional structured context attached by the originating exception.
            Shape depends on the specific error case; clients should treat
            unknown keys as forward-compatible additions and rely on the HTTP
            status code for branching logic.
          additionalProperties: true
          example:
            resource_type: checkout
            resource_id: checkout_abc123
    ValidationError:
      type: object
      description: Validation error response with field-specific errors
      required:
        - message
        - errors
      properties:
        message:
          type: string
          description: General validation error message
          example: The given data was invalid.
        errors:
          type: object
          description: |
            Field-specific validation errors.
            Keys are field names (using dot notation for nested fields).
            Values are arrays of error messages.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            email:
              - The email field is required.
            products.0.id:
              - The selected products.0.id is invalid.
    Checkout:
      type: object
      description: |
        A checkout session represents a hosted payment flow.
        Customers are redirected to the checkout URL to complete their purchase.
      required:
        - id
        - resource
        - customerId
        - orderId
        - testmode
        - redirectUrlSuccess
        - redirectUrlCanceled
        - metadata
        - locale
        - status
        - createdAt
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the checkout
          example: checkout_QdEpFhdSrG4Y3DnfsdqsH
        resource:
          type: string
          description: Resource type identifier
          const: checkout
          example: checkout
        customerId:
          type:
            - string
            - 'null'
          description: |
            ID of the customer associated with this checkout.
            Null until a customer has been associated (for an anonymous
            checkout this happens when the buyer completes payment).
          example: customer_7kBmRtPvXw2NjLhYcZaE
        orderId:
          type:
            - string
            - 'null'
          description: |
            ID of the order created from this checkout. Always present in the
            payload; `null` until the checkout completes, then set to the created
            order id.
          example: order_Tk7mNvBxKw2RjTgYcZaE
        testmode:
          type: boolean
          description: Whether this checkout is in test mode
          example: false
        redirectUrlSuccess:
          type: string
          format: uri
          description: URL to redirect customers after successful payment
          example: https://example.com/success
        redirectUrlCanceled:
          type: string
          format: uri
          description: URL to redirect customers if they cancel the checkout
          example: https://example.com/canceled
        metadata:
          $ref: '#/components/schemas/Metadata'
        locale:
          type:
            - string
            - 'null'
          description: |
            The language you asked the hosted checkout to be presented in, as sent on
            creation. `null` means you did not specify one, and the checkout picks a
            language from the shopper's browser.
          enum:
            - en
            - de
            - fr
            - nl
            - es
            - it
            - pt
            - pl
            - null
          example: de
        status:
          type: string
          description: |
            Current status of the checkout:
            - `created` - Checkout is active and awaiting payment
            - `paid` - Payment successful, order created
            - `canceled` - Checkout was canceled by the customer
            - `failed` - Payment failed
            - `expired` - Checkout expired without completion
          enum:
            - created
            - paid
            - canceled
            - failed
            - expired
          example: created
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When this checkout will expire (ISO 8601 format)
          example: '2024-01-15T14:30:00Z'
        createdAt:
          type: string
          format: date-time
          description: When this checkout was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - checkoutUrl
            - self
            - order
          additionalProperties: false
          properties:
            checkoutUrl:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Hosted checkout page URL (text/html)
            self:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to this checkout resource
            order:
              oneOf:
                - $ref: '#/components/schemas/Link'
                - type: 'null'
              description: Link to the created order. Always present; `null` until the checkout completes.
    CheckoutProduct:
      type: object
      description: A product to add to the checkout
      required:
        - id
      additionalProperties: false
      properties:
        id:
          type: string
          description: |
            Product identifier. Must be either:
            - A one-off product ID (starts with `one_off_product_`)
            - A subscription plan ID (starts with `subscription_plan_`)
          pattern: ^(one_off_product_|subscription_plan_)
          example: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
        quantity:
          type: integer
          description: Number of units to purchase
          minimum: 1
          default: 1
          example: 2
        price:
          oneOf:
            - $ref: '#/components/schemas/Money'
            - type: 'null'
          description: |
            Custom price override for this product.
            If not provided, the product's default price is used.
        trialDays:
          type:
            - integer
            - 'null'
          description: |
            Trial period in days for subscription plans.
            Only applicable when `id` references a subscription plan.
          minimum: 0
          example: 14
        metadata:
          $ref: '#/components/schemas/Metadata'
    CreateCheckoutRequest:
      type: object
      description: Request body for creating a new checkout
      required:
        - redirectUrlSuccess
        - redirectUrlCanceled
        - products
      additionalProperties: false
      properties:
        redirectUrlSuccess:
          type: string
          description: |
            URL to redirect customers after successful payment.

            You may include the literal `{CHECKOUT_ID}` placeholder anywhere in the
            URL (e.g. `https://example.com/return?checkout_id={CHECKOUT_ID}`). Vatly
            substitutes it with this checkout's id at creation time, so the host can
            learn the checkout id on the redirect back without any server-side token
            store. Only `{CHECKOUT_ID}` is supported.
          example: https://example.com/return?checkout_id={CHECKOUT_ID}
        redirectUrlCanceled:
          type: string
          description: |
            URL to redirect customers if they cancel the checkout.

            Supports the same `{CHECKOUT_ID}` placeholder as `redirectUrlSuccess`.
          example: https://example.com/canceled?checkout_id={CHECKOUT_ID}
        customerId:
          type:
            - string
            - 'null'
          description: |
            Existing customer ID to associate with this checkout.
            If provided, the customer's email will be pre-filled.
            Must match the testmode of the API token.
          example: customer_7kBmRtPvXw2NjLhYcZaE
        metadata:
          $ref: '#/components/schemas/Metadata'
        locale:
          type:
            - string
            - 'null'
          description: |
            Language to present the hosted checkout in, including its validation and
            error messages. Set this when you already know the customer's language —
            it is a better signal than their browser's.

            Send a bare language code (`de`), a BCP 47 tag (`de-AT`), or a POSIX /
            ISO 15897 locale (`de_DE`) — whichever your stack already stores. All
            three are folded to the language, so `de`, `de-AT` and `de_DE` are the
            same request. There are no region-specific variants: an Austrian and a
            German customer are both served `de`.

            The language also carries through to the payment provider's own hosted
            page, in whatever format that provider expects.

            Supported languages: `en`, `de`, `fr`, `nl`, `es`, `it`, `pt`, `pl`.
            Anything else is a `422` naming the supported set.

            Omit it (or send `null`) to detect the language from the shopper's
            `Accept-Language` header, falling back to English. A shopper can always
            override your choice with the checkout's own language switcher.

            The response echoes back the folded language, not the string you sent.
          example: de
        products:
          type: array
          description: Products to include in this checkout
          minItems: 1
          items:
            $ref: '#/components/schemas/CheckoutProduct'
          example:
            - id: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
              quantity: 1
            - id: subscription_plan_Rk5pQrSvWm8NjLhYbUcP
              trialDays: 14
    Customer:
      type: object
      description: |
        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.
      required:
        - id
        - resource
        - testmode
        - email
        - name
        - createdAt
        - metadata
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the customer
          example: customer_7kBmRtPvXw2NjLhYcZaE
        resource:
          type: string
          description: Resource type identifier
          const: customer
          example: customer
        testmode:
          type: boolean
          description: Whether this customer is in test mode
          example: false
        email:
          type: string
          format: email
          description: |
            Customer's email address.
            Internationalized domains are stored and returned in their
            Punycode (ASCII) form per UTS #46 — e.g. `user@xn--mller-kva.de`.
            Convert back to Unicode for display in your own UI.
          example: customer@example.com
        name:
          type:
            - string
            - 'null'
          description: |
            Customer's display / account-holder name. This is an identity field
            for communication (dunning emails, dashboard) — it is distinct from,
            and does not affect, the billing name on invoices.
          example: John Doe
        createdAt:
          type: string
          format: date-time
          description: When this customer was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        metadata:
          $ref: '#/components/schemas/Metadata'
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
          additionalProperties: false
          properties:
            self:
              $ref: '#/components/schemas/Link'
              description: Link to this customer resource
    CreateCustomerRequest:
      type: object
      description: Request body for creating a new customer
      required:
        - email
      additionalProperties: false
      properties:
        email:
          type: string
          format: email
          description: |
            Customer's email address. Submit it in any form: the local part is
            lower-cased and an internationalized domain is converted to its
            Punycode (ASCII) form per UTS #46, so `User@Müller.de` is stored and
            returned as `user@xn--mller-kva.de`.

            An address another customer in this storefront and testmode already
            holds is not an error — that customer is returned with `200`.
          example: customer@example.com
        name:
          type:
            - string
            - 'null'
          maxLength: 255
          description: Customer's display / account-holder name.
          example: John Doe
        metadata:
          $ref: '#/components/schemas/Metadata'
    OneOffProduct:
      type: object
      description: |
        A one-off product represents a single-purchase item.
        Products are configured in the Vatly dashboard and can be added to checkouts.
      required:
        - id
        - resource
        - testmode
        - name
        - description
        - basePrice
        - taxBehavior
        - productType
        - status
        - archivedAt
        - createdAt
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the product (always starts with `one_off_product_`)
          pattern: ^one_off_product_
          example: one_off_product_Vr8kQdFhSrG4Y3DnfsdqH
        resource:
          type: string
          description: Resource type identifier
          const: one_off_product
          example: one_off_product
        testmode:
          type: boolean
          description: Whether this product is in test mode
          example: false
        name:
          type: string
          description: Display name of the product
          example: Premium License
        description:
          type: string
          description: Detailed description of the product
          example: Lifetime access to all premium features
        basePrice:
          $ref: '#/components/schemas/Money'
          description: |
            Default price of the product (can be overridden in checkout).
            Interpretation depends on `taxBehavior`:
            - `exclusive` → `basePrice` is the net amount; tax is added at checkout.
            - `inclusive` → `basePrice` already includes tax; net is back-computed from the buyer's jurisdiction.
        taxBehavior:
          type: string
          description: |
            Whether `basePrice` is tax-exclusive (B2B convention; tax added on top at checkout)
            or tax-inclusive (B2C convention; price already includes tax).
            Immutable after product creation. A checkout may not mix products with different
            `taxBehavior` values; doing so returns `422 Unprocessable Entity`.
          enum:
            - exclusive
            - inclusive
          example: exclusive
        productType:
          type: string
          description: |
            What kind of product this is:
            - `saas` — software supplied as a service (hosted, licensed or otherwise
              delivered online)
            - `ebook` — an electronic publication supplied as a download or stream

            Set when the product is created. Subscription plans accept `saas` only;
            an e-book is a one-time purchase, so sell it as a one-off product.
          enum:
            - saas
            - ebook
          example: saas
        status:
          type: string
          description: |
            Current status of the product:
            - `active` - Product is active and can be purchased
            - `pending` - Product is awaiting approval
            - `rejected` - Product has been rejected
          enum:
            - active
            - pending
            - rejected
          example: active
        archivedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            When this product was archived (ISO 8601), or `null` while it is on
            sale. Always present. An archived product is hidden from
            `GET /v1/one-off-products` and refused by `POST /v1/checkouts`; restore
            it with `DELETE /v1/one-off-products/{oneOffProductId}/archive`.
          example: null
        pendingUpdates:
          type:
            - object
            - 'null'
          description: |
            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.
          additionalProperties: false
          properties:
            name:
              type: string
              example: Premium License v2
            description:
              type: string
              example: Now with more premium
            basePrice:
              $ref: '#/components/schemas/Money'
            productType:
              type: string
              enum:
                - saas
                - ebook
          example:
            basePrice:
              currency: EUR
              value: '349.00'
        updateStatus:
          type:
            - string
            - 'null'
          description: |
            Lifecycle of a pending update, or `null` when there is none:
            - `pending` - An update was submitted and is awaiting review
            - `reviewing` - The update is being reviewed
          enum:
            - pending
            - reviewing
            - null
          example: null
        createdAt:
          type: string
          format: date-time
          description: When this product was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
          additionalProperties: false
          properties:
            self:
              $ref: '#/components/schemas/Link'
              description: Link to this product resource
    CreateOneOffProductRequest:
      type: object
      description: Request body for creating a one-off product.
      required:
        - name
        - description
        - basePrice
        - productType
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 255
          description: Display name of the product.
          example: Premium License
        description:
          type: string
          description: Detailed description of the product.
          example: Lifetime access to all premium features
        basePrice:
          $ref: '#/components/schemas/Money'
          description: Price of the product.
        productType:
          type: string
          description: |
            What kind of product this is:
            - `saas` — software supplied as a service (hosted, licensed or otherwise
              delivered online)
            - `ebook` — an electronic publication supplied as a download or stream

            Set when the product is created. Subscription plans accept `saas` only;
            an e-book is a one-time purchase, so sell it as a one-off product.
          enum:
            - saas
            - ebook
          example: saas
        taxBehavior:
          type: string
          description: |
            Whether `basePrice` is tax-exclusive (B2B convention) or tax-inclusive
            (B2C convention). Optional; defaults to `exclusive`. Immutable after
            product creation.
          enum:
            - exclusive
            - inclusive
          default: exclusive
          example: exclusive
    SubscriptionPlan:
      type: object
      description: |
        A subscription plan defines recurring billing terms.
        Plans are configured in the Vatly dashboard and can be added to checkouts.
      required:
        - id
        - resource
        - testmode
        - name
        - description
        - basePrice
        - taxBehavior
        - interval
        - intervalCount
        - productType
        - status
        - archivedAt
        - createdAt
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the plan (always starts with `subscription_plan_`)
          pattern: ^subscription_plan_
          example: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
        resource:
          type: string
          description: Resource type identifier
          const: subscription_plan
          example: subscription_plan
        testmode:
          type: boolean
          description: Whether this plan is in test mode
          example: false
        name:
          type: string
          description: Display name of the plan
          example: Pro Monthly
        description:
          type: string
          description: Detailed description of the plan
          example: Full access to all Pro features, billed monthly
        basePrice:
          $ref: '#/components/schemas/Money'
          description: |
            Price per billing interval.
            Interpretation depends on `taxBehavior`:
            - `exclusive` → `basePrice` is the net amount; tax is added at checkout.
            - `inclusive` → `basePrice` already includes tax; net is back-computed from the buyer's jurisdiction.
        taxBehavior:
          type: string
          description: |
            Whether `basePrice` is tax-exclusive (B2B convention) or tax-inclusive (B2C convention).
            Immutable after plan creation — create a new plan for the other mode. A checkout may not
            mix products with different `taxBehavior` values; doing so returns
            `422 Unprocessable Entity`.
          enum:
            - exclusive
            - inclusive
          example: exclusive
        interval:
          type: string
          description: |
            Billing interval unit:
            - `day` - Daily billing
            - `week` - Weekly billing
            - `month` - Monthly billing
            - `year` - Yearly billing
          enum:
            - day
            - week
            - month
            - year
          example: month
        intervalCount:
          type: integer
          description: |
            Number of interval units between billing cycles.
            For example, `interval: month` with `intervalCount: 3` bills every 3 months.
          minimum: 1
          example: 1
        productType:
          type: string
          description: |
            What kind of product this plan sells. Only `saas` is available on a
            subscription plan — an e-book is a one-time purchase, so sell it as a
            one-off product instead.

            Set when the plan is created.
          enum:
            - saas
          example: saas
        status:
          type: string
          description: |
            Current status of the plan:
            - `active` - Plan is active and can be subscribed to
            - `pending` - Plan is awaiting approval
            - `rejected` - Plan has been rejected
          enum:
            - active
            - pending
            - rejected
          example: active
        archivedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            When this plan was archived (ISO 8601), or `null` while it is open to
            new business. Always present. An archived plan is hidden from
            `GET /v1/subscription-plans`, refused by `POST /v1/checkouts`, and
            cannot be switched to from `PATCH /v1/subscriptions/{subscriptionId}`.
            Subscribers already on the plan keep billing unchanged. Restore it with
            `DELETE /v1/subscription-plans/{subscriptionPlanId}/archive`.
          example: null
        pendingUpdates:
          type:
            - object
            - 'null'
          description: |
            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.
          additionalProperties: false
          properties:
            name:
              type: string
              example: Pro Weekly
            description:
              type: string
              example: Billed weekly
            basePrice:
              $ref: '#/components/schemas/Money'
            interval:
              type: string
              enum:
                - day
                - week
                - month
                - year
            intervalCount:
              type: integer
              minimum: 1
            productType:
              type: string
              enum:
                - saas
          example:
            interval: week
            intervalCount: 1
        updateStatus:
          type:
            - string
            - 'null'
          description: |
            Lifecycle of a pending update, or `null` when there is none:
            - `pending` - An update was submitted and is awaiting review
            - `reviewing` - The update is being reviewed
          enum:
            - pending
            - reviewing
            - null
          example: null
        createdAt:
          type: string
          format: date-time
          description: When this plan was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
          additionalProperties: false
          properties:
            self:
              $ref: '#/components/schemas/Link'
              description: Link to this plan resource
    CreateSubscriptionPlanRequest:
      type: object
      description: Request body for creating a subscription plan.
      required:
        - name
        - description
        - basePrice
        - productType
        - interval
        - intervalCount
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 255
          description: Display name of the plan.
          example: Pro Monthly
        description:
          type: string
          description: Detailed description of the plan.
          example: Full access to all Pro features, billed monthly
        basePrice:
          $ref: '#/components/schemas/Money'
          description: Price per billing interval.
        productType:
          type: string
          description: |
            What kind of product this plan sells. Only `saas` is available on a
            subscription plan — an e-book is a one-time purchase, so sell it as a
            one-off product instead.

            Set when the plan is created.
          enum:
            - saas
          example: saas
        taxBehavior:
          type: string
          description: |
            Whether `basePrice` is tax-exclusive (B2B convention) or tax-inclusive
            (B2C convention). Optional; defaults to `exclusive`. Immutable after
            plan creation — create a new plan for the other mode.
          enum:
            - exclusive
            - inclusive
          default: exclusive
          example: exclusive
        interval:
          type: string
          description: |
            Billing interval unit. `day` is sandbox-only (test mode); live plans
            support `week`, `month`, and `year`.
          enum:
            - day
            - week
            - month
            - year
          example: month
        intervalCount:
          type: integer
          minimum: 1
          description: |
            Number of interval units between billing cycles. Bounded per unit:
            up to 365 days, 52 weeks, or 12 months. For `year`, billing is always
            annual and this value is ignored.
          example: 1
    Order:
      type: object
      description: |
        An order represents a completed purchase.
        Orders are created when checkouts complete or subscriptions renew.
      required:
        - id
        - resource
        - customerId
        - testmode
        - metadata
        - createdAt
        - status
        - total
        - subtotal
        - reversedSubtotal
        - refundableSubtotal
        - taxSummary
        - lines
        - customerDetails
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the order
          example: order_Hn5xWqVfKm8RjTgYbUcP
        resource:
          type: string
          description: Resource type identifier
          const: order
          example: order
        customerId:
          type:
            - string
            - 'null'
          description: ID of the customer who made this purchase. Always present; `null` for orders with no associated customer.
          example: customer_Lp3mNvBxKw7RjTgYcZaE
        testmode:
          type: boolean
          description: Whether this order is in test mode
          example: false
        metadata:
          $ref: '#/components/schemas/Metadata'
        paymentMethod:
          type:
            - string
            - 'null'
          description: |
            Payment method used for this order.
            Examples: `ideal`, `creditcard`, `bancontact`, `paypal`
          example: ideal
        createdAt:
          type: string
          format: date-time
          description: When this order was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        status:
          type: string
          description: |
            Current status of the order:
            - `created` - Order has just been created
            - `pending` - Payment is being processed
            - `paid` - Payment successful
            - `canceled` - Order has been canceled
            - `expired` - Order has expired
          enum:
            - created
            - pending
            - paid
            - canceled
            - expired
          example: paid
        invoiceNumber:
          type:
            - string
            - 'null'
          description: Invoice number for this order (assigned after payment)
          example: INV-2024-0001
        total:
          $ref: '#/components/schemas/Money'
          description: Total amount including taxes
        subtotal:
          $ref: '#/components/schemas/Money'
          description: Subtotal amount before taxes
        reversedSubtotal:
          $ref: '#/components/schemas/Money'
          description: Amount of the captured payment returned to the customer, before taxes, via refund or chargeback (settled)
        refundableSubtotal:
          $ref: '#/components/schemas/Money'
          description: Remaining amount that can still be refunded, before taxes.
        taxSummary:
          type: array
          description: Tax breakdown by rate
          items:
            $ref: '#/components/schemas/TaxSummaryItem'
        lines:
          type: array
          description: Line items in this order
          items:
            $ref: '#/components/schemas/OrderLine'
        customerDetails:
          $ref: '#/components/schemas/BillingDetails'
          description: Customer billing details (buyer)
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
            - customer
            - customerInvoice
          additionalProperties: false
          properties:
            self:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to this order resource
            customer:
              oneOf:
                - $ref: '#/components/schemas/Link'
                - type: 'null'
              description: Link to the customer who made this purchase. Null for orders with no associated customer.
            customerInvoice:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to the customer-facing invoice page in the customer portal (text/html)
    OrderLine:
      type: object
      description: A line item in an order
      required:
        - id
        - resource
        - description
        - quantity
        - basePrice
        - total
        - subtotal
        - taxes
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for this line item
          example: order_item_Jk4pQrSvWm8NjLhYbUcP
        resource:
          type: string
          description: Resource type identifier
          const: orderline
          example: orderline
        description:
          type: string
          description: Description of the item
          example: Pro Monthly Subscription
        quantity:
          type: integer
          description: Number of units
          minimum: 1
          example: 1
        basePrice:
          $ref: '#/components/schemas/Money'
          description: Price per unit before taxes
        total:
          $ref: '#/components/schemas/Money'
          description: Total price including taxes (basePrice * quantity + taxes)
        subtotal:
          $ref: '#/components/schemas/Money'
          description: Subtotal before taxes (basePrice * quantity)
        taxes:
          type: array
          description: Tax breakdown by rate for this line
          items:
            $ref: '#/components/schemas/TaxSummaryItem'
        productType:
          type:
            - string
            - 'null'
          enum:
            - one_off_product
            - subscription_plan
            - subscription
            - billing_details_verification
            - auth_request_product
            - null
          description: The product type this line links to; null when the line has no product link.
          example: subscription
        productId:
          type:
            - string
            - 'null'
          description: The linked product's id; for a `subscription` line this is the public `subscription_…` id.
          example: subscription_Hn5xWqVfKm8RjTgYbUcP
    InvoiceUpdateLink:
      type: object
      description: A signed URL for the customer to update invoice details (billing address, VAT number, company name)
      required:
        - href
        - type
      additionalProperties: false
      properties:
        href:
          type: string
          format: uri
          description: |
            Signed URL to the address update page.
            Valid for a limited time (typically 24 hours).
          example: https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP/edit?signature=abc123...
        type:
          type: string
          description: Content type of the linked page
          const: text/html
          example: text/html
    Refund:
      type: object
      description: |
        A refund represents a partial or full reversal of an order payment.
        Refunds are processed through the original payment provider.
      required:
        - id
        - resource
        - orderId
        - customerId
        - testmode
        - createdAt
        - status
        - originalOrderId
        - total
        - subtotal
        - taxSummary
        - lines
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the refund
          example: refund_Xk9pQrSvWm4NjLhYbUcP
        resource:
          type: string
          description: Resource type identifier
          const: refund
          example: refund
        orderId:
          type:
            - string
            - 'null'
          description: |
            ID of the credit note order created for this refund. Always present in
            the payload; `null` until the refund is processed, then set to the
            credit-note order id.
          example: order_Vr8kQdFhSrG4Y3DnfsdqH
        customerId:
          type: string
          description: ID of the customer receiving the refund
          example: customer_Lp3mNvBxKw7RjTgYcZaE
        testmode:
          type: boolean
          description: Whether this refund is in test mode
          example: false
        createdAt:
          type: string
          format: date-time
          description: When this refund was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        status:
          type: string
          description: |
            Current status of the refund:
            - `pending` - Refund is ready to be sent to the bank
            - `queued` - Refund is queued due to a lack of balance
            - `processing` - Refund is being processed (cancellation no longer possible)
            - `refunded` - Refund has been processed successfully
            - `failed` - Refund has failed after processing
            - `canceled` - Refund was canceled
          enum:
            - pending
            - queued
            - processing
            - refunded
            - failed
            - canceled
          example: refunded
        originalOrderId:
          type: string
          description: ID of the original order being refunded
          example: order_Fp2kQrSvWm8NjLhYbUcP
        total:
          $ref: '#/components/schemas/Money'
          description: Total refund amount including taxes
        subtotal:
          $ref: '#/components/schemas/Money'
          description: Refund subtotal before taxes
        taxSummary:
          type: array
          description: Tax breakdown by rate being refunded
          items:
            $ref: '#/components/schemas/TaxSummaryItem'
        lines:
          type: array
          description: Refund line items
          items:
            $ref: '#/components/schemas/RefundLine'
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
            - originalOrder
            - order
          additionalProperties: false
          properties:
            self:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to this refund resource
            originalOrder:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to the original order
            order:
              oneOf:
                - $ref: '#/components/schemas/Link'
                - type: 'null'
              description: Link to the credit note order. Always present; `null` until the credit-note order is created.
    RefundLine:
      type: object
      description: A line item in a refund
      required:
        - id
        - resource
        - description
        - quantity
        - basePrice
        - total
        - subtotal
        - taxes
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for this refund line
          example: refund_item_Tk7mNvBxKw2RjTgYcZaE
        resource:
          type: string
          description: Resource type identifier
          const: refundline
          example: refundline
        description:
          type: string
          description: Description of the refunded item
          example: Pro Monthly Subscription (Refund)
        quantity:
          type: integer
          description: Number of units being refunded
          minimum: 1
          example: 1
        basePrice:
          $ref: '#/components/schemas/Money'
          description: Refund amount per unit before taxes
        total:
          $ref: '#/components/schemas/Money'
          description: Total refund amount including taxes
        subtotal:
          $ref: '#/components/schemas/Money'
          description: Refund subtotal before taxes
        taxes:
          type: array
          description: Tax breakdown by rate being refunded
          items:
            $ref: '#/components/schemas/TaxSummaryItem'
    CreateRefundRequest:
      type: object
      description: Request body for creating a partial refund
      required:
        - items
      additionalProperties: false
      properties:
        items:
          type: array
          description: Items to refund
          minItems: 1
          items:
            $ref: '#/components/schemas/RefundItem'
          example:
            - itemId: order_item_Jk4pQrSvWm8NjLhYbUcP
              amount:
                value: '15.00'
                currency: EUR
              description: Partial refund
        metadata:
          $ref: '#/components/schemas/Metadata'
    CreateFullRefundRequest:
      type: object
      description: Request body for creating a full refund
      additionalProperties: false
      properties:
        metadata:
          $ref: '#/components/schemas/Metadata'
    Chargeback:
      type: object
      description: |
        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.
      required:
        - id
        - resource
        - customerId
        - testmode
        - createdAt
        - status
        - amount
        - settlementAmount
        - total
        - subtotal
        - taxSummary
        - reason
        - originalOrderId
        - orderId
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the chargeback
          example: chargeback_Mn6xBtPvKw2RjTgYcZaE
        resource:
          type: string
          description: Resource type identifier
          const: chargeback
          example: chargeback
        customerId:
          type: string
          description: ID of the customer the chargeback was raised against
          example: customer_Lp3mNvBxKw7RjTgYcZaE
        testmode:
          type: boolean
          description: Whether this chargeback is in test mode
          example: false
        createdAt:
          type: string
          format: date-time
          description: When this chargeback was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        status:
          type: string
          description: |
            Current status of the chargeback dispute:
            - `pending` - Dispute received, awaiting action
            - `accepted` - Merchant accepted the dispute
            - `rejected` - Dispute rejected
            - `evidence_submitted` - Evidence submitted, awaiting decision
            - `won` - Dispute resolved in the merchant's favor
            - `lost` - Dispute resolved in the customer's favor
          enum:
            - pending
            - accepted
            - rejected
            - evidence_submitted
            - won
            - lost
          example: pending
        amount:
          $ref: '#/components/schemas/Money'
          description: Amount of the chargeback
        settlementAmount:
          $ref: '#/components/schemas/Money'
          description: |
            Amount that was deducted from the merchant's settlement.
            May differ from `amount` due to currency conversion or fees.
        total:
          $ref: '#/components/schemas/Money'
          description: Total chargeback amount including taxes
        subtotal:
          $ref: '#/components/schemas/Money'
          description: Chargeback subtotal before taxes
        taxSummary:
          type: array
          description: Tax breakdown by rate for the chargeback
          items:
            $ref: '#/components/schemas/TaxSummaryItem'
        reason:
          type: string
          description: |
            Reason code or description for the chargeback.
            Common reasons include:
            - `fraud` - Unauthorized transaction
            - `product_not_received` - Customer claims non-delivery
            - `product_unacceptable` - Customer claims product was defective
            - `duplicate` - Customer claims duplicate charge
            - `subscription_canceled` - Customer claims subscription was canceled
          example: fraud
        originalOrderId:
          type: string
          description: ID of the original order that was charged back
          example: order_Fp2kQrSvWm8NjLhYbUcP
        orderId:
          type:
            - string
            - 'null'
          description: |
            ID of the credit note order created for this chargeback. Always present
            in the payload; `null` until the chargeback is processed, then set to the
            credit-note order id.
          example: order_Rk5pQrSvWm8NjLhYbUcP
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
            - originalOrder
            - order
          additionalProperties: false
          properties:
            self:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to this chargeback resource
            originalOrder:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to the original order
            order:
              oneOf:
                - $ref: '#/components/schemas/Link'
                - type: 'null'
              description: Link to the credit note order. Always present; `null` until the credit-note order is created.
    WebhookEvent:
      type: object
      description: |
        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`.
      required:
        - id
        - resource
        - eventName
        - entityType
        - entityId
        - object
        - createdAt
        - testmode
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the webhook event
          example: webhook_event_Qk8pRtSvWm2NjLhYcZaE
        resource:
          type: string
          description: Resource type identifier
          const: webhook_event
          example: webhook_event
        eventName:
          type: string
          description: |
            Name of the event that triggered this webhook:
            - `order.paid` - Order payment was successful
            - `order.canceled` - Order was canceled
            - `order.chargeback_received` - Chargeback was received for an order
            - `order.chargeback_reversed` - Chargeback was reversed
            - `order.payment_failed` - A payment failed and a dunning process was initiated for the order
            - `refund.completed` - Refund was processed successfully
            - `refund.failed` - Refund processing failed
            - `refund.canceled` - Refund was canceled
            - `subscription.started` - Subscription was started
            - `subscription.canceled_immediately` - Subscription was canceled immediately
            - `subscription.canceled_for_nonpayment` - Subscription was canceled because payment recovery was exhausted
            - `subscription.canceled_with_grace_period` - Subscription was canceled with a grace period
            - `subscription.cancellation_grace_period_completed` - Subscription grace period ended
            - `subscription.resumed` - A canceled subscription was resumed during its grace period
            - `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
            - `subscription.updated` - A subscription changed immediately (plan/price/interval or quantity)
            - `subscription.update_scheduled` - A plan/price/quantity change was scheduled for the next billing cycle; the target values are in `object.scheduledUpdate`
            - `checkout.paid` - Checkout was paid successfully
            - `checkout.failed` - Checkout payment failed
            - `checkout.canceled` - Checkout was canceled
            - `checkout.expired` - Checkout session expired

            `webhook.setup` is intentionally absent: the verification handshake is not
            persisted and so never appears on this resource (see `WebhookDelivery`).

            This list is kept in sync with the webhook transformer registry by
            `php artisan openapi:audit-webhook-drift`.
          enum:
            - 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
          example: order.paid
        entityType:
          type: string
          description: Type of the resource this event relates to
          example: order
        entityId:
          type: string
          description: ID of the resource this event relates to
          example: order_Hn5xWqVfKm8RjTgYbUcP
        object:
          description: |
            The full resource payload at the time of the event, serialized identically
            to the corresponding REST resource. The concrete shape is selected by the
            payload's own `resource` field (the discriminator):
              - `order.paid`, `order.canceled`, `order.payment_failed` → Order
              - `order.chargeback_received`, `order.chargeback_reversed` → Chargeback
              - `refund.*` → Refund
              - `subscription.*` → Subscription
              - `checkout.*` → Checkout
              - `one_off_product.*` → OneOffProduct
              - `subscription_plan.*` → SubscriptionPlan

            Note `object.resource` may differ from `entityType`: chargeback events carry
            `entityType: order` (the order the chargeback belongs to) but a Chargeback object.
          oneOf:
            - $ref: '#/components/schemas/Order'
            - $ref: '#/components/schemas/Chargeback'
            - $ref: '#/components/schemas/Refund'
            - $ref: '#/components/schemas/Subscription'
            - $ref: '#/components/schemas/Checkout'
            - $ref: '#/components/schemas/OneOffProduct'
            - $ref: '#/components/schemas/SubscriptionPlan'
          discriminator:
            propertyName: resource
            mapping:
              order: '#/components/schemas/Order'
              chargeback: '#/components/schemas/Chargeback'
              refund: '#/components/schemas/Refund'
              subscription: '#/components/schemas/Subscription'
              checkout: '#/components/schemas/Checkout'
              one_off_product: '#/components/schemas/OneOffProduct'
              subscription_plan: '#/components/schemas/SubscriptionPlan'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the webhook event was created.
          example: '2026-05-21T14:32:08+00:00'
        testmode:
          type: boolean
          description: |
            Whether the event originated from a test-mode resource.
            `true` for events created with a `test_` prefixed token, `false` for live events.
          example: false
        links:
          type: object
          description: HATEOAS links to related resources. Always present on the persisted event.
          required:
            - self
          additionalProperties: false
          properties:
            self:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to this webhook event resource
    WebhookEndpoint:
      type: object
      description: |
        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.
      required:
        - id
        - resource
        - testmode
        - url
        - enabledEvents
        - createdAt
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the webhook endpoint
          example: webhook_QdEpFhdSrG4Y3DnfsdqsH
        resource:
          type: string
          description: Resource type identifier
          const: webhook_endpoint
          example: webhook_endpoint
        testmode:
          type: boolean
          description: Whether this endpoint receives test-mode events
          example: false
        url:
          type: string
          format: uri
          description: The HTTPS URL deliveries are POSTed to
          example: https://merchant.example/webhooks/vatly
        enabledEvents:
          type: array
          description: |
            The endpoint's persisted subscription names. Current names in this list
            are delivered; a retired public name can remain visible for stable
            readback but is inert. New event names are not added automatically;
            update this list to opt in. An empty list means no domain events are
            delivered, although `webhook.setup` is still sent whenever Vatly
            verifies the endpoint configuration.
          uniqueItems: true
          items:
            type: string
            description: A current subscribable name or a retired public name retained on this endpoint.
          example:
            - order.paid
            - refund.completed
        createdAt:
          type: string
          format: date-time
          description: When this endpoint was created (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
          additionalProperties: false
          properties:
            self:
              $ref: '#/components/schemas/Link'
              description: Link to this webhook endpoint resource
    CreateWebhookEndpointRequest:
      type: object
      description: Request body for registering a new webhook endpoint
      required:
        - url
        - secret
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          description: |
            The HTTPS URL deliveries are POSTed to. Must be publicly reachable and
            present a valid SSL certificate — Vatly sends a `webhook.setup`
            verification ping on registration and rejects the request if it fails.
            `localhost` and loopback addresses are not allowed.
          example: https://merchant.example/webhooks/vatly
        secret:
          type: string
          minLength: 10
          description: |
            Signing secret for this endpoint, used to compute the `Vatly-Signature`
            HMAC on every delivery. You choose it (e.g. pinned from an environment
            variable) and use it to verify inbound webhooks. It is write-only — keep
            this value, as the API never returns it.
          example: whsec_3f9a1c7e2d4f7b9c5a2c1d5b7e9f3a8d
        enabledEvents:
          type: array
          description: |
            The explicit events delivered to this endpoint. If omitted, Vatly
            stores all event names available at registration time. New event names
            added later are not enabled automatically. Send an empty list to create
            a dormant endpoint. `webhook.setup` cannot be selected and remains an
            unconditional configuration-verification event.
          uniqueItems: true
          items:
            $ref: '#/components/schemas/WebhookSubscriptionEventName'
          example:
            - order.paid
            - refund.completed
    UpdateWebhookEndpointRequest:
      type: object
      description: |
        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.
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          description: |
            New HTTPS delivery URL. Revalidated for reachability and SSL the same
            way as on creation.
          example: https://merchant.example/webhooks/vatly-v2
        secret:
          type: string
          minLength: 10
          description: |
            New signing secret for this endpoint. Write-only — keep the value, as
            the API never returns it.
          example: whsec_a1b2c3d4e5f60718293a4b5c6d7e8f90
        enabledEvents:
          type: array
          description: |
            Replaces the endpoint's complete event subscription set. Omit this
            field to preserve the current subscriptions; send an empty list to make
            the endpoint dormant. New event names are never added automatically.
            `webhook.setup` is not subscribable.
          uniqueItems: true
          items:
            $ref: '#/components/schemas/WebhookSubscriptionEventName'
          example:
            - checkout.paid
            - order.paid
    WebhookSubscriptionEventName:
      type: string
      description: |
        A public event name that can be enabled for a webhook endpoint. The
        `webhook.setup` verification event is deliberately excluded: Vatly sends
        that event whenever it verifies endpoint configuration, regardless of the
        endpoint's subscriptions.
      enum:
        - 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
      example: order.paid
    Subscription:
      type: object
      description: |
        A subscription represents a recurring billing relationship with a customer.
        Subscriptions automatically renew according to their billing interval.
      required:
        - id
        - resource
        - customerId
        - subscriptionPlanId
        - testmode
        - name
        - description
        - billingAddress
        - basePrice
        - quantity
        - interval
        - intervalCount
        - status
        - cancellationReason
        - mandate
        - startedAt
        - endedAt
        - canceledAt
        - renewedAt
        - renewedUntil
        - nextRenewalAt
        - trialUntil
        - scheduledUpdate
        - links
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the subscription
          example: subscription_Lp3mNvBxKw7RjTgYcZaE
        resource:
          type: string
          description: Resource type identifier
          const: subscription
          example: subscription
        customerId:
          type: string
          description: ID of the customer who owns this subscription
          example: customer_Lp3mNvBxKw7RjTgYcZaE
        subscriptionPlanId:
          type: string
          description: ID of the subscription plan this subscription is based on
          example: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
        testmode:
          type: boolean
          description: Whether this subscription is in test mode
          example: false
        name:
          type: string
          description: Name of the subscription (from the plan)
          example: Pro Monthly
        description:
          type: string
          description: Description of the subscription
          example: Full access to all Pro features
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
          description: Customer's billing address for this subscription
        basePrice:
          $ref: '#/components/schemas/Money'
          description: Price per billing cycle before taxes
        quantity:
          type: integer
          description: Number of subscription units (e.g., seats)
          minimum: 1
          example: 1
        interval:
          type: string
          description: Billing interval unit
          enum:
            - day
            - week
            - month
            - year
          example: month
        intervalCount:
          type: integer
          description: Number of interval units between billing cycles
          minimum: 1
          example: 1
        status:
          type: string
          description: |
            Current status of the subscription:
            - `active` - Subscription is active and will renew
            - `created` - Subscription has been created but not yet started
            - `trial` - Subscription is in trial period
            - `on_grace_period` - Subscription is canceled but still active until period ends
            - `paused` - Subscription is temporarily paused
            - `canceled` - Subscription has been canceled
          enum:
            - active
            - created
            - trial
            - on_grace_period
            - paused
            - canceled
          example: active
        cancellationReason:
          type:
            - string
            - 'null'
          description: |
            Why the subscription was canceled. Null unless a cancellation has been
            requested. Public values are intentionally decoupled from internal domain
            reason names:
            - `payment_failure` - Payment recovery was exhausted after failed renewals
            - `merchant_request` - The merchant explicitly canceled the subscription
            - `customer_request` - The customer canceled from the self-service portal
          enum:
            - payment_failure
            - merchant_request
            - customer_request
            - null
          example: null
        mandate:
          oneOf:
            - $ref: '#/components/schemas/Mandate'
            - type: 'null'
          description: |
            Payment method on file for this subscription, as an inline summary
            intended for billing-portal rendering ("Visa ending in 4242"). May
            be `null` when the subscription has no mandate yet (e.g. ended /
            canceled-before-payment states).
        startedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the subscription started (ISO 8601 format)
          example: '2024-01-15T10:30:00Z'
        endedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the subscription ended (ISO 8601 format)
        canceledAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the subscription was canceled (ISO 8601 format)
        renewedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the subscription was last renewed (ISO 8601 format)
          example: '2024-02-15T10:30:00Z'
        renewedUntil:
          type:
            - string
            - 'null'
          format: date-time
          description: Current billing period end date (ISO 8601 format)
          example: '2024-03-15T10:30:00Z'
        nextRenewalAt:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            When the next renewal will be attempted (ISO 8601 format).
            Null if subscription is canceled or ended.
          example: '2024-03-15T10:30:00Z'
        trialUntil:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            When the trial period ends (ISO 8601 format).
            Null if not in trial or trial has ended.
        links:
          type: object
          description: HATEOAS links to related resources
          required:
            - self
            - customer
          additionalProperties: false
          properties:
            self:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to this subscription resource
            customer:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to the customer who owns this subscription
        scheduledUpdate:
          type:
            - object
            - 'null'
          description: |
            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.
          required:
            - subscriptionPlanId
            - name
            - description
            - basePrice
            - quantity
            - interval
            - intervalCount
            - effectiveAt
          additionalProperties: false
          properties:
            subscriptionPlanId:
              type: string
              description: ID of the plan the subscription will switch to
              example: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
            name:
              type: string
              description: Name of the scheduled plan
              example: Pro Annual
            description:
              type: string
              description: Description of the scheduled plan
            basePrice:
              $ref: '#/components/schemas/Money'
              description: Scheduled price per billing cycle before taxes
            quantity:
              type: integer
              minimum: 1
              description: Scheduled quantity
              example: 1
            interval:
              type: string
              description: Scheduled billing interval unit
              enum:
                - day
                - week
                - month
                - year
              example: month
            intervalCount:
              type: integer
              minimum: 1
              description: Scheduled number of interval units between billing cycles
              example: 1
            effectiveAt:
              type:
                - string
                - 'null'
              format: date-time
              description: |
                When the change takes effect — the subscription's next renewal date. Null if the
                subscription has no scheduled renewal.
              example: '2024-03-15T10:30:00Z'
    UpdateSubscriptionRequest:
      type: object
      description: |
        Request body for updating a subscription.
        At least one of `subscriptionPlanId`, `quantity`, or `price` must be provided.
      additionalProperties: false
      properties:
        subscriptionPlanId:
          type: string
          description: |
            ID of the new subscription plan.
            Must match the testmode of the current subscription.
          pattern: ^subscription_plan_
          example: subscription_plan_Wt5mNvBxKw7YcZaEjLhR
        quantity:
          type: integer
          description: |
            The new total quantity (e.g. number of seats). This sets the
            quantity to the given value — it is not added to the current
            quantity. Omit it to leave the quantity unchanged.
          minimum: 1
          example: 5
        price:
          type: object
          description: |
            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.
          additionalProperties: false
          required:
            - value
            - currency
          properties:
            value:
              type: string
              description: Price amount as a decimal string, with the exact number of decimals for the currency.
              example: '99.99'
            currency:
              type: string
              description: |
                Must match the subscription's own currency (a subscription's
                currency is fixed at checkout and cannot be changed via an update).
              enum:
                - EUR
                - USD
              example: EUR
        prorate:
          type: boolean
          description: |
            Whether to prorate charges for the partial billing period.
            If true, the customer is credited for unused time on the old plan
            and charged for remaining time on the new plan.
          default: true
          example: true
        applyImmediately:
          type: boolean
          description: |
            Whether to apply changes immediately or at the end of the current billing period.
            - `true`: Changes take effect immediately (with proration if enabled)
            - `false`: Changes apply when the current period ends
          default: false
          example: true
        invoiceImmediately:
          type: boolean
          description: |
            Whether to generate and charge an invoice immediately for proration.
            Only applies when `applyImmediately` and `prorate` are both true.

            When `false` (the default) the proration delta is parked on the current
            cycle and billed as a line on the next renewal invoice — the customer
            gets one invoice and one payment covering both. If the subscription is
            cancelled before that renewal there is no next invoice and the parked
            amount is waived, so a customer is never charged at the moment they
            cancel.

            **Set this to `true` on yearly and other long-interval plans.** The
            default suits monthly billing, where the delta is collected within
            weeks. On a yearly plan an upgrade in month 2 is not billed until
            month 12, and is waived entirely if the customer cancels at any point
            in between — so the longer the interval, the more the deferral costs
            you. Charging immediately trades that for a separate invoice and
            payment (and its transaction fee) per change.
          default: false
          example: false
        anchor:
          type:
            - string
            - 'null'
          format: date
          description: |
            Set the billing anchor to a specific calendar date (YYYY-MM-DD,
            interpreted in UTC). The new billing cycle is recalculated around
            this anchor. Date-only by design — the anchor identifies a day,
            not an instant, so daylight-saving transitions don't shift it.
            Cannot be combined with `resetAnchor`.
          example: '2024-02-01'
        resetAnchor:
          type: boolean
          description: |
            Reset the billing anchor to "now" — the moment the update
            is processed becomes the new cycle anchor, and future
            renewals align to it. Useful when a customer upgrades
            mid-cycle and you want the new plan's billing period to
            start fresh from today.
            Cannot be combined with `anchor`.
          default: false
          example: true
        trialUntil:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            Extend or set a trial period until this date (ISO 8601 format).
            Cannot be combined with `anchor`.
          example: '2024-02-15T00:00:00Z'
    UpdateSubscriptionBillingRequest:
      type: object
      description: Request body for updating subscription billing details via hosted flow
      required:
        - redirectUrlSuccess
        - redirectUrlCanceled
      additionalProperties: false
      properties:
        redirectUrlSuccess:
          type: string
          format: uri
          description: URL to redirect after successful billing update
          example: https://example.com/billing-updated
        redirectUrlCanceled:
          type: string
          format: uri
          description: URL to redirect if customer cancels the update
          example: https://example.com/billing-canceled
        billingAddress:
          oneOf:
            - $ref: '#/components/schemas/BillingAddress'
            - type: 'null'
          description: |
            Pre-fill billing address fields.
            Customer can modify these values in the hosted form.
    Mandate:
      type: object
      description: |
        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.
      required:
        - method
        - maskedIdentifier
      additionalProperties: false
      properties:
        method:
          type: string
          description: |
            Normalized payment method category, provider-agnostic:
            - `card` — credit/debit card (incl. Apple Pay, Google Pay wallets)
            - `sepa_debit` — SEPA Direct Debit (incl. iDEAL, Bancontact, KBC and
              other rail aliases that settle into a directdebit mandate)
            - `paypal` — PayPal billing agreement
            - `bacs_debit` — UK Bacs Direct Debit
          enum:
            - card
            - sepa_debit
            - paypal
            - bacs_debit
          example: card
        maskedIdentifier:
          type:
            - string
            - 'null'
          description: |
            Customer-facing masked identifier for the payment method on file:
            the last 4 of a card (`"4242"`), a masked IBAN (`"NL91****4300"`),
            a masked PayPal email (`"j***@example.com"`), or last 4 of a Bacs
            account (`"****5678"`).

            May briefly be `null` for freshly-subscribed customers when the
            underlying authorization event doesn't carry the masked identifier
            inline — in that case it lands on a follow-up sync (runs at most
            every 5 minutes) and the field updates from `null` to the resolved
            value once the sync completes.
          example: '4242'
    UpdateCustomerRequest:
      type: object
      description: |
        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.
      additionalProperties: false
      properties:
        name:
          type:
            - string
            - 'null'
          maxLength: 255
          description: Customer's display / account-holder name.
          example: John Doe
        email:
          type: string
          format: email
          description: |
            Customer's email address, canonicalized on the way in exactly as on
            create (lower-cased local part, Punycode domain per UTS #46).

            Unlike create, a collision is rejected here: moving this customer onto
            an address another customer in the same storefront and testmode holds
            returns `422`. Creating with a known address is a recovery; moving one
            customer onto another's address is a conflict.
          example: new.email@example.com
    CreatePortalSessionRequest:
      type: object
      description: Options for a short-lived hosted customer portal session.
      additionalProperties: false
      properties:
        returnUrl:
          type:
            - string
            - 'null'
          format: uri
          pattern: ^[Hh][Tt][Tt][Pp][Ss]://
          maxLength: 2048
          description: |
            Absolute HTTPS URL without embedded credentials, rendered as a return
            link in the hosted portal. The runtime limit is 2,048 UTF-8 bytes.
            Vatly never fetches or automatically redirects to this URL.
          example: https://merchant.example/account/billing
    PortalSession:
      type: object
      description: A short-lived, single-use entry link to the hosted customer portal.
      required:
        - url
        - expiresAt
        - returnUrl
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          description: Single-use HTTPS URL to redirect the customer to.
          example: https://billing.vatly.com/authenticate?credential=...
        expiresAt:
          type: string
          format: date-time
          description: Expiry of the one-time entry link, not of the resulting browser session.
          example: '2026-09-01T12:15:00Z'
        returnUrl:
          type:
            - string
            - 'null'
          format: uri
          pattern: ^[Hh][Tt][Tt][Pp][Ss]://
          maxLength: 2048
          description: |
            The validated absolute HTTPS return URL supplied in the request, or
            null. It contains no embedded credentials and is limited to 2,048
            UTF-8 bytes.
          example: https://merchant.example/account/billing
    UpdateOneOffProductRequest:
      type: object
      description: |
        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).
      minProperties: 1
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 255
          description: New display name of the product.
          example: Premium License v2
        description:
          type: string
          description: New description of the product.
          example: Now with more premium
        basePrice:
          $ref: '#/components/schemas/Money'
          description: New price of the product.
        productType:
          type: string
          description: |
            What kind of product this is:
            - `saas` — software supplied as a service (hosted, licensed or otherwise
              delivered online)
            - `ebook` — an electronic publication supplied as a download or stream

            Set when the product is created. Subscription plans accept `saas` only;
            an e-book is a one-time purchase, so sell it as a one-off product.
          enum:
            - saas
            - ebook
          example: saas
    UpdateSubscriptionPlanRequest:
      type: object
      description: |
        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.
      minProperties: 1
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 255
          description: New display name of the plan.
          example: Pro Weekly
        description:
          type: string
          description: New description of the plan.
          example: Billed weekly
        basePrice:
          $ref: '#/components/schemas/Money'
          description: New price per billing interval.
        productType:
          type: string
          enum:
            - saas
          example: saas
        interval:
          type: string
          enum:
            - day
            - week
            - month
            - year
          example: week
        intervalCount:
          type: integer
          minimum: 1
          description: Required when `interval` is provided.
          example: 1
    TaxSummaryRate:
      type: object
      description: Simplified tax rate information
      required:
        - name
        - percentage
        - taxablePercentage
      properties:
        name:
          type: string
          description: Human-readable name of the tax rate
          example: VAT
        percentage:
          type: number
          description: Tax rate percentage
          example: 21
        taxablePercentage:
          type: number
          description: Percentage of the amount that is taxable
          example: 100
    TaxSummaryItem:
      type: object
      description: A single tax rate entry with its calculated amount
      required:
        - taxRate
        - amount
      properties:
        taxRate:
          $ref: '#/components/schemas/TaxSummaryRate'
        amount:
          $ref: '#/components/schemas/Money'
          description: Tax amount for this rate
    RefundItem:
      type: object
      description: An item to refund from an order
      required:
        - itemId
        - amount
      additionalProperties: false
      properties:
        itemId:
          type: string
          description: ID of the order line item to refund
          example: order_item_Jk4pQrSvWm8NjLhYbUcP
        amount:
          $ref: '#/components/schemas/Money'
          description: |
            Amount to refund for this item (before taxes).
            Cannot exceed the remaining refundable amount for the item.
        description:
          type:
            - string
            - 'null'
          description: Custom description for this refund line
          example: Partial refund for service issue
        descriptionAdditionalLine:
          type:
            - string
            - 'null'
          description: Additional description line for the refund
          example: 'Ticket #12345'
    FastForwardSubscriptionRenewalRequest:
      type: object
      properties:
        paymentStatus:
          type: string
          enum:
            - paid
            - failed
          description: |
            Outcome to force on the renewal payment.

            Omit it to advance the billing cycle and leave the renewal payment
            pending, which is this endpoint's original behaviour.

            `failed` declines the payment and starts a payment recovery for the
            renewal order, so `order.payment_failed` is delivered to your webhook
            endpoint. `paid` settles it.
          example: failed
        failureReason:
          type: string
          enum:
            - 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
          description: |
            Which decline to simulate. Only valid alongside `paymentStatus: failed`;
            sending it with `paid` is rejected.

            The reason decides how the payment recovery proceeds. A soft decline
            (`insufficient_funds`, `temporary_decline`, `general_failure`) means the
            payment method is still good, so recovery retries on a multi-week
            timeline. Every other value is a hard decline: the payment method is
            dead, retrying is pointless, and recovery instead drives the customer to
            supply a new one on a short timeline.

            Defaults to `general_failure`, which is soft.
          default: general_failure
          example: card_expired
    Webhook:
      type: object
      description: |
        A registered webhook endpoint configuration — the subject of a `webhook.setup`
        verification call. Never includes the signing secret.
      required:
        - resource
        - id
        - url
        - testmode
      additionalProperties: false
      properties:
        resource:
          type: string
          const: webhook
          example: webhook
        id:
          type: string
          description: The webhook endpoint identifier.
          example: webhook_QdEpFhdSrG4Y3DnfsdqsH
        url:
          type: string
          format: uri
          description: The endpoint the verification call was sent to.
          example: https://merchant.example/webhooks/vatly
        testmode:
          type: boolean
          example: true
    WebhookDelivery:
      type: object
      description: |
        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).
      required:
        - id
        - resource
        - eventName
        - entityType
        - entityId
        - object
        - createdAt
        - testmode
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the webhook event
          example: webhook_event_Qk8pRtSvWm2NjLhYcZaE
        resource:
          type: string
          description: Resource type identifier
          const: webhook_event
          example: webhook_event
        eventName:
          type: string
          description: |
            Name of the event that triggered this webhook:
            - `order.paid` - Order payment was successful
            - `order.canceled` - Order was canceled
            - `order.chargeback_received` - Chargeback was received for an order
            - `order.chargeback_reversed` - Chargeback was reversed
            - `order.payment_failed` - A payment failed and a dunning process was initiated for the order
            - `refund.completed` - Refund was processed successfully
            - `refund.failed` - Refund processing failed
            - `refund.canceled` - Refund was canceled
            - `subscription.started` - Subscription was started
            - `subscription.canceled_immediately` - Subscription was canceled immediately
            - `subscription.canceled_for_nonpayment` - Subscription was canceled because payment recovery was exhausted
            - `subscription.canceled_with_grace_period` - Subscription was canceled with a grace period
            - `subscription.cancellation_grace_period_completed` - Subscription grace period ended
            - `subscription.resumed` - A canceled subscription was resumed during its grace period
            - `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
            - `subscription.updated` - A subscription changed immediately (plan/price/interval or quantity)
            - `subscription.update_scheduled` - A plan/price/quantity change was scheduled for the next billing cycle; the target values are in `object.scheduledUpdate`
            - `checkout.paid` - Checkout was paid successfully
            - `checkout.failed` - Checkout payment failed
            - `checkout.canceled` - Checkout was canceled
            - `checkout.expired` - Checkout session expired
            - `webhook.setup` - Verification call sent when an endpoint is registered or its URL changes (`entityType` is `webhook`)

            This list is the single source of truth for SDK generators and is kept in
            sync with the webhook transformer registry by `php artisan openapi:audit-webhook-drift`.
          enum:
            - 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
          example: order.paid
        entityType:
          type: string
          description: Type of the resource this event relates to
          example: order
        entityId:
          type: string
          description: ID of the resource this event relates to
          example: order_Hn5xWqVfKm8RjTgYbUcP
        object:
          description: |
            The full resource payload at the time of the event, serialized identically
            to the corresponding REST resource. The concrete shape is selected by the
            payload's own `resource` field (the discriminator):
              - `order.paid`, `order.canceled`, `order.payment_failed` → Order
              - `order.chargeback_received`, `order.chargeback_reversed` → Chargeback
              - `refund.*` → Refund
              - `subscription.*` → Subscription
              - `checkout.*` → Checkout
              - `webhook.setup` → Webhook (the endpoint config; verification handshake)
              - `one_off_product.*` → OneOffProduct
              - `subscription_plan.*` → SubscriptionPlan

            Note `object.resource` may differ from `entityType`: chargeback events carry
            `entityType: order` (the order the chargeback belongs to) but a Chargeback object.
          oneOf:
            - $ref: '#/components/schemas/Order'
            - $ref: '#/components/schemas/Chargeback'
            - $ref: '#/components/schemas/Refund'
            - $ref: '#/components/schemas/Subscription'
            - $ref: '#/components/schemas/Checkout'
            - $ref: '#/components/schemas/OneOffProduct'
            - $ref: '#/components/schemas/SubscriptionPlan'
            - $ref: '#/components/schemas/Webhook'
          discriminator:
            propertyName: resource
            mapping:
              order: '#/components/schemas/Order'
              chargeback: '#/components/schemas/Chargeback'
              refund: '#/components/schemas/Refund'
              subscription: '#/components/schemas/Subscription'
              checkout: '#/components/schemas/Checkout'
              one_off_product: '#/components/schemas/OneOffProduct'
              subscription_plan: '#/components/schemas/SubscriptionPlan'
              webhook: '#/components/schemas/Webhook'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the webhook event was created.
          example: '2026-05-21T14:32:08+00:00'
        testmode:
          type: boolean
          description: |
            Whether the event originated from a test-mode resource.
            `true` for events created with a `test_` prefixed token, `false` for live events.
          example: false
        links:
          type: object
          description: |
            HATEOAS links to related resources. Present on event deliveries; omitted on
            the `webhook.setup` verification call, which is not a persisted resource.
          required:
            - self
          additionalProperties: false
          properties:
            self:
              allOf:
                - $ref: '#/components/schemas/Link'
              description: Link to this webhook event resource
  requestBodies:
    WebhookDelivery:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookDelivery'