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

# Create a subscription

> Creates a new subscription for a customer directly, without requiring a checkout session.

<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>


## OpenAPI

````yaml /api-reference/openapi.json post /subscriptions/create/
openapi: 3.0.0
info:
  title: kelviq API
  version: 1.0.0
  description: >-
    API for interacting with kelviq services, derived from Python SDK
    documentation.
servers:
  - url: https://sandboxapi.kelviq.com/api/v1
    description: Sandbox — Test payments
  - url: https://api.kelviq.com/api/v1
    description: Production — Live payments
security:
  - bearerAuth: []
tags:
  - name: Products
    description: Catalog products.
  - name: Product Settings
    description: Per-product settings (currency, VPN/Tor/proxy, product URL).
  - name: Product Files
    description: Product images and downloadable assets.
  - name: Features
    description: Catalog features that can be granted as plan entitlements.
  - name: Plans
    description: Catalog plans (CRUD, publish, versions, prices).
  - name: Plan Entitlements
    description: Feature entitlements attached to a plan.
  - name: Plan Files
    description: Files attached to plans, and signed download links.
  - name: Media
    description: Generate presigned S3 upload URLs for product/plan images and files.
  - name: Partner
    description: Partner integration APIs (organization provisioning, lookup).
  - name: Charges
    description: >-
      One-time payments charged immediately against a customer's default payment
      method.
  - name: Refunds
    description: Full and partial refunds for paid orders.
  - name: Transactions
    description: >-
      Charges, refunds, disputes, and other financial movements for the
      authenticated organization.
  - name: Payment Methods
    description: Saved customer payment methods (cards, etc.).
  - name: Orders
    description: Completed and resolved orders for the authenticated organization.
  - name: Order Events
    description: Timeline events for a specific order.
  - name: Webhooks
    description: Delivery logs for webhook events sent to your configured endpoints.
  - name: Checkout Sessions
    description: Merchant-side view of checkout sessions created by customers.
  - name: Checkout Session Events
    description: Timeline events for a specific checkout session.
paths:
  /subscriptions/create/:
    post:
      tags:
        - Subscriptions
      summary: Create a subscription
      description: >-
        Creates a new subscription for a customer directly, without requiring a
        checkout session.
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '201':
          description: Subscription Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubscriptionResponse'
              example:
                id: 520ca8a5-9fc0-4d6a-bc7a-2ba331595441
                startDate: '2026-02-07'
                endDate: null
                billingPeriodStartTime: '2026-02-07T06:02:05Z'
                billingPeriodEndTime: '2026-02-08T06:02:05Z'
                amount: '2000.00'
                recurrence: month
                currency: USD
                status: trialing
                product:
                  name: Invoice Test
                  id: 88e437b8-6017-405b-9328-e0f4e140bb79
                  identifier: invoice-test
                plan:
                  name: iUltra
                  identifier: i-ultra
                features: []
                trialDaysRemaining: 1
                customerId: geojacob
                billingType: SUBSCRIPTION
                recurrenceUnit: 1
                recurrenceType: MONTH
                files:
                  - id: bf9f0fe0-c9c0-436d-8811-e412d0365470
                    name: custom-pricinig.png
                    file: >-
                      https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png
                    ordering: 0
                    enabled: true
                    downloadUrl: >-
                      https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/
                links:
                  - name: Product documentation
                    url: https://example.com/docs
                license:
                  - id: f81efb90-5f29-4dd1-9c7b-be4085e473de
                    licenseKey: 10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1
                    activatedOn: null
                    expiresOn: null
                    activationUsage: 0
                    activationLimit: 2
                    enabled: true
        '400':
          description: Bad Request - Validation or business logic error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailErrorResponse'
              example:
                detail: Customer does not exist.
components:
  schemas:
    CreateSubscriptionRequest:
      type: object
      required:
        - planIdentifier
        - chargePeriod
        - customerId
      properties:
        planIdentifier:
          type: string
          description: The identifier of the specific plan the customer is subscribing to.
          example: plan-pro-monthly
        successUrl:
          type: string
          format: url
          nullable: true
          description: >-
            The URL to which the user will be redirected after a successful
            subscription creation. Optional.
          example: https://kelviq.com/subscription/success
        chargePeriod:
          type: string
          description: >-
            The billing cycle for the subscription. If the plan is free, pass
            `ONE_TIME` as the chargePeriod.
          enum:
            - ONE_TIME
            - MONTHLY
            - YEARLY
            - WEEKLY
            - DAILY
            - TWENTY_EIGHT_DAYS
            - THREE_MONTHS
            - SIX_MONTHS
          example: MONTHLY
        customerId:
          type: string
          nullable: true
          description: The ID of the customer creating the subscription.
          example: cust_789
        features:
          type: array
          items:
            $ref: '#/components/schemas/FeatureInput'
          nullable: true
          description: A list of features and their desired quantities.
          example:
            - identifier: seats
              quantity: 5
        ipAddress:
          type: string
          nullable: true
          description: The IP Address of the customer, used for location-based pricing.
          example: 103.154.35.20
    CreateSubscriptionResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the created subscription.
          example: 520ca8a5-9fc0-4d6a-bc7a-2ba331595441
        startDate:
          type: string
          format: date
          description: The start date of the subscription.
          example: '2026-02-07'
        endDate:
          type: string
          format: date
          nullable: true
          description: The end date of the subscription, if applicable.
          example: null
        billingPeriodStartTime:
          type: string
          format: date-time
          description: The start time of the current billing period.
          example: '2026-02-07T06:02:05Z'
        billingPeriodEndTime:
          type: string
          format: date-time
          description: The end time of the current billing period.
          example: '2026-02-08T06:02:05Z'
        amount:
          type: string
          description: The subscription amount.
          example: '2000.00'
        recurrence:
          type: string
          description: The recurrence interval of the subscription.
          example: month
        currency:
          type: string
          description: The currency of the subscription.
          example: USD
        status:
          type: string
          description: The current status of the subscription.
          example: trialing
        product:
          type: object
          properties:
            name:
              type: string
              description: The name of the product.
              example: Invoice Test
            id:
              type: string
              format: uuid
              description: The unique identifier of the product.
              example: 88e437b8-6017-405b-9328-e0f4e140bb79
            identifier:
              type: string
              description: The identifier of the product.
              example: invoice-test
        plan:
          type: object
          properties:
            name:
              type: string
              description: The name of the plan.
              example: iUltra
            identifier:
              type: string
              description: The identifier of the plan.
              example: i-ultra
        features:
          type: array
          items: {}
          description: List of features included in the subscription.
        trialDaysRemaining:
          type: integer
          description: Number of trial days remaining.
          example: 1
        customerId:
          type: string
          description: The customer identifier associated with this subscription.
          example: geojacob
        files:
          type: array
          description: Downloadable files attached to the subscription's plan.
          items:
            $ref: '#/components/schemas/PlanFile'
        links:
          type: array
          description: External links attached to the subscription's plan.
          items:
            $ref: '#/components/schemas/PlanLink'
        license:
          type: array
          description: Issued licenses associated with the subscription.
          items:
            $ref: '#/components/schemas/SubscriptionLicense'
    DetailErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable error message.
          example: Customer does not exist.
    FeatureInput:
      type: object
      required:
        - identifier
        - quantity
      properties:
        identifier:
          type: string
          description: The unique identifier for the feature.
          example: seats
        quantity:
          type: integer
          description: The desired quantity for this feature.
          example: 5
    PlanFile:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: bf9f0fe0-c9c0-436d-8811-e412d0365470
        name:
          type: string
          example: custom-pricinig.png
        file:
          type: string
          format: uri
          readOnly: true
          example: >-
            https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png
        ordering:
          type: integer
          example: 0
        enabled:
          type: boolean
          example: true
        downloadUrl:
          type: string
          format: uri
          readOnly: true
          description: >-
            URL clients can hit to download the file. Will redirect to a
            forced-download URL.
          example: >-
            https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/
    PlanLink:
      type: object
      properties:
        name:
          type: string
          example: Product page
        url:
          type: string
          format: uri
          example: https://example.com/product
    SubscriptionLicense:
      type: object
      description: An issued license associated with a subscription.
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          example: f81efb90-5f29-4dd1-9c7b-be4085e473de
        licenseKey:
          type: string
          nullable: true
          description: The issued license key.
          example: 10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1
        activatedOn:
          type: string
          format: date-time
          nullable: true
          description: When the license was first activated.
          example: null
        expiresOn:
          type: string
          format: date-time
          nullable: true
          description: When the license expires, if applicable.
          example: null
        activationUsage:
          type: integer
          nullable: true
          description: Number of currently active instances.
          example: 0
        activationLimit:
          type: integer
          nullable: true
          description: Maximum number of allowed concurrent activations.
          example: 2
        enabled:
          type: boolean
          nullable: true
          description: Whether the license is enabled.
          example: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Server API Key obtained from the kelviq application. Pass as a
        Bearer token in the Authorization header. Example: 'Authorization:
        Bearer __YOUR_API_KEY__'

````