Parameters
| Query parameter | Meaning | Example |
|---|---|---|
bookingReference | Booking reference (the HBL number) to filter by. | AIRLAMD132196 |
limit | Maximum number of invoices in the response. | 25 |
offset | Number of invoices to skip. | 0 |
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/invoices?bookingReference=AIRLAMD132196&limit=25&offset=0' \
--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"
}
]- rate_list holds one row per charge with its type, description, rate and the tax split on that line.
- hbl_release_status and bl_release_request say whether the house bill has been released against this invoice.
- cgst, sgst and igst are the Indian GST components; they are zero on invoices where GST does not apply.
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
Which invoices are included?
Approved invoices only. Drafts and invoices still under review do not appear until they are approved.
How do I fetch a single invoice?
Use the Invoice Data endpoint, GET /invoice, with the invoice number.
Other endpoints
- GET /trackntrace · Track & Trace Events
- GET /booking · Ocean Booking
- POST /bookings · Ocean Booking Service
- GET /documents · Commercial Shipping Documents
- GET /invoice · Invoice Data
- All API documentation
- Free tariff API
Need access? Register your application in the developer portal; the API is open to approved Airlift customers.