curl --request PATCH \
--url https://api.voiceaiwrapper.app/api/v2/external-billing/payment-requests/{payment_request_id}/update \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "PAID",
"external_payment_id": "txn_abc123"
}
'{
"message": "Payment status updated successfully.",
"data": {
"id": "10",
"client_id": "42",
"client_name": "Acme Corp",
"subscription_id": "1",
"status": "PAID",
"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": "2025-01-14T09:30:00",
"external_payment_id": "txn_abc123",
"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-14T09:30:00"
}
}{
"message": "Invalid status 'UNKNOWN'.",
"valid_values": [
"PENDING",
"PAID",
"FAILED",
"CANCELED",
"OVERDUE"
]
}{
"message": "Authorization header not found"
}{
"message": "External Billing API access requires a PRO plan. Error Code: external_billing_api"
}{
"message": "Payment request not found"
}{
"message": "Internal server error"
}Payment Requests
Update Payment Request
Update the status of a payment request. Any status transition is permitted.
PATCH
/
api
/
v2
/
external-billing
/
payment-requests
/
{payment_request_id}
/
update
curl --request PATCH \
--url https://api.voiceaiwrapper.app/api/v2/external-billing/payment-requests/{payment_request_id}/update \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "PAID",
"external_payment_id": "txn_abc123"
}
'{
"message": "Payment status updated successfully.",
"data": {
"id": "10",
"client_id": "42",
"client_name": "Acme Corp",
"subscription_id": "1",
"status": "PAID",
"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": "2025-01-14T09:30:00",
"external_payment_id": "txn_abc123",
"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-14T09:30:00"
}
}{
"message": "Invalid status 'UNKNOWN'.",
"valid_values": [
"PENDING",
"PAID",
"FAILED",
"CANCELED",
"OVERDUE"
]
}{
"message": "Authorization header not found"
}{
"message": "External Billing API access requires a PRO plan. Error Code: external_billing_api"
}{
"message": "Payment request not found"
}{
"message": "Internal server error"
}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.What happens when you mark a request as PAID
Sending "status": "PAID" triggers the internal payment service in addition to updating the status field:
paid_atis recorded with the current timestamp.external_payment_idis stored if provided (useful as a reference to your payment processor’s transaction ID).- The platform checks whether the linked subscription has any remaining unpaid cycle requests (
PENDINGorOVERDUE).- If none remain → subscription status returns to
activeand any paused campaigns are automatically resumed. - If others remain → subscription stays in its current state until all are resolved.
- If none remain → subscription status returns to
external_payment_id is optional
You can mark a request as PAID without providing external_payment_id. It is recommended when you have a transaction reference from your payment processor (e.g. txn_abc123, pi_abc123 from Stripe), but the field is not required.
Status reference
| Status | When to use |
|---|---|
PAID | Client has paid. Triggers subscription recovery if no other cycle requests are outstanding. |
PENDING | Reset to pending (e.g. if you marked paid by mistake). |
FAILED | Payment attempt failed - client should be contacted. |
CANCELED | Charge is void - no payment needed. |
OVERDUE | Mark manually overdue (normally set automatically by the platform’s sweep). |
Setting a cycle request to
PAID can change the subscription status and resume paused campaigns. Verify you are acting on the correct payment request before proceeding.Authorizations
Path Parameters
Body
application/json
Was this page helpful?

