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

# Create subscription

> Create a subscription for a customer. Commet selects the default price when priceId is omitted. The subscription starts at the base USD price; market and currency are resolved from the buyer's request country when the checkout opens. Without an offer override, Commet applies the price's automatic introductory Offer. Pass offerId to apply an active compatible Offer directly, or cardPromotionId to preselect a card-eligible Promotional Offer for the initial checkout when card promotions are enabled for the organization. For the initial checkout, provider accepts either a processor name or an exact payment connection ID. When the price's free trial requires no payment method, the subscription starts trialing right away with no checkout (checkoutUrl null, hasPaymentMethod false); it cannot be combined with offerId, promoCode, cardPromotionId or provider, and an organization that cannot charge yet receives 403.

> [!NOTE]
>
> This reference describes API version `2026-07-31`. Send `Commet-Version: 2026-07-31` with your request.


## OpenAPI

````yaml /openapi/en/rest/2026-07-31.json post /subscriptions
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-07-31'
  description: Billing and payments API for SaaS and AI products.
servers:
  - url: https://commet.co/api/v1
security:
  - ApiKeyAuth: []
tags:
  - name: Test Clock
    description: >-
      Simulate the passage of time in sandbox to test billing flows. Mirrors
      Stripe test clocks: forward-only and sandbox-only.
  - name: Customers
  - name: Subscriptions
  - name: Plans
  - name: Markets
    description: >-
      Reusable country groups for market-specific prices and selectable price
      variants.
  - name: Offers
  - name: Promo Codes
  - name: Features
  - name: Usage
  - name: Seats
  - name: Quota
  - name: Add-ons
  - name: Portal
  - name: Credit Packs
  - name: Plan Groups
  - name: Invoices
  - name: Payments
    description: >-
      One-time payments with no subscription or plan. Charge a customer's saved
      payment method off-session, or create a payment link the customer opens to
      pay. Tax, invoice, and receipt are handled automatically.
  - name: Transactions
  - name: Webhooks
  - name: API Keys
  - name: Payouts
    description: >-
      Withdraw available balance to your bank and manage the payout account
      (verification + destination bank accounts).
  - name: Provisioning
    description: >-
      Take ownership of an organization an agent provisioned headlessly. The
      agent holds the API keys from the start; a human claims the account
      through a claim link.
paths:
  /subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Create subscription
      description: >-
        Create a subscription for a customer. Commet selects the default price
        when priceId is omitted. The subscription starts at the base USD price;
        market and currency are resolved from the buyer's request country when
        the checkout opens. Without an offer override, Commet applies the
        price's automatic introductory Offer. Pass offerId to apply an active
        compatible Offer directly, or cardPromotionId to preselect a
        card-eligible Promotional Offer for the initial checkout when card
        promotions are enabled for the organization. For the initial checkout,
        provider accepts either a processor name or an exact payment connection
        ID. When the price's free trial requires no payment method, the
        subscription starts trialing right away with no checkout (checkoutUrl
        null, hasPaymentMethod false); it cannot be combined with offerId,
        promoCode, cardPromotionId or provider, and an organization that cannot
        charge yet receives 403.
      operationId: create-subscription
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Unique key used to safely retry this write for 24 hours without
            applying it twice.
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - name: Commet-Version
          in: header
          required: false
          description: >-
            API version used by this reference. Send this header to select this
            contract explicitly.
          schema:
            type: string
            default: '2026-07-31'
          example: '2026-07-31'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    customerId:
                      type: string
                      minLength: 1
                      maxLength: 200
                    billingInterval:
                      anyOf:
                        - type: string
                          enum:
                            - weekly
                            - monthly
                            - quarterly
                            - semiannual
                            - yearly
                            - one_time
                        - type: 'null'
                    priceId:
                      description: >-
                        Public price ID. When omitted, Commet selects the
                        default price for the billing interval and still applies
                        its market pricing.
                      type: string
                      minLength: 1
                    initialSeats:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    provider:
                      anyOf:
                        - type: string
                          enum:
                            - stripe
                            - commet
                            - dlocal
                        - type: string
                          pattern: ^pcon_.*
                      description: >-
                        Payment provider name or exact public payment connection
                        ID for the initial checkout. Overrides country routing
                        when present.
                    paymentMethodTypes:
                      minItems: 1
                      type: array
                      items:
                        type: string
                        enum:
                          - card
                          - oxxo
                          - mercado_pago
                          - google_pay
                          - smartpix
                      description: >-
                        Payment methods the initial checkout may offer.
                        Restricts what the checkout already offers for the
                        buyer's country, currency and payment connection; it
                        never enables a method the connection does not have and
                        never changes routing. When none of them is available to
                        the buyer, the checkout shows that it cannot accept
                        payments.
                    name:
                      type: string
                    startDate:
                      type: string
                      format: date-time
                    successUrl:
                      type: string
                      format: uri
                    prepaidPeriods:
                      description: >-
                        Billing periods of the subscription's interval paid with
                        the first payment, including the current one. Defaults
                        to 1. The interval does not change: each paid period
                        renews at zero and the subscription renews normally
                        after the last one unless `cancelAtPeriodEnd` is true.
                      type: integer
                      minimum: 1
                      maximum: 60
                    cancelAtPeriodEnd:
                      description: >-
                        Schedules the cancellation from creation so the
                        subscription ends after its last paid period and never
                        renews with any payment method.
                      type: boolean
                    planVersionId:
                      description: >-
                        Public ID of a published version of the plan, current or
                        not, including an experiment's versions. The
                        subscription is created on that version and stays on it:
                        checkout charges its price and activation grants its
                        credits, add-ons and credit packs. When omitted, the
                        subscription gets the current version, or the version an
                        experiment code (planCode `<plan code>:<experiment
                        code>`) sells.
                      type: string
                      minLength: 1
                    offerId:
                      not: {}
                    promoCode:
                      type: string
                      minLength: 1
                    customTrialDays:
                      description: >-
                        Trial length in days, replacing the price's trial. A
                        customer who already had this plan, in a trial or
                        paying, gets no trial and goes through the regular
                        checkout.
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    skipTrial:
                      default: false
                      type: boolean
                    planId:
                      type: string
                      minLength: 1
                  required:
                    - customerId
                    - planId
                  additionalProperties: false
                - type: object
                  properties:
                    customerId:
                      type: string
                      minLength: 1
                      maxLength: 200
                    billingInterval:
                      anyOf:
                        - type: string
                          enum:
                            - weekly
                            - monthly
                            - quarterly
                            - semiannual
                            - yearly
                            - one_time
                        - type: 'null'
                    priceId:
                      description: >-
                        Public price ID. When omitted, Commet selects the
                        default price for the billing interval and still applies
                        its market pricing.
                      type: string
                      minLength: 1
                    initialSeats:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    provider:
                      anyOf:
                        - type: string
                          enum:
                            - stripe
                            - commet
                            - dlocal
                        - type: string
                          pattern: ^pcon_.*
                      description: >-
                        Payment provider name or exact public payment connection
                        ID for the initial checkout. Overrides country routing
                        when present.
                    paymentMethodTypes:
                      minItems: 1
                      type: array
                      items:
                        type: string
                        enum:
                          - card
                          - oxxo
                          - mercado_pago
                          - google_pay
                          - smartpix
                      description: >-
                        Payment methods the initial checkout may offer.
                        Restricts what the checkout already offers for the
                        buyer's country, currency and payment connection; it
                        never enables a method the connection does not have and
                        never changes routing. When none of them is available to
                        the buyer, the checkout shows that it cannot accept
                        payments.
                    name:
                      type: string
                    startDate:
                      type: string
                      format: date-time
                    successUrl:
                      type: string
                      format: uri
                    prepaidPeriods:
                      description: >-
                        Billing periods of the subscription's interval paid with
                        the first payment, including the current one. Defaults
                        to 1. The interval does not change: each paid period
                        renews at zero and the subscription renews normally
                        after the last one unless `cancelAtPeriodEnd` is true.
                      type: integer
                      minimum: 1
                      maximum: 60
                    cancelAtPeriodEnd:
                      description: >-
                        Schedules the cancellation from creation so the
                        subscription ends after its last paid period and never
                        renews with any payment method.
                      type: boolean
                    planVersionId:
                      description: >-
                        Public ID of a published version of the plan, current or
                        not, including an experiment's versions. The
                        subscription is created on that version and stays on it:
                        checkout charges its price and activation grants its
                        credits, add-ons and credit packs. When omitted, the
                        subscription gets the current version, or the version an
                        experiment code (planCode `<plan code>:<experiment
                        code>`) sells.
                      type: string
                      minLength: 1
                    offerId:
                      not: {}
                    promoCode:
                      type: string
                      minLength: 1
                    customTrialDays:
                      description: >-
                        Trial length in days, replacing the price's trial. A
                        customer who already had this plan, in a trial or
                        paying, gets no trial and goes through the regular
                        checkout.
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    skipTrial:
                      default: false
                      type: boolean
                    planCode:
                      type: string
                      minLength: 1
                      description: >-
                        The plan code, or an experiment code as `<plan
                        code>:<experiment code>` to sell the version the
                        experiment sells.
                  required:
                    - customerId
                    - planCode
                  additionalProperties: false
                - type: object
                  properties:
                    customerId:
                      type: string
                      minLength: 1
                      maxLength: 200
                    billingInterval:
                      anyOf:
                        - type: string
                          enum:
                            - weekly
                            - monthly
                            - quarterly
                            - semiannual
                            - yearly
                            - one_time
                        - type: 'null'
                    priceId:
                      description: >-
                        Public price ID. When omitted, Commet selects the
                        default price for the billing interval and still applies
                        its market pricing.
                      type: string
                      minLength: 1
                    initialSeats:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    provider:
                      anyOf:
                        - type: string
                          enum:
                            - stripe
                            - commet
                            - dlocal
                        - type: string
                          pattern: ^pcon_.*
                      description: >-
                        Payment provider name or exact public payment connection
                        ID for the initial checkout. Overrides country routing
                        when present.
                    paymentMethodTypes:
                      minItems: 1
                      type: array
                      items:
                        type: string
                        enum:
                          - card
                          - oxxo
                          - mercado_pago
                          - google_pay
                          - smartpix
                      description: >-
                        Payment methods the initial checkout may offer.
                        Restricts what the checkout already offers for the
                        buyer's country, currency and payment connection; it
                        never enables a method the connection does not have and
                        never changes routing. When none of them is available to
                        the buyer, the checkout shows that it cannot accept
                        payments.
                    name:
                      type: string
                    startDate:
                      type: string
                      format: date-time
                    successUrl:
                      type: string
                      format: uri
                    prepaidPeriods:
                      description: >-
                        Billing periods of the subscription's interval paid with
                        the first payment, including the current one. Defaults
                        to 1. The interval does not change: each paid period
                        renews at zero and the subscription renews normally
                        after the last one unless `cancelAtPeriodEnd` is true.
                      type: integer
                      minimum: 1
                      maximum: 60
                    cancelAtPeriodEnd:
                      description: >-
                        Schedules the cancellation from creation so the
                        subscription ends after its last paid period and never
                        renews with any payment method.
                      type: boolean
                    planVersionId:
                      description: >-
                        Public ID of a published version of the plan, current or
                        not, including an experiment's versions. The
                        subscription is created on that version and stays on it:
                        checkout charges its price and activation grants its
                        credits, add-ons and credit packs. When omitted, the
                        subscription gets the current version, or the version an
                        experiment code (planCode `<plan code>:<experiment
                        code>`) sells.
                      type: string
                      minLength: 1
                    offerId:
                      type: string
                      minLength: 1
                    promoCode:
                      not: {}
                    customTrialDays:
                      description: >-
                        Trial length in days, replacing the price's trial. A
                        customer who already had this plan, in a trial or
                        paying, gets no trial and goes through the regular
                        checkout.
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    skipTrial:
                      default: false
                      type: boolean
                    planId:
                      type: string
                      minLength: 1
                  required:
                    - customerId
                    - offerId
                    - planId
                  additionalProperties: false
                - type: object
                  properties:
                    customerId:
                      type: string
                      minLength: 1
                      maxLength: 200
                    billingInterval:
                      anyOf:
                        - type: string
                          enum:
                            - weekly
                            - monthly
                            - quarterly
                            - semiannual
                            - yearly
                            - one_time
                        - type: 'null'
                    priceId:
                      description: >-
                        Public price ID. When omitted, Commet selects the
                        default price for the billing interval and still applies
                        its market pricing.
                      type: string
                      minLength: 1
                    initialSeats:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    provider:
                      anyOf:
                        - type: string
                          enum:
                            - stripe
                            - commet
                            - dlocal
                        - type: string
                          pattern: ^pcon_.*
                      description: >-
                        Payment provider name or exact public payment connection
                        ID for the initial checkout. Overrides country routing
                        when present.
                    paymentMethodTypes:
                      minItems: 1
                      type: array
                      items:
                        type: string
                        enum:
                          - card
                          - oxxo
                          - mercado_pago
                          - google_pay
                          - smartpix
                      description: >-
                        Payment methods the initial checkout may offer.
                        Restricts what the checkout already offers for the
                        buyer's country, currency and payment connection; it
                        never enables a method the connection does not have and
                        never changes routing. When none of them is available to
                        the buyer, the checkout shows that it cannot accept
                        payments.
                    name:
                      type: string
                    startDate:
                      type: string
                      format: date-time
                    successUrl:
                      type: string
                      format: uri
                    prepaidPeriods:
                      description: >-
                        Billing periods of the subscription's interval paid with
                        the first payment, including the current one. Defaults
                        to 1. The interval does not change: each paid period
                        renews at zero and the subscription renews normally
                        after the last one unless `cancelAtPeriodEnd` is true.
                      type: integer
                      minimum: 1
                      maximum: 60
                    cancelAtPeriodEnd:
                      description: >-
                        Schedules the cancellation from creation so the
                        subscription ends after its last paid period and never
                        renews with any payment method.
                      type: boolean
                    planVersionId:
                      description: >-
                        Public ID of a published version of the plan, current or
                        not, including an experiment's versions. The
                        subscription is created on that version and stays on it:
                        checkout charges its price and activation grants its
                        credits, add-ons and credit packs. When omitted, the
                        subscription gets the current version, or the version an
                        experiment code (planCode `<plan code>:<experiment
                        code>`) sells.
                      type: string
                      minLength: 1
                    offerId:
                      type: string
                      minLength: 1
                    promoCode:
                      not: {}
                    customTrialDays:
                      description: >-
                        Trial length in days, replacing the price's trial. A
                        customer who already had this plan, in a trial or
                        paying, gets no trial and goes through the regular
                        checkout.
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    skipTrial:
                      default: false
                      type: boolean
                    planCode:
                      type: string
                      minLength: 1
                      description: >-
                        The plan code, or an experiment code as `<plan
                        code>:<experiment code>` to sell the version the
                        experiment sells.
                  required:
                    - customerId
                    - offerId
                    - planCode
                  additionalProperties: false
                - type: object
                  properties:
                    customerId:
                      type: string
                      minLength: 1
                      maxLength: 200
                    billingInterval:
                      anyOf:
                        - type: string
                          enum:
                            - weekly
                            - monthly
                            - quarterly
                            - semiannual
                            - yearly
                            - one_time
                        - type: 'null'
                    priceId:
                      description: >-
                        Public price ID. When omitted, Commet selects the
                        default price for the billing interval and still applies
                        its market pricing.
                      type: string
                      minLength: 1
                    initialSeats:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    provider:
                      anyOf:
                        - type: string
                          enum:
                            - stripe
                            - commet
                            - dlocal
                        - type: string
                          pattern: ^pcon_.*
                      description: >-
                        Payment provider name or exact public payment connection
                        ID for the initial checkout. Overrides country routing
                        when present.
                    paymentMethodTypes:
                      minItems: 1
                      type: array
                      items:
                        type: string
                        enum:
                          - card
                          - oxxo
                          - mercado_pago
                          - google_pay
                          - smartpix
                      description: >-
                        Payment methods the initial checkout may offer.
                        Restricts what the checkout already offers for the
                        buyer's country, currency and payment connection; it
                        never enables a method the connection does not have and
                        never changes routing. When none of them is available to
                        the buyer, the checkout shows that it cannot accept
                        payments.
                    name:
                      type: string
                    startDate:
                      type: string
                      format: date-time
                    successUrl:
                      type: string
                      format: uri
                    prepaidPeriods:
                      description: >-
                        Billing periods of the subscription's interval paid with
                        the first payment, including the current one. Defaults
                        to 1. The interval does not change: each paid period
                        renews at zero and the subscription renews normally
                        after the last one unless `cancelAtPeriodEnd` is true.
                      type: integer
                      minimum: 1
                      maximum: 60
                    cancelAtPeriodEnd:
                      description: >-
                        Schedules the cancellation from creation so the
                        subscription ends after its last paid period and never
                        renews with any payment method.
                      type: boolean
                    planVersionId:
                      description: >-
                        Public ID of a published version of the plan, current or
                        not, including an experiment's versions. The
                        subscription is created on that version and stays on it:
                        checkout charges its price and activation grants its
                        credits, add-ons and credit packs. When omitted, the
                        subscription gets the current version, or the version an
                        experiment code (planCode `<plan code>:<experiment
                        code>`) sells.
                      type: string
                      minLength: 1
                    offerId:
                      not: {}
                    cardPromotionId:
                      type: string
                      minLength: 1
                      description: >-
                        Public card promotion ID. The offer is shown immediately
                        and remains conditional on card eligibility until
                        checkout confirmation.
                    promoCode:
                      not: {}
                    customTrialDays:
                      not: {}
                    skipTrial:
                      default: false
                      type: boolean
                      const: false
                    planId:
                      type: string
                      minLength: 1
                  required:
                    - customerId
                    - cardPromotionId
                    - planId
                  additionalProperties: false
                - type: object
                  properties:
                    customerId:
                      type: string
                      minLength: 1
                      maxLength: 200
                    billingInterval:
                      anyOf:
                        - type: string
                          enum:
                            - weekly
                            - monthly
                            - quarterly
                            - semiannual
                            - yearly
                            - one_time
                        - type: 'null'
                    priceId:
                      description: >-
                        Public price ID. When omitted, Commet selects the
                        default price for the billing interval and still applies
                        its market pricing.
                      type: string
                      minLength: 1
                    initialSeats:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    provider:
                      anyOf:
                        - type: string
                          enum:
                            - stripe
                            - commet
                            - dlocal
                        - type: string
                          pattern: ^pcon_.*
                      description: >-
                        Payment provider name or exact public payment connection
                        ID for the initial checkout. Overrides country routing
                        when present.
                    paymentMethodTypes:
                      minItems: 1
                      type: array
                      items:
                        type: string
                        enum:
                          - card
                          - oxxo
                          - mercado_pago
                          - google_pay
                          - smartpix
                      description: >-
                        Payment methods the initial checkout may offer.
                        Restricts what the checkout already offers for the
                        buyer's country, currency and payment connection; it
                        never enables a method the connection does not have and
                        never changes routing. When none of them is available to
                        the buyer, the checkout shows that it cannot accept
                        payments.
                    name:
                      type: string
                    startDate:
                      type: string
                      format: date-time
                    successUrl:
                      type: string
                      format: uri
                    prepaidPeriods:
                      description: >-
                        Billing periods of the subscription's interval paid with
                        the first payment, including the current one. Defaults
                        to 1. The interval does not change: each paid period
                        renews at zero and the subscription renews normally
                        after the last one unless `cancelAtPeriodEnd` is true.
                      type: integer
                      minimum: 1
                      maximum: 60
                    cancelAtPeriodEnd:
                      description: >-
                        Schedules the cancellation from creation so the
                        subscription ends after its last paid period and never
                        renews with any payment method.
                      type: boolean
                    planVersionId:
                      description: >-
                        Public ID of a published version of the plan, current or
                        not, including an experiment's versions. The
                        subscription is created on that version and stays on it:
                        checkout charges its price and activation grants its
                        credits, add-ons and credit packs. When omitted, the
                        subscription gets the current version, or the version an
                        experiment code (planCode `<plan code>:<experiment
                        code>`) sells.
                      type: string
                      minLength: 1
                    offerId:
                      not: {}
                    cardPromotionId:
                      type: string
                      minLength: 1
                      description: >-
                        Public card promotion ID. The offer is shown immediately
                        and remains conditional on card eligibility until
                        checkout confirmation.
                    promoCode:
                      not: {}
                    customTrialDays:
                      not: {}
                    skipTrial:
                      default: false
                      type: boolean
                      const: false
                    planCode:
                      type: string
                      minLength: 1
                      description: >-
                        The plan code, or an experiment code as `<plan
                        code>:<experiment code>` to sell the version the
                        experiment sells.
                  required:
                    - customerId
                    - cardPromotionId
                    - planCode
                  additionalProperties: false
      responses:
        '201':
          description: Success
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedSubscription'
        '400':
          description: Bad request
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: string
            RateLimit-Reset:
              description: Seconds until the rate limit window resets.
              schema:
                type: string
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  headers:
    RequestId:
      description: >-
        Server-generated identifier that correlates this response with Platform
        logs.
      schema:
        type: string
        format: uuid
  schemas:
    CreatedSubscription:
      type: object
      properties:
        id:
          type: string
        customerId:
          type: string
        plan:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
          required:
            - id
            - name
          additionalProperties: false
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        status:
          $ref: '#/components/schemas/SubscriptionStatus'
        billingInterval:
          anyOf:
            - $ref: '#/components/schemas/BillingInterval'
            - type: 'null'
        trialEndsAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        currentPeriod:
          anyOf:
            - type: object
              properties:
                start:
                  type: string
                  format: date-time
                end:
                  type: string
                  format: date-time
                daysRemaining:
                  type: number
              required:
                - start
                - end
                - daysRemaining
              additionalProperties: false
            - type: 'null'
        cancellation:
          anyOf:
            - type: object
              properties:
                scheduledAt:
                  type: string
                  format: date-time
                reason:
                  type:
                    - string
                    - 'null'
                effectiveAt:
                  type: string
                  format: date-time
              required:
                - scheduledAt
                - reason
                - effectiveAt
              additionalProperties: false
            - type: 'null'
        cancelAtPeriodEnd:
          type: boolean
        scheduledPlanChange:
          anyOf:
            - type: object
              properties:
                changeType:
                  type: string
                  enum:
                    - plan_downgrade
                    - interval_change
                newPlanId:
                  type:
                    - string
                    - 'null'
                newPlanName:
                  type:
                    - string
                    - 'null'
                newBillingInterval:
                  type:
                    - string
                    - 'null'
                scheduledFor:
                  type: string
                  format: date-time
              required:
                - changeType
                - newPlanId
                - newPlanName
                - newBillingInterval
                - scheduledFor
              additionalProperties: false
            - type: 'null'
        startDate:
          type: string
          format: date-time
        endDate:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        billingDayOfMonth:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        nextBillingDate:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        checkoutUrl:
          type:
            - string
            - 'null'
        hasPaymentMethod:
          type: boolean
          description: >-
            Whether Commet can charge this subscription on its own at its next
            charge (the trial end or the renewal). A trial that started without
            a payment method reports false until the customer adds one for this
            subscription; a payment method saved for another subscription does
            not count. A subscription on a free plan reports false.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        planVersion:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                  description: Public plan version ID.
                label:
                  type: string
                  description: >-
                    Main versions are 1, 2, 3; an experiment's versions carry
                    its own code, like price-test 2.
              required:
                - id
                - label
              additionalProperties: false
            - type: 'null'
          description: >-
            The plan version whose terms the subscription has now. It keeps
            paying and receiving everything from this version until it is moved.
        offerApplications:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionOfferApplication'
        checkoutProvider:
          anyOf:
            - $ref: '#/components/schemas/PaymentProvider'
            - type: 'null'
          description: >-
            Payment provider resolved for this checkout when the subscription
            response was created. This is an informational snapshot and may
            differ when the checkout is loaded if its country or the
            organization's routing changes.
        priceId:
          type:
            - string
            - 'null'
        object:
          type: string
          const: subscription
        livemode:
          type: boolean
      required:
        - id
        - customerId
        - plan
        - name
        - description
        - status
        - billingInterval
        - trialEndsAt
        - currentPeriod
        - cancellation
        - cancelAtPeriodEnd
        - scheduledPlanChange
        - startDate
        - endDate
        - billingDayOfMonth
        - nextBillingDate
        - checkoutUrl
        - hasPaymentMethod
        - createdAt
        - updatedAt
        - planVersion
        - offerApplications
        - checkoutProvider
        - priceId
        - object
        - livemode
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            param:
              type: string
            details: {}
            doc_url:
              type: string
          required:
            - type
            - code
            - message
            - doc_url
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    SubscriptionStatus:
      type: string
      enum:
        - draft
        - pending_payment
        - trialing
        - active
        - past_due
        - paused
        - canceled
    BillingInterval:
      type: string
      enum:
        - weekly
        - monthly
        - quarterly
        - semiannual
        - yearly
        - one_time
    SubscriptionOfferApplication:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        appliesTo:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  const: plan_price
                id:
                  type: string
              required:
                - type
                - id
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  const: addon
                id:
                  type: string
              required:
                - type
                - id
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  const: credit_pack
                id:
                  type: string
              required:
                - type
                - id
              additionalProperties: false
        offerId:
          type:
            - string
            - 'null'
        source:
          type: string
          enum:
            - direct
            - introductory
            - promo_code
            - card_promotion
            - custom
        status:
          type: string
          enum:
            - quoted
            - applied
            - failed
            - expired
        currency:
          type:
            - string
            - 'null'
        subtotal:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        discountAmount:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        total:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        phases:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionOfferApplicationPhase'
        quotedAt:
          type: string
          format: date-time
        expiresAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        appliedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
      required:
        - id
        - name
        - appliesTo
        - offerId
        - source
        - status
        - currency
        - subtotal
        - discountAmount
        - total
        - phases
        - quotedAt
        - expiresAt
        - appliedAt
      additionalProperties: false
    PaymentProvider:
      type: string
      enum:
        - stripe
        - commet
        - dlocal
    SubscriptionOfferApplicationPhase:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              const: free_trial
            durationDays:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            durationInterval:
              anyOf:
                - type: string
                  enum:
                    - weekly
                    - monthly
                    - quarterly
                    - semiannual
                    - yearly
                - type: 'null'
            startsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
            endsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
          required:
            - type
            - durationDays
            - durationInterval
            - startsAt
            - endsAt
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: percentage
            durationCycles:
              anyOf:
                - type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            durationInterval:
              anyOf:
                - type: string
                  enum:
                    - weekly
                    - monthly
                    - quarterly
                    - semiannual
                    - yearly
                - type: 'null'
            percentage:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            startsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
            endsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
          required:
            - type
            - durationCycles
            - durationInterval
            - percentage
            - startsAt
            - endsAt
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: amount_off
            durationCycles:
              anyOf:
                - type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            durationInterval:
              anyOf:
                - type: string
                  enum:
                    - weekly
                    - monthly
                    - quarterly
                    - semiannual
                    - yearly
                - type: 'null'
            amount:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            startsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
            endsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
          required:
            - type
            - durationCycles
            - durationInterval
            - amount
            - startsAt
            - endsAt
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: fixed_price
            durationCycles:
              anyOf:
                - type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            durationInterval:
              anyOf:
                - type: string
                  enum:
                    - weekly
                    - monthly
                    - quarterly
                    - semiannual
                    - yearly
                - type: 'null'
            price:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            startsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
            endsAt:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
          required:
            - type
            - durationCycles
            - durationInterval
            - price
            - startsAt
            - endsAt
          additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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