> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upwell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Responding to a carrier-invoice approval request

> Resolve a pending carrier-invoice approval request from your integration by setting its status to SUCCEEDED or FAILED.

# 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.

<Note>
  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.
</Note>

## The resource

`GET /api/rest/carrier_invoice_approval_requests/{id}` returns a single request:

```bash theme={null}
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](/api-guides/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. |

<Note>
  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`.
</Note>

## 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`:

```bash theme={null}
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"`.

<Warning>
  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.
</Warning>

<Note>
  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](/api-reference/introduction) — it is generated directly from the live API.
</Note>

## Recommended flow

<Steps>
  <Step title="Discover the request">
    Receive it via a webhook, or poll `GET /api/rest/carrier_invoice_approval_requests`.
  </Step>

  <Step title="Decide">
    Use the nested `carrierInvoice` details (carrier, invoice number, amount) to make your decision.
  </Step>

  <Step title="Resolve it">
    `PATCH` the request with `status` `SUCCEEDED` or `FAILED`. This clears the pending **Approve** state in Upwell.
  </Step>
</Steps>

<Note>
  For the carrier-invoice lifecycle itself — statuses, exceptions, and how to know when processing is done — see [Knowing when a carrier invoice is processed](/api-guides/carrier-invoice-status). To submit carrier invoices in the first place, see [Submitting carrier invoices via API](/api-guides/carrier-invoice-submission).
</Note>