Approving Cargobase invoices from a finance system

Providers submit invoices in Cargobase. The shipper’s finance system is where the amount is checked. This write-up is how that approval stays in Cargobase instead of living only in an email thread.

The problem

An invoice sits in Cargobase as Awaiting audit. Finance already has the provider’s invoice number and the shipment. Someone still has to open Cargobase and click approve or decline.

The integration should list invoices for this company, match them to the finance record, and write the decision back.

What we use

A Shipper token. Invoice reads are also available to a provider token for that provider’s own invoices; the approve and decline call is the shipper audit step. See Authentication.

Both operations are in the Shipper API reference.

Need	Call
Invoices for a month or a status	GET /api/1/invoices/
One invoice, including organization and service	GET /api/1/invoices/{invoice_reference}/
Approve or decline	POST /api/1/invoice-status-update/{invoice_reference}

The list defaults to 50 invoices per page, newest first. Filter with the query values the API already documents, for example status=awaiting_audit and submit_date=this_month.

How it plugs into finance

On each invoice row in finance, store invoice_reference from Cargobase and the provider’s own number (provider_invoice_number) so the two systems can be matched when a new list page arrives.

1. GET /api/1/invoices/?status=awaiting_audit&submit_date=this_month.
2. Page with page until next is empty.
3. For each invoice_reference finance does not already have, GET the detail and create or update the finance record.
4. When a clerk approves or declines in finance, POST that decision. action is approved or declined. comment is required.

POST https://sandbox.cargobase.com/api/1/invoice-status-update/I12345678
Authorization: Token <access_token>
Content-Type: application/json

{
  "action": "approved",
  "comment": "Matches the awarded quote."
}

201 means Cargobase recorded the decision. 400 with “already Approved/Declined” means the invoice was acted on already — leave the finance row as it is and do not retry. 404 means that reference is not visible to this token.

List statuses you will see include Awaiting audit, Approved, Declined, Removed, Canceled, and Unsubmitted (providers only). Filter values are the snake-case forms, such as awaiting_audit.

What this achieves

Invoices waiting on the shipper show up in finance with the Cargobase reference, the provider invoice number, and the shipment. An approval or decline in finance is the same state Cargobase shows, and a second post does not flip an invoice that was already decided.