Invoice Data API

GET /invoice returns a single invoice by its invoice number, with the same record the invoices list returns: the booking and container it belongs to, each charge line with its rate, exchange rate and tax components, the taxable and non-taxable amounts, the total, the payment type, the e-invoice status and the house bill release status. Use it to refresh one invoice after a status change instead of re-reading the whole list.

GEThttps://api.airliftusa.com/api/v1/api-service/external/invoice · scope invoice:read · reference updated 2025-01-06

Parameters

Query parameterMeaningExample
invoiceNumberThe Airlift invoice number.INV-12345

Send Authorization: Bearer <token> with every request. The token comes from the OAuth 2.0 client credentials flow and must carry the invoice:read scope.

Example request

curl 'https://api.airliftusa.com/api/v1/api-service/external/invoice?invoiceNumber=INV-12345' \
  --header 'Authorization: Bearer YOUR_TOKEN'

Example response (200)

{
  "invoice_number": "INV-12345",
  "date": "2024-01-20",
  "hbl_number": "HBL12345",
  "container_no": "CMAU1234567",
  "payment_type": "PREPAID",
  "rate_list": [
    { "type": "FREIGHT", "rate_description": "Ocean Freight", "rate": 3000, "exchange_rate": 1, "cgst_in": 270, "sgst_in": 270, "igst_in": 0, "collections": "COLLECTED" }
  ],
  "taxable_amount": 5000,
  "non_taxable_amount": 1000.5,
  "cgst": 450,
  "sgst": 450,
  "igst": 0,
  "total": 5900.5,
  "e_invoice_status": "ISSUED",
  "hbl_release_status": "RELEASED",
  "bl_release_request": "APPROVED",
  "remarks": "Freight charges"
}
  • total is taxable_amount plus the tax components plus non_taxable_amount.
  • e_invoice_status reports whether an e-invoice has been issued for the document.

Other status codes: 400 missing or invalid parameter, 401 token missing or expired, 403 scope not granted, 404 nothing matches the reference, 500 server error. Limits are 60 requests a minute and 4,000 an hour per consumer, reported in the X-RateLimit-* headers.

Frequently asked questions

Where do I get the invoice number?

From the invoices list endpoint, from the invoice PDF, or from the customer portal.

Is the amount in USD?

The record carries the rate and an exchange_rate per charge line; the currency follows the invoice as issued. Check exchange_rate before summing lines across invoices.

Other endpoints

Need access? Register your application in the developer portal; the API is open to approved Airlift customers.

Full reference: models, response schemas, client snippets and a live console

Everything the guide above leaves out: every response schema, the request in cURL, Node.js, Python and Go, the environment and token panel, the OpenAPI download and the Swagger console.

Models

ErrorResponseModel
object1 fields
Fields
error
object
Properties
code
string

Error code

message
string

Human-readable error message

InvoiceModel
object16 fields
Description

Invoice details.

Fields
bl_release_request
string

BL release request status.

cgst
number

CGST amount.

container_no
string

Container numbers.

date
string

Invoice date.

e_invoice_status
string

E-invoice status.

hbl_number
string

HBL number.

hbl_release_status
string

HBL release status.

igst
number

IGST amount.

invoice_number
string

Invoice number.

non_taxable_amount
number

Non-taxable amount.

payment_type
string

Payment type.

rate_list
array

Rate list items.

remarks
string

Remarks.

sgst
number

SGST amount.

taxable_amount
number

Taxable amount.

total
number

Total amount.

InvoiceRateModel
object8 fields
Description

Invoice rate details.

Fields
cgst_in
number

CGST amount.

collections
string

Collections type.

exchange_rate
number

Exchange rate.

igst_in
number

IGST amount.

rate
number

Rate amount.

rate_description
string

Rate description.

sgst_in
number

SGST amount.

type
string

Rate type.

Release Notes

Version Date Notes
1.0.02025-01-06Initial release of invoice retrieval.

We value your privacy

We use cookies to keep our portal working, measure site usage, and analyse the businesses that visit us. Under U.S. state privacy laws, the data we share with our analytics, advertising and sales partners is considered a “sale” or “sharing” of personal data.