Orders
An order through the API is the order you place on the portal’s order page: the same checks, on file at once, the same confirmation email. Your key needs the scope orders:write. Ask your Golden Arcus contact to add it.
Place an order
Section titled “Place an order”curl -X POST https://api.ga-oms.com/v1/orders \ -H "Authorization: Bearer ga_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d @order.jsonorder.json:
{ "mawb": "000-12345675", "service_type": "T11", "destination": "LAX", "origin": "HGH", "eta": "2026-12-01", "flight": "CX 880", "cartons": 120, "gross_weight_kg": 1520.5, "importers": ["Example Importer LLC"], "channels": [ { "channel": "UPS", "cartons": 80 }, { "channel": "USPS", "cartons": 40 } ]}The answer is 201 with the order and the shipment it made:
{ "id": "ord_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "object": "order", "shipment_id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "warnings": [], "shipment": { "id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "object": "shipment", "mawb": "000-12345675", "phase": "flight", "…": "…" }}Save id to change the order, and shipment_id to follow the cargo with Shipments and Events.
| Field | Meaning |
|---|---|
mawb |
NNN-NNNNNNNN |
service_type |
T01, T11 or Ground Handling |
destination |
LAX, ORD, JFK or IAH |
origin |
Departure airport |
eta |
Arrival date at the destination, YYYY-MM-DD |
flight |
Flight number |
cartons |
Cartons on the MAWB |
pieces |
HAWB pieces |
gross_weight_kg |
Gross weight in kilograms |
importers |
Importer account names. T01 takes up to three, T11 one, Ground Handling none |
channels |
The cartons per last-mile channel: channel, cartons, and tape for a tape colour. They add up to cartons |
draft_7501 |
true to confirm the 7501 draft before it is filed |
tracking |
box to have every carton scanned. It needs template_file with the packing list. Default none |
customer_ref |
Your own reference. It is named on the confirmation email |
remark |
Words for our operations team |
template_file |
The filled GA order template, sent first. See below |
attachments |
Other files for the order, sent first. Up to 10 |
Numbers are numbers, not text. A field the API does not know is refused, so a mistyped name is not silently dropped.
Send the order template instead
Section titled “Send the order template instead”The GA order template (.xlsx, from the order page of the portal) carries the customs lines and the packing list. Send the file first:
curl -X POST https://api.ga-oms.com/v1/files \ -H "Authorization: Bearer ga_live_YOUR_KEY" \ -F purpose=order_template \{ "id": "file_01JCX7M4Z9Q8R6T5V3W2Y1N0AB", "object": "file", "purpose": "order_template", "filename": "GA-order-000-12345675.xlsx", "size": 48213, "expires_at": "2026-11-19T22:05:11Z"}Then name it in the order. Any field you leave out is read from the template, and a field you send wins:
{ "template_file": "file_01JCX7M4Z9Q8R6T5V3W2Y1N0AB" }purposeisorder_template(.xlsx, 10 MB at most) orattachment(pdf, doc, docx, xls, xlsx, csv, png, jpg; 25 MB at most).- A file belongs to one order. A file no order has used is deleted after two days.
- A template with problems is refused with each problem and its sheet and rows.
Check before you send
Section titled “Check before you send”POST /v1/orders/validate takes the same body, checks it exactly as a create would and saves nothing:
{ "object": "order_check", "valid": true, "action": "create", "warnings": [] }An order that would be refused is refused here with the same answer.
When an order is refused
Section titled “When an order is refused”Every problem comes at once, in order_invalid:
{ "type": "https://developers.ga-oms.com/errors/order_invalid", "title": "The order has problems", "status": 422, "code": "order_invalid", "detail": "The order was not accepted: 2 problems", "errors": [ { "message": "ETA \"soon\" must be Y-m-d" }, { "message": "Last-mile CTNs (120) do not equal total CTNs (130)" } ], "request_id": "req_01JCX7M4Z9Q8R6T5V3W2Y1N0AB"}Send Accept-Language: zh to get the problems in 中文.
Change an order
Section titled “Change an order”PATCH /v1/orders/{id} changes only the fields you send:
curl -X PATCH https://api.ga-oms.com/v1/orders/ord_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d \ -H "Authorization: Bearer ga_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "flight": "CX 884", "gross_weight_kg": 1498 }'- You can change
origin,eta,flight,cartons,pieces,gross_weight_kg,remark,channels,attachments, andtemplate_file(withtracking: "box"to turn box scan on). - An ETA already on file stays, and so does a figure our team corrected. The answer’s
warningssay what was not applied. channelsmust list the same number of channels the order has.mawb,destination,service_type,importers,draft_7501andcustomer_refcannot be changed here. Contact us.
GET /v1/orders/{id} reads the order with its shipment as it stands now.
Sending it twice
Section titled “Sending it twice”One MAWB is one order. If a create may have gone through, send it again: when it did, the answer is order_exists with the order’s id.
{ "type": "https://developers.ga-oms.com/errors/order_exists", "title": "Already on file", "status": 409, "code": "order_exists", "detail": "MAWB 000-12345675 is already your order ord_0a1b…: change it with PATCH /v1/orders/ord_0a1b….", "order_id": "ord_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "shipment_id": "shp_0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d", "request_id": "req_01JCX7M4Z9Q8R6T5V3W2Y1N0AB"}On busy nothing was saved: wait the seconds in Retry-After and send the same call again.
The order object
Section titled “The order object”| Field | Meaning |
|---|---|
id |
Made by us. Use it to read and change the order |
shipment_id |
The shipment this order is |
warnings |
What was accepted but not applied as sent, in words. Empty when an order is read |
shipment |
The whole shipment object as it stands now |