Skip to main content
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"
  }
}
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:
  1. paid_at is recorded with the current timestamp.
  2. external_payment_id is stored if provided (useful as a reference to your payment processor’s transaction ID).
  3. The platform checks whether the linked subscription has any remaining unpaid cycle requests (PENDING or OVERDUE).
    • If none remain → subscription status returns to active and any paused campaigns are automatically resumed.
    • If others remain → subscription stays in its current state until all are resolved.

​
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

StatusWhen to use
PAIDClient has paid. Triggers subscription recovery if no other cycle requests are outstanding.
PENDINGReset to pending (e.g. if you marked paid by mistake).
FAILEDPayment attempt failed - client should be contacted.
CANCELEDCharge is void - no payment needed.
OVERDUEMark 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

​
Authorization
string
header
required

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

Path Parameters

​
payment_request_id
string
required

Integer ID of the payment request to update.

Example:

"10"

Body

application/json
​
status
enum<string>
required

New status for the payment request. Required.

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

"PAID"

​
external_payment_id
string

Optional external transaction reference (e.g. txn_abc123 from your payment processor). Recommended when setting status to PAID.

Example:

"txn_abc123"

Response

Payment request updated successfully. Returns a confirmation message and the full updated payment request object.

​
message
string

Confirmation that the payment request status was updated.

Example:

"Payment status updated successfully."

​
data
object