> ## 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 and resolves its market from the customer's billing country. 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. Create a subscription for a customer. Commet selects the default price when priceId is omitted and resolves its market from the customer's billing country. 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. ## OpenAPI ````yaml /openapi/es/rest/2026-08-27.json post /subscriptions openapi: 3.1.0 info: title: Commet API version: '2026-08-27' 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 and resolves its market from the customer's billing country. 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. 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-08-27' example: '2026-08-27' 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 - 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. name: type: string startDate: type: string format: date-time successUrl: type: string format: uri offerId: not: {} promoCode: type: string minLength: 1 customTrialDays: 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 - 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. name: type: string startDate: type: string format: date-time successUrl: type: string format: uri offerId: not: {} promoCode: type: string minLength: 1 customTrialDays: type: integer minimum: 0 maximum: 9007199254740991 skipTrial: default: false type: boolean planCode: type: string minLength: 1 required: - customerId - planCode additionalProperties: false - type: object properties: customerId: type: string minLength: 1 maxLength: 200 billingInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - 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. name: type: string startDate: type: string format: date-time successUrl: type: string format: uri offerId: type: string minLength: 1 promoCode: not: {} customTrialDays: not: {} skipTrial: default: false type: boolean const: false 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 - 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. name: type: string startDate: type: string format: date-time successUrl: type: string format: uri offerId: type: string minLength: 1 promoCode: not: {} customTrialDays: not: {} skipTrial: default: false type: boolean const: false planCode: type: string minLength: 1 required: - customerId - offerId - planCode additionalProperties: false - type: object properties: customerId: type: string minLength: 1 maxLength: 200 billingInterval: anyOf: - type: string enum: - weekly - monthly - quarterly - 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. name: type: string startDate: type: string format: date-time successUrl: type: string format: uri 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 - 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. name: type: string startDate: type: string format: date-time successUrl: type: string format: uri 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 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' example: id: sub_1a2b3c4d customerId: cus_1a2b3c4d plan: id: plan_1a2b3c4d name: Pro name: Pro description: null status: pending_payment billingInterval: monthly trialEndsAt: null currentPeriod: null cancellation: null cancelAtPeriodEnd: false scheduledPlanChange: null startDate: '2026-09-07T12:00:00.000Z' endDate: null billingDayOfMonth: null nextBillingDate: null checkoutUrl: https://commet.co/checkout/example_checkout_token createdAt: '2026-09-07T12:00:00.000Z' updatedAt: '2026-09-07T12:00:00.000Z' offerApplications: [] pause: null priceId: price_1a2b3c4d object: subscription livemode: false checkoutProvider: commet '400': description: Bad request headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: validation_error code: validation_error message: The request contains an invalid parameter. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md '401': description: Unauthorized headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: authentication_error code: unauthorized message: A valid API key is required. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md '403': description: Forbidden headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: authentication_error code: forbidden message: You do not have permission to perform this operation. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md '404': description: Not found headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: not_found_error code: not_found message: The requested resource was not found. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md '409': description: Conflict headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: conflict_error code: idempotency_in_progress message: >- A request with this idempotency key is still being processed. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md '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' example: error: type: rate_limit_error code: rate_limited message: >- Too many requests. Retry after the interval specified in the Retry-After header. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md '500': description: Internal server error headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: internal_error code: internal_error message: An unexpected error occurred while processing the request. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md '503': description: Service unavailable headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: internal_error code: idempotency_unavailable message: >- Idempotency storage is temporarily unavailable. Retry with the same idempotency key. doc_url: >- https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md x-codeSamples: - lang: typescript label: TypeScript source: |- import { Commet } from "@commet/node"; const commet = new Commet({ apiKey: "ck_xxx" }); const createdSubscription = await commet.subscriptions.create({ customerId: "user_123", planId: "pln_xxx", }); - lang: python label: Python source: |- from commet import Commet commet = Commet("ck_xxx") created_subscription = commet.subscriptions.create( customer_id="user_123", plan_id="pln_xxx", ) - lang: go label: Go source: "client, err := commet.New(\"ck_xxx\")\nif err != nil {\n\tlog.Fatal(err)\n}\nctx := context.Background()\n\ncreatedSubscription, err := client.Subscriptions.Create(ctx, &commet.CreateSubscriptionParams{\n\tCustomerID: \"user_123\",\n\tPlanID: func(value string) *string { return &value }(\"pln_xxx\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}" - lang: java label: Java source: |- import co.commet.Commet; import co.commet.params.CreateSubscriptionParams; var commet = Commet.builder().apiKey("ck_xxx").build(); var createdSubscription = commet.subscriptions().create( CreateSubscriptionParams.builder("user_123").planId("pln_xxx").build() ); - lang: php label: PHP source: |- use Commet\Commet; $commet = new Commet('ck_xxx'); $createdSubscription = $commet->subscriptions->create( customerId: 'user_123', planId: 'pln_xxx', ); 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: anyOf: - type: string - type: '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: anyOf: - type: string - type: '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: anyOf: - type: string - type: 'null' newPlanName: anyOf: - type: string - type: 'null' newBillingInterval: anyOf: - type: string - type: '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: anyOf: - type: string - type: 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time offerApplications: type: array items: $ref: '#/components/schemas/SubscriptionOfferApplication' pause: anyOf: - oneOf: - type: object properties: status: type: string const: scheduled mode: type: string const: period_end requestedAt: type: string format: date-time effectiveAt: type: string format: date-time resumeAt: anyOf: - type: string format: date-time - type: 'null' required: - status - mode - requestedAt - effectiveAt - resumeAt additionalProperties: false - type: object properties: status: type: string const: active mode: type: string enum: - immediate - period_end requestedAt: type: string format: date-time effectiveAt: type: string format: date-time resumeAt: anyOf: - type: string format: date-time - type: 'null' required: - status - mode - requestedAt - effectiveAt - resumeAt additionalProperties: false - type: 'null' 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: anyOf: - type: string - type: '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 - createdAt - updatedAt - offerApplications - pause - 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 - 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: anyOf: - type: string - type: 'null' source: type: string enum: - direct - introductory - promo_code - card_promotion - custom status: type: string enum: - quoted - applied - failed - expired currency: anyOf: - type: string - type: '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 - 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 - 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 - 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 - 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 ```` ## Related topics - [Pagos únicos](/docs/es/one-time-payments.md) - [Create a recovery payment link for a past due subscription](/docs/es/api-reference/subscriptions/create-subscription-recovery-link.md) - [subscription.created](/docs/es/webhooks/subscription-created.md) - [Create webhook endpoint](/docs/es/api-reference/webhooks/create-webhook-endpoint.md) - [Create a payment link](/docs/es/api-reference/payments/create-payment.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.