# AUTO-GENERATED — run: pnpm api:openapi:generate
openapi: 3.1.0
info:
  title: "Clearway Documentation"
  version: 2026-06-10
  description: "Machine-facing HTTP API for Clearway merchants. Call `POST https://api-dev.clearway.to/<FUNCTION_NAME>`. Paths use function names such as `POST /CREATE_PAYMENT_LINK`. Authenticate with `Authorization: Bearer clwy_test_…` or the `x-clearway-api-key` header."
servers:
  - url: "https://api-dev.clearway.to"
    description: "Clearway merchant API"
tags:
  - name: Analytics
  - name: Checkout
  - name: Customers
  - name: Orders
  - name: "Payment links"
  - name: Payments
  - name: Products
  - name: Subscriptions
paths:
  /CANCEL_MERCHANT_SUBSCRIPTION:
    post:
      operationId: CANCEL_MERCHANT_SUBSCRIPTION
      summary: "Cancel subscriptions"
      description: "Cancel a payer subscription using your commerce cancel policy (immediate or at period end). Use the `id` field from LIST_MERCHANT_SUBSCRIPTIONS — not `stripe_subscription_id`."
      tags:
        - Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  example: 14635c65-b6ff-4b46-8eda-f5dbd8598f21
              additionalProperties: true
            example:
              id: 14635c65-b6ff-4b46-8eda-f5dbd8598f21
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: CANCEL_MERCHANT_SUBSCRIPTION
      x-clearway-scope: "cancel:subscription"
      x-clearway-money-moving: false
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /CHANGE_MERCHANT_SUBSCRIPTION_PLAN:
    post:
      operationId: CHANGE_MERCHANT_SUBSCRIPTION_PLAN
      summary: "Change subscription plans"
      description: "Apply a plan change for a payer subscription to another catalog product in the same plan family. Preview first. Use Clearway subscription `id` as `subscriptionId`. Sandbox-mode API keys return a simulated success via EXECUTE_API_SANDBOX_CALL (no live charge)."
      tags:
        - Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptionId:
                  type: string
                  example: 14635c65-b6ff-4b46-8eda-f5dbd8598f21
                targetProductId:
                  type: string
                  example: 00000000-0000-4000-8000-000000000002
              additionalProperties: true
            example:
              subscriptionId: 14635c65-b6ff-4b46-8eda-f5dbd8598f21
              targetProductId: 00000000-0000-4000-8000-000000000002
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: CHANGE_MERCHANT_SUBSCRIPTION_PLAN
      x-clearway-scope: "change:subscription_plan"
      x-clearway-money-moving: true
      x-clearway-idempotency: required
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /CREATE_CHECKOUT_SESSION:
    post:
      operationId: CREATE_CHECKOUT_SESSION
      summary: "Create checkout sessions"
      description: "Create Stripe Checkout Sessions (and Payment Intents; both surfaces reuse this scope)."
      tags:
        - Checkout
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 2500
                currency:
                  type: string
                  example: USD
                productName:
                  type: string
                  example: "30-min consultation"
                description:
                  type: string
                  example: "Strategy session"
                successUrl:
                  type: string
                  example: "https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
                cancelUrl:
                  type: string
                  example: "https://example.com/cancel"
                metadata:
                  type: object
                  example:
                    order_ref: CONS-4821
              additionalProperties: true
            example:
              amount: 2500
              currency: USD
              productName: "30-min consultation"
              description: "Strategy session"
              successUrl: "https://example.com/success?session_id={CHECKOUT_SESSION_ID}"
              cancelUrl: "https://example.com/cancel"
              metadata:
                order_ref: CONS-4821
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: CREATE_CHECKOUT_SESSION
      x-clearway-scope: "create:checkout_session"
      x-clearway-money-moving: true
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /CREATE_MERCHANT_COUPON:
    post:
      operationId: CREATE_MERCHANT_COUPON
      summary: "Write merchant coupons"
      description: "Create Stripe Connect coupons on your connected account (percent_off or amount_off). Never writes platform promo_codes."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Launch 15"
                percentOff:
                  type: number
                  example: 15
                duration:
                  type: string
                  example: once
              additionalProperties: true
            example:
              name: "Launch 15"
              percentOff: 15
              duration: once
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: CREATE_MERCHANT_COUPON
      x-clearway-scope: "write:merchant_coupons"
      x-clearway-money-moving: false
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /CREATE_PAYMENT_INTENT:
    post:
      operationId: CREATE_PAYMENT_INTENT
      summary: "Create payment intent"
      description: "Create a Payment Intent for embedded or custom checkout integrations."
      tags:
        - Checkout
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 2500
                currency:
                  type: string
                  example: USD
                productName:
                  type: string
                  example: "30-min consultation"
                description:
                  type: string
                  example: "Strategy session"
              additionalProperties: true
            example:
              amount: 2500
              currency: USD
              productName: "30-min consultation"
              description: "Strategy session"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: CREATE_PAYMENT_INTENT
      x-clearway-scope: "create:checkout_session"
      x-clearway-money-moving: true
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /CREATE_PAYMENT_LINK:
    post:
      operationId: CREATE_PAYMENT_LINK
      summary: "Create payment links"
      description: "Create reusable or one-off Clearway-hosted payment links."
      tags:
        - "Payment links"
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 4999
                currency:
                  type: string
                  example: USD
                productName:
                  type: string
                  example: "Premium annual plan"
                description:
                  type: string
                  example: "Billed yearly"
                linkUsage:
                  type: string
                  example: repeatable
                metadata:
                  type: object
                  example:
                    campaign: launch-2026
              additionalProperties: true
            example:
              amount: 4999
              currency: USD
              productName: "Premium annual plan"
              description: "Billed yearly"
              linkUsage: repeatable
              metadata:
                campaign: launch-2026
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: CREATE_PAYMENT_LINK
      x-clearway-scope: "create:payment_link"
      x-clearway-money-moving: true
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /CREATE_PRODUCT:
    post:
      operationId: CREATE_PRODUCT
      summary: "Write products"
      description: "Create, update, or delete catalog products via API key."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Pro plan"
                amount_cents:
                  type: number
                  example: 2900
                mode:
                  type: string
                  example: subscription
                recurring_interval:
                  type: string
                  example: month
              additionalProperties: true
            example:
              name: "Pro plan"
              amount_cents: 2900
              mode: subscription
              recurring_interval: month
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: CREATE_PRODUCT
      x-clearway-scope: "write:products"
      x-clearway-money-moving: false
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /DELETE_PRODUCT:
    post:
      operationId: DELETE_PRODUCT
      summary: "Delete product"
      description: "Delete a catalog product via API key (write:products)."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: string
                  example: prod_example
              additionalProperties: true
            example:
              productId: prod_example
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: DELETE_PRODUCT
      x-clearway-scope: "write:products"
      x-clearway-money-moving: false
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /GET_ANALYTICS_ENTITLEMENT:
    post:
      operationId: GET_ANALYTICS_ENTITLEMENT
      summary: "Read analytics"
      description: "Dashboard-only — returns 403 API_GATEWAY_KEY_FORBIDDEN when called with an API key on the merchant API gateway. Use the Clearway dashboard instead. Advanced analytics entitlement probe. Requires the read:analytics scope (or full_access). Session-backed today; API key path reserved."
      tags:
        - Analytics
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:

              additionalProperties: true
            example:

      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: GET_ANALYTICS_ENTITLEMENT
      x-clearway-scope: "read:analytics"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: dashboard-only
      x-zudoku-playground-enabled: false
  /GET_ORDER:
    post:
      operationId: GET_ORDER
      summary: "Get order"
      description: "Fetch a single order by Clearway order id."
      tags:
        - Orders
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: string
                  example: 00000000-0000-4000-8000-000000000001
              additionalProperties: true
            example:
              orderId: 00000000-0000-4000-8000-000000000001
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: GET_ORDER
      x-clearway-scope: "read:orders"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /GET_PRODUCT:
    post:
      operationId: GET_PRODUCT
      summary: "Get product"
      description: "Fetch a single catalog product by Clearway product id. Public GET never includes trial fields (trial_period_days / aliases) — use LIST_PRODUCTS for merchant catalog management including trials."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: string
                  example: 00000000-0000-4000-8000-000000000001
                includeImages:
                  type: boolean
                  example: true
              additionalProperties: true
            example:
              productId: 00000000-0000-4000-8000-000000000001
              includeImages: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiGetProductSuccess"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: GET_PRODUCT
      x-clearway-scope: "read:products"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /LIST_MERCHANT_COUPONS:
    post:
      operationId: LIST_MERCHANT_COUPONS
      summary: "Read merchant coupons"
      description: "List Stripe Connect coupons on your connected account. Distinct from platform promo_codes (Clearway fee packages)."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  example: 50
              additionalProperties: true
            example:
              limit: 50
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: LIST_MERCHANT_COUPONS
      x-clearway-scope: "read:merchant_coupons"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /LIST_MERCHANT_CUSTOMERS:
    post:
      operationId: LIST_MERCHANT_CUSTOMERS
      summary: "Manage customers"
      description: "Dashboard-only — returns 403 API_GATEWAY_KEY_FORBIDDEN when called with an API key on the merchant API gateway. Use the Clearway dashboard instead. List merchant customers with lifetime stats and repeat purchase data. Requires the manage:customers scope (or full_access)."
      tags:
        - Customers
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  example: 50
              additionalProperties: true
            example:
              limit: 50
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: LIST_MERCHANT_CUSTOMERS
      x-clearway-scope: "manage:customers"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: dashboard-only
      x-zudoku-playground-enabled: false
  /LIST_MERCHANT_SUBSCRIPTIONS:
    post:
      operationId: LIST_MERCHANT_SUBSCRIPTIONS
      summary: "Read subscriptions"
      description: "List payer subscriptions to your catalog products. Each row includes an `id` (Clearway UUID) — use that value in Cancel subscriptions, not `stripe_subscription_id`. Response includes `totalCount`, `offset`, `limit`, and `capped` when more rows exist than returned."
      tags:
        - Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  example: 50
                offset:
                  type: number
                  example: 0
                status:
                  type: string
                  example: active
                productId:
                  type: string
                  example: 00000000-0000-4000-8000-000000000001
                q:
                  type: string
                  example: "payer@example.com"
              additionalProperties: true
            example:
              limit: 50
              offset: 0
              status: active
              productId: 00000000-0000-4000-8000-000000000001
              q: "payer@example.com"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: LIST_MERCHANT_SUBSCRIPTIONS
      x-clearway-scope: "read:subscriptions"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /LIST_ORDERS:
    post:
      operationId: LIST_ORDERS
      summary: "Read orders"
      description: "List settled orders and fetch individual order records for revenue integrations."
      tags:
        - Orders
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  example: 25
                status:
                  type: string
                  example: paid
                lookbackDays:
                  type: number
                  example: 30
              additionalProperties: true
            example:
              limit: 25
              status: paid
              lookbackDays: 30
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: LIST_ORDERS
      x-clearway-scope: "read:orders"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /LIST_PAYMENT_LINKS:
    post:
      operationId: LIST_PAYMENT_LINKS
      summary: "List payment links"
      description: "List your payment links with Clearway share URLs (provider fields stripped)."
      tags:
        - "Payment links"
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  example: 25
              additionalProperties: true
            example:
              limit: 25
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: LIST_PAYMENT_LINKS
      x-clearway-scope: "create:payment_link"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /LIST_PRODUCTS:
    post:
      operationId: LIST_PRODUCTS
      summary: "Read products"
      description: "List or fetch merchant products and catalog data."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  example: 20
                active:
                  type: boolean
                  example: true
              additionalProperties: true
            example:
              limit: 20
              active: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: LIST_PRODUCTS
      x-clearway-scope: "read:products"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /PREVIEW_MERCHANT_SUBSCRIPTION_PLAN_CHANGE:
    post:
      operationId: PREVIEW_MERCHANT_SUBSCRIPTION_PLAN_CHANGE
      summary: "Preview subscription plan changes"
      description: "Preview proration / timing for moving a payer subscription to another catalog product in the same plan family. Use the Clearway subscription `id` from list subscriptions as `subscriptionId`."
      tags:
        - Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptionId:
                  type: string
                  example: 14635c65-b6ff-4b46-8eda-f5dbd8598f21
                targetProductId:
                  type: string
                  example: 00000000-0000-4000-8000-000000000002
              additionalProperties: true
            example:
              subscriptionId: 14635c65-b6ff-4b46-8eda-f5dbd8598f21
              targetProductId: 00000000-0000-4000-8000-000000000002
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: PREVIEW_MERCHANT_SUBSCRIPTION_PLAN_CHANGE
      x-clearway-scope: "preview:subscription_plan_change"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /PREVIEW_PLATFORM_FEE:
    post:
      operationId: PREVIEW_PLATFORM_FEE
      summary: "Preview platform fees"
      description: "Simulate Clearway platform fees and wallet impact for a hypothetical charge amount without creating payment objects."
      tags:
        - Payments
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amountCents:
                  type: number
                  example: 50000
                currency:
                  type: string
                  example: USD
              additionalProperties: true
            example:
              amountCents: 50000
              currency: USD
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: PREVIEW_PLATFORM_FEE
      x-clearway-scope: "read:pricing"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /PROCESS_MERCHANT_REFUND:
    post:
      operationId: PROCESS_MERCHANT_REFUND
      summary: "Process refunds"
      description: "Issue full or partial refunds on paid destination charges (reverse_transfer). Requires a client idempotency token per attempt."
      tags:
        - Payments
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: string
                  example: 00000000-0000-4000-8000-000000000001
                idempotencyToken:
                  type: string
                  example: 00000000-0000-4000-8000-000000000002
                refundType:
                  type: string
                  example: full
                reason:
                  type: string
                  example: requested_by_customer
              additionalProperties: true
            example:
              orderId: 00000000-0000-4000-8000-000000000001
              idempotencyToken: 00000000-0000-4000-8000-000000000002
              refundType: full
              reason: requested_by_customer
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: PROCESS_MERCHANT_REFUND
      x-clearway-scope: "process:refund"
      x-clearway-money-moving: true
      x-clearway-idempotency: required
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /RESOLVE_EMBED_DISPLAY:
    post:
      operationId: RESOLVE_EMBED_DISPLAY
      summary: "Resolve embed display"
      description: "Resolve tamper-safe catalog display payloads for Clearway Elements product cards and subscription modals."
      tags:
        - Payments
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                catalogProductId:
                  type: string
                  example: prod_example
                theme:
                  type: string
                  example: minimal
              additionalProperties: true
            example:
              catalogProductId: prod_example
              theme: minimal
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: RESOLVE_EMBED_DISPLAY
      x-clearway-scope: "create:checkout_session"
      x-clearway-money-moving: false
      x-clearway-idempotency: none
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /UPDATE_MERCHANT_COUPON:
    post:
      operationId: UPDATE_MERCHANT_COUPON
      summary: "Update merchant coupon"
      description: "Update a Stripe Connect coupon name on your connected account. Distinct from platform promo_codes."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                stripeCouponId:
                  type: string
                  example: coup_fixture_1
                name:
                  type: string
                  example: "Launch 20"
              additionalProperties: true
            example:
              stripeCouponId: coup_fixture_1
              name: "Launch 20"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: UPDATE_MERCHANT_COUPON
      x-clearway-scope: "write:merchant_coupons"
      x-clearway-money-moving: false
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
  /UPDATE_PRODUCT:
    post:
      operationId: UPDATE_PRODUCT
      summary: "Update product"
      description: "Update a catalog product via API key (write:products)."
      tags:
        - Products
      security:
        - BearerAuth: []
      parameters:
        - name: x-cid
          in: header
          required: false
          schema:
            type: string
          description: "Optional correlation id for support trails."
        - name: x-brand-id
          in: header
          required: false
          schema:
            type: string
          description: "Optional platform brand slug for multi-brand merchants."
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: "Stable key for safe retries on money-moving requests."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: string
                  example: prod_example
                name:
                  type: string
                  example: "Pro plan (updated)"
                amount_cents:
                  type: number
                  example: 3900
              additionalProperties: true
            example:
              productId: prod_example
              name: "Pro plan (updated)"
              amount_cents: 3900
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MerchantApiSuccessEnvelope"
        401:
          $ref: "#/components/responses/Unauthorized"
        403:
          $ref: "#/components/responses/Forbidden"
        429:
          $ref: "#/components/responses/RateLimited"
      x-clearway-function: UPDATE_PRODUCT
      x-clearway-scope: "write:products"
      x-clearway-money-moving: false
      x-clearway-idempotency: recommended
      x-clearway-status: wired
      x-clearway-rate-limit:
        maxRequests: 60
        windowSeconds: 60
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "Clearway API key (`clwy_live_…` or `clwy_test_…`)."
    ClearwayApiKeyHeader:
      type: apiKey
      in: header
      name: x-clearway-api-key
      description: "Alternative header for server-to-server integrations."
  schemas:
    MerchantApiSuccessEnvelope:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          example: true
      additionalProperties: true
    MerchantApiProductDetail:
      type: object
      description: "Public GET_PRODUCT product body — trial_period_days and aliases are never present (H-1)."
      properties:
        productId:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        amountCents:
          type: integer
        currency:
          type: string
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        images:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: false
    MerchantApiGetProductSuccess:
      type: object
      required:
        - success
        - product
      properties:
        success:
          type: boolean
          example: true
        product:
          $ref: "#/components/schemas/MerchantApiProductDetail"
      additionalProperties: true
    MerchantApiErrorEnvelope:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        code:
          type: string
  responses:
    Unauthorized:
      description: "Missing or invalid API key"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MerchantApiErrorEnvelope"
          example:
            success: false
            error: "Invalid or revoked API key"
            code: UNAUTHORIZED
    Forbidden:
      description: "Scope denied or account not ready"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MerchantApiErrorEnvelope"
          example:
            success: false
            error: "API key missing required scope"
            code: FORBIDDEN
    RateLimited:
      description: "Too many requests"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MerchantApiErrorEnvelope"
          example:
            success: false
            error: "Too many requests. Please try again later."
            code: RATE_LIMIT_EXCEEDED