Skip to content

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.

curl -X POST https://api.ga-oms.com/v1/orders \
-H "Authorization: Bearer ga_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d @order.json

order.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.

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" }
  • purpose is order_template (.xlsx, 10 MB at most) or attachment (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.

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.

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 中文.

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, and template_file (with tracking: "box" to turn box scan on).
  • An ETA already on file stays, and so does a figure our team corrected. The answer’s warnings say what was not applied.
  • channels must list the same number of channels the order has.
  • mawb, destination, service_type, importers, draft_7501 and customer_ref cannot be changed here. Contact us.

GET /v1/orders/{id} reads the order with its shipment as it stands now.

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.

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