> ## 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. Requires planId or planCode plus customerId. If the subscription is saved but its initial payment checkout cannot be created, the endpoint returns `subscription_activation_failed`; retry the same request to recover the pending subscription without creating another invoice.

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


## OpenAPI

````yaml /openapi/es/rest/2026-06-07.json post /subscriptions
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-06-07'
  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: 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. Requires planId or planCode plus
        customerId. If the subscription is saved but its initial payment
        checkout cannot be created, the endpoint returns
        `subscription_activation_failed`; retry the same request to recover the
        pending subscription without creating another invoice.
      operationId: create-subscription
      parameters:
        - 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-06-07'
          example: '2026-06-07'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                planId:
                  type: string
                  minLength: 1
                planCode:
                  type: string
                customerId:
                  type: string
                  minLength: 1
                  maxLength: 200
                billingInterval:
                  anyOf:
                    - type: string
                      enum:
                        - weekly
                        - monthly
                        - quarterly
                        - semiannual
                        - yearly
                        - one_time
                    - type: 'null'
                initialSeats:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                skipTrial:
                  default: false
                  type: boolean
                customTrialDays:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                introOffer:
                  type: object
                  properties:
                    discountType:
                      type: string
                      enum:
                        - percentage
                        - amount
                    discountValue:
                      type: integer
                      minimum: 1
                      maximum: 9007199254740991
                    durationCycles:
                      type: integer
                      minimum: 1
                      maximum: 9007199254740991
                  required:
                    - discountType
                    - discountValue
                    - durationCycles
                  additionalProperties: false
                promoCode:
                  type: string
                  minLength: 1
                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
              required:
                - customerId
                - skipTrial
              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:
                type: object
                properties:
                  success:
                    const: true
                  data:
                    $ref: '#/components/schemas/CreatedSubscription'
                required:
                  - success
                  - data
        '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'
        '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'
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:
          type: string
          enum:
            - draft
            - pending_payment
            - trialing
            - active
            - past_due
            - canceled
        billingInterval:
          anyOf:
            - type: string
              enum:
                - weekly
                - monthly
                - quarterly
                - semiannual
                - yearly
                - one_time
            - 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.
        checkoutProvider:
          anyOf:
            - type: string
              enum:
                - stripe
                - commet
                - dlocal
            - 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.
        object:
          type: string
          const: subscription
        livemode:
          type: boolean
        discount:
          anyOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - percentage
                    - amount
                value:
                  type: number
                name:
                  anyOf:
                    - type: string
                    - type: 'null'
                endsAt:
                  anyOf:
                    - type: string
                      format: date-time
                    - type: 'null'
              required:
                - type
                - value
                - name
                - endsAt
              additionalProperties: false
            - type: 'null'
      required:
        - id
        - customerId
        - plan
        - name
        - description
        - status
        - billingInterval
        - trialEndsAt
        - currentPeriod
        - cancellation
        - cancelAtPeriodEnd
        - scheduledPlanChange
        - startDate
        - endDate
        - billingDayOfMonth
        - nextBillingDate
        - checkoutUrl
        - hasPaymentMethod
        - createdAt
        - updatedAt
        - planVersion
        - discount
        - checkoutProvider
        - object
        - livemode
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        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:
        - success
        - error
      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.