Skip to main content

​
Responding to a carrier-invoice approval request

When a carrier invoice needs sign-off from an external system before Upwell proceeds, Upwell opens a carrier-invoice approval request and waits for your integration to resolve it. This page shows how to read a pending request and resolve it with the callback.
An approval request is a small state record (carrier_invoice_approval_request) tracking one pending decision on a carrier invoice — the invoice it belongs to, the payloads exchanged, retry state, and its status. While a request is unresolved, the corresponding Approve action in Upwell stays in progress; resolving the request (below) is what completes it.

​
The resource

GET /api/rest/carrier_invoice_approval_requests/{id} returns a single request: 
curl https://api.upwell.com/api/rest/carrier_invoice_approval_requests/APPROVAL_REQUEST_ID \
  -H "Authorization: YOUR_API_KEY"
# -> { "carrierInvoiceApprovalRequest": {
#        "id": "...", "carrierInvoiceId": "cari_...", "status": "...",
#        "retryCount": 0, "createdAt": "...", "updatedAt": "...",
#        "carrierInvoice": { "invoiceNumber": "...", "totalAmount": 125000,
#                            "carrier": { "id": "car_...", "name": "Acme Trucking" } } } }
FieldMeaning
idApproval-request ID — use this in the callback below.
carrierInvoiceIdThe carrier invoice awaiting a decision.
carrierInvoiceNested summary: carrier (id, name), invoiceNumber, totalAmount (in cents).
statusCurrent state (see below).
retryCountHow many times Upwell has re-sent the request.
createdAt / updatedAtTimestamps.
You can list open requests with GET /api/rest/carrier_invoice_approval_requests (supports limit / offset), or — preferably — be notified via outbound webhooks instead of polling.

​
Resolution statuses

status is a CarrierInvoiceApprovalRequestStatusEnum. When you resolve a request, set it to one of:
StatusMeaning
SUCCEEDEDThe invoice was approved by your system.
FAILEDThe invoice was rejected or could not be approved.
Only SUCCEEDED and FAILED are accepted when resolving a request. A GET may also return lifecycle states that Upwell manages itself and that you don’t set directly — INITIATED, IN_PROGRESS, RETRYING, and ABANDONED.

​
Resolve a request — the callback

PATCH /api/rest/carrier_invoice_approval_requests/{id} sets the request’s status. This is the call that clears the pending state on the Upwell side. The request id comes from the URL path; the body just carries an input object with the new status: 
curl -X PATCH https://api.upwell.com/api/rest/carrier_invoice_approval_requests/APPROVAL_REQUEST_ID \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "status": "SUCCEEDED" } }'
# -> { "updatedCarrierInvoiceApprovalRequest": { "id": "APPROVAL_REQUEST_ID", "status": "SUCCEEDED" } }
To reject instead, send "status": "FAILED".
The approval-request id is taken from the URL path — the body only needs input. A top-level id in the body is optional and, if included, must match the path. The response echoes only id and status; read the full record with GET /carrier_invoice_approval_requests/{id} if you need the rest.
The input object accepts more than status (for example, a payload capturing your system’s response). For the complete, always-current request schema, see the carrier_invoice_approval_requests entry in the API Reference — it is generated directly from the live API.
1

Discover the request

Receive it via a webhook, or poll GET /api/rest/carrier_invoice_approval_requests.
2

Decide

Use the nested carrierInvoice details (carrier, invoice number, amount) to make your decision.
3

Resolve it

PATCH the request with status SUCCEEDED or FAILED. This clears the pending Approve state in Upwell.
For the carrier-invoice lifecycle itself — statuses, exceptions, and how to know when processing is done — see Knowing when a carrier invoice is processed. To submit carrier invoices in the first place, see Submitting carrier invoices via API.