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

# List Subscriptions

> Retrieve a paginated list of client subscriptions for your tenant, with optional filters for client and status.

<Info>
  This endpoint requires a **PRO plan or above**. If your plan does not include the External Billing API, the request returns `403` with error code `external_billing_api`.
</Info>

## Combining filters

All query parameters are optional and can be used together or individually:

```
GET /api/v2/external-billing/subscriptions?client_id=<ID>&status=active
GET /api/v2/external-billing/subscriptions?status=past_due
GET /api/v2/external-billing/subscriptions?client_id=<ID>
```

| Parameter   | Optional | Notes                                                 |
| ----------- | -------- | ----------------------------------------------------- |
| `client_id` | Yes      | Scope to a single client. Omit to return all clients. |
| `status`    | Yes      | Filter by subscription status.                        |
| `page`      | Yes      | Defaults to `1`.                                      |
| `page_size` | Yes      | Defaults to `20`, max `100`.                          |

## Subscription statuses

| Status     | Meaning                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------- |
| `active`   | Subscription is running normally.                                                        |
| `past_due` | A payment request was not paid by its due date. Client portal and campaigns are blocked. |
| `blocked`  | Grace period expired without payment. Subscription must be canceled and restarted.       |
| `canceled` | Subscription was explicitly canceled. History is preserved.                              |


## OpenAPI

````yaml GET /api/v2/external-billing/subscriptions
openapi: 3.1.0
info:
  title: VoiceAIWrapper API
  description: >-
    REST API for managing campaigns, leads, clients, web widgets, and voice
    providers on VoiceAIWrapper.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.voiceaiwrapper.app
security:
  - bearerAuth: []
paths:
  /api/v2/external-billing/subscriptions:
    get:
      tags:
        - External Billing - Subscriptions
      summary: List Subscriptions
      description: >-
        Returns a paginated list of client subscriptions for your tenant.


        If `client_id` is provided, returns subscriptions for that specific
        client only. Otherwise, returns subscriptions for **all clients** under
        your agency.


        ## Authentication

        Requires `Authorization: Bearer <api_key>`. The API key must belong to a
        tenant on a **PRO plan or above**.
      operationId: listSubscriptions
      parameters:
        - name: client_id
          in: query
          required: false
          description: >-
            Filter subscriptions for a specific client. Accepts a plain integer
            ID or a base64 GraphQL global ID. Omit to return all clients under
            the tenant.
          schema:
            type: string
            example: Q2xpZW50OjEyMw==
        - name: status
          in: query
          required: false
          description: Filter by subscription status.
          schema:
            type: string
            enum:
              - active
              - past_due
              - blocked
              - canceled
            example: active
        - name: page
          in: query
          required: false
          description: 'Page number. Default: `1`.'
          schema:
            type: integer
            default: 1
            example: 1
        - name: page_size
          in: query
          required: false
          description: 'Results per page. Default: `20`. Maximum: `100`.'
          schema:
            type: integer
            default: 20
            maximum: 100
            example: 20
      responses:
        '200':
          description: Subscriptions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
              example:
                data:
                  - id: '1'
                    client_id: '42'
                    client_name: Acme Corp
                    product_id: '7'
                    product_name: Pro Plan
                    status: active
                    current_period_start: '2025-01-01T00:00:00'
                    current_period_end: '2025-02-01T00:00:00'
                    created_at: '2025-01-01T00:00:00'
                    updated_at: '2025-01-15T10:00:00'
                meta:
                  total: 1
                  page: 1
                  page_size: 20
        '400':
          description: Invalid query parameter - e.g. unrecognised `status` value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                message: Invalid status 'unknown'.
                valid_values:
                  - active
                  - past_due
                  - blocked
                  - canceled
        '401':
          description: >-
            Authentication failed - `Authorization` header missing, malformed,
            or API key not found / disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                message: Authorization header not found
        '403':
          description: >-
            Access denied - your current plan does not include the External
            Billing API. Upgrade to PRO or above.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                message: >-
                  External Billing API access requires a PRO plan. Error Code:
                  external_billing_api
        '404':
          description: Client not found or does not belong to your tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                message: Client not found
        '500':
          description: Internal server error. Contact support if this persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                message: Internal server error
components:
  schemas:
    SubscriptionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: Invalid status 'unknown'.
        valid_values:
          type: array
          items:
            type: string
          example:
            - PENDING
            - PAID
            - FAILED
            - CANCELED
            - OVERDUE
    ErrorMessage:
      type: object
      properties:
        message:
          type: string
    Subscription:
      type: object
      properties:
        id:
          type: string
          description: Subscription ID.
          example: '1'
        client_id:
          type: string
          description: ID of the client this subscription belongs to.
          example: '42'
        client_name:
          type: string
          description: Display name of the client.
          example: Acme Corp
        product_id:
          type: string
          description: ID of the billing plan/product.
          example: '7'
        product_name:
          type: string
          description: Name of the billing plan/product.
          example: Starter Plan
        status:
          type: string
          enum:
            - active
            - past_due
            - blocked
            - canceled
          description: Current subscription status.
          example: active
        current_period_start:
          type: string
          format: date-time
          nullable: true
          description: Start of the current billing period (ISO 8601).
          example: '2025-01-01T00:00:00'
        current_period_end:
          type: string
          format: date-time
          nullable: true
          description: End of the current billing period (ISO 8601).
          example: '2025-02-01T00:00:00'
        created_at:
          type: string
          format: date-time
          description: When the subscription was created (ISO 8601).
          example: '2025-01-01T00:00:00'
        updated_at:
          type: string
          format: date-time
          description: When the subscription was last updated (ISO 8601).
          example: '2025-01-15T10:00:00'
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of records matching the query.
          example: 1
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of records per page.
          example: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````