Freight Invoices API Tutorial
Table of contents
Using the Freight Invoice API, you’ll be able to retrieve a list of all invoices corresponding to your shipments as well as the details of any one invoice. You can start using this API once you have established your Flexport API credentials.
Endpoints
GET /invoices
GET /invoices/id
We’ll have examples of each but first you may want to check out the full Invoice JSON object before you start.
You can retrieve invoices from Flexport issued to you by performing a GET request, such as:
curl -X "GET" "https://api.flexport.com/invoices" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Content-Type: application/json" \
and receive this as a response:
{
"_object": "/api/response",
"self": "https://api.flexport.com/invoices",
"version": 2,
"data": {
"_object": "/api/collections/paginated",
"prev": null,
"next": "https://api.flexport.com/invoices/?per=1&page=2",
"total_count": 106,
"data": [
{
"_object": "/invoice",
"id": "4SzihRl_Qq2F1FcjoNI9xQ",
"name": "FLEX-1042953-1",
"issued_at": "2021-02-24T02:53:39.983Z",
"due_date": "2021-04-24",
"total": {
"_object": "/money",
"amount": "1941.13",
"currency_code": "USD"
},
"balance": {
"_object": "/money",
"amount": "1941.13",
"currency_code": "USD"
},
"status": "past_due",
"type": "Shipment",
"voided_at": null,
"last_updated_at": null,
"notes": [
"**Containers** \n\n No containers in shipment.",
"**Notes** \n\n"
],
"recipient": {
"_object": "/company_entity",
"id": 529296,
"name": "PROSERVE Test Account",
"mailing_address": {
"_object": "/address",
"street_address": "250 Market Street",
"street_address2": "Suite 1000",
"city": "San Francisco",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94102",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "Main_Address",
"vat_numbers": [
{
"_object": "/company_entity/vat_number",
"country_code": "DE",
"number": "DE811949297"
}
]
},
"issuer": {
"_object": "/company_entity",
"id": 28714,
"name": "Flexport LLC",
"mailing_address": {
"_object": "/address",
"street_address": "760 MARKET ST FL 8",
"street_address2": "",
"city": "SAN FRANCISCO",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94102-2300",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": null
},
"ref": "id-28714",
"vat_numbers": []
},
"items": [
{
"_object": "/invoice_item",
"name": "Import Handling",
"slug": "import_handling",
"category": "destination",
"amount": {
"_object": "/money",
"amount": "55",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "55.00",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "total"
}
},
{
"_object": "/invoice_item",
"name": "Import Security Filing",
"slug": "import_security_filing",
"category": "customs",
"amount": {
"_object": "/money",
"amount": "25",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "25.00",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "bill of lading"
}
},
{
"_object": "/invoice_item",
"name": "Destination Container Freight Station Fee",
"slug": "destination_container_freight_station_fee",
"category": "destination",
"amount": {
"_object": "/money",
"amount": "440",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "44.00",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "10.000",
"qualifier": "CBM"
}
},
{
"_object": "/invoice_item",
"name": "Automated Manifest System",
"slug": "automated_manifest_system_freight",
"category": "freight",
"amount": {
"_object": "/money",
"amount": "35",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "35.00",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "bill of lading"
}
},
{
"_object": "/invoice_item",
"name": "Document",
"slug": "document",
"category": "destination",
"amount": {
"_object": "/money",
"amount": "50.4",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "50.40",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "bill of lading"
}
},
{
"_object": "/invoice_item",
"name": "LCL - Ocean Freight",
"slug": "lcl_ocean_freight",
"category": "freight",
"amount": {
"_object": "/money",
"amount": "1056",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "105.60",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "10.000",
"qualifier": "CBM"
}
},
{
"_object": "/invoice_item",
"name": "Cartage Base",
"slug": "cartage_base",
"category": "destination",
"amount": {
"_object": "/money",
"amount": "82.5",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "82.50",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "total"
}
},
{
"_object": "/invoice_item",
"name": "Fuel Surcharge",
"slug": "fuel_surcharge",
"category": "destination",
"amount": {
"_object": "/money",
"amount": "27.23",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "33",
"qualifier": "% Cartage Base"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "82.50",
"qualifier": "USD"
}
},
{
"_object": "/invoice_item",
"name": "Import Customs Clearance",
"slug": "import_customs_clearance",
"category": "customs",
"amount": {
"_object": "/money",
"amount": "125",
"currency_code": "USD"
},
"rate": {
"_object": "/invoice/rate",
"value": "125.00",
"qualifier": "USD"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "total"
}
},
{
"_object": "/invoice_item",
"name": "Freight Insurance",
"slug": "freight_insurance",
"category": "additional",
"amount": {
"_object": "/money",
"amount": "45",
"currency_code": "USD"
},
"rate": null,
"quantity": null
}
],
"credit_memos": [],
"shipments": {
"_object": "/api/refs/collection",
"ref_type": "/shipment",
"link": "https://api.flexport.com/shipments?f.invoice_id=4SzihRl_Qq2F1FcjoNI9xQ"
}
}
]
},
"error": null
}
We can request the details of a given invoice using its id:
curl -X "GET" "https://api.flexport.com/invoices/gwdpaYrhTI-T1ljn1M7o7w" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Content-Type: application/json" \
where id is that of a previously obtained invoice. You will receive the following response:
{
"_object": "/api/response",
"self": "https://api.flexport.com/invoices",
"version": 2,
"data": {
"_object": "/invoice",
"id": "gwdpaYrhTI-T1ljn1M7o7w",
"name": "FLEX-123456-1",
"issued_at": "2019-05-22T18:39:53.679Z",
"due_date": "2019-05-22",
"total": {
"_object": "/money",
"amount": "6843.29",
"currency_code": "EUR"
},
"balance": {
"_object": "/money",
"amount": "6743.29",
"currency_code": "EUR"
},
"status": "void",
"type": "Shipment",
"voided_at": "2019-05-22T20:49:15.639Z",
"last_updated_at": "2019-05-24T20:49:15.653Z",
"notes": [
"**Container numbers**\n\n1234567",
"**Notes**\n\nOther details about this invoice"
],
"recipient": {
"_object": "/company_entity",
"id": 123456,
"name": "Your Company Name",
"mailing_address": {
"_object": "/address",
"street_address": "123 MAIN ST",
"street_address2": "",
"city": "Anytown",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "12345",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": "my-address-ref"
},
"ref": "id-123456",
"vat_numbers": [
{
"_object": "company_entity/vat_number",
"country_code": "US",
"number": "US 573467947"
}
]
},
"issuer": {
"_object": "/company_entity",
"id": 28714,
"name": "Flexport LLC",
"mailing_address": {
"_object": "/address",
"street_address": "760 MARKET ST FL 8",
"street_address2": "",
"city": "SAN FRANCISCO",
"state": "CA",
"country": "United States",
"country_code": "US",
"zip": "94102-2300",
"unlocode": null,
"timezone": "America/Los_Angeles",
"ref": "flexport-address-ref"
},
"ref": "id-54321",
"vat_numbers": [
{
"_object": "company_entity/vat_number",
"country_code": "US",
"number": "US 572559803"
}
]
},
"items": [
{
"_object": "/invoice_item",
"name": "Import Customs Clearance",
"slug": "import_customs_clearance",
"category": "customs",
"amount": {
"_object": "/money",
"amount": "125",
"currency_code": "EUR"
},
"rate": {
"_object": "/invoice/rate",
"value": "125.00",
"qualifier": "EUR"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "total"
}
},
{
"_object": "/invoice_item",
"name": "Fuel Surcharge",
"slug": "fuel_surcharge",
"category": "destination",
"amount": {
"_object": "/money",
"amount": "200.61",
"currency_code": "EUR"
},
"rate": {
"_object": "/invoice/rate",
"value": "23",
"qualifier": "% Cartage Base"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "872.22",
"qualifier": "EUR"
}
},
{
"_object": "/invoice_item",
"name": "Cartage Base",
"slug": "cartage_base",
"category": "destination",
"amount": {
"_object": "/money",
"amount": "872.22",
"currency_code": "EUR"
},
"rate": {
"_object": "/invoice/rate",
"value": "0.5233",
"qualifier": "EUR"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1667",
"qualifier": "100_LB"
}
},
{
"_object": "/invoice_item",
"name": "Automated Manifest System",
"slug": "automated_manifest_system_freight",
"category": "freight",
"amount": {
"_object": "/money",
"amount": "15",
"currency_code": "EUR"
},
"rate": {
"_object": "/invoice/rate",
"value": "15",
"qualifier": "EUR"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1",
"qualifier": "bill of lading"
}
},
{
"_object": "/invoice_item",
"name": "Air Freight",
"slug": "air_freight",
"category": "freight",
"amount": {
"_object": "/money",
"amount": "5197.13",
"currency_code": "EUR"
},
"rate": {
"_object": "/invoice/rate",
"value": "3.1183",
"qualifier": "EUR"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1667.67",
"qualifier": "KG"
}
},
{
"_object": "/invoice_item",
"name": "Fuel Surcharge",
"slug": "fuel_surcharge",
"category": "freight",
"amount": {
"_object": "/money",
"amount": "433.33",
"currency_code": "EUR"
},
"rate": {
"_object": "/invoice/rate",
"value": "0.26",
"qualifier": "EUR"
},
"quantity": {
"_object": "/invoice/quantity",
"value": "1667.67",
"qualifier": "KG"
}
}
],
"credit_memos": [
{
"_object": "/credit_memo",
"amount": {
"_object": "/money",
"amount": "100",
"currency_code": "EUR"
},
"category": "customs",
"reason": "reason for credit",
"credited_at": "2019-05-24T18:39:53.679Z"
}
],
"shipments": {
"_object": "/api/refs/collection",
"ref_type": "/shipment",
"link": "https://api.flexport.com/shipments?f.invoice_id=882a43a2-7b04-4be4-9c6f-2fb92edbf6c3"
}
}
}
The List all invoices endpoint allows you to filter using the parameters here.
It is not recommended to use expansion parameters when querying the /invoices index. If you need to expand a resource, it is recommended that you do this under the unique invoice URI (at /invoices/:id).
In general, most customers are interested in retrieving unpaid invoices (status=’outstanding’). If you are polling invoices to integrate with your AP system, the field name is the unique Flexport invoice number.
It’s recommended that you add a query per page parameter with a maximum of ten per page, per=10 for better performance. However, we support a maximum value of 100, e.g., per=100.
Let’s look at possible errors and steps necessary to correct them. This is example of an error response:
{
"_object": "/api/error",
"status": 400,
"code": "invalid_pagination",
"message": "Invalid Sort Direction. allowed values: desc, asc"
}
You’ll want to use the status and message fields to handle exceptions.