Skip to main content
GET
/
api
/
v2
/
external-billing
/
payment-requests
List Payment Requests
curl --request GET \
  --url https://api.voiceaiwrapper.app/api/v2/external-billing/payment-requests \
  --header 'Authorization: Bearer <token>'
{
  "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
  }
}
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.

​
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>
ParameterOptionalNotes
client_idYesScope to a single client. Omit to return all clients.
statusYesFilter by payment status (PENDING, PAID, FAILED, CANCELED, OVERDUE).
typeYesFilter by request type (SUBSCRIPTION, ADDON, OVERAGE, ONE_TIME).
pageYesDefaults to 1.
page_sizeYesDefaults to 20, max 100.

​
Payment request statuses

StatusMeaning
PENDINGCreated, awaiting payment.
PAIDMarked as paid.
OVERDUEDue date passed without payment. Triggers past_due on the linked subscription (cycle requests only).
FAILEDPayment could not be completed.
CANCELEDCanceled — no longer requires payment.

​
Payment request types

TypeMeaning
SUBSCRIPTIONRecurring flat-fee charge for a billing period.
ADDONCharge for an add-on pack applied to a client.
OVERAGEPer-minute overage charge generated at the end of a billing period.
ONE_TIMEOne-off charge outside the normal billing cycle.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
client_id
string

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.

Example:

"Q2xpZW50OjEyMw=="

​
status
enum<string>

Filter by payment request status.

Available options:
PENDING,
PAID,
FAILED,
CANCELED,
OVERDUE
Example:

"PENDING"

​
type
enum<string>

Filter by payment request type.

Available options:
SUBSCRIPTION,
ADDON,
OVERAGE,
ONE_TIME
Example:

"SUBSCRIPTION"

​
page
integer
default:1

Page number. Default: 1.

Example:

1

​
page_size
integer
default:20

Results per page. Default: 20. Maximum: 100.

Required range: x <= 100
Example:

20

Response

Payment requests returned successfully.

​
data
object[]
​
meta
object