> ## 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.

# List Subscriptions

> Retrieves a paginated list of subscriptions. Optionally filter the results by customer.

<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 get /subscriptions/
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: Payment Methods
    description: Saved customer payment methods (cards, etc.).
paths:
  /subscriptions/:
    get:
      tags:
        - Subscriptions
      summary: List Subscriptions
      description: >-
        Retrieves a paginated list of subscriptions. Optionally filter the
        results by customer.
      operationId: listSubscriptions
      parameters:
        - name: customer_id
          in: query
          required: false
          description: >-
            Optional. The client-defined unique identifier of the customer whose
            subscriptions will be returned.
          schema:
            type: string
        - name: page_size
          in: query
          required: false
          description: Number of results to return per page. Defaults to 10, maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: page
          in: query
          required: false
          description: The initial index from which to return the results.
          schema:
            type: integer
      responses:
        '200':
          description: A paginated list of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
              example:
                count: 1
                next: null
                previous: null
                results:
                  - id: 09d706ca-58f3-4fb2-818f-5b8623d67e6e
                    externalSubscriptionId: sub_1RpoZoSBstCzyocS7iPmith3
                    startDate: '2025-07-28'
                    endDate: null
                    billingPeriodStartTime: '2025-07-28T10:46:34Z'
                    billingPeriodEndTime: '2025-08-28T10:46:34Z'
                    amount: '261.00'
                    recurrence: month
                    currency: usd
                    status: active
                    product: Aphelo
                    plan:
                      name: Premium
                      identifier: premium1
                    features:
                      - id: b417ae2f-35e2-48f2-a5c4-fdaa99b2b96a
                        identifier: products
                        name: Products
                        description: ''
                        featureType: CUSTOMIZABLE
                        details: {}
                        isArchived: false
                        metadata: {}
                        modifiedOn: '2025-06-14T11:36:26.062491Z'
                        meter: {}
                        featureDetails:
                          units:
                            plural: counts
                            singular: count
                        reset: null
                        resetTime: null
                        value: 100
                        hardLimit: false
                    trialDaysRemaining: 0
                    customerId: testuser
                    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
components:
  schemas:
    SubscriptionListResponse:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          format: uri
          nullable: true
        previous:
          type: string
          format: uri
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
    Subscription:
      type: object
      properties:
        id:
          type: string
          format: uuid
        externalSubscriptionId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
          nullable: true
        billingPeriodStartTime:
          type: string
          format: date-time
        billingPeriodEndTime:
          type: string
          format: date-time
        amount:
          type: string
        recurrence:
          type: string
        currency:
          type: string
        status:
          type: string
        product:
          type: string
        plan:
          $ref: '#/components/schemas/SubscriptionPlan'
        features:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionFeatureDetail'
        trialDaysRemaining:
          type: integer
        customerId:
          type: string
        billingType:
          type: string
          enum:
            - SUBSCRIPTION
            - ONE_TIME
        recurrenceUnit:
          type: integer
          nullable: true
        recurrenceType:
          type: string
          nullable: true
        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'
    SubscriptionPlan:
      type: object
      properties:
        name:
          type: string
        identifier:
          type: string
    SubscriptionFeatureDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        identifier:
          type: string
        name:
          type: string
        description:
          type: string
        featureType:
          type: string
        details:
          type: object
        isArchived:
          type: boolean
        metadata:
          type: object
        modifiedOn:
          type: string
          format: date-time
        meter:
          type: object
        featureDetails:
          type: object
          properties:
            units:
              type: object
              properties:
                plural:
                  type: string
                singular:
                  type: string
        reset:
          type: string
          nullable: true
        resetTime:
          type: string
          nullable: true
        value:
          type: integer
        hardLimit:
          type: boolean
    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__'

````