> ## 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 Payment Requests

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

<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/payment-requests?client_id=<ID>&status=PENDING&type=SUBSCRIPTION
GET /api/v2/external-billing/payment-requests?status=OVERDUE
GET /api/v2/external-billing/payment-requests?client_id=<ID>&type=ADDON
GET /api/v2/external-billing/payment-requests?client_id=<ID>
```

| Parameter   | Optional | Notes                                                                          |
| ----------- | -------- | ------------------------------------------------------------------------------ |
| `client_id` | Yes      | Scope to a single client. Omit to return all clients.                          |
| `status`    | Yes      | Filter by payment status (`PENDING`, `PAID`, `FAILED`, `CANCELED`, `OVERDUE`). |
| `type`      | Yes      | Filter by request type (`SUBSCRIPTION`, `ADDON`, `OVERAGE`, `ONE_TIME`).       |
| `page`      | Yes      | Defaults to `1`.                                                               |
| `page_size` | Yes      | Defaults to `20`, max `100`.                                                   |

## Payment request statuses

| Status     | Meaning                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------ |
| `PENDING`  | Created, awaiting payment.                                                                             |
| `PAID`     | Marked as paid.                                                                                        |
| `OVERDUE`  | Due date passed without payment. Triggers `past_due` on the linked subscription (cycle requests only). |
| `FAILED`   | Payment could not be completed.                                                                        |
| `CANCELED` | Canceled - no longer requires payment.                                                                 |

## Payment request types

| Type           | Meaning                                                             |
| -------------- | ------------------------------------------------------------------- |
| `SUBSCRIPTION` | Recurring flat-fee charge for a billing period.                     |
| `ADDON`        | Charge for an add-on pack applied to a client.                      |
| `OVERAGE`      | Per-minute overage charge generated at the end of a billing period. |
| `ONE_TIME`     | One-off charge outside the normal billing cycle.                    |


## OpenAPI

````yaml GET /api/v2/external-billing/payment-requests
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/payment-requests:
    get:
      tags:
        - External Billing - Payment Requests
      summary: List Payment Requests
      description: >-
        Returns a paginated list of payment requests for your tenant.


        If `client_id` is provided, returns payment requests for that specific
        client only. Otherwise, returns payment requests for **all clients**
        under your agency. Supports filtering by `status` and `type`.


        ## Authentication

        Requires `Authorization: Bearer <api_key>`. The API key must belong to a
        tenant on a **PRO plan or above**.
      operationId: listPaymentRequests
      parameters:
        - name: client_id
          in: query
          required: false
          description: >-
            Filter payment requests 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 payment request status.
          schema:
            type: string
            enum:
              - PENDING
              - PAID
              - FAILED
              - CANCELED
              - OVERDUE
            example: PENDING
        - name: type
          in: query
          required: false
          description: Filter by payment request type.
          schema:
            type: string
            enum:
              - SUBSCRIPTION
              - ADDON
              - OVERAGE
              - ONE_TIME
            example: SUBSCRIPTION
        - 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: Payment requests returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestListResponse'
              example:
                data:
                  - id: '10'
                    client_id: '42'
                    client_name: Acme Corp
                    subscription_id: '1'
                    status: PENDING
                    type: SUBSCRIPTION
                    amount: '99.00'
                    currency: USD
                    due_date: '2025-01-15T00:00:00'
                    grace_period_ends_at: '2025-01-22T00:00:00'
                    paid_at: null
                    external_payment_id: null
                    notes: null
                    line_items: []
                    period_start: '2025-01-01T00:00:00'
                    period_end: '2025-02-01T00:00:00'
                    created_at: '2025-01-01T00:00:00'
                    updated_at: '2025-01-01T00:00:00'
                meta:
                  total: 1
                  page: 1
                  page_size: 20
        '400':
          description: >-
            Invalid query parameter - e.g. unrecognised `status` or `type`
            value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                message: Invalid status 'unknown'.
                valid_values:
                  - PENDING
                  - PAID
                  - FAILED
                  - CANCELED
                  - OVERDUE
        '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:
    PaymentRequestListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRequest'
        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
    PaymentRequest:
      type: object
      properties:
        id:
          type: string
          description: Payment request ID.
          example: '10'
        client_id:
          type: string
          description: ID of the client this payment request belongs to.
          example: '42'
        client_name:
          type: string
          description: Display name of the client.
          example: Acme Corp
        subscription_id:
          type: string
          nullable: true
          description: >-
            ID of the associated subscription (null for non-subscription
            requests).
          example: '1'
        status:
          type: string
          enum:
            - PENDING
            - PAID
            - FAILED
            - CANCELED
            - OVERDUE
          description: Current payment request status.
          example: PENDING
        type:
          type: string
          enum:
            - SUBSCRIPTION
            - ADDON
            - OVERAGE
            - ONE_TIME
          description: Type of the payment request.
          example: SUBSCRIPTION
        amount:
          type: string
          description: Total amount as a decimal string.
          example: '99.00'
        currency:
          type: string
          description: 3-letter currency code.
          example: USD
        period_start:
          type: string
          format: date-time
          nullable: true
          description: Start of the billing period this request covers.
          example: '2025-01-01T00:00:00'
        period_end:
          type: string
          format: date-time
          nullable: true
          description: End of the billing period this request covers.
          example: '2025-02-01T00:00:00'
        due_date:
          type: string
          format: date-time
          nullable: true
          description: Date by which payment is due.
          example: '2025-01-15T00:00:00'
        grace_period_ends_at:
          type: string
          format: date-time
          nullable: true
          description: End of grace period (cycle requests only). Null for pack requests.
          example: '2025-01-22T00:00:00'
        paid_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the request was marked paid. Null if not yet paid.
          example: null
        external_payment_id:
          type: string
          nullable: true
          description: >-
            Optional external transaction reference (e.g. a payment processor
            transaction ID).
          example: null
        notes:
          type: string
          nullable: true
          description: Free-text notes on the request.
          example: null
        line_items:
          type: array
          items:
            type: object
          description: Breakdown of individual line items making up the total amount.
        created_at:
          type: string
          format: date-time
          description: When the request was created (ISO 8601).
          example: '2025-01-01T00:00:00'
        updated_at:
          type: string
          format: date-time
          description: When the request was last updated (ISO 8601).
          example: '2025-01-01T00: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

````