> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Amend

> Changes the values of a pending subscription proposal before it is decided. Send only the fields to change. `requested`, the values the source sent, stays as it is, and `current` takes the changes. A field sent with a value other than its `requested` value joins `amendedFields`, a field sent with its `requested` value leaves it, and a field not sent keeps its state. Only a pinned proposal names a version. Its `planVersionId` compares with the version a `pinned` `requested` names, else with the plan's default version; on a proposal the source sent floating, a pinned version is amended.

Set a nullable field to null to clear it: the field leaves `current`, and the default a create applies takes its place. On a pinned proposal, `planVersionId: null`, or a new `planId` without a `planVersionId`, pins the plan's default version. Setting `versionPolicy` to `floating` drops the version: the proposal then follows the plan's default. `elapsedPeriodBilling`, `versionPolicy`, `metadata`, `changeReason` and `changeMetadata` take no null: to reset one, send its default value (`none`, `floating`, `{}`, `unspecified` and `{}`).

The result is checked as a subscription create checks its values, at the moment of the request, and a request that fails a check changes nothing. A request that changes neither `current` nor `amendedFields` is not checked: it writes nothing and answers the proposal as it is, even when the proposal has become invalid since its last change, for example past the twelve-month limit of `per_period`. A plan or plan version that no longer exists still answers 404. A proposal that is no longer pending answers 409 with the code `SUBSCRIPTION_PROPOSAL_NOT_PENDING`. With `basedOnHash`, a proposal whose `hash` changed since it was read answers 409 `SUBSCRIPTION_PROPOSAL_CHANGED`, after the pending check, so two reviewers cannot overwrite each other's amends. A proposal of another merchant answers 404, as an unknown one does.



## OpenAPI

````yaml /openapi.json patch /v0/subscriptionProposals/{id}
openapi: 3.1.0
info:
  title: Paygentic API
  version: 0.1.0
  description: >
    The Paygentic API provides a comprehensive platform for building and scaling
    monetization infrastructure.


    ## Authentication

    All API requests require authentication using an API key passed in the
    `Authorization` header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    ## Base URL

    All API requests should be made to:

    ```

    https://api.paygentic.io/v0

    ```
  contact:
    name: Paygentic Support
    email: support@paygentic.io
  license:
    name: Proprietary
servers:
  - url: https://api.paygentic.io
    description: Production API
  - url: https://api.sandbox.paygentic.io
    description: Sandbox API
security:
  - BearerAuth: []
tags:
  - name: Customers
    description: >-
      A `Customer` is an entity connected to a `Merchant` via a `Subscription`.
      This represents the merchant-facing perspective of `Consumers` who
      purchase their `Products`.
  - name: Billable Metrics
    description: >-
      A `Billable Metric` defines a measurable quantity tied to a `Product`'s
      consumption. Each metric stores details including its label, an
      explanatory description, and measurement units.
  - name: Grants
    description: >-
      Grants credit a customer's metered entitlement balance. Merchants can
      create grants directly or void existing ones.


      Use `GET /v1/entitlements?customerId={id}` or `GET
      /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id`
      needed for these endpoints.
  - name: Features
    description: >-
      A `Feature` represents a specific capability or functionality provided by
      a `Product`. Features can be metered (usage-based), static (fixed
      allocation), or boolean (enabled/disabled).
  - name: Fees
    description: >-
      A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees
      are linked to prices, and cadence is defined on the Price.
  - name: Plans
    description: >-
      A `Plan` links a collection of `Prices` to a `Product`. It functions as a
      pricing structure document for a particular feature set or service
      offering.
  - name: Prices
    description: >-
      A `Price` determines the monetary value for a single unit of a `Billable
      Metric`. Prices are exclusively grouped within a `Plan`.
  - name: Products
    description: >-
      A `Product` is an offering sold by a `Merchant`. It includes product
      metadata like title, summary, and pricing details. `Plans`, `Prices`, and
      `Subscriptions` are all associated with products.
  - name: Sources
    description: >-
      A `Source` is an external data provider capable of automatically creating
      usage events. Configuration occurs at the plan level, enabling data
      retrieval from third-party platforms such as Stripe to produce billable
      events.
  - name: Subscriptions
    description: >-
      A `Subscription` is a customer's commitment to purchase a `Product`
      following the terms of a `Plan` and its linked `Prices`.
  - name: Subscription Proposals
    description: >-
      A `SubscriptionProposal` holds the values of a subscription until a person
      on your team approves or rejects it. Nothing is billed while it waits.
  - name: Users
    description: >-
      A `User` is an entity granted access to an Organization's resources. All
      operations are performed by users.
  - name: Invoices V2
    description: >-
      Invoice V2 operations supporting billing cycles organized by time periods.
      Warning: v0 invoice endpoints are no longer supported.
  - name: Revenue
    description: Revenue data from invoices and payments
  - name: Profitability
    description: Per-customer profitability summaries
  - name: Test Clocks
    description: >-
      Test clocks provide programmable time control to simulate subscription and
      billing scenarios during testing.
  - name: Merchant Data
    description: Reset a merchant's data outside production
  - name: Events
    description: Ingest raw metering events that are processed by the meters service.
  - name: Payments
    description: >-
      Create and manage one-off payments. A payment represents a single charge
      that a merchant wants to collect from a customer.
  - name: Payment Sessions
    description: >-
      Handle payment session lifecycle and processing across various entity
      types including invoices and subscriptions
  - name: Costs
    description: >-
      A Cost represents the operational or infrastructure expense of serving
      customers for a given product. Costs are metered (driven by event-based
      usage) and are tracked in parallel with billable metrics to give merchants
      visibility into both revenue and cost per customer.
  - name: ExternalReferences
    description: >-
      An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a
      record in an external system such as Salesforce or NetSuite. Multiple
      external records may map to the same Paygentic entity, but each external
      id is the *primary* reference of at most one entity per merchant.
  - name: Items
    description: >-
      An `Item` is the canonical "thing you sell" that external-system mappings
      point at. It is fully decoupled from the billing `Product` and holds no
      pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to
      it lives entirely in its `ExternalReference` rows.
  - name: MerchantIntegrations
    description: >-
      A `MerchantIntegration` records a merchant's connection to an external
      provider. One connection per `(merchant, provider)` — re-connecting
      upserts in place.
  - name: Approvals
    description: Submit, decide, cancel, and read maker-checker approvals.
  - name: Orders
    description: Manage Orders, their line items, and billing schedules.
  - name: Billing Schedules
    description: >-
      Owner-polymorphic billing schedules with intervals and staged invoice
      projections. A BillingSchedule belongs to exactly one Order or one
      Subscription (XOR). Cadence lives on ScheduleIntervals
      (cadence-on-the-line).
  - name: Webhooks
    description: >-
      Endpoints for setting up webhook integrations and administering webhook
      settings
  - name: Me
    description: 'The caller: who it is in its active organization and what it can do'
paths:
  /v0/subscriptionProposals/{id}:
    patch:
      tags:
        - Subscription Proposals
      summary: Amend
      description: >-
        Changes the values of a pending subscription proposal before it is
        decided. Send only the fields to change. `requested`, the values the
        source sent, stays as it is, and `current` takes the changes. A field
        sent with a value other than its `requested` value joins
        `amendedFields`, a field sent with its `requested` value leaves it, and
        a field not sent keeps its state. Only a pinned proposal names a
        version. Its `planVersionId` compares with the version a `pinned`
        `requested` names, else with the plan's default version; on a proposal
        the source sent floating, a pinned version is amended.


        Set a nullable field to null to clear it: the field leaves `current`,
        and the default a create applies takes its place. On a pinned proposal,
        `planVersionId: null`, or a new `planId` without a `planVersionId`, pins
        the plan's default version. Setting `versionPolicy` to `floating` drops
        the version: the proposal then follows the plan's default.
        `elapsedPeriodBilling`, `versionPolicy`, `metadata`, `changeReason` and
        `changeMetadata` take no null: to reset one, send its default value
        (`none`, `floating`, `{}`, `unspecified` and `{}`).


        The result is checked as a subscription create checks its values, at the
        moment of the request, and a request that fails a check changes nothing.
        A request that changes neither `current` nor `amendedFields` is not
        checked: it writes nothing and answers the proposal as it is, even when
        the proposal has become invalid since its last change, for example past
        the twelve-month limit of `per_period`. A plan or plan version that no
        longer exists still answers 404. A proposal that is no longer pending
        answers 409 with the code `SUBSCRIPTION_PROPOSAL_NOT_PENDING`. With
        `basedOnHash`, a proposal whose `hash` changed since it was read answers
        409 `SUBSCRIPTION_PROPOSAL_CHANGED`, after the pending check, so two
        reviewers cannot overwrite each other's amends. A proposal of another
        merchant answers 404, as an unknown one does.
      operationId: updateSubscriptionProposal
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                autoCharge:
                  type: boolean
                  nullable: true
                  description: >-
                    Enable automatic charging of invoices using stored payment
                    methods. When true, invoices will be automatically paid
                    using off-session payment. Defaults to false.
                taxExempt:
                  type: boolean
                  nullable: true
                  description: >-
                    When true, forces tax rate to 0%. Use for customers with
                    verified tax-exempt status.
                customerId:
                  $ref: '#/components/schemas/CustomerId'
                endingAt:
                  type: string
                  nullable: true
                  format: date-time
                  description: >-
                    Subscription expiration timestamp in ISO 8601 format. Sample
                    values: '2024-12-31T23:59:59Z', '2025-01-15T10:30:00Z'. Omit
                    for indefinite subscriptions. Must be after startedAt: a
                    value at or before it is rejected with 400.
                name:
                  type: string
                  description: >-
                    Subscription identifier combining customer and service
                    details. Sample values: 'TechCorp - LLM API Access',
                    'Analytics Co - Data Platform Enterprise', 'StartupXYZ -
                    Image Generation Service', 'Enterprise Inc - ML Training
                    Platform'
                planId:
                  $ref: '#/components/schemas/PlanId'
                prefundAmount:
                  type: string
                  nullable: true
                  deprecated: true
                  description: Deprecated. This field is ignored and has no effect.
                minimumAccountBalance:
                  type: string
                  nullable: true
                  deprecated: true
                  description: Deprecated. This field is ignored and has no effect.
                redirectUrls:
                  title: UpdateSubscriptionProposalRedirectUrls
                  type: object
                  nullable: true
                  description: >-
                    Optional redirect URLs after payment completion or failure.
                    If not provided, uses default platform behavior.
                  properties:
                    onSuccess:
                      type: string
                      format: uri
                      description: >-
                        Redirect destination after successful payment. Sample
                        values: 'https://app.example.com/success',
                        'https://dashboard.company.com/welcome',
                        'https://portal.startup.io/complete'
                    onFailure:
                      type: string
                      format: uri
                      description: >-
                        Redirect destination after failed payment. Sample
                        values: 'https://app.example.com/payment-failed',
                        'https://dashboard.company.com/retry',
                        'https://portal.startup.io/error'
                startedAt:
                  type: string
                  format: date-time
                  description: >-
                    Subscription activation timestamp in ISO 8601 format. Sample
                    values: '2024-01-15T10:30:00Z', '2024-02-01T00:00:00Z'
                elapsedPeriodBilling:
                  title: UpdateSubscriptionProposalElapsedPeriodBilling
                  type: string
                  enum:
                    - none
                    - per_period
                  description: >-
                    Whether a backdated start bills its elapsed periods. A start
                    is backdated when `startedAt` is more than 24 hours before
                    the subscription is created. `none` bills only charges that
                    fall due from the moment of creation, for a customer whose
                    earlier periods another system already billed. `per_period`
                    bills every charge that fell due from `startedAt`, on one
                    first invoice; it refuses a `startedAt` more than 12 months
                    back, with the code `PER_PERIOD_LOOKBACK_EXCEEDED`. Has no
                    effect on a start that is not backdated. Defaults to `none`.
                billingAnchor:
                  type: string
                  nullable: true
                  format: date-time
                  description: >-
                    A billing anchor for this subscription, in place of the
                    plan's. Any instant, past or future. The subscription's
                    billing anchor is its first recurrence on or after
                    `startedAt`, stepping back or forward by whole billing
                    cadences. Example: on a monthly plan, an anchor of
                    '2027-01-31T00:00:00Z' with a start of
                    '2026-10-10T00:00:00Z' gives '2026-10-31T00:00:00Z'. A
                    create is refused with 400 when the resolved anchor does not
                    line up with the usage period anchor of a feature that
                    credits unused balance. Omit it to use the plan's billing
                    anchor. A repeated create that names an anchor resolving to
                    a different instant than the existing subscription's gets
                    409.
                testClockId:
                  type: string
                  nullable: true
                  description: >-
                    Test clock identifier for simulating time-based billing
                    scenarios. Sample values: 'tc_abc123xyz', 'tc_789def456'.
                    Restricted to non-production environments (local, dev,
                    sandbox). Must belong to the same merchant organization.
                renewalReminderEnabled:
                  type: boolean
                  nullable: true
                  description: >-
                    Override plan setting for renewal reminder emails. When set,
                    this subscription's setting takes precedence over the plan
                    default. Set to true to enable reminders, false to disable,
                    or null/omit to use plan default.
                renewalReminderDays:
                  type: integer
                  nullable: true
                  description: >-
                    Override plan setting for number of days before renewal to
                    send the reminder. Only used if renewalReminderEnabled is
                    true (or inherited from plan). Set to null to use plan
                    default.
                  minimum: 1
                  maximum: 30
                paymentTermDays:
                  type: integer
                  nullable: true
                  description: >-
                    Payment term in days ("Net X") applied to every invoice the
                    subscription generates: invoice dueAt = invoice issue date +
                    paymentTermDays. Defaults to 0 ("due on issue"). A non-zero
                    value needs `metadata.bankTransferOnly: true`; without it
                    the request answers 400
                    `PAYMENT_TERM_DAYS_REQUIRES_BANK_TRANSFER_ONLY`.
                  minimum: 0
                  maximum: 365
                sessionExpiryMinutes:
                  type: number
                  nullable: true
                  description: >-
                    Number of minutes until the payment session expires.
                    Defaults to 240 minutes (4 hours) if not provided.
                  minimum: 1
                versionPolicy:
                  $ref: '#/components/schemas/SubscriptionVersionPolicy'
                metadata:
                  $ref: '#/components/schemas/SubscriptionMetadata'
                changeReason:
                  $ref: '#/components/schemas/ChangeReason'
                changeDescription:
                  type: string
                  nullable: true
                  maxLength: 1000
                  description: A free-text note on why these intervals are changing.
                changeMetadata:
                  $ref: '#/components/schemas/IntervalChangeMetadata'
                addPrices:
                  type: array
                  nullable: true
                  maxItems: 25
                  items:
                    $ref: '#/components/schemas/SubscriptionCreateAddPriceOp'
                  description: >-
                    Catalog prices to bill on this subscription that its plan
                    version does not carry. Each must be owned by the same
                    merchant and use the standard price model.
                overridePrices:
                  type: array
                  nullable: true
                  maxItems: 25
                  items:
                    $ref: '#/components/schemas/SubscriptionCreateOverridePriceOp'
                  description: >-
                    Rate or quantity overrides for prices the plan version does
                    carry.
                removePrices:
                  type: array
                  nullable: true
                  maxItems: 25
                  items:
                    $ref: '#/components/schemas/SubscriptionCreateRemovePriceOp'
                  description: Plan prices this subscription does not bill.
                planVersionId:
                  type: string
                  nullable: true
                  description: >-
                    A published version of `planId` to pin the proposal to. Only
                    a pinned proposal (`versionPolicy: "pinned"`) names a
                    version. One that names none, or `null`, pins the plan's
                    default version, as a change of `planId` without a version
                    does. A floating proposal follows the plan's default
                    version, and one that names a version is refused with 400.
                adjustments:
                  type: array
                  nullable: true
                  maxItems: 25
                  items:
                    $ref: '#/components/schemas/CreateSubscriptionAdjustmentRequest'
                  description: >-
                    Adjustments the subscription gets when the proposal is
                    approved. Each is checked as subscription adjustment create
                    checks it, against the prices the proposal bills and the
                    other adjustments in this list.
                basedOnHash:
                  type: string
                  pattern: ^[0-9a-f]{64}$
                  description: >-
                    The proposal's `hash` as the person read it. When sent and
                    the proposal has changed since, the amend is refused with
                    409 `SUBSCRIPTION_PROPOSAL_CHANGED` and nothing is written:
                    read the proposal again and amend what it holds now. Leave
                    it out to amend whatever the proposal holds.
      responses:
        '200':
          description: Subscription proposal amended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionProposal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            The proposal is decided (`SUBSCRIPTION_PROPOSAL_NOT_PENDING`) or
            changed since `basedOnHash` was read
            (`SUBSCRIPTION_PROPOSAL_CHANGED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionProposalConflict'
        '429':
          description: >-
            Another change is in progress on this subscription proposal. Retry
            after the time in the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CustomerId:
      type: string
      pattern: ^cus_[a-zA-Z0-9]+$
      description: Unique identifier for a customer
    PlanId:
      type: string
      pattern: ^plan_[a-zA-Z0-9]+$
      description: Unique identifier for a plan
    SubscriptionVersionPolicy:
      type: string
      enum:
        - floating
        - pinned
      description: >-
        How the subscription follows new versions of its plan. `floating`
        follows the plan's default version: when the default changes, the
        subscription bills from the new default from its next billing period.
        `pinned` keeps the plan version that the subscription holds. A
        subscription created without a value is `floating`. A change to this
        value does not change a billing period that has already started.
    SubscriptionMetadata:
      type: object
      description: >-
        Free-form merchant metadata to attach to the subscription. Values must
        be strings, numbers, or booleans.
      additionalProperties:
        type:
          - string
          - number
          - boolean
    ChangeReason:
      type: string
      enum:
        - commercial
        - correction
        - migration
        - unspecified
        - contractual
      x-speakeasy-unknown-values: allow
      description: >-
        Why a change was made. `correction` repairs data that was entered wrong;
        `migration` moves a contract from another system; `commercial` is a real
        change to the deal; `contractual` applies a step the original contract
        scheduled, such as an annual uplift. Defaults to `unspecified`.
    IntervalChangeMetadata:
      type: object
      description: Your own key-value data about the change, such as a CRM deal ID.
      maxProperties: 50
      propertyNames:
        maxLength: 100
      additionalProperties:
        type:
          - string
          - number
          - boolean
        maxLength: 500
    SubscriptionCreateAddPriceOp:
      type: object
      additionalProperties: false
      required:
        - priceId
      description: >-
        A catalog price the plan version does not carry. The rate is always
        stored on the interval, because an added price has no plan slot and so
        version copy-on-write never freezes a snapshot for it. Omit unitPrice to
        store the named price's own rate; supply one to store a negotiated rate
        instead. Supply total and installments instead to collect one obligation
        over several billing periods.
      properties:
        priceId:
          type: string
          description: >-
            The catalog price to bill. Must belong to the subscription's
            merchant and must not already be carried by the plan version.
        unitPrice:
          type: string
          description: >-
            The agreed rate, as a decimal string. Defaults to the named price's
            own rate. Cannot be combined with total.
        baseQuantity:
          type: string
          description: >-
            Quantity to bill. Defaults to the catalog price's own quantity.
            Cannot be combined with total.
        total:
          type: string
          pattern: ^(0|[1-9]\d*)(\.\d+)?$
          maxLength: 21
          description: >-
            The whole contract amount to collect as equal installments, as a
            positive decimal string in plain notation. With installments it must
            divide into equal amounts at two decimal places; beside amounts it
            is an optional checksum that must equal their exact sum. The named
            price must be an obligation carrying quantity 1 on the
            subscription's own billing cadence. Recorded on the interval exactly
            as written, so an exponent, a sign, a radix prefix or a leading-zero
            run is rejected rather than normalized.
        installments:
          type: integer
          minimum: 2
          maximum: 60
          description: >-
            How many billing periods the total is collected over, producing
            equal installments. Requires total, and cannot accompany amounts.
            One installment is one billing period of the subscription, so a
            count of 3 on an annual subscription runs three years. The window is
            derived from the subscription's billing grid; no date is accepted.
        amounts:
          type: array
          minItems: 2
          maxItems: 60
          items:
            type: string
          description: >-
            The installment schedule stated explicitly: one positive decimal
            amount per billing period, in order, each in plain notation with at
            most 2 decimal places. The amounts need not be equal, and their
            exact sum is the contract total; a total supplied alongside acts as
            a checksum and must equal that sum. Cannot accompany installments,
            unitPrice, baseQuantity, or any date: the window is derived in full
            from the subscription's billing grid. Use this shape when the
            contract's split is not equal - for example 2950.00 in three monthly
            instalments of 984.00, 983.00 and 983.00.
    SubscriptionCreateOverridePriceOp:
      type: object
      additionalProperties: false
      description: >-
        A rate or quantity override for a price the plan version carries. Supply
        at least one of unitPrice or baseQuantity; a request supplying neither
        is rejected with a 400 naming the entry.
      required:
        - overridesPriceId
      properties:
        overridesPriceId:
          type: string
          description: >-
            The plan-version price being overridden. Its priceKey lineage is
            preserved.
        unitPrice:
          type: string
          description: The agreed rate, as a decimal string.
        baseQuantity:
          type: string
          description: The agreed quantity, as a decimal string.
    SubscriptionCreateRemovePriceOp:
      type: object
      additionalProperties: false
      required:
        - priceId
      properties:
        priceId:
          type: string
          description: The plan-version price this subscription does not bill.
    CreateSubscriptionAdjustmentRequest:
      description: >-
        One adjustment to attach to the subscription. The type decides which
        number the body carries: a rate for percentageDiscount, a unit count and
        one target price for usageDiscount, and a contracted quantity and one
        target price for minimumQuantity and maximumQuantity.
      oneOf:
        - $ref: '#/components/schemas/CreatePercentageDiscountAdjustment'
        - $ref: '#/components/schemas/CreateUsageDiscountAdjustment'
        - $ref: '#/components/schemas/CreateMinimumQuantityAdjustment'
        - $ref: '#/components/schemas/CreateMaximumQuantityAdjustment'
      discriminator:
        propertyName: type
        mapping:
          percentageDiscount: '#/components/schemas/CreatePercentageDiscountAdjustment'
          usageDiscount: '#/components/schemas/CreateUsageDiscountAdjustment'
          minimumQuantity: '#/components/schemas/CreateMinimumQuantityAdjustment'
          maximumQuantity: '#/components/schemas/CreateMaximumQuantityAdjustment'
    SubscriptionProposal:
      type: object
      description: >-
        A subscription a client proposed, held until a person approves or
        rejects it. No subscription exists until it is approved.
      required:
        - id
        - object
        - merchantId
        - status
        - customerId
        - planId
        - planVersionId
        - resolvedPlanVersionId
        - hash
        - testClockId
        - requested
        - current
        - amendedFields
        - refusedResync
        - lockVersion
        - source
        - externalReference
        - subscriptionId
        - rejectionReason
        - rejectionText
        - decidedAt
        - decidedByPrincipalId
        - decidedBy
        - strandedAt
        - createdByPrincipalId
        - createdByCredentialId
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        object:
          type: string
          enum:
            - subscriptionProposal
        merchantId:
          $ref: '#/components/schemas/OrganizationId'
        status:
          $ref: '#/components/schemas/SubscriptionProposalStatus'
        customerId:
          $ref: '#/components/schemas/CustomerId'
        planId:
          $ref: '#/components/schemas/PlanId'
        planVersionId:
          type: string
          nullable: true
          description: >-
            The plan version a pinned proposal is pinned to. Null for a floating
            proposal, which follows the plan's default version.
        resolvedPlanVersionId:
          type: string
          nullable: true
          description: >-
            The plan version approve would use now: `planVersionId` when pinned,
            else the plan's default version. Null when the plan has no published
            version.
        hash:
          type: string
          description: >-
            Changes whenever `current` or `resolvedPlanVersionId` changes. A
            decision sends it as `basedOnHash`, so a person only decides on the
            proposal they read.
        testClockId:
          type: string
          nullable: true
        requested:
          $ref: '#/components/schemas/SubscriptionProposalValues'
          description: >-
            The values as the client last sent them, without
            `externalReference`.
        current:
          $ref: '#/components/schemas/SubscriptionProposalValues'
          description: >-
            The values as they are now, amendments included, with
            `planVersionId` when the proposal is pinned. Approve creates the
            subscription from them.
        amendedFields:
          type: array
          items:
            type: string
          description: >-
            The top-level fields a person amended. A re-send of the external
            reference keeps the person's value for each; a field stays amended
            when the client sends the person's value.
        refusedResync:
          anyOf:
            - $ref: '#/components/schemas/SubscriptionProposalRefusedResync'
            - type: 'null'
          description: >-
            The CRM's latest refused re-sync, or null. It changes `hash`, so a
            decision made before it arrived answers 409
            `SUBSCRIPTION_PROPOSAL_CHANGED`.
        lockVersion:
          type: integer
          description: Starts at 1, and every change to the proposal adds one.
        source:
          type: string
          description: >-
            The `provider` of the proposal's external reference, or `api` when
            it has none.
        externalReference:
          anyOf:
            - $ref: '#/components/schemas/SubscriptionProposalExternalReference'
            - type: 'null'
          description: >-
            The record the proposal comes from. Null when it was created without
            one.
        subscriptionId:
          type: string
          nullable: true
          description: The subscription approve created.
        rejectionReason:
          anyOf:
            - $ref: '#/components/schemas/SubscriptionProposalRejectionReason'
            - type: 'null'
          description: Why the proposal was rejected. Null unless it is `rejected`.
        rejectionText:
          type: string
          nullable: true
          description: The notes the reviewer gave with the rejection.
        decidedAt:
          type: string
          format: date-time
          nullable: true
        decidedByPrincipalId:
          type: string
          nullable: true
        decidedBy:
          anyOf:
            - $ref: '#/components/schemas/SubscriptionProposalDecider'
            - type: 'null'
          description: >-
            Who approved or rejected the proposal, by name. Null until it is
            decided, and when the decider cannot be named: a decision made with
            the platform key, or by a principal that no longer exists.
        strandedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Set when an approve ended with its subscription waiting for its
            first invoice; a repeated approve resumes it.
        createdByPrincipalId:
          type: string
          nullable: true
        createdByCredentialId:
          type: string
          nullable: true
          description: >-
            The API key or OAuth client that created the proposal; null for a
            dashboard session.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        revisions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionProposalRevision'
          description: >-
            Each set of values the client sent, earliest first. Present only
            with `expand=revisions`. The last one is `requested`.
    SubscriptionProposalConflict:
      type: object
      required:
        - error
        - message
      description: A 409 of a proposal route. Branch on `code`, never on `message`.
      properties:
        requestId:
          $ref: '#/components/schemas/RequestId'
        error:
          title: SubscriptionProposalConflictErrorType
          type: string
          enum:
            - conflict
        message:
          type: string
        code:
          $ref: '#/components/schemas/SubscriptionProposalConflictCode'
        details:
          $ref: '#/components/schemas/SubscriptionProposalConflictDetails'
    Error:
      type: object
      required:
        - message
      properties:
        error:
          type: string
          description: >-
            Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps
            to the HTTP status code.
        message:
          type: string
          description: >-
            Human-readable error message. Clients must not parse this field
            programmatically.
        code:
          type: string
          examples:
            - TAX_NOT_ENABLED
            - PAYMENT_SESSION_EXPIRED
          description: >-
            Optional semantic business error code for machine-readable
            discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients
            should check this field, not message.
        details:
          type: object
          description: Additional error details
          additionalProperties: true
        reason:
          $ref: '#/components/schemas/AuthorizationDenialReason'
        requiredPermissions:
          type: array
          items:
            type: string
          description: >-
            Present on a 403 from the authorization check. The permissions the
            caller needs for this request.
        requestId:
          $ref: '#/components/schemas/RequestId'
      example:
        message: The requested resource was not found
        error: not_found
    CreatePercentageDiscountAdjustment:
      type: object
      additionalProperties: false
      required:
        - type
        - percentageDiscount
        - effectiveFrom
      properties:
        type:
          type: string
          enum:
            - percentageDiscount
          description: Reduces every discountable charge on the invoice by a rate.
        percentageDiscount:
          type: string
          description: >-
            The discount rate as a decimal fraction between 0 and 1, sent as a
            string. "0.35" means 35 percent. "1" means 100 percent, not 1
            percent. At most 6 decimal places. A value of 0 or above 1 is
            rejected.
        effectiveFrom:
          type: string
          format: date-time
          description: The first instant the discount applies. Inclusive.
        effectiveTo:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            The instant the discount stops applying. Exclusive, so a window
            ending on the same date another begins neither overlaps nor leaves a
            gap. Null means the discount never stops, and it cannot be ended
            later — set an instant whenever the deal has a known end date. Must
            be after effectiveFrom.
        description:
          type:
            - string
            - 'null'
          maxLength: 255
          description: The deal's own name, shown on each discount line of the invoice.
        idempotencyKey:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            A key of your choosing that makes a retry safe. Sending the same key
            against the same subscription returns the adjustment already created
            and creates no second one. Without a key a retried request creates a
            second adjustment, and two percentage discounts compound — two of
            0.35 bill 57.75 percent off, not 35 percent.
          example: adj_fy26_growth_001
    CreateUsageDiscountAdjustment:
      type: object
      additionalProperties: false
      required:
        - type
        - usageDiscount
        - targetPriceIds
        - effectiveFrom
      properties:
        type:
          type: string
          enum:
            - usageDiscount
          description: >-
            Reduces one metered price's billable quantity by a number of usage
            units, before the line is priced.
        usageDiscount:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          description: >-
            The number of usage units to take off the billable quantity, sent as
            a plain decimal string. "300" waives 300 units. Greater than 0, at
            most 6 decimal places, fewer than 35 digits before the point. Plain
            notation only — no sign, exponent, hex or digit separators, so
            "1_000" and "1e3" are rejected rather than read as 1000. Applied in
            full or not at all — a unit count is never prorated across a partial
            window — and once per matching line, so an invoice bundling several
            periods is corrected on each of them. The line is floored at 0, so a
            discount larger than the billable quantity zeroes it rather than
            crediting. On a volume ladder the corrected quantity also re-selects
            the band, so a waiver that crosses a boundary can bill more than the
            uncorrected line did: waiving 300 of 1000 units on a ladder of 2.00
            up to 999 and 1.00 beyond bills 700 at 2.00 for 1400.00, where the
            1000 units billed 1000.00. That is the ladder's price for the
            corrected usage — what a customer who genuinely used 700 units pays
            — so check the ladder before waiving units near a band boundary.
        targetPriceIds:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 1
          description: >-
            Exactly one metered price of this subscription, priced as standard
            or volume. Usage units are not comparable across metrics, so a usage
            discount names the one price it reduces. A dynamic or percentage
            price is refused: its quantity is a monetary amount rather than a
            unit count. A price billing at a negative rate (a usage-scaled
            rebate) is refused too, because removing its units would raise the
            invoice.
        effectiveFrom:
          type: string
          format: date-time
          description: >-
            Opens the window. Exclusive for this type: a metered line is
            corrected when its period END falls after this instant, so a window
            opening exactly when a period ends belongs to the next period, not
            that one. Set it to the start of the period you are correcting.
        effectiveTo:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Closes the window. INCLUSIVE for this type, unlike
            percentageDiscount: a metered line bills in arrears, so set this to
            the exact period end you are correcting and that period is covered.
            Null means the discount never stops — it then takes its full unit
            count off this price on EVERY later invoice, so set both bounds
            whenever you are correcting one period. Must be after effectiveFrom.
        description:
          type:
            - string
            - 'null'
          maxLength: 255
          description: >-
            Your own name for this correction. A usageDiscount emits no invoice
            line, so this is printed nowhere on the invoice — it is returned on
            the adjustment for your own records.
        idempotencyKey:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            A key of your choosing that makes a retry safe. Sending the same key
            against the same subscription returns the adjustment already created
            and creates no second one. Without a key a retried request creates a
            second adjustment, and usage discounts against one price SUM — two
            of "300" waive 600 units, not 300. Nothing else detects a duplicate.
          example: adj_mar_outage_001
    CreateMinimumQuantityAdjustment:
      type: object
      additionalProperties: false
      required:
        - type
        - minimumQuantity
        - targetPriceIds
        - effectiveFrom
      properties:
        type:
          type: string
          enum:
            - minimumQuantity
          description: >-
            Bills at least the contracted quantity on one price, whatever the
            customer actually used.
        minimumQuantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          description: >-
            The contracted minimum quantity for one billing period of the target
            price, sent as a plain decimal string. Not negative, at most 6
            decimal places, fewer than 35 digits before the point. Plain
            notation only — no sign, exponent, hex or digit separators, so
            "1_000" and "1e3" are rejected rather than read as 1000. "4" bills 4
            seats in a period the customer used 2 in; a value of 0 binds
            nothing. Measured over the whole billing period, not per line: where
            a period is split into several lines, each line's quantity counts
            for its share of the period, and every line is scaled by the same
            factor to bring the period to the minimum. Several bounds of the
            same direction on one price do not add up — the greatest minimum and
            the least maximum are the ones that apply.
        targetPriceIds:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 1
          description: >-
            Exactly one price of this subscription. A metered price is accepted,
            and so is a price whose supply is outside the scope of VAT: a bound
            constrains a measurement rather than an amount of consideration. A
            price that bills once rather than per period is refused, because
            there is no repeating period for the bound to be measured over.
        effectiveFrom:
          type: string
          format: date-time
          description: >-
            Opens the window. Exclusive for this type: a line is bounded when
            its period END falls after this instant, so a window opening exactly
            when a period ends belongs to the next period, not that one. The
            bound is never prorated — a window opening mid-period applies to
            that whole period.
        effectiveTo:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Closes the window. INCLUSIVE for this type, like usageDiscount and
            unlike percentageDiscount: set this to the exact period end you are
            bounding and that period is covered. Null means the bound never
            stops. Must be after effectiveFrom.
        description:
          type:
            - string
            - 'null'
          maxLength: 255
          description: >-
            Your own name for this term. A quantity bound emits no invoice line,
            so this is printed nowhere on the invoice — it is returned on the
            adjustment for your own records.
        idempotencyKey:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            A key of your choosing that makes a retry safe. Sending the same key
            against the same subscription returns the adjustment already created
            and creates no second one. Without a key a retried request creates a
            second bound; two identical bounds change nothing, because bounds of
            one direction do not add up.
          example: adj_fortress_seats_001
    CreateMaximumQuantityAdjustment:
      type: object
      additionalProperties: false
      required:
        - type
        - maximumQuantity
        - targetPriceIds
        - effectiveFrom
      properties:
        type:
          type: string
          enum:
            - maximumQuantity
          description: >-
            Bills at most the contracted quantity on one price, whatever the
            customer actually used.
        maximumQuantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          description: >-
            The contracted maximum quantity for one billing period of the target
            price, sent as a plain decimal string. Not negative, at most 6
            decimal places, fewer than 35 digits before the point. Plain
            notation only — no sign, exponent, hex or digit separators, so
            "1_000" and "1e3" are rejected rather than read as 1000. "4" bills 4
            seats in a period the customer used 9 in; a value of 0 bills nothing
            at all. Measured over the whole billing period, not per line: where
            a period is split into several lines, each line's quantity counts
            for its share of the period, and every line is scaled by the same
            factor to bring the period to the maximum. Several bounds of the
            same direction on one price do not add up — the greatest minimum and
            the least maximum are the ones that apply.
        targetPriceIds:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 1
          description: >-
            Exactly one price of this subscription. A metered price is accepted,
            and so is a price whose supply is outside the scope of VAT: a bound
            constrains a measurement rather than an amount of consideration. A
            price that bills once rather than per period is refused, because
            there is no repeating period for the bound to be measured over.
        effectiveFrom:
          type: string
          format: date-time
          description: >-
            Opens the window. Exclusive for this type: a line is bounded when
            its period END falls after this instant, so a window opening exactly
            when a period ends belongs to the next period, not that one. The
            bound is never prorated — a window opening mid-period applies to
            that whole period.
        effectiveTo:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Closes the window. INCLUSIVE for this type, like usageDiscount and
            unlike percentageDiscount: set this to the exact period end you are
            bounding and that period is covered. Null means the bound never
            stops. Must be after effectiveFrom.
        description:
          type:
            - string
            - 'null'
          maxLength: 255
          description: >-
            Your own name for this term. A quantity bound emits no invoice line,
            so this is printed nowhere on the invoice — it is returned on the
            adjustment for your own records.
        idempotencyKey:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            A key of your choosing that makes a retry safe. Sending the same key
            against the same subscription returns the adjustment already created
            and creates no second one. Without a key a retried request creates a
            second bound; two identical bounds change nothing, because bounds of
            one direction do not add up.
          example: adj_fortress_seats_001
    OrganizationId:
      type: string
      pattern: ^org_[a-zA-Z0-9]+$
      description: Unique identifier for an organization
    SubscriptionProposalStatus:
      type: string
      enum:
        - pending
        - approved
        - rejected
      description: '`pending` until a person approves or rejects the proposal.'
    SubscriptionProposalValues:
      type: object
      additionalProperties: false
      description: >-
        The values of a subscription proposal: the fields of `POST
        /v0/subscriptionProposals` without `externalReference`, each as that
        request takes it. A field the client left out is absent.
      required:
        - planId
        - customerId
        - name
        - startedAt
      properties:
        autoCharge:
          type: boolean
          description: >-
            Enable automatic charging of invoices using stored payment methods.
            When true, invoices will be automatically paid using off-session
            payment. Defaults to false.
        taxExempt:
          type: boolean
          description: >-
            When true, forces tax rate to 0%. Use for customers with verified
            tax-exempt status.
        customerId:
          $ref: '#/components/schemas/CustomerId'
        endingAt:
          type: string
          format: date-time
          description: >-
            Subscription expiration timestamp in ISO 8601 format. Sample values:
            '2024-12-31T23:59:59Z', '2025-01-15T10:30:00Z'. Omit for indefinite
            subscriptions. Must be after startedAt: a value at or before it is
            rejected with 400.
        name:
          type: string
          description: >-
            Subscription identifier combining customer and service details.
            Sample values: 'TechCorp - LLM API Access', 'Analytics Co - Data
            Platform Enterprise', 'StartupXYZ - Image Generation Service',
            'Enterprise Inc - ML Training Platform'
        planId:
          $ref: '#/components/schemas/PlanId'
        prefundAmount:
          type: string
          deprecated: true
          description: Deprecated. This field is ignored and has no effect.
        minimumAccountBalance:
          type: string
          deprecated: true
          description: Deprecated. This field is ignored and has no effect.
        redirectUrls:
          title: SubscriptionProposalRedirectUrls
          type: object
          description: >-
            Optional redirect URLs after payment completion or failure. If not
            provided, uses default platform behavior.
          properties:
            onSuccess:
              type: string
              format: uri
              description: >-
                Redirect destination after successful payment. Sample values:
                'https://app.example.com/success',
                'https://dashboard.company.com/welcome',
                'https://portal.startup.io/complete'
            onFailure:
              type: string
              format: uri
              description: >-
                Redirect destination after failed payment. Sample values:
                'https://app.example.com/payment-failed',
                'https://dashboard.company.com/retry',
                'https://portal.startup.io/error'
        startedAt:
          type: string
          format: date-time
          description: >-
            Subscription activation timestamp in ISO 8601 format. Sample values:
            '2024-01-15T10:30:00Z', '2024-02-01T00:00:00Z'
        elapsedPeriodBilling:
          type: string
          enum:
            - none
            - per_period
          description: >-
            Whether a backdated start bills its elapsed periods. A start is
            backdated when `startedAt` is more than 24 hours before the
            subscription is created. `none` bills only charges that fall due
            from the moment of creation, for a customer whose earlier periods
            another system already billed. `per_period` bills every charge that
            fell due from `startedAt`, on one first invoice; it refuses a
            `startedAt` more than 12 months back, with the code
            `PER_PERIOD_LOOKBACK_EXCEEDED`. Has no effect on a start that is not
            backdated. Defaults to `none`.
        billingAnchor:
          type: string
          format: date-time
          description: >-
            A billing anchor for this subscription, in place of the plan's. Any
            instant, past or future. The subscription's billing anchor is its
            first recurrence on or after `startedAt`, stepping back or forward
            by whole billing cadences. Example: on a monthly plan, an anchor of
            '2027-01-31T00:00:00Z' with a start of '2026-10-10T00:00:00Z' gives
            '2026-10-31T00:00:00Z'. A create is refused with 400 when the
            resolved anchor does not line up with the usage period anchor of a
            feature that credits unused balance. Omit it to use the plan's
            billing anchor. A repeated create that names an anchor resolving to
            a different instant than the existing subscription's gets 409.
        testClockId:
          type: string
          description: >-
            Test clock identifier for simulating time-based billing scenarios.
            Sample values: 'tc_abc123xyz', 'tc_789def456'. Restricted to
            non-production environments (local, dev, sandbox). Must belong to
            the same merchant organization.
        renewalReminderEnabled:
          type: boolean
          nullable: true
          description: >-
            Override plan setting for renewal reminder emails. When set, this
            subscription's setting takes precedence over the plan default. Set
            to true to enable reminders, false to disable, or null/omit to use
            plan default.
        renewalReminderDays:
          type: integer
          nullable: true
          description: >-
            Override plan setting for number of days before renewal to send the
            reminder. Only used if renewalReminderEnabled is true (or inherited
            from plan). Set to null to use plan default.
          minimum: 1
          maximum: 30
        paymentTermDays:
          type: integer
          description: >-
            Payment term in days ("Net X") applied to every invoice the
            subscription generates: invoice dueAt = invoice issue date +
            paymentTermDays. Defaults to 0 ("due on issue"). A non-zero value
            needs `metadata.bankTransferOnly: true`; without it the request
            answers 400 `PAYMENT_TERM_DAYS_REQUIRES_BANK_TRANSFER_ONLY`.
          minimum: 0
          maximum: 365
        sessionExpiryMinutes:
          type: number
          description: >-
            Number of minutes until the payment session expires. Defaults to 240
            minutes (4 hours) if not provided.
          minimum: 1
        versionPolicy:
          $ref: '#/components/schemas/SubscriptionVersionPolicy'
        metadata:
          $ref: '#/components/schemas/SubscriptionMetadata'
        changeReason:
          $ref: '#/components/schemas/ChangeReason'
        changeDescription:
          type: string
          maxLength: 1000
          description: A free-text note on why these intervals are changing.
        changeMetadata:
          $ref: '#/components/schemas/IntervalChangeMetadata'
        addPrices:
          type: array
          maxItems: 25
          items:
            $ref: '#/components/schemas/SubscriptionCreateAddPriceOp'
          description: >-
            Catalog prices to bill on this subscription that its plan version
            does not carry. Each must be owned by the same merchant and use the
            standard price model.
        overridePrices:
          type: array
          maxItems: 25
          items:
            $ref: '#/components/schemas/SubscriptionCreateOverridePriceOp'
          description: Rate or quantity overrides for prices the plan version does carry.
        removePrices:
          type: array
          maxItems: 25
          items:
            $ref: '#/components/schemas/SubscriptionCreateRemovePriceOp'
          description: Plan prices this subscription does not bill.
        planVersionId:
          type: string
          description: >-
            A published version of `planId` to pin the proposal to. Only a
            pinned proposal (`versionPolicy: "pinned"`) names a version. One
            that names none, or `null`, pins the plan's default version, as a
            change of `planId` without a version does. A floating proposal
            follows the plan's default version, and one that names a version is
            refused with 400.
        adjustments:
          type: array
          maxItems: 25
          items:
            $ref: '#/components/schemas/CreateSubscriptionAdjustmentRequest'
          description: >-
            Adjustments the subscription gets when the proposal is approved.
            Each is checked as subscription adjustment create checks it, against
            the prices the proposal bills and the other adjustments in this
            list.
    SubscriptionProposalRefusedResync:
      type: object
      description: >-
        The CRM's latest re-sync of this proposal that was refused, so a
        reviewer can see what the CRM asked for. A later send that applies or
        matches `requested`, an amend after which `current` holds every value it
        changed, and a reject clear it. A send that repeats it changes nothing.
      required:
        - receivedAt
        - code
        - fields
        - values
        - credentialId
      additionalProperties: false
      properties:
        receivedAt:
          type: string
          format: date-time
          description: When the refused values arrived.
        code:
          type: string
          enum:
            - SUBSCRIPTION_PROPOSAL_RESYNC_CONFLICT
            - SUBSCRIPTION_PROPOSAL_ALREADY_APPROVED
          description: The code of the 409 the send answered.
        fields:
          type: array
          items:
            type: string
          description: >-
            The fields that conflict with an amendment, or on an approved
            proposal the fields the CRM changed.
        values:
          $ref: '#/components/schemas/SubscriptionProposalValues'
          description: The values the CRM sent, without `externalReference`.
        credentialId:
          anyOf:
            - type: string
            - type: 'null'
          description: The key or OAuth client that sent them; null for a session.
    SubscriptionProposalExternalReference:
      type: object
      description: >-
        The record in another system, such as a CRM deal, that the proposal
        comes from. A create naming a record that already has a proposal acts on
        that proposal, as the create operation describes.
      required:
        - provider
        - externalId
      additionalProperties: false
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        externalId:
          $ref: '#/components/schemas/ExternalId'
    SubscriptionProposalRejectionReason:
      type: string
      enum:
        - price_mismatch
        - wrong_plan
        - wrong_start_date
        - wrong_customer
        - duplicate
        - other
      x-speakeasy-unknown-values: allow
      description: >-
        Why a person rejected the proposal. `price_mismatch`: a price or
        discount is not the one agreed. `wrong_plan`: the proposal names the
        wrong plan. `wrong_start_date`: the start date is wrong.
        `wrong_customer`: the proposal names the wrong customer. `duplicate`:
        the customer already has this subscription, or another proposal holds
        it. `other`: another reason, explained in `text`.
    SubscriptionProposalDecider:
      type: object
      description: Who decided a proposal.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - user
            - apiKey
          x-speakeasy-unknown-values: allow
          description: >-
            `user` for a member of the merchant, `apiKey` for an API key. Open
            set.
        name:
          type: string
          description: >-
            A user's first and last name, or their email when both are blank; an
            API key's name.
    SubscriptionProposalRevision:
      type: object
      description: >-
        One set of values the client sent for a proposal. A revision never
        changes.
      required:
        - id
        - version
        - values
        - createdAt
        - createdByCredentialId
      additionalProperties: false
      properties:
        id:
          type: string
        version:
          type: integer
          minimum: 1
          description: >-
            1 for the values the proposal was created with, then one more for
            each set sent after.
        values:
          $ref: '#/components/schemas/SubscriptionProposalValues'
          description: The values as the client sent them, without `externalReference`.
        createdAt:
          type: string
          format: date-time
        createdByCredentialId:
          type: string
          nullable: true
          description: >-
            The API key or OAuth client that sent the values; null for a
            dashboard session.
    ValidationError:
      type: object
      required:
        - message
        - errors
      properties:
        error:
          type: string
          enum:
            - validation_error
          default: validation_error
          description: Error type indicating validation failure
        message:
          type: string
          description: Human-readable error message
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: The field that failed validation
              message:
                type: string
                description: Validation error message for this field
              code:
                type: string
                description: Validation error code
            required:
              - field
              - message
          description: Array of field-specific validation errors
        requestId:
          $ref: '#/components/schemas/RequestId'
      example:
        message: Validation failed
        error: validation_error
        errors:
          - field: email
            message: Invalid email format
            code: invalid_format
    RequestId:
      type: string
      description: >-
        Identifies this request in our logs. Include it when you contact
        support. Also sent in the `request-id` response header.
      examples:
        - 105445aa7843bc8bf206b12000100000
    SubscriptionProposalConflictCode:
      type: string
      enum:
        - SUBSCRIPTION_PROPOSAL_RESYNC_CONFLICT
        - SUBSCRIPTION_PROPOSAL_ALREADY_APPROVED
        - SUBSCRIPTION_PROPOSAL_NOT_PENDING
        - SUBSCRIPTION_PROPOSAL_CHANGED
        - SUBSCRIPTION_PROPOSAL_DUPLICATE
        - SUBSCRIPTION_PROPOSAL_INVALID
      x-speakeasy-unknown-values: allow
      description: >-
        Why a proposal route answered 409. `RESYNC_CONFLICT`: a re-sync changed
        a field a person amended; stop, a person rejects and the CRM sends
        again. `ALREADY_APPROVED`: the proposal is approved; stop.
        `NOT_PENDING`: the proposal is decided; stop. `CHANGED`: the proposal
        changed since it was read; read it again and retry. `DUPLICATE`: the
        customer already has a live subscription for the product; reject the
        proposal. `INVALID`: the proposal now fails a check of subscription
        create; amend or reject it. Open set: approve can pass on a conflict of
        subscription create with that conflict's own code, so treat any other
        code as an unhandled conflict.
    SubscriptionProposalConflictDetails:
      type: object
      additionalProperties: true
      description: What the conflict names. Which fields are set depends on `code`.
      properties:
        code:
          type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_INVALID`, the failed check's own code,
            when it has one. On the other codes, the conflict's `code` again.
        details:
          type: object
          additionalProperties: true
          description: >-
            On `SUBSCRIPTION_PROPOSAL_INVALID`, the failed check's own details,
            when it has them.
        fields:
          type: array
          items:
            type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_RESYNC_CONFLICT`, the fields that conflict
            with an amendment.
        subscriptionId:
          type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_ALREADY_APPROVED`, the subscription the
            proposal created. On `SUBSCRIPTION_PROPOSAL_DUPLICATE`, the
            customer's live subscription for the product.
        status:
          type: string
          description: On `SUBSCRIPTION_PROPOSAL_NOT_PENDING`, the proposal's status.
        field:
          type: string
          description: >-
            On `SUBSCRIPTION_PROPOSAL_CHANGED` from approve's compare-and-set,
            `lockVersion`, the compared field.
        expected:
          type:
            - integer
            - 'null'
          description: >-
            On `SUBSCRIPTION_PROPOSAL_CHANGED` from approve's compare-and-set,
            the `lockVersion` the proposal holds.
        actual:
          type: integer
          description: >-
            On `SUBSCRIPTION_PROPOSAL_CHANGED` from approve's compare-and-set,
            the `lockVersion` approve read.
        entityType:
          type: string
        entityId:
          type: string
    AuthorizationDenialReason:
      type: string
      enum:
        - no_permission
        - insufficient_scope
        - not_member
      description: >-
        Present on a 403 from the authorization check. Says why access was
        refused: the caller has no role that grants the permission, the OAuth
        token lacks the scope, or the caller is not a member of the
        organization.
    Provider:
      type: string
      pattern: ^[a-z][a-z0-9_]*$
      maxLength: 64
      description: Lowercase snake_case provider identifier (e.g. `salesforce`, `netsuite`)
    ExternalId:
      type: string
      pattern: ^[a-zA-Z0-9_-]+$
      maxLength: 255
      description: >-
        Optional external identifier for cross-referencing with external
        systems. Alphanumeric characters, hyphens, and underscores only.
  responses:
    BadRequest:
      description: >-
        Bad Request - The request could not be understood or was missing
        required parameters
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/ValidationError'
    Unauthorized:
      description: Unauthorized - Authentication failed or user does not have permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden - Request is understood but refused
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found - The requested resource could not be found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error - Something went wrong on the server side
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.