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" } } } }

Field	Meaning
`id`	Approval-request ID — use this in the callback below.
`carrierInvoiceId`	The carrier invoice awaiting a decision.
`carrierInvoice`	Nested summary: `carrier` (`id`, `name`), `invoiceNumber`, `totalAmount` (in cents).
`status`	Current state (see below).
`retryCount`	How many times Upwell has re-sent the request.
`createdAt` / `updatedAt`	Timestamps.

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:

Status	Meaning
`SUCCEEDED`	The invoice was approved by your system.
`FAILED`	The invoice was rejected or could not be approved.

Resolve a request with SUCCEEDED or FAILED — those are the only two values Upwell acts on, and only SUCCEEDED advances the carrier invoice to APPROVED. The endpoint does not currently reject the other values, so writing one leaves the request in a state nothing will progress; treat that as a bug in your integration rather than a supported option. A GET may also return the lifecycle states Upwell manages itself — INITIATED, IN_PROGRESS, RETRYING, and ABANDONED — all defined in the Vocabulary.

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 request schema, see the carrier_invoice_approval_requests entry in the API Reference — it is generated from the API schema.

Recommended flow

Discover the request

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

Decide

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

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.

​Responding to a carrier-invoice approval request

​The resource

​Resolution statuses

​Resolve a request — the callback

​Recommended flow

Responding to a carrier-invoice approval request

The resource

Resolution statuses

Resolve a request — the callback

Recommended flow