> ## Documentation Index > Fetch the complete documentation index at: https://docs.quentli.com/llms.txt > Use this file to discover all available pages before exploring further. # Create subscription > Creates a new recurring subscription for a customer. ## OpenAPI ````yaml /openapi.yaml post /v1/subscriptions openapi: 3.0.3 info: title: Quentli REST API version: 1.0.0 description: OpenAPI spec for Quentli REST endpoints. servers: - url: https://api.quentli.com description: Production API - url: https://api.staging.quentli.com description: Staging API for production-like validation - url: https://api.demo.quentli.com description: Demo API hostname served by staging security: - organizationApiKey: [] tags: - name: Auth - name: Billing - name: Catalog - name: Customers - name: Invoices - name: Payment Methods - name: Payment Sessions - name: Payments - name: Subscriptions - name: Tax Invoices - name: Webhooks paths: /v1/subscriptions: post: tags: - Subscriptions summary: Create subscription description: Creates a new recurring subscription for a customer. operationId: subscriptions_create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionArgs' responses: '200': description: Subscription created content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionPayload' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/UserError' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/UserError' '403': description: Permission denied content: application/json: schema: $ref: '#/components/schemas/UserError' components: schemas: CreateSubscriptionArgs: type: object properties: input: type: object properties: description: type: string description: >- Human-readable description of the subscription. Auto-generated from item names when omitted. example: Colegiatura mensual nextCollectionDate: anyOf: - type: string description: Date string - type: string format: date-time description: Date object - nullable: true description: >- Date of the first (or next) charge. Required when using recurring `items`. example: '2025-06-01T00:00:00.000Z' numberOfPayments: type: number nullable: true minimum: 1 maximum: 999 description: >- Total number of invoices to generate before the subscription ends. Null means indefinite. example: 12 onlyAutomaticCollection: type: boolean description: >- Whether this subscription only allows automatic payment collection. example: false beneficiaryId: type: string nullable: true description: >- Optional identifier of a different customer who is the actual beneficiary. example: null taxProfileId: type: string nullable: true description: Optional tax profile to use for invoice generation. example: null customerId: type: string description: Identifier of the customer who will be charged. example: cus_1234567890abcdefghij templateId: type: string description: Optional template to use for subscription messaging. example: null collectionMethod: type: string enum: - SEND_REMINDER - AUTOMATIC - NONE description: >- How payment is collected: SEND_REMINDER sends a notification, AUTOMATIC charges a saved payment method, NONE does nothing. example: SEND_REMINDER paymentMethodId: type: string nullable: true description: >- Identifier of the payment method to use for automatic collection. Falls back to the customer's default method. example: null recurrentDetail: type: object properties: chargeEach: type: number minimum: 1 maximum: 999 description: Number of intervals between charges. example: 1 collectionInterval: type: string enum: - DAY - WEEK - FORTNIGHT - MONTH - YEAR description: Time interval unit (e.g. MONTH, WEEK). example: MONTH toleranceDays: type: integer nullable: true minimum: 0 description: Grace days after the due date before the invoice expires. example: 5 required: - chargeEach - collectionInterval description: >- Custom recurrence configuration. Inferred from the concepts when omitted. modifiers: type: array items: type: object properties: modifierId: type: string description: Identifier of the price modifier to attach. example: prm_1234567890abcdefghij required: - modifierId description: >- Price modifiers (early payment discounts or late payment interest) to apply to every generated invoice. discounts: type: array items: type: object properties: discountId: type: string description: Identifier of the discount to apply. example: disc_1234567890abcdefghij maxInvoices: type: integer nullable: true minimum: 1 description: >- Maximum number of invoices this discount applies to. Null means all invoices. example: 3 required: - discountId description: Discounts to apply to generated invoices. invoices: type: array items: type: object properties: items: type: array items: type: object properties: conceptId: type: string description: Identifier of the payment concept. example: pc_1234567890abcdefghij quantity: type: number minimum: 1 description: Number of units. example: 1 amount: type: number nullable: true minimum: 0 maximum: 99999999999 description: >- Optional unit price snapshot in minor currency units. example: 150000 currency: type: string nullable: true description: Optional ISO 4217 currency snapshot. example: MXN description: type: string nullable: true minLength: 1 description: Optional line-item description snapshot. example: Colegiatura Junio required: - conceptId - quantity minItems: 1 maxItems: 100 description: Line items for this invoice. dueDate: anyOf: - type: string description: Date string - type: string format: date-time description: Date object description: Due date for this invoice. example: '2025-06-01T00:00:00.000Z' expireDate: anyOf: - type: string description: Date string - type: string format: date-time description: Date object description: Optional expiration date for this invoice. example: null required: - items - dueDate minItems: 1 maxItems: 1000 description: >- Pre-defined invoices with explicit due dates and items. Mutually exclusive with `items`. items: type: array items: type: object properties: conceptId: type: string description: Identifier of the payment concept. example: pc_1234567890abcdefghij quantity: type: number minimum: 1 description: Number of units. example: 1 amount: type: number nullable: true minimum: 0 maximum: 99999999999 description: Optional unit price snapshot in minor currency units. example: 150000 currency: type: string nullable: true description: Optional ISO 4217 currency snapshot. example: MXN description: type: string nullable: true minLength: 1 description: Optional line-item description snapshot. example: Colegiatura mensual required: - conceptId - quantity minItems: 1 maxItems: 100 description: >- Recurring items whose invoices are auto-generated on each collection date. Mutually exclusive with `invoices`. required: - customerId - collectionMethod required: - input description: Request body for creating a subscription. CreateSubscriptionPayload: type: object properties: subscription: $ref: '#/components/schemas/Subscription' required: - subscription description: Successful subscription creation response. UserError: type: object properties: error: type: object properties: message: type: string required: - message required: - error additionalProperties: false description: Standard user-facing error response envelope. Subscription: type: object properties: id: type: string description: Unique identifier of the subscription. example: sub_1234567890abcdefghij createdAt: anyOf: - type: string description: Date string - type: string format: date-time description: Date object description: Date and time when the subscription was created. example: '2025-01-01T06:00:00.000Z' updatedAt: anyOf: - type: string description: Date string - type: string format: date-time description: Date object description: Date and time when the subscription was last updated. example: '2025-01-01T06:00:00.000Z' description: type: string nullable: true description: Human-readable description of the subscription. example: Colegiatura mensual customerId: type: string description: Identifier of the customer this subscription belongs to. example: cus_1234567890abcdefghij status: type: string nullable: true enum: - INACTIVE - ACTIVE - CANCELED - COMPLETED - null description: 'Current status: INACTIVE, ACTIVE, CANCELED, or COMPLETED.' example: ACTIVE collectionMethod: type: string enum: - AUTOMATIC - SEND_REMINDER - NONE description: 'How payment is collected: AUTOMATIC, SEND_REMINDER, or NONE.' example: AUTOMATIC paymentMethodId: type: string nullable: true description: Identifier of the payment method used for automatic collection. example: pm_1234567890abcdefghij taxProfileId: type: string nullable: true description: Identifier of the tax profile used for invoice generation. example: null nextCollectionDate: anyOf: - type: string description: Date string - type: string format: date-time description: Date object - nullable: true description: Date and time of the next scheduled collection. example: '2025-02-01T06:00:00.000Z' firstCollectionDate: anyOf: - type: string description: Date string - type: string format: date-time description: Date object description: Date and time of the first collection. example: '2025-01-01T06:00:00.000Z' lastCollectionDate: anyOf: - type: string description: Date string - type: string format: date-time description: Date object - nullable: true description: Date and time of the last collection, if set. example: '2025-12-01T06:00:00.000Z' generationMode: type: string enum: - MANUAL - AUTO description: Whether invoices are generated manually or automatically. example: AUTO metadata: type: object nullable: true additionalProperties: type: string description: Flattened metadata map where each key maps to a string value. example: Nivel: Preparatoria onlyAutomaticCollection: type: boolean description: Whether only automatic collection is allowed. example: false customCancelReason: type: string nullable: true description: Custom cancellation reason provided by the user. example: null canceledAt: anyOf: - type: string description: Date string - type: string format: date-time description: Date object - nullable: true description: Date and time when the subscription was canceled. example: null canceledById: type: string nullable: true description: Identifier of the user who canceled the subscription. example: null isActive: type: boolean description: Whether the subscription is currently active. example: true isCompleted: type: boolean description: Whether the subscription has completed all scheduled collections. example: false required: - id - createdAt - updatedAt - description - customerId - collectionMethod - paymentMethodId - taxProfileId - nextCollectionDate - firstCollectionDate - lastCollectionDate - generationMode - onlyAutomaticCollection - customCancelReason - canceledAt - canceledById - isActive - isCompleted description: Recurring billing subscription tied to a customer. securitySchemes: organizationApiKey: type: http scheme: bearer description: 'Organization API key using `Authorization: Bearer sk_...`.' ````