{"openapi":"3.1.0","info":{"title":"RAMPS API","description":"The **RAMPS API** is a secure REST interface to RAMPS Logistics' operational\ndata. It lets authorised partners create, read, and update purchase orders — over a clean, versioned,\nOAuth2-protected API.\n\n## Overview\n\n- **Base path:** all endpoints live under `/api/v1`.\n- **Format:** JSON responses; JSON or XML accepted where noted.\n- **Transport:** HTTPS only.\n- **Auth:** OAuth2 **client-credentials** (server-to-server) — see below.\n\nThe underlying systems are never exposed directly — you interact only with the\nresources documented here.\n\n## Environments\n\nSelect the target server from the **Servers** dropdown above. Credentials are issued\nper environment and are **not** interchangeable.\n\n| Environment | Purpose |\n|---|---|\n| Production | Live data. Use your production credentials. |\n| Sandbox / Staging | Integration testing against non-live data (if provisioned). |\n\n## Getting started (3 steps)\n\n1. **Get credentials.** You'll be issued a `client_id` and `client_secret`, scoped to\n   what your integration is permitted to do.\n2. **Get a token.** `POST /api/v1/oauth/token` with\n   `grant_type=client_credentials` + your credentials → you receive an `access_token`\n   (valid ~30 min).\n3. **Call the API.** Send `Authorization: Bearer <access_token>` on every request.\n   On this page, click **Authorize** (top right) once and it applies to all\n   \"Try it out\" calls (it persists across refreshes).\n\n## Scopes\n\nEach token carries scopes that gate what it can do:\n\n| Scope | Grants |\n|---|---|\n| `orders:read` | Read and list purchase orders |\n| `orders:write` | Create and update purchase orders |\n\nA missing scope returns **403 `insufficient_scope`**; a missing/expired token returns\n**401 `unauthorized`**.\n\n## Referencing your own IDs\n\nYou can send **your own identifiers** on a purchase order and we resolve them to our\nrecords — no need to look up ours first:\n\n- **Delivery location** — send `delivery_address.id` (your Ship-To / location code, e.g.\n  `TA32`). The **first** time we see a code, include the address alongside it and we\n  register it; **after that the code alone is enough** and we fill in the address for you.\n- **Supplier** — send `supplier_id` (your vendor number). Once it's linked to a supplier\n  on our side, every future order with that ID matches the supplier automatically. An\n  ID we don't yet recognise never fails the order — it's recorded and linked on our side.\n\nAnything we can't match is returned in `warnings` **without failing the request**, so a\nfirst-time code or a new supplier is never a hard error.\n\n## Units of measure\n\nEach line item accepts a **`uom`** (unit of measure, e.g. `EA`, `KG`, `CBM`) that we\ncarry through with the line. Send it per line under `lines[].uom` (XML: `CargoLine/UOM`).\n\n## Idempotency\n\n`POST /purchase-orders` accepts an **`Idempotency-Key`** header with a value unique to\neach logical submission. Re-sending the same key **with the same body** returns the\n*original* result — so it is always safe to retry on a timeout or network error.\n\nIf you resend a purchase order **with changed data**, the existing order (matched on your\nPO number) is **updated in place** with the new values — never duplicated. So a correction\nalways takes effect, whether you send it under a new key, no key, or the same key.\n\n## Pagination\n\nList endpoints (`/purchase-orders`) accept **`limit`** (1–200, default 50) and\n**`offset`**, and return `count` (total matches, ignoring paging), `limit`, `offset`,\nand `results`. Compute pages from `count`.\n\n## Errors\n\nEvery error uses one envelope — **branch on the stable `error` code, not the message** —\nand includes the `request_id` for support:\n\n```json\n{ \"error\": \"insufficient_scope\", \"error_description\": \"Token is missing required scope: orders:write\", \"request_id\": \"a1b2c3…\" }\n```\n\n| Status | `error` | Meaning |\n|---|---|---|\n| 400 | `bad_request` / `missing_idempotency` | Malformed or missing input |\n| 401 | `unauthorized` | Missing, invalid, or expired token |\n| 403 | `insufficient_scope` | Token lacks the required scope |\n| 404 | `not_found` | Resource does not exist |\n| 409 | `conflict` | Idempotency clash |\n| 422 | `validation_error` | Request body failed validation |\n| 429 | `rate_limited` | Too many requests — back off and retry |\n| 502 | `upstream_error` | An upstream service returned an error |\n| 503 | `upstream_unavailable` / `database_unavailable` | Temporary — retry after `Retry-After` |\n\n**Retries:** treat `429`, `502`, and `503` as retryable (honour `Retry-After` when present);\n`4xx` other than `429` are permanent — fix the request.\n\n## Rate limiting\n\nFair-use limits may apply per credential. When exceeded you receive **429 `rate_limited`**\nwith a `Retry-After` header — back off and retry after the indicated delay.\n\n## Versioning\n\nThe API is versioned in the path (`/api/v1`). We add fields and\nendpoints without notice (**additive, backward-compatible**); breaking changes ship\nunder a new version prefix. Ignore unknown fields you don't use.","contact":{"name":"RAMPS Logistics — Integrations","url":"https://rampslogistics.com/","email":"integrations@rampslogistics.com"},"license":{"name":"Proprietary — RAMPS Logistics"},"version":"1.0.0"},"paths":{"/health":{"get":{"tags":["meta"],"summary":"Liveness / readiness","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/upstream":{"get":{"tags":["meta"],"summary":"Upstream connectivity check","operationId":"health_upstream_health_upstream_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/oauth/token":{"post":{"tags":["Authentication"],"summary":"Get an access token","description":"**Step 1 of every integration.** Exchange your `client_id` and `client_secret` for a short-lived Bearer token, then send that token as `Authorization: Bearer <token>` on all other calls.\n\n- **Grant type:** `client_credentials` (server-to-server).\n- **Credentials:** pass `client_id`/`client_secret` as form fields, *or* as an HTTP Basic `Authorization` header.\n- **Scope:** omit to receive all scopes your client is allowed; or request a subset (space-separated). Requesting a scope you don't have → `400`.\n- **Lifetime:** see `expires_in` (seconds). Request a new token when it expires.","operationId":"issue_token_api_v1_oauth_token_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_issue_token_api_v1_oauth_token_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"The request was malformed or missing a required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"bad_request","error_description":"The request was malformed or missing a required field."}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/purchase-orders":{"post":{"tags":["Purchase Orders"],"summary":"Create or update a purchase order","description":"Submit a purchase order (XML or JSON). Creates an order — or, if an order with the same\n**customer PO number** already exists, **updates it in place** with the new values (no\nduplicate). Resend the same PO whenever its data changes and the existing order is\nupdated to match. The raw payload is stored for audit.\n\nThe existing order is found through your own submission history first, then by\nsearching on the customer PO number — so the same PO always lands on the same order.\nIf several orders somehow carry the same PO number (legacy duplicates), the response\n`warnings` lists the others so they can be cleaned up.\n\n### Required fields (create)\n\nMissing any of these returns **400 `missing_required_fields`** listing exactly what's absent.\n\n| Field (JSON key) | XML location | Notes |\n|---|---|---|\n| `customer_po_number` | `Header/PurchaseOrderNumber` | Your PO number — also the duplicate check |\n| `customer_name` | `Header/Customer/Name` | Matched to your customer account by name (fuzzy). **Not on file → the customer is registered automatically** (noted in `warnings`) |\n| `direction` | `Header/Direction` | `IMPORT` or `EXPORT` |\n| `incoterms` | `Header/Incoterms` | Standard code, e.g. `FOB`, `EXW`, `CIF` |\n\n### Optional fields\n\n| Field (JSON key) | XML location | Notes |\n|---|---|---|\n| `customer_reference` | `Header/CustomerReference` | Your Freight Order Number (also settable later via PUT) |\n| `supplier` | `Header/Vendor` | Supplier object: `id` (your supplier ID), `name`, `email`, `phone`, and address (`street1`, `street2`, `city`, `state`, `zip`, `country`). **The `id` is authoritative**: known → selects that supplier (never recreated) and refreshes its stored details with whatever changed; unknown → registers a new supplier under that `id`. Name matching is used only when no `id` is sent |\n| `vendor_name` / `supplier_id` *(alias `vendor_ref`)* | `Header/Vendor/Name`, `Header/Vendor/VendorNumber` | Flat form of the above — still accepted |\n| `pickup_address.supplier_id` | `Header/PickUpAddress/SupplierId` | Links the pick-up address to that supplier (a supplier can have several pick-up addresses). Defaults to the order's supplier |\n| `dates.required_by` *(alias `required_on_site`)* | `Header/Dates/RequiredOnSiteDate` | `YYYY-MM-DD` — when the cargo is needed on site |\n| `mode_of_transport` | `Header/ModeOfTransport` | Stored as `air_freight`, `ocean_freight`, `road` or `mode_of_transport_not_set`. `AIR`, `OCEAN`, `SEA`, `ROAD`, `TRUCK` are accepted and normalised |\n| `incoterms_location` | `Header/IncotermsLocation` | Named place for the incoterm |\n| `company_code` | `Header/CompanyCode` | Your company code |\n| `currency` | `Header/Currency` | ISO code, e.g. `USD` |\n| `cargo_value` | `Header/TotalCargoValue` | Declared value |\n| `special_instructions` | `Header/SpecialInstructions` | |\n| `order_details` | `Header/OrderDetails` | |\n| `dates.cargo_ready_date` *(alias `cargo_ready`)* | `Header/Dates/CargoReadyDate` | `YYYY-MM-DD` |\n| `dates.supplier_promise_date` *(alias `supplier_promise`)* | `Header/Dates/SupplierPromiseDate` | `YYYY-MM-DD` |\n| `dates.approval_to_ship_date` *(alias `approval_to_ship`)* | `Header/Dates/ApprovalToShipDate` | `YYYY-MM-DD` |\n| `cargo_description` | `CargoDetails/CargoDescriptionSummary` | |\n| `total_pieces` / `total_weight` / `total_volume` | `CargoDetails/Total*` | |\n| `delivery_address` | `Header/DeliveryAddress` | Drop location: `id` (your Ship-To/location code), `street1`, `street2`, `city`, `state`, `zip`, `country`, `region`. A known `id` alone resolves the registered address; sending an address **with** the `id` makes the sent address win for this order (that's how you change where an order delivers); a new `id` **with** an address is registered so the `id` alone works next time |\n| `pickup_address` | `Header/PickUpAddress` | **Omit if unavailable** — we arrange collection with the supplier |\n| `…address.location_name` | `…Address/LocationName` | Name the address is filed under (site / depot / warehouse). Defaults to `street1`. Sent **with an address**, a different name registers a **new** address and points this order at it — stored addresses are shared between orders, so they are never renamed in place. Sent with a known `id` and no address it is ignored (the `id` resolves), so a GET response can be echoed straight back |\n| `…address.country` | `…Address/Country` | **ISO 3166-1 alpha-2 code** (`TT`, `US`) — returned as the code too. Full country names are still accepted on submit |\n| `…address.region` | `…Address/Region` | **ISO 3166-2 subdivision code** within the country (`CTT`, `TX`). The full ISO form (`TT-CTT`) and the region name are also accepted. Optional — omitting it leaves the region unset |\n| `po_details[]` *(legacy alias `lines`)* | `CargoDetails/CargoLine` | Line items → PO Details: `line`, `description`, `quantity`, `material_code` (XML `MaterialCode`; falls back to `part_number`). Physical data per line goes to the cargo lines: `part_number`, `lot_number`, `piece_count`, `weight`, `volume`, dimensions. **Lines are matched on `line`** and updated in place, so resubmitting keeps each line's identity; lines you omit are left untouched |\n| `po_details[].status` | `CargoDetails/CargoLine/Status` | `created`, `updated` or `deleted`. A `deleted` line is **kept** on the order for history — that is why there is no delete endpoint. Omit to leave the stored status alone; an unrecognised value warns |\n\nSend more rather than less — everything we can map is stored; anything we can't match\n(e.g. an unknown supplier name) is reported in the response `warnings` **without failing\nthe request**.\n\n**Idempotency:** send an `Idempotency-Key` header unique to each submission. Re-sending\nthe *same key with the same body* replays the original result (safe retry) — but only\nafter confirming with Odoo that the order still exists; if it was deleted or closed\nsince, the submission is processed fresh and a new order is created. Re-sending\n**changed data** — whether under a new key, no key, or even the same key — updates the\nexisting order rather than replaying, so a correction always takes effect.\n\nResponse `action` is `created` or `updated`; `warnings` lists non-fatal mapping notes.","operationId":"create_or_update_purchase_order_api_v1_purchase_orders_post","security":[{"OAuth2ClientCredentials":["orders:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Unique per submission; re-sending returns the original result.","title":"Idempotency-Key"},"description":"Unique per submission; re-sending returns the original result."}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderResult"}}}},"200":{"description":"Updated an existing order, or idempotent replay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderResult"}}}},"400":{"description":"The request was malformed or missing a required field.","content":{"application/json":{"example":{"error":"bad_request","error_description":"The request was malformed or missing a required field."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with current state (e.g. an idempotency clash).","content":{"application/json":{"example":{"error":"conflict","error_description":"The request conflicts with current state (e.g. an idempotency clash)."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"example":{"customer_po_number":"4500015030","customer_reference":"FO-2026-00045","customer_name":"Shell Trinidad and Tobago Limited","supplier":{"id":"200000004","name":"Gulf Coast Industrial Supplies Inc.","email":"orders@gulfcoastindustrial.com","phone":"+1 780 555 0142","street1":"9915 108 Street NW","street2":"6th Floor South Petroleum Plaza","city":"Edmonton","state":"","zip":"T5K 2G8","country":"CA","region":"AB"},"pickup_address":{"supplier_id":"200000004","location_name":"Petroleum Plaza Depot","street1":"9915 108 Street NW","street2":"Dock 4, Bay B","city":"Edmonton","zip":"T5K 2G8","country":"CA","region":"AB"},"direction":"import","incoterms":"FOB","incoterms_location":"Point Lisas, Trinidad","company_code":"TT01","mode_of_transport":"OCEAN","currency":"USD","cargo_value":45000.0,"cargo_description":"Industrial valves, gaskets, and centrifugal pump","special_instructions":"Delivery At Place","dates":{"required_by":"2026-04-10","cargo_ready_date":"2026-03-15"},"delivery_address":{"id":"TA32","location_name":"Point Lisas Warehouse 14","street1":"Point Lisas Industrial Estate","street2":"Warehouse 14","city":"Couva","state":"","zip":"","country":"TT","region":"CTT"},"po_details":[{"line":"10","status":"updated","description":"SP15 YN & YN - Normal","quantity":30,"uom":"EA","material_code":"1000060021","weight":450.0},{"line":"20","status":"created","description":"SP15 YN & YN - Normal","quantity":2,"uom":"EA","material_code":"1000060021","weight":450.0},{"line":"30","status":"deleted","description":"SP15 YN & YN - Normal","quantity":10,"uom":"EA","material_code":"1000060021","weight":450.0}]}},"application/xml":{"example":"<PurchaseOrder>\n  <Header>\n    <PurchaseOrderNumber>4500123456</PurchaseOrderNumber>\n    <CustomerReference>FO-2026-00045</CustomerReference>\n    <Direction>IMPORT</Direction>\n    <Incoterms>FOB</Incoterms>\n    <IncotermsLocation>Point Lisas, Trinidad</IncotermsLocation>\n    <CompanyCode>TT01</CompanyCode>\n    <ModeOfTransport>OCEAN</ModeOfTransport>\n    <Currency>USD</Currency>\n    <TotalCargoValue>45000.00</TotalCargoValue>\n    <Dates>\n      <RequiredOnSiteDate>2026-04-10</RequiredOnSiteDate>\n      <CargoReadyDate>2026-03-15</CargoReadyDate>\n    </Dates>\n    <Customer><Name>Shell Trinidad and Tobago Limited</Name></Customer>\n    <Vendor>\n      <VendorNumber>200000004</VendorNumber>\n      <Name>Gulf Coast Industrial Supplies Inc.</Name>\n      <Email>orders@gulfcoastindustrial.com</Email>\n      <Phone>+1 780 555 0142</Phone>\n      <Address><Street1>9915 108 Street NW</Street1><City>Edmonton</City><PostalCode>T5K 2G8</PostalCode><Country>CA</Country></Address>\n    </Vendor>\n    <PickUpAddress><SupplierId>200000004</SupplierId><LocationName>Petroleum Plaza Depot</LocationName><Street1>9915 108 Street NW</Street1><Street2>Dock 4, Bay B</Street2><City>Edmonton</City><PostalCode>T5K 2G8</PostalCode><Country>CA</Country><Region>AB</Region></PickUpAddress>\n    <DeliveryAddress><ShipToCode>TA32</ShipToCode><LocationName>Point Lisas Warehouse 14</LocationName><Street1>Point Lisas Industrial Estate</Street1><Street2>Warehouse 14</Street2><City>Couva</City><Country>TT</Country><Region>CTT</Region></DeliveryAddress>\n  </Header>\n  <CargoDetails>\n    <CargoDescriptionSummary>Industrial valves</CargoDescriptionSummary>\n    <CargoLine><LineNumber>1</LineNumber><Status>updated</Status><Description>Gate Valves 4IN</Description><Quantity>2</Quantity><UOM>EA</UOM><MaterialCode>MAT-78923-A1</MaterialCode><Weight>450.0</Weight></CargoLine>\n  </CargoDetails>\n</PurchaseOrder>"}}}},"get":{"tags":["Purchase Orders"],"summary":"List / search purchase orders","description":"Paginated list of purchase orders. **Closed orders are excluded.** Orders created before 2026-07-01 are excluded. Filter by state or by customer PO number (partial match). The list view returns order summaries; the booking, addresses, and PO Details are included on the single-order read — see **Get a purchase order** for the full field reference.","operationId":"list_purchase_orders_api_v1_purchase_orders_get","security":[{"OAuth2ClientCredentials":["orders:read"]}],"parameters":[{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by order state.","title":"State"},"description":"Filter by order state."},{"name":"customer_po_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by customer PO number (partial, case-insensitive).","title":"Customer Po Number"},"description":"Search by customer PO number (partial, case-insensitive)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"},"example":{"count":128,"limit":50,"offset":0,"results":[{"order_reference":"ORD00001","customer_po_number":"4500123456","pro_reference":"PRO-2026-01","trucker_reference":"","freight_unit_number":"FU-8100412345","freight_order_type":"ZFO5","change_ordinal_number":3,"source_location_id":"1000123","destination_location_id":"1005678","asn_number":"ASN-2026-000001","asn_type":"original","asn_date":"2026-03-15","state":"order","direction":"import","mode_of_transport":"ocean_freight","freight_type":"fcl","hazardous":"no","is_cargo_bonded":"","has_house_booking":"does_not_have_house_booking","trucking_arranged_by":"ramps","consignee":"Shell Trinidad and Tobago Limited","shipper":"Gulf Coast Industrial Supplies Inc.","origin_agent":"","trucker":"","assigned_to":"Maria Garcia","port_of_loading":"Houston, US","booking_reference":"RHB1948","quotation":"","cargo_description":"Industrial valves, gaskets, and centrifugal pump","cargo_value":45000.0,"pickup_date":"2026-03-15","cargo_ready_date":"2026-03-15","supplier_promise_date":"2026-03-20","approval_to_ship_date":"2026-03-14","created_at":"2026-03-06T09:12:00","attended_by":"","attention":"","special_instructions":"Temperature controlled storage required. Do not stack.","order_details":"Shell Materials Management — LSP notification","customer":"Shell Trinidad and Tobago Limited","customer_reference":"FO-2026-00045","incoterms":"fob","incoterms_location":"Point Lisas, Trinidad","company_code":"TT01","currency":"USD","move_type":"","ready_to_ship":"no","carrier":"","customer_care_rep":"","assigned_bde":"","port_of_discharge":"Port of Spain, TT","destination_country":"Trinidad and Tobago","total_pieces":8.0,"total_weight":2450.0,"total_volume":12.5,"required_by":"2026-04-10","warehouse_receipt_number":""}]}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/purchase-orders/{identifier}":{"put":{"tags":["Purchase Orders"],"summary":"Update a purchase order (partial)","description":"Partially update an existing order, identified by our **ORD number** or your **customer PO number** (auto-detected). Send **only the field(s) you want to change** — everything else is left untouched:\n\n* `customer_reference` — your **Freight Order Number**.\n* `freight_unit_number` / `freight_unit_type` / `freight_order_type` — your **Freight Unit** and Freight Order references, updatable individually or together.\n* `delivery_address` — switch where the order delivers: a Ship-To `id` alone resolves the registered location; an address (with or without `id`) sets it explicitly, and a new `id` sent with an address is registered for future use.\n* `pickup_address` — the collection address.\n* Order data: `special_instructions`, `order_details`, `cargo_description`, `cargo_value`, `hazardous`, `incoterms`, `incoterms_location`, `company_code`, `mode_of_transport`, `direction`, `currency`, `total_pieces`, `total_weight`, `total_volume`, and `dates` (`cargo_ready_date`, `required_by`, `supplier_promise_date`, `approval_to_ship_date` — the same names the GET returns).\n* `po_details` — **replaces** the PO Details / cargo line items with exactly what you send (same shape as `po_details[]` on submit, incl. `material_code`; `weight` lands on the cargo line). `lines` is accepted as a legacy alias.\n\nThe response's `updated_fields` confirms exactly what changed; anything that could not be applied (e.g. an unrecognised incoterm) is reported in `warnings` without failing the rest of the update. To change line items or parties, re-submit the purchase order via `POST /purchase-orders` — the same customer PO number updates the existing order instead of creating a new one.\n\nThe operation is idempotent: sending the same values twice leaves the order unchanged.","operationId":"update_purchase_order_api_v1_purchase_orders__identifier__put","security":[{"OAuth2ClientCredentials":["orders:write"]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderUpdateResult"}}}},"400":{"description":"The request was malformed or missing a required field.","content":{"application/json":{"example":{"error":"bad_request","error_description":"The request was malformed or missing a required field."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"example":{"error":"validation_error","error_description":"The request body failed validation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Purchase Orders"],"summary":"Get a purchase order","description":"Read one purchase order by our **ORD number** or the **customer PO number** (auto-detected). Returns the full field set including the related freight booking, pick-up/delivery addresses, and PO Details line items. Closed orders are excluded. Orders created before 2026-07-01 are excluded.\n\n### Response field reference\n\n| Field | Meaning |\n|---|---|\n| `order_reference` | Our unique order reference (ORD number), assigned when the order is created. Use it to read or update this order. |\n| `customer_po_number` | Your purchase order number, exactly as submitted. Also used to detect duplicates: re-submitting the same number updates the existing order. |\n| `pro_reference` | Carrier PRO (tracking) number for the road/trucking leg, when assigned. |\n| `trucker_reference` | Our trucker booking reference (RTR), generated when a pick-up trucking booking is created for this order. |\n| `freight_unit_number` | Your Freight Unit reference for this order. Set via `PUT /purchase-orders/{identifier}` or the dedicated `…/freight-unit` route. |\n| `freight_order_type` | Your Freight Order type code. `ZFO5` for **EPCM** and **return** orders; left **blank** for anything else. Set via `PUT /purchase-orders/{identifier}` or the dedicated `…/freight-unit` route. |\n| `freight_unit_type` | The Freight Unit's own type code (e.g. `Z001`) — not to be confused with `freight_order_type` above, which is the Freight Order type (`ZFO5`). |\n| `change_ordinal_number` | How many times this order has been changed, counting the original as 1. Incremented by us whenever a field the Freight Order carries is updated (addresses, references, dates, basic order fields, line items) — read-only, and it only ever goes up. Travels on the Freight Order payload as `changeOrdinalNumberValue` so your TM system can order our messages. |\n| `source_location_id` | Your location ID of the source (pick-up) location — stored with the Freight Unit details. |\n| `destination_location_id` | Your location ID of the destination (delivery) location — stored with the Freight Unit details. |\n| `asn_number` | Reference of the most recent ASN issued for this order — stamped automatically by `POST /purchase-orders/{identifier}/asn`. |\n| `asn_type` | Type of the most recent ASN: `original` or `change`. |\n| `asn_date` | Date the most recent ASN was issued. |\n| `state` | Where the order is in its lifecycle: `new` = under review, `order` = pending at the supplier, `trucking` = pick-up in progress, `warehouse` = received at our warehouse, `pick_pack` = being picked & packed for shipment, `closed` = completed (closed orders are not returned by the API). |\n| `direction` | Direction of the movement: `import` (into the destination country) or `export` (out of it). |\n| `mode_of_transport` | International mode of transport for the onward shipment. The complete list: `air_freight` (Air), `ocean_freight` (Ocean), `road` (Road), `mode_of_transport_not_set` (International Mode Of Transport Not Set). `mode_of_transport_not_set` means it has not been decided yet. |\n| `freight_type` | Ocean service type: `fcl` (Full Container Load), `lcl` (Less than Container Load), or `breakbulk`. Empty for air/road. |\n| `hazardous` | Whether the cargo is classified as hazardous / dangerous goods (`yes`/`no`). |\n| `is_cargo_bonded` | Whether the cargo moves under customs bond (`yes`/`no`). |\n| `has_house_booking` | Whether the order has been consolidated onto a freight booking yet (`has_house_booking` / `does_not_have_house_booking`). When it has, see `booking_reference` and `booking`. |\n| `trucking_arranged_by` | Who arranges the supplier pick-up: `ramps` (our forwarding team) or `supplier` (the supplier delivers). |\n| `consignee` | The receiving party the goods are consigned to. |\n| `shipper` | The supplier / shipper the goods are collected from. |\n| `origin_agent` | Agent handling the cargo at origin, when one is involved. |\n| `trucker` | Trucking company performing the pick-up, once trucking is booked. |\n| `assigned_to` | Our team member responsible for this order. |\n| `port_of_loading` | Port/airport where the cargo is loaded for the international leg. |\n| `booking_reference` | Reference (RHB) of the freight booking this order was consolidated onto, once booked. See the `booking` object on the single-order read for its details. |\n| `quotation` | Approved quotation linked to this order, if any. |\n| `cargo_description` | Summary description of the cargo. |\n| `cargo_value` | Declared cargo value in USD. |\n| `pickup_date` | Scheduled date for the supplier pick-up. |\n| `cargo_ready_date` | Date the cargo is/was ready for collection at the supplier. |\n| `supplier_promise_date` | Date the supplier promised the goods would be ready. |\n| `approval_to_ship_date` | Date approval to ship was given. |\n| `actual_pickup_date` | Date the cargo was actually collected from the supplier. |\n| `delivered_to_carrier_date` | Date the cargo was handed over to the international carrier. |\n| `created_at` | When the order was created in our system. |\n| `attended_by` | Team member who attended to the order intake. |\n| `attention` | Attention / contact person for trucking instructions. |\n| `special_instructions` | Handling instructions supplied on the purchase order. |\n| `order_details` | Free-text order notes supplied on the purchase order. |\n| `customer` | The customer account this order belongs to. |\n| `customer_reference` | Your **Freight Order Number** — your own reference for this order, separate from the purchase order number. Updatable via `PUT /purchase-orders/{identifier}`. |\n| `incoterms_location` | Named place for the incoterm (e.g. the port or city the term applies to). |\n| `company_code` | Your company code for the order. |\n| `incoterms` | Agreed Incoterm for the purchase (lowercase code): `exw`, `fca`, `fob`, `cif`, `ddp`, etc. |\n| `currency` | Currency of the declared cargo value. |\n| `move_type` | How the cargo is routed at destination: `direct_to_customer` or `deliver_agent` (delivered via an agent). |\n| `ready_to_ship` | Whether the order has been flagged ready to ship (`yes`/`no`). |\n| `carrier` | Carrier associated with the order (e.g. the line/airline used). |\n| `customer_care_rep` | Our customer-care representative for this order. |\n| `assigned_bde` | Our business development executive assigned to your account. |\n| `port_of_discharge` | Port/airport where the cargo is discharged at destination. |\n| `destination_country` | Final destination country of the cargo. |\n| `total_pieces` | Total piece count across all cargo lines. |\n| `total_weight` | Total weight across all cargo lines (KG unless noted). |\n| `total_volume` | Total volume across all cargo lines (CBM unless noted). |\n| `required_by` | Required On Site date — the date you need the goods on site / in your warehouse. Drives how the shipment is planned and prioritised. |\n| `customer_release_date` | Date you released the order for onward shipping, when a customer release step applies. |\n| `date_delivered_to_warehouse` | Date the cargo was received at our warehouse. |\n| `warehouse_receipt_number` | Warehouse receipt number issued when the cargo was received at our warehouse. |\n\n#### `booking` — the freight booking this order is consolidated onto\n\n| Field | Meaning |\n|---|---|\n| `booking.reference` | Booking reference (RHB number). |\n| `booking.status` | Current status of the booking in the freight flow. |\n| `booking.booking_type` | `import` or `export`. |\n| `booking.mode_of_transport` | Mode of transport on the booking. The complete list: `ocean_freight` (Ocean Freight), `air_freight` (Air Freight). Note a booking has no road mode — that list is narrower than the order's `mode_of_transport`. |\n| `booking.type_of_move` | Freight service type on the booking. The complete list: `fcl` (FCL), `lcl` (LCL), `breakbulk` (BreakBulk), `air` (Air), `airgcx` (Air GCX), `in_out` (In and Out). |\n| `booking.etd` | Estimated date of departure. |\n| `booking.eta` | Estimated date of arrival. |\n| `booking.cutoff_date` | Cut-off by which cargo must be delivered to make the booked departure. |\n| `booking.vessel` | Vessel name (ocean bookings). |\n| `booking.voyage` | Voyage number (ocean bookings). |\n| `booking.master_bill_number` | Master transport document — the Master Bill of Lading (ocean) or Master Airway Bill (air), whichever applies for this booking's mode. |\n| `booking.house_bill_number` | House transport document — the House Bill of Lading (ocean) or House Airway Bill (air), whichever applies for this booking's mode. |\n| `booking.port_of_loading` | Port/airport of loading. |\n| `booking.port_of_discharge` | Port/airport of discharge. |\n| `booking.consignee` | Receiving party on the booking. |\n| `booking.shipper` | Shipper on the booking. |\n| `booking.customer_reference` | Customer reference(s) carried on the booking — for consolidated bookings this can list several orders. |\n| `booking.description_of_goods` | Goods description on the booking. |\n| `booking.shipment_reference` | Reference of the live shipment created from this booking, once it departs the booking stage. |\n\n#### `supplier` — the supplier (shipper) with their stored details\n\n| Field | Meaning |\n|---|---|\n| `supplier.id` | Your supplier ID (the partner's Internal Reference). |\n| `supplier.name` |  |\n| `supplier.email` |  |\n| `supplier.phone` |  |\n| `supplier.street1` |  |\n| `supplier.street2` |  |\n| `supplier.city` |  |\n| `supplier.state` |  |\n| `supplier.zip` |  |\n| `supplier.country` | ISO 3166-1 alpha-2 country code. |\n\n#### `pickup_address` / `delivery_address`\n\n| Field | Meaning |\n|---|---|\n| `…address.id` | Your Ship-To / location code this address is registered under, when known (the same `id` you send on submit). Empty for addresses without a registered code. |\n| `…address.location_id` | Internal ID of the address record the order points to. Changes when the order is updated to a different address — use it to verify an address update took effect. |\n| `…address.location_name` | Name the address is filed under (the site / depot / warehouse name). Defaults to `street1` when you don't send one. |\n| `…address.street1` | Street address, line 1. |\n| `…address.street2` | Street address, line 2 (suite/warehouse/dock). |\n| `…address.city` | City. |\n| `…address.state` | State / province. |\n| `…address.zip` | Postal / ZIP code. |\n| `…address.country` | ISO 3166-1 alpha-2 country code. |\n| `…address.region` | ISO 3166-2 subdivision code within the country — the bare code, since `country` already carries the country. Empty when the address has no region on record. |\n| `…address.supplier_id` | Supplier ID of the supplier this pick-up address belongs to — the address's own supplier link when set, otherwise the order's supplier. |\n\n`supplier_id` is a pick-up-address field only — delivery addresses don't carry it.\n\n#### `po_details[]` — your purchase order line items\n\n| Field | Meaning |\n|---|---|\n| `po_details[].line` | Line number from your purchase order. |\n| `po_details[].description` | Item / material description for the line. |\n| `po_details[].quantity` | Ordered quantity for the line. |\n| `po_details[].uom` | Unit of measure for the quantity, as a **UN/ECE Rec 20** code (`EA` each, `KGM` kilogram, `LBR` pound). |\n| `po_details[].material_code` | Your material / part number for the line (always a string, even when numeric). |\n| `po_details[].status` | Lifecycle of this line: `created`, `updated` or `deleted`. Set from your submission, matched on `line`. A `deleted` line stays on the order for history rather than being removed. |\n\n#### `cargo_details[]` — cargo lines with full physical detail\n\n| Field | Meaning |\n|---|---|\n| `cargo_details[].line` | Line number. |\n| `cargo_details[].description` |  |\n| `cargo_details[].part_number` |  |\n| `cargo_details[].lot_number` |  |\n| `cargo_details[].package_type` | Package type (name). |\n| `cargo_details[].quantity` |  |\n| `cargo_details[].piece_count` |  |\n| `cargo_details[].gross_weight` | Gross weight. |\n| `cargo_details[].weight_uom` | Gross-weight unit as a **UN/ECE Rec 20** code: `KGM` kilogram, `LBR` pound, `TNE` metric tonne. |\n| `cargo_details[].length` |  |\n| `cargo_details[].width` |  |\n| `cargo_details[].height` |  |\n| `cargo_details[].dimension_uom` | Dimension unit as a **UN/ECE Rec 20** code: `MTR` metre, `CMT` centimetre, `INH` inch, `FOT` foot. |\n| `cargo_details[].volume` |  |\n| `cargo_details[].volume_uom` | Volume unit as a **UN/ECE Rec 20** code: `MTQ` cubic metre, `FTQ` cubic foot, `INQ` cubic inch. |\n\n#### `attachments[]` — every file on the order\n\n| Field | Meaning |\n|---|---|\n| `attachments[].type` | What this file is. One of: `customer_po` (Customer PO), `order_confirmation` (Order confirmation), `cargo_image` (Cargo image), `warehouse_receipt` (Warehouse receipt), `trucker_document` (Trucker document), `trucker_bl` (Trucker bill of lading), `msds` (Material safety data sheet), `dangerous_goods` (IMO dangerous goods declaration), `scanned_document` (Scanned document). |\n| `attachments[].filename` | Original file name, including extension. |\n| `attachments[].mimetype` | MIME type of the file. |\n| `attachments[].size` | Decoded file size in bytes. |\n| `attachments[].created_on` | When the file was attached to the order (UTC). |\n| `attachments[].encoding` | Encoding of `content_base64`. Always `base64`. |\n| `attachments[].content_base64` | The complete file content, base64-encoded. |\n\nEach file is embedded complete — decode `content_base64` to obtain it (the same\nshape the ASN and the Freight Order carry). `type` says what the file is:\n`customer_po` — Customer PO, `order_confirmation` — Order confirmation, `cargo_image` — Cargo image, `warehouse_receipt` — Warehouse receipt, `trucker_document` — Trucker document, `trucker_bl` — Trucker bill of lading, `msds` — Material safety data sheet, `dangerous_goods` — IMO dangerous goods declaration, `scanned_document` — Scanned document.","operationId":"get_purchase_order_api_v1_purchase_orders__identifier__get","security":[{"OAuth2ClientCredentials":["orders:read"]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderView"},"example":{"order_reference":"ORD00001","customer_po_number":"4500123456","pro_reference":"PRO-2026-01","trucker_reference":"","freight_unit_number":"FU-8100412345","freight_order_type":"ZFO5","change_ordinal_number":3,"source_location_id":"1000123","destination_location_id":"1005678","asn_number":"ASN-2026-000001","asn_type":"original","asn_date":"2026-03-15","state":"order","direction":"import","mode_of_transport":"ocean_freight","freight_type":"fcl","hazardous":"no","is_cargo_bonded":"","has_house_booking":"does_not_have_house_booking","trucking_arranged_by":"ramps","consignee":"Shell Trinidad and Tobago Limited","shipper":"Gulf Coast Industrial Supplies Inc.","origin_agent":"","trucker":"","assigned_to":"Maria Garcia","port_of_loading":"Houston, US","booking_reference":"RHB1948","quotation":"","cargo_description":"Industrial valves, gaskets, and centrifugal pump","cargo_value":45000.0,"pickup_date":"2026-03-15","cargo_ready_date":"2026-03-15","supplier_promise_date":"2026-03-20","approval_to_ship_date":"2026-03-14","created_at":"2026-03-06T09:12:00","attended_by":"","attention":"","special_instructions":"Temperature controlled storage required. Do not stack.","order_details":"Shell Materials Management — LSP notification","customer":"Shell Trinidad and Tobago Limited","customer_reference":"FO-2026-00045","incoterms":"fob","incoterms_location":"Point Lisas, Trinidad","company_code":"TT01","currency":"USD","move_type":"","ready_to_ship":"no","carrier":"","customer_care_rep":"","assigned_bde":"","port_of_discharge":"Port of Spain, TT","destination_country":"Trinidad and Tobago","total_pieces":8.0,"total_weight":2450.0,"total_volume":12.5,"required_by":"2026-04-10","warehouse_receipt_number":"","booking":{"reference":"RHB1948","status":"cargo_ready","booking_type":"import","mode_of_transport":"air_freight","type_of_move":"air","etd":"2026-03-17","eta":"2026-03-19","cutoff_date":"2026-03-13T14:00:00","vessel":"","voyage":"","master_bill_number":"810 41010911","house_bill_number":"HAWB18343","port_of_loading":"Port of Miami (USMIA)","port_of_discharge":"Piarco","consignee":"Shell Trinidad and Tobago Limited","shipper":"THENEX GMBH","customer_reference":"","description_of_goods":"ACTUATORS + PARTS","shipment_reference":"RLL145713"},"supplier":{"id":"200000004","name":"Gulf Coast Industrial Supplies Inc.","email":"orders@gulfcoastindustrial.com","phone":"+1 780 555 0142","street1":"9915 108 Street NW","street2":"6th Floor South Petroleum Plaza","city":"Edmonton","state":"Alberta","zip":"T5K 2G8","country":"CA"},"pickup_address":{"id":"","location_id":5230,"location_name":"Westheimer Depot","supplier_id":"200000004","street1":"12000 Westheimer Road","street2":"Warehouse B, Dock 7","city":"Houston","state":"Texas","zip":"77077","country":"US","region":"TX"},"delivery_address":{"id":"TA32","location_id":5231,"location_name":"Point Lisas Warehouse 14","street1":"Point Lisas Industrial Estate","street2":"Warehouse 14","city":"Couva","state":"","zip":"","country":"TT","region":"CTT"},"po_details":[{"line":"1","description":"Gate Valves 4IN","quantity":2,"uom":"EA","material_code":"MAT-78923-A1","status":"created"},{"line":"2","description":"Spiral Wound Gaskets","quantity":2,"uom":"EA","material_code":"MAT-78924-B0","status":"updated"}],"cargo_details":[{"line":"1","description":"Gate Valves 4IN","part_number":"MAT-78923-A1","lot_number":"","package_type":"Pallet","quantity":2,"piece_count":2,"gross_weight":450.0,"weight_uom":"KGM","length":1.2,"width":0.8,"height":1.0,"dimension_uom":"MTR","volume":0.96,"volume_uom":"MTQ"}],"attachments":[{"type":"customer_po","filename":"PO 4500123456.pdf","mimetype":"application/pdf","size":434848,"created_on":"2026-08-03T12:34:56","encoding":"base64","content_base64":"JVBERi0xLjcKJeLjz9MK..."}]}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/purchase-orders/{identifier}/freight-unit":{"put":{"tags":["Purchase Orders"],"summary":"Add freight unit","description":"Store the **Freight Unit** details on an order, identified by our **ORD number** or your **customer PO number** (auto-detected).\n\nSend any subset of `freight_unit_number`, `freight_unit_type`, `freight_order_type`, `freight_order_number`, `source_location_id` and `destination_location_id` — only the field(s) you provide are updated; everything else is left untouched. The same fields can also be set via the general `PUT /purchase-orders/{identifier}` partial update; they are not accepted on the PO submit. Sending new values replaces what is stored; the GET returns them, and the source / destination location IDs travel on the Freight Order payload.","operationId":"add_freight_unit_api_v1_purchase_orders__identifier__freight_unit_put","security":[{"OAuth2ClientCredentials":["orders:write"]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightUnitUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightUnitResult"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"example":{"error":"validation_error","error_description":"The request body failed validation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/purchase-orders/{identifier}/asn":{"post":{"tags":["Purchase Orders"],"summary":"Issue an ASN (Advanced Shipping Notice)","description":"Generate the **Advanced Shipping Notice** for an order — the cargo-ready notification carrying the full cargo detail (pieces, weight, dimensions, UOMs), the parties, addresses, and the shipment dates. Identify the order by our **ORD number** or your **customer PO number** (auto-detected).\n\nThe ASN is built from the order's current data. The body is optional: send `asn_type` (`original` — the first notice for the order, the default — or `change` for a revision to a previously sent ASN), and/or `cargo_ready_date` / `pickup_date` to override those dates on the ASN (the cargo ready date defaults to the order's value, else today — issuing an ASN asserts the cargo is ready).\n\nWhen OpenText TradingGrid is configured, the issued ASN is **transmitted to Shell** in the same call (docType `ASN`): the outcome comes back in the `X-Transmission-Status` response header (`sent` / `failed` / `skipped_not_configured`) with the OpenText trace id in `X-OTTG-Session-Id`. A failed transmission never voids the ASN — it is issued, audited, and can be re-sent from the stored payload.\n\nThe pick-up and delivery addresses carry their `country` / `region` as ISO codes (`TT` / `CTT`), and **every file on the order** (customer PO, cargo images, warehouse receipt…) is embedded in `attachments[]`, tagged with its `type`, with the complete base64 content (`filename`, `mimetype`, `size`, `encoding`, `content_base64`) so the receiving system can ingest the documents directly.\n\nEvery call issues a **new ASN reference** (`ASN-<year>-<sequence>`) and the returned payload is stored for audit (attachment content excluded). The issued reference, type, and date are also stamped on the order itself and returned by the GET as `asn_number` / `asn_type` / `asn_date`. Field names match the order GET, so the ASN can be reconciled 1:1 against `GET /purchase-orders/{identifier}`.","operationId":"issue_asn_api_v1_purchase_orders__identifier__asn_post","security":[{"OAuth2ClientCredentials":["orders:write"]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ASNRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ASNView"},"example":{"asn_reference":"ASN-2026-000001","asn_type":"original","asn_date":"2026-03-15","order_reference":"ORD00001","customer_po_number":"4500123456","direction":"import","mode_of_transport":"ocean_freight","freight_type":"lcl","cargo_description":"Industrial valves, gaskets, and centrifugal pump","cargo_value":45000.0,"currency":"USD","shipper":{"id":"200000004","name":"Gulf Coast Industrial Supplies Inc.","email":"orders@gulfcoastindustrial.com","phone":"+1 780 555 0142","street1":"9915 108 Street NW","street2":"6th Floor South Petroleum Plaza","city":"Edmonton","state":"Alberta","zip":"T5K 2G8","country":"CA"},"consignee":"Shell Trinidad and Tobago Limited","pickup_address":{"id":"","location_id":5230,"location_name":"Westheimer Depot","supplier_id":"200000004","street1":"12000 Westheimer Road","street2":"Warehouse B, Dock 7","city":"Houston","state":"Texas","zip":"77077","country":"US","region":"TX"},"delivery_address":{"id":"TA32","location_id":5231,"location_name":"Point Lisas Warehouse 14","street1":"Point Lisas Industrial Estate","street2":"Warehouse 14","city":"Couva","state":"","zip":"","country":"TT","region":"CTT"},"supplier_promise_date":"2026-03-14","cargo_ready_date":"2026-03-15","approval_to_ship_date":"2026-03-16","pickup_date":"2026-03-18","required_by":"2026-04-10","incoterms":"fca","incoterms_location":"Houston, US","company_code":"TT01","total_pieces":8.0,"total_weight":2450.0,"total_volume":12.5,"hazardous":"no","special_instructions":"Temperature controlled storage required. Do not stack.","order_details":"Shell Materials Management — LSP notification","po_details":[{"line":"1","description":"Gate Valves 4IN","quantity":2,"uom":"EA","material_code":"MAT-78923-A1","status":"created"},{"line":"2","description":"Spiral Wound Gaskets","quantity":2,"uom":"EA","material_code":"MAT-78924-B0","status":"updated"}],"cargo_details":[{"line":"1","description":"Gate Valves 4IN","part_number":"MAT-78923-A1","lot_number":"","package_type":"Pallet","quantity":2,"piece_count":2,"gross_weight":450.0,"weight_uom":"KGM","length":1.2,"width":0.8,"height":1.0,"dimension_uom":"MTR","volume":0.96,"volume_uom":"MTQ"}],"attachments":[{"type":"customer_po","filename":"PO 4500123456.pdf","mimetype":"application/pdf","size":434848,"created_on":"2026-08-03T12:34:56","encoding":"base64","content_base64":"JVBERi0xLjcKJeLjz9MK..."}]}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/purchase-orders/{identifier}/freight-order":{"post":{"tags":["Purchase Orders"],"summary":"Generate a Freight Order payload","description":"Build the **Freight Order** payload for an order — sent to the customer to create the Freight Order in their system once the Freight Unit details and the transport plan are in. Identify the order by our **ORD number** or your **customer PO number** (auto-detected).\n\nThe payload is built from the order's current data and uses the **same field names as the order GET / ASN** — the source is `pickup_address` (with the supplier as `shipper`), the destination is `delivery_address` (with its location `id`), and the line detail travels as `po_details[]` / `cargo_details[]` with full physical detail and UOMs. The body is optional: send `fo_type` (`original` — default — `change` for a revision, or `cancel` to withdraw one; the payload's `action_code` follows as `01` / `02` / `03`), and/or the transport plan as it is confirmed — `pickup_date` (planned pick-up), `delivery_date` (planned delivery at the agreed location, defaults to the order's required-by date), and `trucker`.\n\nWhen OpenText TradingGrid is configured, the payload is **transmitted to Shell** in the same call (docType `FREIGHT_ORDER`): the outcome comes back in the `X-Transmission-Status` response header (`sent` / `failed` / `skipped_not_configured`) with the OpenText trace id in `X-OTTG-Session-Id`; a failed transmission is queued for automatic retry and never voids the payload.\n\nEvery call issues a new `FO-<year>-<sequence>` reference and the payload is stored for audit (attachment content excluded). Your own Freight Order number, assigned on your side, is stored back on the order via `PUT /purchase-orders/{identifier}` (`customer_reference`) and returns as `freight_order_number` on subsequent payloads.","operationId":"issue_freight_order_api_v1_purchase_orders__identifier__freight_order_post","security":[{"OAuth2ClientCredentials":["orders:write"]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/FreightOrderRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightOrderView"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"example":{"error":"validation_error","error_description":"The request body failed validation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/purchase-orders/{identifier}/milestones":{"post":{"tags":["Purchase Orders"],"summary":"Report a transport milestone","description":"Report a **transport milestone** on an order — us updating you that an activity has occurred (or that an expected date has moved). Identify the order by our **ORD number** or your **customer PO number** (auto-detected).\n\nOne milestone per call, and the body is flat — which milestone, and when:\n\n    {\"milestone\": \"actual_pickup\", \"date_time\": \"2026-08-23T14:20:00Z\"}\n\nOptionally add `location` (where it occurred), `document_reference` (the supporting document — AWB/BL, customs entry, warehouse receipt, POD) and `notes`. Revise a previously reported date by reporting the same milestone again with the new one; `delayed` usually carries a `notes` explaining why.\n\nEvery update carries a per-order `sequence` (first = 1) so you can order our messages even if they arrive out of order, and your `freight_order_number` when you have stored one on the order.","operationId":"report_milestone_api_v1_purchase_orders__identifier__milestones_post","security":[{"OAuth2ClientCredentials":["orders:write"]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","title":"Identifier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneView"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"example":{"error":"validation_error","error_description":"The request body failed validation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"example":{"error":"upstream_error","error_description":"An upstream service returned an error."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/freight-orders":{"post":{"tags":["Freight Orders"],"summary":"Submit a Freight Order payload","description":"Submit (POST) a **Freight Order payload** — the same document `POST /purchase-orders/{identifier}/freight-order` generates, so a generated payload can be posted back verbatim after review or completion.\n\nThe order is resolved from `order_reference` and/or `customer_po_number`. The payload is validated, stored on the FO audit trail, and the reference data it carries is synced onto the order: the Freight Unit details (`freight_unit_number` / `freight_order_type`), the `source_location_id` / `destination_location_id`, and the `freight_order_number` (stored as the order's customer reference). Fields the ERP cannot store yet are reported in `warnings` without failing the submission.\n\nOmit `fo_reference` to have one assigned. Re-posting an **identical** payload under the same `fo_reference` returns `duplicate: true` (200); a different payload under an existing reference is rejected (409).","operationId":"submit_freight_order_api_v1_freight_orders_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightOrderSubmission"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightOrderSubmissionResult"}}}},"200":{"description":"Idempotent replay — this exact payload was already submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightOrderSubmissionResult"}}}},"400":{"description":"The request was malformed or missing a required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"bad_request","error_description":"The request was malformed or missing a required field."}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"not_found","error_description":"The requested resource does not exist."}}}},"409":{"description":"The request conflicts with current state (e.g. an idempotency clash).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"conflict","error_description":"The request conflicts with current state (e.g. an idempotency clash)."}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","error_description":"The request body failed validation."}}}},"502":{"description":"An upstream service returned an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"upstream_error","error_description":"An upstream service returned an error."}}}},"503":{"description":"The service is temporarily unavailable — retry after Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"upstream_unavailable","error_description":"The service is temporarily unavailable — retry after Retry-After."}}}}},"security":[{"OAuth2ClientCredentials":["orders:write"]}]}},"/api/v1/integration/messages":{"get":{"tags":["Integration Hub"],"summary":"List integration messages","description":"The durable queue: everything queued, retrying, succeeded or dead-lettered. Filter by `status` and/or `correlation_id` (the customer PO number / document reference).","operationId":"list_messages_api_v1_integration_messages_get","security":[{"OAuth2ClientCredentials":["orders:read"]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"queued | processing | succeeded | dead_letter","title":"Status"},"description":"queued | processing | succeeded | dead_letter"},{"name":"correlation_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correlation Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MessageView"},"title":"Response List Messages Api V1 Integration Messages Get"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integration/messages/{message_id}":{"get":{"tags":["Integration Hub"],"summary":"Message envelope + timeline","description":"One message with its full correlation timeline — received, queued, each attempt, and how it ended.","operationId":"get_message_api_v1_integration_messages__message_id__get","security":[{"OAuth2ClientCredentials":["orders:read"]}],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integration/messages/{message_id}/retry":{"post":{"tags":["Integration Hub"],"summary":"Requeue a message","description":"Reprocess a **dead-lettered** (or stuck) message from its stored payload — no need to ask the partner to resend. The attempt counter restarts; a message that already succeeded is not requeued (409).","operationId":"retry_message_api_v1_integration_messages__message_id__retry_post","security":[{"OAuth2ClientCredentials":["orders:write"]}],"parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryResult"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"example":{"error":"not_found","error_description":"The requested resource does not exist."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The request conflicts with current state (e.g. an idempotency clash).","content":{"application/json":{"example":{"error":"conflict","error_description":"The request conflicts with current state (e.g. an idempotency clash)."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integration/stats":{"get":{"tags":["Integration Hub"],"summary":"Integration dashboard counts","description":"Today's inbound/outbound message counts and the current state of the queue — the numbers an operator checks first.","operationId":"integration_stats_api_v1_integration_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationStats"}}}},"401":{"description":"Missing, invalid, or expired bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"unauthorized","error_description":"Missing, invalid, or expired bearer token."}}}},"403":{"description":"The token lacks the scope required for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"insufficient_scope","error_description":"The token lacks the scope required for this operation."}}}}},"security":[{"OAuth2ClientCredentials":["orders:read"]}]}},"/admin/integration":{"get":{"summary":"Integration Page","operationId":"integration_page_admin_integration_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","default":"","title":"Status"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/integration/msg/{message_id}":{"get":{"summary":"Integration Message Page","operationId":"integration_message_page_admin_integration_msg__message_id__get","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/integration/msg/{message_id}/retry":{"post":{"summary":"Integration Retry","operationId":"integration_retry_admin_integration_msg__message_id__retry_post","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"string","title":"Message Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ASNRequest":{"properties":{"asn_type":{"type":"string","title":"Asn Type","description":"Whether this notice is the **original** ASN for the order or a **change** (revision) to one previously sent. Accepted values: `original`, `change`.","default":"original","examples":["original"]},"cargo_ready_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cargo Ready Date","description":"Overrides the cargo ready date on the ASN (defaults to the order's value, else today).","examples":["2026-03-15"]},"pickup_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pickup Date","description":"Overrides the scheduled pick-up date on the ASN (defaults to the order's value).","examples":["2026-03-18"]}},"type":"object","title":"ASNRequest","description":"Optional overrides when issuing an ASN. Send an empty body (or none at\nall) to generate an **original** ASN straight from the order's current data."},"ASNView":{"properties":{"asn_reference":{"type":"string","title":"Asn Reference","description":"Unique ASN reference, assigned on issue.","examples":["ASN-2026-000001"]},"asn_type":{"type":"string","title":"Asn Type","description":"`original` — first notice for the order; `change` — a revision to a previously sent ASN.","default":"original","examples":["original"]},"asn_date":{"type":"string","format":"date","title":"Asn Date","description":"Date the ASN was issued.","examples":["2026-03-15"]},"order_reference":{"type":"string","title":"Order Reference","examples":["ORD00001"]},"customer_po_number":{"type":"string","title":"Customer Po Number","default":"","examples":["4500123456"]},"direction":{"type":"string","title":"Direction","default":"","examples":["import"]},"mode_of_transport":{"type":"string","title":"Mode Of Transport","default":"","examples":["ocean_freight"]},"freight_type":{"type":"string","title":"Freight Type","default":"","examples":["lcl"]},"cargo_description":{"type":"string","title":"Cargo Description","default":"","examples":["Industrial valves, gaskets, and centrifugal pump"]},"cargo_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cargo Value","examples":[45000.0]},"currency":{"type":"string","title":"Currency","default":"","examples":["USD"]},"shipper":{"anyOf":[{"$ref":"#/components/schemas/SupplierInfo"},{"type":"null"}],"description":"The supplier the cargo is collected from, with their stored details."},"consignee":{"type":"string","title":"Consignee","default":"","examples":["Shell Trinidad and Tobago Limited"]},"pickup_address":{"anyOf":[{"$ref":"#/components/schemas/PickupAddress"},{"type":"null"}]},"delivery_address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"supplier_promise_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Supplier Promise Date","examples":["2026-03-14"]},"cargo_ready_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cargo Ready Date","description":"Date the cargo is confirmed ready for collection — the date this ASN asserts.","examples":["2026-03-15"]},"approval_to_ship_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Approval To Ship Date","examples":["2026-03-16"]},"pickup_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pickup Date","examples":["2026-03-18"]},"required_by":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Required By","examples":["2026-04-10"]},"incoterms":{"type":"string","title":"Incoterms","default":"","examples":["fca"]},"incoterms_location":{"type":"string","title":"Incoterms Location","default":"","examples":["Houston, US"]},"company_code":{"type":"string","title":"Company Code","default":"","examples":["TT01"]},"total_pieces":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Pieces","examples":[8.0]},"total_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Weight","examples":[2450.0]},"total_volume":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Volume","examples":[12.5]},"hazardous":{"type":"string","title":"Hazardous","default":"","examples":["no"]},"special_instructions":{"type":"string","title":"Special Instructions","default":"","examples":["Temperature controlled storage required."]},"order_details":{"type":"string","title":"Order Details","default":"","examples":["Shell Materials Management — LSP notification"]},"po_details":{"items":{"$ref":"#/components/schemas/PODetailLine"},"type":"array","title":"Po Details"},"cargo_details":{"items":{"$ref":"#/components/schemas/CargoLine"},"type":"array","title":"Cargo Details"},"attachments":{"items":{"$ref":"#/components/schemas/EmbeddedAttachment"},"type":"array","title":"Attachments","description":"Every file on the order, each tagged with its `type` and embedded with its base64 content for direct ingestion."}},"type":"object","required":["asn_reference","asn_date","order_reference"],"title":"ASNView","description":"An Advanced Shipping Notice — the cargo-ready notification issued for an\norder, with full cargo detail. Field names match the order GET.","examples":[{"approval_to_ship_date":"2026-03-16","asn_date":"2026-03-15","asn_reference":"ASN-2026-000001","asn_type":"original","attachments":[{"content_base64":"JVBERi0xLjcKJeLjz9MK...","created_on":"2026-08-03T12:34:56","encoding":"base64","filename":"PO 4500123456.pdf","mimetype":"application/pdf","size":434848,"type":"customer_po"}],"cargo_description":"Industrial valves, gaskets, and centrifugal pump","cargo_details":[{"description":"Gate Valves 4IN","dimension_uom":"MTR","gross_weight":450.0,"height":1.0,"length":1.2,"line":"1","lot_number":"","package_type":"Pallet","part_number":"MAT-78923-A1","piece_count":2,"quantity":2,"volume":0.96,"volume_uom":"MTQ","weight_uom":"KGM","width":0.8}],"cargo_ready_date":"2026-03-15","cargo_value":45000.0,"company_code":"TT01","consignee":"Shell Trinidad and Tobago Limited","currency":"USD","customer_po_number":"4500123456","delivery_address":{"city":"Couva","country":"TT","id":"TA32","location_id":5231,"location_name":"Point Lisas Warehouse 14","region":"CTT","state":"","street1":"Point Lisas Industrial Estate","street2":"Warehouse 14","zip":""},"direction":"import","freight_type":"lcl","hazardous":"no","incoterms":"fca","incoterms_location":"Houston, US","mode_of_transport":"ocean_freight","order_details":"Shell Materials Management — LSP notification","order_reference":"ORD00001","pickup_address":{"city":"Houston","country":"US","id":"","location_id":5230,"location_name":"Westheimer Depot","region":"TX","state":"Texas","street1":"12000 Westheimer Road","street2":"Warehouse B, Dock 7","supplier_id":"200000004","zip":"77077"},"pickup_date":"2026-03-18","po_details":[{"description":"Gate Valves 4IN","line":"1","material_code":"MAT-78923-A1","quantity":2,"status":"created","uom":"EA"},{"description":"Spiral Wound Gaskets","line":"2","material_code":"MAT-78924-B0","quantity":2,"status":"updated","uom":"EA"}],"required_by":"2026-04-10","shipper":{"city":"Edmonton","country":"CA","email":"orders@gulfcoastindustrial.com","id":"200000004","name":"Gulf Coast Industrial Supplies Inc.","phone":"+1 780 555 0142","state":"Alberta","street1":"9915 108 Street NW","street2":"6th Floor South Petroleum Plaza","zip":"T5K 2G8"},"special_instructions":"Temperature controlled storage required. Do not stack.","supplier_promise_date":"2026-03-14","total_pieces":8.0,"total_volume":12.5,"total_weight":2450.0}]},"Address":{"properties":{"id":{"type":"string","title":"Id","description":"Your Ship-To / location code this address is registered under, when known (the same `id` you send on submit). Empty for addresses without a registered code.","default":"","examples":["TA32"]},"location_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Location Id","description":"Internal ID of the address record the order points to. Changes when the order is updated to a different address — use it to verify an address update took effect.","examples":[5231]},"location_name":{"type":"string","title":"Location Name","description":"Name the address is filed under (the site / depot / warehouse name). Defaults to `street1` when you don't send one.","default":"","examples":["Point Lisas Warehouse 14"]},"street1":{"type":"string","title":"Street1","description":"Street address, line 1.","default":"","examples":["12000 Westheimer Road"]},"street2":{"type":"string","title":"Street2","description":"Street address, line 2 (suite/warehouse/dock).","default":"","examples":["Warehouse B, Dock 7"]},"city":{"type":"string","title":"City","description":"City.","default":"","examples":["Houston"]},"state":{"type":"string","title":"State","description":"State / province.","default":"","examples":["Texas"]},"zip":{"type":"string","title":"Zip","description":"Postal / ZIP code.","default":"","examples":["77077"]},"country":{"type":"string","title":"Country","description":"ISO 3166-1 alpha-2 country code.","default":"","examples":["US"]},"region":{"type":"string","title":"Region","description":"ISO 3166-2 subdivision code within the country — the bare code, since `country` already carries the country. Empty when the address has no region on record.","default":"","examples":["TX"]}},"type":"object","title":"Address","description":"A pick-up or delivery address on the order."},"AddressUpdate":{"properties":{"id":{"type":"string","title":"Id","description":"Your Ship-To / location code (e.g. `TA32`). A known code alone resolves the registered address; a code sent **with** an address registers/updates it.","default":"","examples":["TA32"]},"location_name":{"type":"string","title":"Location Name","description":"Name to file the address under (site / depot / warehouse). Defaults to `street1` when omitted. Sent **with an address**, a different name registers a new address and points this order at it — stored addresses are shared between orders, so they are never renamed in place. Sent with a known `id` and no address it is ignored, so a GET response can be echoed back safely.","default":"","examples":["Point Lisas Warehouse 14"]},"street1":{"type":"string","title":"Street1","default":"","examples":["Point Lisas Industrial Estate"]},"street2":{"type":"string","title":"Street2","default":"","examples":["Warehouse 14"]},"city":{"type":"string","title":"City","default":"","examples":["Couva"]},"state":{"type":"string","title":"State","default":"","examples":[""]},"zip":{"type":"string","title":"Zip","default":"","examples":[""]},"country":{"type":"string","title":"Country","description":"ISO 3166-1 alpha-2 country code. The full country name is still accepted.","default":"","examples":["TT"]},"region":{"type":"string","title":"Region","description":"ISO 3166-2 subdivision code within the country (`POS`). The full ISO form (`TT-POS`) and the region name are also accepted. Left unset when omitted — it is no longer derived from the country.","default":"","examples":["POS"]}},"type":"object","title":"AddressUpdate","description":"An address block for a partial update — same shape as on submit."},"Body_issue_token_api_v1_oauth_token_post":{"properties":{"grant_type":{"type":"string","title":"Grant Type","description":"Must be `client_credentials`.","examples":["client_credentials"]},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id","description":"Your client identifier.","examples":["ramps_ab12cd34..."]},"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Secret","description":"Your client secret."},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope","description":"Optional space-separated subset of your allowed scopes.","examples":["orders:read shipments:read"]}},"type":"object","required":["grant_type"],"title":"Body_issue_token_api_v1_oauth_token_post"},"BookingInfo":{"properties":{"reference":{"type":"string","title":"Reference","description":"Booking reference (RHB number).","default":"","examples":["RHB1948"]},"status":{"type":"string","title":"Status","description":"Current status of the booking in the freight flow.","default":"","examples":["cargo_ready"]},"booking_type":{"type":"string","title":"Booking Type","description":"`import` or `export`.","default":"","examples":["import"]},"mode_of_transport":{"type":"string","title":"Mode Of Transport","description":"Mode of transport on the booking. The complete list: `ocean_freight` (Ocean Freight), `air_freight` (Air Freight). Note a booking has no road mode — that list is narrower than the order's `mode_of_transport`.","default":"","examples":["air_freight"]},"type_of_move":{"type":"string","title":"Type Of Move","description":"Freight service type on the booking. The complete list: `fcl` (FCL), `lcl` (LCL), `breakbulk` (BreakBulk), `air` (Air), `airgcx` (Air GCX), `in_out` (In and Out).","default":"","examples":["air"]},"etd":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Etd","description":"Estimated date of departure.","examples":["2026-03-17"]},"eta":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Eta","description":"Estimated date of arrival.","examples":["2026-03-19"]},"cutoff_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cutoff Date","description":"Cut-off by which cargo must be delivered to make the booked departure.","examples":["2026-03-13T14:00:00"]},"vessel":{"type":"string","title":"Vessel","description":"Vessel name (ocean bookings).","default":"","examples":[""]},"voyage":{"type":"string","title":"Voyage","description":"Voyage number (ocean bookings).","default":"","examples":[""]},"master_bill_number":{"type":"string","title":"Master Bill Number","description":"Master transport document — the Master Bill of Lading (ocean) or Master Airway Bill (air), whichever applies for this booking's mode.","default":"","examples":["810 41010911"]},"house_bill_number":{"type":"string","title":"House Bill Number","description":"House transport document — the House Bill of Lading (ocean) or House Airway Bill (air), whichever applies for this booking's mode.","default":"","examples":["HAWB18343"]},"port_of_loading":{"type":"string","title":"Port Of Loading","description":"Port/airport of loading.","default":"","examples":["Port of Miami (USMIA)"]},"port_of_discharge":{"type":"string","title":"Port Of Discharge","description":"Port/airport of discharge.","default":"","examples":["Piarco"]},"consignee":{"type":"string","title":"Consignee","description":"Receiving party on the booking.","default":"","examples":["Shell Trinidad and Tobago Limited"]},"shipper":{"type":"string","title":"Shipper","description":"Shipper on the booking.","default":"","examples":["THENEX GMBH"]},"customer_reference":{"type":"string","title":"Customer Reference","description":"Customer reference(s) carried on the booking — for consolidated bookings this can list several orders.","default":"","examples":[""]},"description_of_goods":{"type":"string","title":"Description Of Goods","description":"Goods description on the booking.","default":"","examples":["ACTUATORS + PARTS"]},"shipment_reference":{"type":"string","title":"Shipment Reference","description":"Reference of the live shipment created from this booking, once it departs the booking stage.","default":"","examples":["RLL145713"]}},"type":"object","title":"BookingInfo","description":"The freight booking this order is consolidated onto (single-order read only).\n\nOrders are grouped onto a booking for the international move; the booking later\nbecomes a live shipment (see ``shipment_reference``)."},"CargoLine":{"properties":{"line":{"type":"string","title":"Line","description":"Line number.","default":"","examples":["1"]},"description":{"type":"string","title":"Description","default":"","examples":["SP15 YN & YN - Normal"]},"part_number":{"type":"string","title":"Part Number","default":"","examples":["1000060021"]},"lot_number":{"type":"string","title":"Lot Number","default":"","examples":[""]},"package_type":{"type":"string","title":"Package Type","description":"Package type (name).","default":"","examples":["Pallet"]},"quantity":{"type":"number","title":"Quantity","default":0,"examples":[2]},"piece_count":{"type":"number","title":"Piece Count","default":0,"examples":[2]},"gross_weight":{"type":"number","title":"Gross Weight","description":"Gross weight.","default":0,"examples":[450.0]},"weight_uom":{"type":"string","title":"Weight Uom","description":"Gross-weight unit as a **UN/ECE Rec 20** code: `KGM` kilogram, `LBR` pound, `TNE` metric tonne.","default":"","examples":["LBR"]},"length":{"type":"number","title":"Length","default":0,"examples":[1.2]},"width":{"type":"number","title":"Width","default":0,"examples":[0.8]},"height":{"type":"number","title":"Height","default":0,"examples":[1.0]},"dimension_uom":{"type":"string","title":"Dimension Uom","description":"Dimension unit as a **UN/ECE Rec 20** code: `MTR` metre, `CMT` centimetre, `INH` inch, `FOT` foot.","default":"","examples":["INH"]},"volume":{"type":"number","title":"Volume","default":0,"examples":[0.96]},"volume_uom":{"type":"string","title":"Volume Uom","description":"Volume unit as a **UN/ECE Rec 20** code: `MTQ` cubic metre, `FTQ` cubic foot, `INQ` cubic inch.","default":"","examples":["MTQ"]}},"type":"object","title":"CargoLine","description":"A cargo line on the order (full physical detail, from Cargo Details)."},"EmbeddedAttachment":{"properties":{"type":{"type":"string","title":"Type","description":"What this file is. One of: `customer_po` (Customer PO), `order_confirmation` (Order confirmation), `cargo_image` (Cargo image), `warehouse_receipt` (Warehouse receipt), `trucker_document` (Trucker document), `trucker_bl` (Trucker bill of lading), `msds` (Material safety data sheet), `dangerous_goods` (IMO dangerous goods declaration), `scanned_document` (Scanned document).","default":"","examples":["customer_po"]},"filename":{"type":"string","title":"Filename","description":"Original file name, including extension.","default":"","examples":["PO 4500123456.pdf"]},"mimetype":{"type":"string","title":"Mimetype","description":"MIME type of the file.","default":"","examples":["application/pdf"]},"size":{"type":"integer","title":"Size","description":"Decoded file size in bytes.","default":0,"examples":[434848]},"created_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created On","description":"When the file was attached to the order (UTC).","examples":["2026-08-03T12:34:56"]},"encoding":{"type":"string","title":"Encoding","description":"Encoding of `content_base64`. Always `base64`.","default":"base64"},"content_base64":{"type":"string","title":"Content Base64","description":"The complete file content, base64-encoded.","default":"","examples":["JVBERi0xLjcKJeLjz9MK..."]}},"type":"object","title":"EmbeddedAttachment","description":"A file on the order, embedded with its complete content as base64 — the\nsame shape on the order GET, the ASN and the Freight Order, so the receiving\nsystem can ingest it directly with no separate download step. `type` says\nwhat the file is."},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error","description":"Stable machine-readable error code — safe to branch on in code.","examples":["not_found"]},"error_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Description","description":"Human-readable explanation. For display/logging, not branching.","examples":["No order or shipment with reference 'ORD00001'."]}},"type":"object","required":["error"],"title":"ErrorResponse","description":"Standard error envelope returned by every endpoint on failure.","examples":[{"error":"not_found","error_description":"No order with reference 'ORD00001'."}]},"EventView":{"properties":{"at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"At"},"step":{"type":"string","title":"Step","examples":["processing"]},"detail":{"type":"string","title":"Detail","default":"","examples":["attempt 1/4"]},"message_id":{"type":"string","title":"Message Id","default":""}},"type":"object","required":["step"],"title":"EventView","description":"One step in a document's timeline."},"FreightOrderRequest":{"properties":{"fo_type":{"type":"string","title":"Fo Type","description":"Whether this is the **original** Freight Order payload for the order, a **change** (revision) to one previously sent, or a **cancel** withdrawing it. Accepted values: `original`, `change`, `cancel` — they set `action_code` to `01` / `02` / `03`.","default":"original","examples":["original"]},"pickup_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pickup Date","description":"Planned pick-up date from the supplier — overrides the order's value.","examples":["2026-08-05"]},"delivery_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Delivery Date","description":"Planned delivery date at the agreed location — defaults to the order's required-by date.","examples":["2026-08-07"]},"trucker":{"type":"string","maxLength":128,"title":"Trucker","description":"Trucking company performing the pick-up — overrides the order's value.","default":"","examples":["Ramps Trucking"]}},"type":"object","title":"FreightOrderRequest","description":"Optional inputs when generating a Freight Order payload. Send an empty\nbody to build an **original** payload straight from the order's current\ndata; override the transport-plan details as they are confirmed."},"FreightOrderSubmission":{"properties":{"fo_reference":{"type":"string","title":"Fo Reference","description":"FO payload reference. Omit to have one assigned (`FO-<year>-<sequence>`).","default":"","examples":["FO-2026-000006"]},"fo_type":{"type":"string","title":"Fo Type","description":"`original` — first FO payload for the order; `change` — a revision to one previously sent; `cancel` — withdraws a previously sent payload.","default":"original","examples":["original"]},"action_code":{"type":"string","title":"Action Code","description":"The action this payload carries, as the customer's TM system expects it: `01` Create, `02` Change, `03` Delete. **Derived from `fo_type`** (`original`→`01`, `change`→`02`, `cancel`→`03`) — sending it has no effect, so the two can never contradict each other.","default":"01","examples":["01"]},"fo_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Fo Date","description":"Date of the payload; defaults to today.","examples":["2026-08-03"]},"order_reference":{"type":"string","title":"Order Reference","description":"Our order reference (ORD). Required unless `customer_po_number` is sent.","default":"","examples":["ORD102313"]},"customer_po_number":{"type":"string","title":"Customer Po Number","default":"","examples":["4500027830"]},"company_code":{"type":"string","title":"Company Code","default":"","examples":["GB9I"]},"freight_order_number":{"type":"string","title":"Freight Order Number","description":"Your Freight Order number for this order, once assigned on your side — stored on the order as the customer reference. Empty on the original payload.","default":"","examples":[""]},"freight_unit_number":{"type":"string","title":"Freight Unit Number","default":"","examples":["FU-8100412345"]},"freight_unit_type":{"type":"string","title":"Freight Unit Type","default":"","examples":["Z001"]},"freight_order_type":{"type":"string","title":"Freight Order Type","default":"","examples":["ZFO5"]},"change_ordinal_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Change Ordinal Number","description":"Position of this order's revision in its sequence of changes — send as `TransportationOrder/@changeOrdinalNumberValue`. Counts the original as 1 and rises with every change we record; gaps are expected when several edits happen between two payloads.","examples":[3]},"source_location_id":{"type":"string","title":"Source Location Id","description":"Your location ID of the source (pick-up) location — stored with the Freight Unit details.","default":"","examples":["1000123"]},"destination_location_id":{"type":"string","title":"Destination Location Id","description":"Your location ID of the destination (delivery) location — stored with the Freight Unit details.","default":"","examples":["1005678"]},"direction":{"type":"string","title":"Direction","default":"","examples":["import"]},"mode_of_transport":{"type":"string","title":"Mode Of Transport","default":"","examples":["air_freight"]},"incoterms":{"type":"string","title":"Incoterms","default":"","examples":["fca"]},"incoterms_location":{"type":"string","title":"Incoterms Location","default":"","examples":["International-USA"]},"cargo_description":{"type":"string","title":"Cargo Description","default":"","examples":["SP11 Y1 & Y1 spare parts (test work order)"]},"cargo_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cargo Value","examples":[1508.0]},"currency":{"type":"string","title":"Currency","default":"","examples":["USD"]},"shipper":{"anyOf":[{"$ref":"#/components/schemas/SupplierInfo"},{"type":"null"}],"description":"The supplier the cargo is collected from, with their stored details."},"consignee":{"type":"string","title":"Consignee","default":"","examples":["Shell Trinidad and Tobago Limited"]},"trucker":{"type":"string","title":"Trucker","description":"Trucking company performing the pick-up.","default":"","examples":["Ramps Trucking"]},"trucker_reference":{"type":"string","title":"Trucker Reference","description":"Our trucker booking reference (RTR), when the pick-up booking exists.","default":"","examples":[""]},"pickup_address":{"anyOf":[{"$ref":"#/components/schemas/PickupAddress"},{"type":"null"}],"description":"Source — where the cargo is collected."},"delivery_address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"description":"Destination — where the cargo is delivered."},"cargo_ready_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cargo Ready Date","description":"Date the cargo was confirmed ready (from the ASN step).","examples":["2026-08-03"]},"pickup_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pickup Date","description":"Planned pick-up date from the supplier.","examples":["2026-08-05"]},"delivery_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Delivery Date","description":"Planned delivery date at the agreed location.","examples":["2026-08-07"]},"required_by":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Required By","examples":["2026-08-31"]},"total_pieces":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Pieces","examples":[18.0]},"total_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Weight","examples":[216.0]},"total_volume":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Volume","examples":[33.36]},"special_instructions":{"type":"string","title":"Special Instructions","default":"","examples":[""]},"po_details":{"items":{"$ref":"#/components/schemas/PODetailLine"},"type":"array","title":"Po Details"},"cargo_details":{"items":{"$ref":"#/components/schemas/CargoLine"},"type":"array","title":"Cargo Details"},"attachments":{"items":{"$ref":"#/components/schemas/EmbeddedAttachment"},"type":"array","title":"Attachments","description":"Every file on the order, each tagged with its `type` and embedded with its base64 content."}},"type":"object","title":"FreightOrderSubmission","description":"A Freight Order payload submitted (POSTed) to us — the same document the\ngenerator returns, so a generated payload can be posted back verbatim after\nreview/completion. Identify the order with `order_reference` and/or\n`customer_po_number`; `fo_reference` is assigned when omitted."},"FreightOrderSubmissionResult":{"properties":{"accepted":{"type":"boolean","title":"Accepted","default":true,"examples":[true]},"duplicate":{"type":"boolean","title":"Duplicate","description":"True when this exact payload was already submitted under the same `fo_reference`.","default":false,"examples":[false]},"fo_reference":{"type":"string","title":"Fo Reference","examples":["FO-2026-000006"]},"fo_type":{"type":"string","title":"Fo Type","default":"original","examples":["original"]},"order_reference":{"type":"string","title":"Order Reference","default":"","examples":["ORD102313"]},"customer_po_number":{"type":"string","title":"Customer Po Number","default":"","examples":["4500027830"]},"synced_to_order":{"items":{"type":"string"},"type":"array","title":"Synced To Order","description":"Order fields updated from this payload (Freight Unit details, source/destination location IDs, Freight Order number).","examples":[["freight_unit_number","freight_order_type"]]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal notes (e.g. fields the ERP cannot store yet)."}},"type":"object","required":["fo_reference"],"title":"FreightOrderSubmissionResult","description":"Result of submitting a Freight Order payload.","examples":[{"accepted":true,"customer_po_number":"4500027830","duplicate":false,"fo_reference":"FO-2026-000006","fo_type":"original","order_reference":"ORD102313","synced_to_order":["freight_unit_number","freight_order_type","source_location_id","destination_location_id"],"warnings":[]}]},"FreightOrderView":{"properties":{"fo_reference":{"type":"string","title":"Fo Reference","description":"Unique FO payload reference, assigned on issue.","examples":["FO-2026-000001"]},"fo_type":{"type":"string","title":"Fo Type","description":"`original` — first FO payload for the order; `change` — a revision to one previously sent; `cancel` — withdraws a previously sent payload.","default":"original","examples":["original"]},"action_code":{"type":"string","title":"Action Code","description":"The action this payload carries, as the customer's TM system expects it: `01` Create, `02` Change, `03` Delete. **Derived from `fo_type`** (`original`→`01`, `change`→`02`, `cancel`→`03`) — sending it has no effect, so the two can never contradict each other.","default":"01","examples":["01"]},"fo_date":{"type":"string","format":"date","title":"Fo Date","description":"Date the payload was issued.","examples":["2026-08-03"]},"order_reference":{"type":"string","title":"Order Reference","examples":["ORD102313"]},"customer_po_number":{"type":"string","title":"Customer Po Number","default":"","examples":["4500027830"]},"company_code":{"type":"string","title":"Company Code","default":"","examples":["GB9I"]},"freight_order_number":{"type":"string","title":"Freight Order Number","description":"Your Freight Order number for this order, once assigned on your side — stored on the order as the customer reference. Empty on the original payload.","default":"","examples":[""]},"freight_unit_number":{"type":"string","title":"Freight Unit Number","default":"","examples":["FU-8100412345"]},"freight_unit_type":{"type":"string","title":"Freight Unit Type","default":"","examples":["Z001"]},"freight_order_type":{"type":"string","title":"Freight Order Type","default":"","examples":["ZFO5"]},"change_ordinal_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Change Ordinal Number","description":"Position of this order's revision in its sequence of changes — send as `TransportationOrder/@changeOrdinalNumberValue`. Counts the original as 1 and rises with every change we record; gaps are expected when several edits happen between two payloads.","examples":[3]},"source_location_id":{"type":"string","title":"Source Location Id","description":"Your location ID of the source (pick-up) location — stored with the Freight Unit details.","default":"","examples":["1000123"]},"destination_location_id":{"type":"string","title":"Destination Location Id","description":"Your location ID of the destination (delivery) location — stored with the Freight Unit details.","default":"","examples":["1005678"]},"direction":{"type":"string","title":"Direction","default":"","examples":["import"]},"mode_of_transport":{"type":"string","title":"Mode Of Transport","default":"","examples":["air_freight"]},"incoterms":{"type":"string","title":"Incoterms","default":"","examples":["fca"]},"incoterms_location":{"type":"string","title":"Incoterms Location","default":"","examples":["International-USA"]},"cargo_description":{"type":"string","title":"Cargo Description","default":"","examples":["SP11 Y1 & Y1 spare parts (test work order)"]},"cargo_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cargo Value","examples":[1508.0]},"currency":{"type":"string","title":"Currency","default":"","examples":["USD"]},"shipper":{"anyOf":[{"$ref":"#/components/schemas/SupplierInfo"},{"type":"null"}],"description":"The supplier the cargo is collected from, with their stored details."},"consignee":{"type":"string","title":"Consignee","default":"","examples":["Shell Trinidad and Tobago Limited"]},"trucker":{"type":"string","title":"Trucker","description":"Trucking company performing the pick-up.","default":"","examples":["Ramps Trucking"]},"trucker_reference":{"type":"string","title":"Trucker Reference","description":"Our trucker booking reference (RTR), when the pick-up booking exists.","default":"","examples":[""]},"pickup_address":{"anyOf":[{"$ref":"#/components/schemas/PickupAddress"},{"type":"null"}],"description":"Source — where the cargo is collected."},"delivery_address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"description":"Destination — where the cargo is delivered."},"cargo_ready_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cargo Ready Date","description":"Date the cargo was confirmed ready (from the ASN step).","examples":["2026-08-03"]},"pickup_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pickup Date","description":"Planned pick-up date from the supplier.","examples":["2026-08-05"]},"delivery_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Delivery Date","description":"Planned delivery date at the agreed location.","examples":["2026-08-07"]},"required_by":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Required By","examples":["2026-08-31"]},"total_pieces":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Pieces","examples":[18.0]},"total_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Weight","examples":[216.0]},"total_volume":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Volume","examples":[33.36]},"special_instructions":{"type":"string","title":"Special Instructions","default":"","examples":[""]},"po_details":{"items":{"$ref":"#/components/schemas/PODetailLine"},"type":"array","title":"Po Details"},"cargo_details":{"items":{"$ref":"#/components/schemas/CargoLine"},"type":"array","title":"Cargo Details"},"attachments":{"items":{"$ref":"#/components/schemas/EmbeddedAttachment"},"type":"array","title":"Attachments","description":"Every file on the order, each tagged with its `type` and embedded with its base64 content."}},"type":"object","required":["fo_reference","fo_date","order_reference"],"title":"FreightOrderView","description":"A Freight Order payload — sent to the customer to create the Freight\nOrder in their system once the Freight Unit details and the transport plan\nare in. Field names match the order GET / ASN; the customer's own Freight\nOrder number, returned on their side, is stored back on the order via\n`PUT` (`customer_reference`) and appears here as `freight_order_number`\non subsequent payloads."},"FreightUnitResult":{"properties":{"updated":{"type":"boolean","title":"Updated","default":true,"examples":[true]},"order_reference":{"type":"string","title":"Order Reference","description":"Our order reference (ORD number).","examples":["ORD00001"]},"customer_po_number":{"type":"string","title":"Customer Po Number","default":"","examples":["4500123456"]},"updated_fields":{"items":{"type":"string"},"type":"array","title":"Updated Fields","description":"Which field(s) this request changed.","examples":[["freight_unit_number","freight_order_type"]]},"freight_unit_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freight Unit Number","description":"The value stored by this call (null when not part of the update).","examples":["FU-8100412345"]},"freight_unit_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freight Unit Type","description":"The value stored by this call (null when not part of the update).","examples":["Z001"]},"freight_order_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freight Order Number","description":"The value stored by this call (null when not part of the update).","examples":["FO-2026-00045"]},"freight_order_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Freight Order Type","description":"The value stored by this call (null when not part of the update).","examples":["ZFO5"]},"source_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Location Id","description":"The value stored by this call (null when not part of the update).","examples":["1000123"]},"destination_location_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Destination Location Id","description":"The value stored by this call (null when not part of the update).","examples":["1005678"]}},"type":"object","required":["order_reference"],"title":"FreightUnitResult","description":"Result of storing the Freight Unit details on an order.","examples":[{"customer_po_number":"4500123456","destination_location_id":"1005678","freight_order_number":"FO-2026-00045","freight_order_type":"ZFO5","freight_unit_number":"FU-8100412345","freight_unit_type":"Z001","order_reference":"ORD00001","source_location_id":"1000123","updated":true,"updated_fields":["freight_unit_number","freight_order_type","source_location_id","destination_location_id"]}]},"FreightUnitUpdate":{"properties":{"freight_unit_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Freight Unit Number","description":"Your Freight Unit reference number.","examples":["FU-8100412345"]},"freight_unit_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Freight Unit Type","description":"The Freight Unit's own type code (e.g. `Z001`). Distinct from `freight_order_type`, which is the Freight *Order* type (`ZFO5`).","examples":["Z001"]},"freight_order_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Freight Order Number","description":"Your Freight Order number for this order, once assigned on your side. Stored as the order's customer reference — the same value the general PUT sets as `customer_reference` and the Freight Order payload returns as `freight_order_number`.","examples":["FO-2026-00045"]},"freight_order_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Freight Order Type","description":"Your Freight Order type code — `ZFO5` for EPCM and return orders, blank otherwise.","examples":["ZFO5"]},"source_location_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Source Location Id","description":"Your location ID of the source (pick-up) location.","examples":["1000123"]},"destination_location_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Destination Location Id","description":"Your location ID of the destination (delivery) location.","examples":["1005678"]}},"type":"object","title":"FreightUnitUpdate","description":"The Freight Unit details for an order — the FU number and type plus the\nsource / destination location IDs. Send any subset; only the field(s) you\nprovide are updated, everything else is left untouched.","examples":[{"destination_location_id":"1005678","freight_order_number":"FO-2026-00045","freight_order_type":"ZFO5","freight_unit_number":"FU-8100412345","freight_unit_type":"Z001","source_location_id":"1000123"},{"freight_unit_number":"FU-8100412345"}]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IntegrationStats":{"properties":{"date":{"type":"string","title":"Date","examples":["2026-08-25"]},"inbound_today":{"type":"integer","title":"Inbound Today"},"outbound_today":{"type":"integer","title":"Outbound Today"},"succeeded":{"type":"integer","title":"Succeeded"},"queued_or_retrying":{"type":"integer","title":"Queued Or Retrying"},"dead_letter":{"type":"integer","title":"Dead Letter"}},"type":"object","required":["date","inbound_today","outbound_today","succeeded","queued_or_retrying","dead_letter"],"title":"IntegrationStats","description":"Today's traffic, the dashboard numbers."},"MessageDetail":{"properties":{"message":{"$ref":"#/components/schemas/MessageView"},"timeline":{"items":{"$ref":"#/components/schemas/EventView"},"type":"array","title":"Timeline"}},"type":"object","required":["message"],"title":"MessageDetail"},"MessageView":{"properties":{"message_id":{"type":"string","title":"Message Id","examples":["4bb4e9a2-6d1f-4c39-9f2a-1f4dd9f2a111"]},"correlation_id":{"type":"string","title":"Correlation Id","description":"Business handle — the customer PO number or document reference.","default":"","examples":["4500026582"]},"partner":{"type":"string","title":"Partner","default":"SHELL","examples":["SHELL"]},"message_type":{"type":"string","title":"Message Type","examples":["PURCHASE_ORDER"]},"direction":{"type":"string","title":"Direction","examples":["inbound"]},"document_reference":{"type":"string","title":"Document Reference","default":"","examples":["PO-000123"]},"status":{"type":"string","title":"Status","description":"`queued`, `processing`, `succeeded` or `dead_letter`.","examples":["queued"]},"attempt":{"type":"integer","title":"Attempt","examples":[1]},"max_attempts":{"type":"integer","title":"Max Attempts","examples":[4]},"next_attempt_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Attempt At"},"last_error":{"type":"string","title":"Last Error","default":"","examples":[""]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["message_id","message_type","direction","status","attempt","max_attempts"],"title":"MessageView","description":"The envelope of one unit of integration work."},"MilestoneRequest":{"properties":{"milestone":{"type":"string","title":"Milestone","description":"Which milestone happened. One of: `pickup_date` (Pick up Date), `actual_pickup` (Actual Pickup Date), `delivered_to_warehouse` (Date Delivered to Warehouse), `departure_from_warehouse` (Departure from Warehouse), `delivered_to_carrier` (Cargo Delivered to Carrier), `estimated_departure` (Estimated Departure Date), `transhipment_arrival` (Arrival at Transhipment Port), `transhipment_departure` (Last Transhipment Departure), `arrival` (Arrival Date), `shipment_cleared` (Shipment Cleared), `required_on_site` (Required On Site), `delivered_to_client` (Shipment Delivered To Client), `delayed` (Delay).","examples":["actual_pickup"]},"date_time":{"type":"string","format":"date-time","title":"Date Time","description":"When the milestone happened (or, for a milestone like `delayed`, the new date). Include a timezone; a naive value is treated as UTC.","examples":["2026-08-23T14:20:00Z"]},"location":{"type":"string","maxLength":128,"title":"Location","description":"Optional — where the milestone occurred (port, warehouse, city), as free text.","default":"","examples":["Port of Spain"]},"document_reference":{"type":"string","maxLength":128,"title":"Document Reference","description":"Optional — the supporting document for this milestone, whatever fits it: an AWB/BL number for a departure, a customs entry number for `shipment_cleared`, a warehouse receipt for `delivered_to_warehouse`, a POD reference for `delivered_to_client`.","default":"","examples":["MAWB 810-41010911"]},"notes":{"type":"string","maxLength":512,"title":"Notes","description":"Optional free-text context for the customer — e.g. the reason for a `delayed` milestone.","default":"","examples":["Vessel rolled to next sailing"]}},"type":"object","required":["milestone","date_time"],"title":"MilestoneRequest","description":"The milestone to report — one per call.","examples":[{"date_time":"2026-08-23T14:20:00Z","milestone":"actual_pickup"},{"date_time":"2026-08-28T09:15:00Z","document_reference":"Entry C-2026-118845","location":"Port of Spain","milestone":"shipment_cleared"},{"date_time":"2026-08-30T04:00:00Z","milestone":"delayed","notes":"Vessel rolled to next sailing"}]},"MilestoneView":{"properties":{"milestone_reference":{"type":"string","title":"Milestone Reference","description":"Unique reference for this update, assigned on issue.","examples":["MS-2026-000001"]},"milestone_date":{"type":"string","format":"date","title":"Milestone Date","description":"Date the update was issued.","examples":["2026-08-23"]},"order_reference":{"type":"string","title":"Order Reference","description":"Our order reference (ORD).","examples":["ORD102313"]},"customer_po_number":{"type":"string","title":"Customer Po Number","default":"","examples":["4500027830"]},"freight_order_number":{"type":"string","title":"Freight Order Number","description":"Your Freight Order number, when you have stored one on the order — included so the update can be tied to your own document. Empty otherwise.","default":"","examples":["6700000164"]},"freight_unit_number":{"type":"string","title":"Freight Unit Number","description":"Your Freight Unit reference, when stored on the order. Empty otherwise.","default":"","examples":["FU-8100412345"]},"sequence":{"type":"integer","title":"Sequence","description":"Position of this update in the order's milestone history, counting the first as 1 — use it to order our messages if they arrive out of sequence.","examples":[3]},"milestone":{"type":"string","title":"Milestone","description":"The milestone reported.","examples":["actual_pickup"]},"date_time":{"type":"string","format":"date-time","title":"Date Time","description":"The reported moment.","examples":["2026-08-23T14:20:00Z"]},"location":{"type":"string","title":"Location","default":"","examples":[""]},"document_reference":{"type":"string","title":"Document Reference","default":"","examples":[""]},"notes":{"type":"string","title":"Notes","default":"","examples":[""]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal notes about this update."}},"type":"object","required":["milestone_reference","milestone_date","order_reference","sequence","milestone","date_time"],"title":"MilestoneView","description":"A milestone update as issued to the customer.","examples":[{"customer_po_number":"4500027830","date_time":"2026-08-23T14:20:00Z","document_reference":"","freight_order_number":"6700000164","freight_unit_number":"FU-8100412345","location":"Miami, FL","milestone":"actual_pickup","milestone_date":"2026-08-23","milestone_reference":"MS-2026-000001","notes":"","order_reference":"ORD102313","sequence":3,"warnings":[]}]},"OrderDatesUpdate":{"properties":{"cargo_ready_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cargo Ready Date","examples":["2026-03-15"]},"required_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Required By","examples":["2026-04-10"]},"supplier_promise_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Supplier Promise Date","examples":["2026-03-20"]},"approval_to_ship_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approval To Ship Date","examples":["2026-03-25"]}},"type":"object","title":"OrderDatesUpdate","description":"Order dates (`YYYY-MM-DD`) — the same names the GET returns. The original\nsubmit keys (`cargo_ready`, `required_on_site`, `supplier_promise`,\n`approval_to_ship`) remain accepted as legacy aliases."},"OrderList":{"properties":{"count":{"type":"integer","title":"Count","description":"Total matching records, ignoring paging.","examples":[128]},"limit":{"type":"integer","title":"Limit","examples":[50]},"offset":{"type":"integer","title":"Offset","examples":[0]},"results":{"items":{"$ref":"#/components/schemas/OrderView"},"type":"array","title":"Results"}},"type":"object","required":["count","limit","offset","results"],"title":"OrderList","description":"A page of purchase orders (list view omits addresses and PO Details).","examples":[{"count":128,"limit":50,"offset":0,"results":[{"approval_to_ship_date":"2026-03-14","asn_date":"2026-03-15","asn_number":"ASN-2026-000001","asn_type":"original","assigned_bde":"","assigned_to":"Maria Garcia","attachments":[{"content_base64":"JVBERi0xLjcKJeLjz9MK...","created_on":"2026-08-03T12:34:56","encoding":"base64","filename":"PO 4500123456.pdf","mimetype":"application/pdf","size":434848,"type":"customer_po"}],"attended_by":"","attention":"","booking_reference":"RHB1948","cargo_description":"Industrial valves, gaskets, and centrifugal pump","cargo_details":[{"description":"Gate Valves 4IN","dimension_uom":"MTR","gross_weight":450.0,"height":1.0,"length":1.2,"line":"1","lot_number":"","package_type":"Pallet","part_number":"MAT-78923-A1","piece_count":2,"quantity":2,"volume":0.96,"volume_uom":"MTQ","weight_uom":"KGM","width":0.8}],"cargo_ready_date":"2026-03-15","cargo_value":45000.0,"carrier":"","change_ordinal_number":3,"company_code":"TT01","consignee":"Shell Trinidad and Tobago Limited","created_at":"2026-03-06T09:12:00","currency":"USD","customer":"Shell Trinidad and Tobago Limited","customer_care_rep":"","customer_po_number":"4500123456","customer_reference":"FO-2026-00045","destination_country":"Trinidad and Tobago","destination_location_id":"1005678","direction":"import","freight_order_type":"ZFO5","freight_type":"fcl","freight_unit_number":"FU-8100412345","has_house_booking":"does_not_have_house_booking","hazardous":"no","incoterms":"fob","incoterms_location":"Point Lisas, Trinidad","is_cargo_bonded":"","mode_of_transport":"ocean_freight","move_type":"","order_details":"Shell Materials Management — LSP notification","order_reference":"ORD00001","origin_agent":"","pickup_date":"2026-03-15","port_of_discharge":"Port of Spain, TT","port_of_loading":"Houston, US","pro_reference":"PRO-2026-01","quotation":"","ready_to_ship":"no","required_by":"2026-04-10","shipper":"Gulf Coast Industrial Supplies Inc.","source_location_id":"1000123","special_instructions":"Temperature controlled storage required. Do not stack.","state":"order","supplier":{"city":"Edmonton","country":"CA","email":"orders@gulfcoastindustrial.com","id":"200000004","name":"Gulf Coast Industrial Supplies Inc.","phone":"+1 780 555 0142","state":"Alberta","street1":"9915 108 Street NW","street2":"6th Floor South Petroleum Plaza","zip":"T5K 2G8"},"supplier_promise_date":"2026-03-20","total_pieces":8.0,"total_volume":12.5,"total_weight":2450.0,"trucker":"","trucker_reference":"","trucking_arranged_by":"ramps","warehouse_receipt_number":""}]}]},"OrderView":{"properties":{"order_reference":{"type":"string","title":"Order Reference","description":"Our unique order reference (ORD number), assigned when the order is created. Use it to read or update this order.","examples":["ORD00001"]},"customer_po_number":{"type":"string","title":"Customer Po Number","description":"Your purchase order number, exactly as submitted. Also used to detect duplicates: re-submitting the same number updates the existing order.","default":"","examples":["4500123456"]},"pro_reference":{"type":"string","title":"Pro Reference","description":"Carrier PRO (tracking) number for the road/trucking leg, when assigned.","default":"","examples":["PRO-2026-01"]},"trucker_reference":{"type":"string","title":"Trucker Reference","description":"Our trucker booking reference (RTR), generated when a pick-up trucking booking is created for this order.","default":"","examples":[""]},"freight_unit_number":{"type":"string","title":"Freight Unit Number","description":"Your Freight Unit reference for this order. Set via `PUT /purchase-orders/{identifier}` or the dedicated `…/freight-unit` route.","default":"","examples":["FU-8100412345"]},"freight_order_type":{"type":"string","title":"Freight Order Type","description":"Your Freight Order type code. `ZFO5` for **EPCM** and **return** orders; left **blank** for anything else. Set via `PUT /purchase-orders/{identifier}` or the dedicated `…/freight-unit` route.","default":"","examples":["ZFO5"]},"freight_unit_type":{"type":"string","title":"Freight Unit Type","description":"The Freight Unit's own type code (e.g. `Z001`) — not to be confused with `freight_order_type` above, which is the Freight Order type (`ZFO5`).","default":"","examples":["Z001"]},"change_ordinal_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Change Ordinal Number","description":"How many times this order has been changed, counting the original as 1. Incremented by us whenever a field the Freight Order carries is updated (addresses, references, dates, basic order fields, line items) — read-only, and it only ever goes up. Travels on the Freight Order payload as `changeOrdinalNumberValue` so your TM system can order our messages.","examples":[3]},"source_location_id":{"type":"string","title":"Source Location Id","description":"Your location ID of the source (pick-up) location — stored with the Freight Unit details.","default":"","examples":["1000123"]},"destination_location_id":{"type":"string","title":"Destination Location Id","description":"Your location ID of the destination (delivery) location — stored with the Freight Unit details.","default":"","examples":["1005678"]},"asn_number":{"type":"string","title":"Asn Number","description":"Reference of the most recent ASN issued for this order — stamped automatically by `POST /purchase-orders/{identifier}/asn`.","default":"","examples":["ASN-2026-000001"]},"asn_type":{"type":"string","title":"Asn Type","description":"Type of the most recent ASN: `original` or `change`.","default":"","examples":["original"]},"asn_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Asn Date","description":"Date the most recent ASN was issued.","examples":["2026-03-15"]},"state":{"type":"string","title":"State","description":"Where the order is in its lifecycle: `new` = under review, `order` = pending at the supplier, `trucking` = pick-up in progress, `warehouse` = received at our warehouse, `pick_pack` = being picked & packed for shipment, `closed` = completed (closed orders are not returned by the API).","default":"","examples":["order"]},"direction":{"type":"string","title":"Direction","description":"Direction of the movement: `import` (into the destination country) or `export` (out of it).","default":"","examples":["import"]},"mode_of_transport":{"type":"string","title":"Mode Of Transport","description":"International mode of transport for the onward shipment. The complete list: `air_freight` (Air), `ocean_freight` (Ocean), `road` (Road), `mode_of_transport_not_set` (International Mode Of Transport Not Set). `mode_of_transport_not_set` means it has not been decided yet.","default":"","examples":["ocean_freight"]},"freight_type":{"type":"string","title":"Freight Type","description":"Ocean service type: `fcl` (Full Container Load), `lcl` (Less than Container Load), or `breakbulk`. Empty for air/road.","default":"","examples":["fcl"]},"hazardous":{"type":"string","title":"Hazardous","description":"Whether the cargo is classified as hazardous / dangerous goods (`yes`/`no`).","default":"","examples":["no"]},"is_cargo_bonded":{"type":"string","title":"Is Cargo Bonded","description":"Whether the cargo moves under customs bond (`yes`/`no`).","default":"","examples":[""]},"has_house_booking":{"type":"string","title":"Has House Booking","description":"Whether the order has been consolidated onto a freight booking yet (`has_house_booking` / `does_not_have_house_booking`). When it has, see `booking_reference` and `booking`.","default":"","examples":["does_not_have_house_booking"]},"trucking_arranged_by":{"type":"string","title":"Trucking Arranged By","description":"Who arranges the supplier pick-up: `ramps` (our forwarding team) or `supplier` (the supplier delivers).","default":"","examples":["ramps"]},"consignee":{"type":"string","title":"Consignee","description":"The receiving party the goods are consigned to.","default":"","examples":["Shell Trinidad and Tobago Limited"]},"shipper":{"type":"string","title":"Shipper","description":"The supplier / shipper the goods are collected from.","default":"","examples":["Gulf Coast Industrial Supplies Inc."]},"origin_agent":{"type":"string","title":"Origin Agent","description":"Agent handling the cargo at origin, when one is involved.","default":"","examples":[""]},"trucker":{"type":"string","title":"Trucker","description":"Trucking company performing the pick-up, once trucking is booked.","default":"","examples":[""]},"assigned_to":{"type":"string","title":"Assigned To","description":"Our team member responsible for this order.","default":"","examples":["Maria Garcia"]},"port_of_loading":{"type":"string","title":"Port Of Loading","description":"Port/airport where the cargo is loaded for the international leg.","default":"","examples":["Houston, US"]},"booking_reference":{"type":"string","title":"Booking Reference","description":"Reference (RHB) of the freight booking this order was consolidated onto, once booked. See the `booking` object on the single-order read for its details.","default":"","examples":["RHB1948"]},"quotation":{"type":"string","title":"Quotation","description":"Approved quotation linked to this order, if any.","default":"","examples":[""]},"cargo_description":{"type":"string","title":"Cargo Description","description":"Summary description of the cargo.","default":"","examples":["Industrial valves, gaskets, and centrifugal pump"]},"cargo_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cargo Value","description":"Declared cargo value in USD.","examples":[45000.0]},"pickup_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Pickup Date","description":"Scheduled date for the supplier pick-up.","examples":["2026-03-15"]},"cargo_ready_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cargo Ready Date","description":"Date the cargo is/was ready for collection at the supplier.","examples":["2026-03-15"]},"supplier_promise_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Supplier Promise Date","description":"Date the supplier promised the goods would be ready.","examples":["2026-03-20"]},"approval_to_ship_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Approval To Ship Date","description":"Date approval to ship was given.","examples":["2026-03-14"]},"actual_pickup_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Actual Pickup Date","description":"Date the cargo was actually collected from the supplier.","examples":[null]},"delivered_to_carrier_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Delivered To Carrier Date","description":"Date the cargo was handed over to the international carrier.","examples":[null]},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the order was created in our system.","examples":["2026-03-06T09:12:00"]},"attended_by":{"type":"string","title":"Attended By","description":"Team member who attended to the order intake.","default":"","examples":[""]},"attention":{"type":"string","title":"Attention","description":"Attention / contact person for trucking instructions.","default":"","examples":[""]},"special_instructions":{"type":"string","title":"Special Instructions","description":"Handling instructions supplied on the purchase order.","default":"","examples":["Temperature controlled storage required. Do not stack."]},"order_details":{"type":"string","title":"Order Details","description":"Free-text order notes supplied on the purchase order.","default":"","examples":["Shell Materials Management — LSP notification"]},"customer":{"type":"string","title":"Customer","description":"The customer account this order belongs to.","default":"","examples":["Shell Trinidad and Tobago Limited"]},"customer_reference":{"type":"string","title":"Customer Reference","description":"Your **Freight Order Number** — your own reference for this order, separate from the purchase order number. Updatable via `PUT /purchase-orders/{identifier}`.","default":"","examples":["FO-2026-00045"]},"incoterms_location":{"type":"string","title":"Incoterms Location","description":"Named place for the incoterm (e.g. the port or city the term applies to).","default":"","examples":["Point Lisas, Trinidad"]},"company_code":{"type":"string","title":"Company Code","description":"Your company code for the order.","default":"","examples":["TT01"]},"incoterms":{"type":"string","title":"Incoterms","description":"Agreed Incoterm for the purchase (lowercase code): `exw`, `fca`, `fob`, `cif`, `ddp`, etc.","default":"","examples":["fob"]},"currency":{"type":"string","title":"Currency","description":"Currency of the declared cargo value.","default":"","examples":["USD"]},"move_type":{"type":"string","title":"Move Type","description":"How the cargo is routed at destination: `direct_to_customer` or `deliver_agent` (delivered via an agent).","default":"","examples":[""]},"ready_to_ship":{"type":"string","title":"Ready To Ship","description":"Whether the order has been flagged ready to ship (`yes`/`no`).","default":"","examples":["no"]},"carrier":{"type":"string","title":"Carrier","description":"Carrier associated with the order (e.g. the line/airline used).","default":"","examples":[""]},"customer_care_rep":{"type":"string","title":"Customer Care Rep","description":"Our customer-care representative for this order.","default":"","examples":[""]},"assigned_bde":{"type":"string","title":"Assigned Bde","description":"Our business development executive assigned to your account.","default":"","examples":[""]},"port_of_discharge":{"type":"string","title":"Port Of Discharge","description":"Port/airport where the cargo is discharged at destination.","default":"","examples":["Port of Spain, TT"]},"destination_country":{"type":"string","title":"Destination Country","description":"Final destination country of the cargo.","default":"","examples":["Trinidad and Tobago"]},"total_pieces":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Pieces","description":"Total piece count across all cargo lines.","examples":[8.0]},"total_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Weight","description":"Total weight across all cargo lines (KG unless noted).","examples":[2450.0]},"total_volume":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Volume","description":"Total volume across all cargo lines (CBM unless noted).","examples":[12.5]},"required_by":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Required By","description":"Required On Site date — the date you need the goods on site / in your warehouse. Drives how the shipment is planned and prioritised.","examples":["2026-04-10"]},"customer_release_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Customer Release Date","description":"Date you released the order for onward shipping, when a customer release step applies.","examples":[null]},"date_delivered_to_warehouse":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Delivered To Warehouse","description":"Date the cargo was received at our warehouse.","examples":[null]},"warehouse_receipt_number":{"type":"string","title":"Warehouse Receipt Number","description":"Warehouse receipt number issued when the cargo was received at our warehouse.","default":"","examples":[""]},"booking":{"anyOf":[{"$ref":"#/components/schemas/BookingInfo"},{"type":"null"}],"description":"Full details of the related booking (single-order read only)."},"supplier":{"anyOf":[{"$ref":"#/components/schemas/SupplierInfo"},{"type":"null"}],"description":"The supplier (shipper) with their stored details (single-order read only)."},"pickup_address":{"anyOf":[{"$ref":"#/components/schemas/PickupAddress"},{"type":"null"}],"description":"Where the cargo is collected from — usually the supplier's premises (single-order read only)."},"delivery_address":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"description":"Final delivery address for the cargo (single-order read only)."},"po_details":{"items":{"$ref":"#/components/schemas/PODetailLine"},"type":"array","title":"Po Details","description":"Line items from your purchase order (single-order read only)."},"cargo_details":{"items":{"$ref":"#/components/schemas/CargoLine"},"type":"array","title":"Cargo Details","description":"Cargo lines with full physical detail — pieces, weight, dimensions, volume (single-order read only)."},"attachments":{"items":{"$ref":"#/components/schemas/EmbeddedAttachment"},"type":"array","title":"Attachments","description":"Every file on the order — customer PO, cargo images, warehouse receipt, trucker documents… — each tagged with its `type` and embedded with its base64 content (single-order read only)."}},"type":"object","required":["order_reference"],"title":"OrderView","description":"A purchase order / order (both are the same record).\n\nReturns a broad set of fields so integrators have everything they might need;\nfields that are empty on a given order come back as \"\" / null. The related\nbooking, addresses, and PO Details are populated on the single-order read;\nthe list view omits them.","examples":[{"approval_to_ship_date":"2026-03-14","asn_date":"2026-03-15","asn_number":"ASN-2026-000001","asn_type":"original","assigned_bde":"","assigned_to":"Maria Garcia","attachments":[{"content_base64":"JVBERi0xLjcKJeLjz9MK...","created_on":"2026-08-03T12:34:56","encoding":"base64","filename":"PO 4500123456.pdf","mimetype":"application/pdf","size":434848,"type":"customer_po"}],"attended_by":"","attention":"","booking":{"booking_type":"import","consignee":"Shell Trinidad and Tobago Limited","customer_reference":"","cutoff_date":"2026-03-13T14:00:00","description_of_goods":"ACTUATORS + PARTS","eta":"2026-03-19","etd":"2026-03-17","house_bill_number":"HAWB18343","master_bill_number":"810 41010911","mode_of_transport":"air_freight","port_of_discharge":"Piarco","port_of_loading":"Port of Miami (USMIA)","reference":"RHB1948","shipment_reference":"RLL145713","shipper":"THENEX GMBH","status":"cargo_ready","type_of_move":"air","vessel":"","voyage":""},"booking_reference":"RHB1948","cargo_description":"Industrial valves, gaskets, and centrifugal pump","cargo_details":[{"description":"Gate Valves 4IN","dimension_uom":"MTR","gross_weight":450.0,"height":1.0,"length":1.2,"line":"1","lot_number":"","package_type":"Pallet","part_number":"MAT-78923-A1","piece_count":2,"quantity":2,"volume":0.96,"volume_uom":"MTQ","weight_uom":"KGM","width":0.8}],"cargo_ready_date":"2026-03-15","cargo_value":45000.0,"carrier":"","change_ordinal_number":3,"company_code":"TT01","consignee":"Shell Trinidad and Tobago Limited","created_at":"2026-03-06T09:12:00","currency":"USD","customer":"Shell Trinidad and Tobago Limited","customer_care_rep":"","customer_po_number":"4500123456","customer_reference":"FO-2026-00045","delivery_address":{"city":"Couva","country":"TT","id":"TA32","location_id":5231,"location_name":"Point Lisas Warehouse 14","region":"CTT","state":"","street1":"Point Lisas Industrial Estate","street2":"Warehouse 14","zip":""},"destination_country":"Trinidad and Tobago","destination_location_id":"1005678","direction":"import","freight_order_type":"ZFO5","freight_type":"fcl","freight_unit_number":"FU-8100412345","has_house_booking":"does_not_have_house_booking","hazardous":"no","incoterms":"fob","incoterms_location":"Point Lisas, Trinidad","is_cargo_bonded":"","mode_of_transport":"ocean_freight","move_type":"","order_details":"Shell Materials Management — LSP notification","order_reference":"ORD00001","origin_agent":"","pickup_address":{"city":"Houston","country":"US","id":"","location_id":5230,"location_name":"Westheimer Depot","region":"TX","state":"Texas","street1":"12000 Westheimer Road","street2":"Warehouse B, Dock 7","supplier_id":"200000004","zip":"77077"},"pickup_date":"2026-03-15","po_details":[{"description":"Gate Valves 4IN","line":"1","material_code":"MAT-78923-A1","quantity":2,"status":"created","uom":"EA"},{"description":"Spiral Wound Gaskets","line":"2","material_code":"MAT-78924-B0","quantity":2,"status":"updated","uom":"EA"}],"port_of_discharge":"Port of Spain, TT","port_of_loading":"Houston, US","pro_reference":"PRO-2026-01","quotation":"","ready_to_ship":"no","required_by":"2026-04-10","shipper":"Gulf Coast Industrial Supplies Inc.","source_location_id":"1000123","special_instructions":"Temperature controlled storage required. Do not stack.","state":"order","supplier":{"city":"Edmonton","country":"CA","email":"orders@gulfcoastindustrial.com","id":"200000004","name":"Gulf Coast Industrial Supplies Inc.","phone":"+1 780 555 0142","state":"Alberta","street1":"9915 108 Street NW","street2":"6th Floor South Petroleum Plaza","zip":"T5K 2G8"},"supplier_promise_date":"2026-03-20","total_pieces":8.0,"total_volume":12.5,"total_weight":2450.0,"trucker":"","trucker_reference":"","trucking_arranged_by":"ramps","warehouse_receipt_number":""}]},"PODetailLine":{"properties":{"line":{"type":"string","title":"Line","description":"Line number from your purchase order.","default":"","examples":["1"]},"description":{"type":"string","title":"Description","description":"Item / material description for the line.","default":"","examples":["Gate Valves 4IN"]},"quantity":{"type":"integer","title":"Quantity","description":"Ordered quantity for the line.","default":0,"examples":[2]},"uom":{"type":"string","title":"Uom","description":"Unit of measure for the quantity, as a **UN/ECE Rec 20** code (`EA` each, `KGM` kilogram, `LBR` pound).","default":"","examples":["EA"]},"material_code":{"type":"string","title":"Material Code","description":"Your material / part number for the line (always a string, even when numeric).","default":"","examples":["1000060021"]},"status":{"type":"string","title":"Status","description":"Lifecycle of this line: `created`, `updated` or `deleted`. Set from your submission, matched on `line`. A `deleted` line stays on the order for history rather than being removed.","default":"","examples":["created"]}},"type":"object","title":"PODetailLine","description":"A line item on the purchase order (PO Details)."},"POLineUpdate":{"properties":{"line":{"type":"string","title":"Line","description":"Line number.","default":"","examples":["1"]},"description":{"type":"string","title":"Description","default":"","examples":["SP15 YN & YN - Normal"]},"quantity":{"type":"number","title":"Quantity","default":0,"examples":[2]},"uom":{"type":"string","title":"Uom","description":"Unit of measure for the quantity. Send the **UN/ECE Rec 20** code (`EA`, `KGM`, `LBR`) — our own UOM names are still accepted.","default":"","examples":["EA"]},"gross_weight":{"type":"number","title":"Gross Weight","description":"Gross weight — stored on the physical cargo line.","default":0,"examples":[450.0]},"status":{"type":"string","title":"Status","description":"Lifecycle of this line: `created`, `updated` or `deleted`. Matched to the existing line by `line` and stored on it; omit to leave the stored status alone. A `deleted` line is kept on the order for history — there is no delete endpoint.","default":"","examples":["updated"]},"material_code":{"type":"string","title":"Material Code","default":"","examples":["1000060021"]},"part_number":{"type":"string","title":"Part Number","default":"","examples":["1000060021"]},"lot_number":{"type":"string","title":"Lot Number","default":"","examples":[""]},"piece_count":{"type":"number","title":"Piece Count","default":0,"examples":[0]},"volume":{"type":"number","title":"Volume","default":0,"examples":[0]},"length":{"type":"number","title":"Length","default":0,"examples":[0]},"width":{"type":"number","title":"Width","default":0,"examples":[0]},"height":{"type":"number","title":"Height","default":0,"examples":[0]}},"type":"object","title":"POLineUpdate","description":"A PO line item for a partial update — same keys as `lines[]` on submit."},"PickupAddress":{"properties":{"id":{"type":"string","title":"Id","description":"Your Ship-To / location code this address is registered under, when known (the same `id` you send on submit). Empty for addresses without a registered code.","default":"","examples":["TA32"]},"location_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Location Id","description":"Internal ID of the address record the order points to. Changes when the order is updated to a different address — use it to verify an address update took effect.","examples":[5231]},"location_name":{"type":"string","title":"Location Name","description":"Name the address is filed under (the site / depot / warehouse name). Defaults to `street1` when you don't send one.","default":"","examples":["Point Lisas Warehouse 14"]},"street1":{"type":"string","title":"Street1","description":"Street address, line 1.","default":"","examples":["12000 Westheimer Road"]},"street2":{"type":"string","title":"Street2","description":"Street address, line 2 (suite/warehouse/dock).","default":"","examples":["Warehouse B, Dock 7"]},"city":{"type":"string","title":"City","description":"City.","default":"","examples":["Houston"]},"state":{"type":"string","title":"State","description":"State / province.","default":"","examples":["Texas"]},"zip":{"type":"string","title":"Zip","description":"Postal / ZIP code.","default":"","examples":["77077"]},"country":{"type":"string","title":"Country","description":"ISO 3166-1 alpha-2 country code.","default":"","examples":["US"]},"region":{"type":"string","title":"Region","description":"ISO 3166-2 subdivision code within the country — the bare code, since `country` already carries the country. Empty when the address has no region on record.","default":"","examples":["TX"]},"supplier_id":{"type":"string","title":"Supplier Id","description":"Supplier ID of the supplier this pick-up address belongs to — the address's own supplier link when set, otherwise the order's supplier.","default":"","examples":["200000004"]}},"type":"object","title":"PickupAddress","description":"A pick-up address — additionally carries the supplier it belongs to."},"PickupAddressUpdate":{"properties":{"id":{"type":"string","title":"Id","description":"Your Ship-To / location code (e.g. `TA32`). A known code alone resolves the registered address; a code sent **with** an address registers/updates it.","default":"","examples":["TA32"]},"location_name":{"type":"string","title":"Location Name","description":"Name to file the address under (site / depot / warehouse). Defaults to `street1` when omitted. Sent **with an address**, a different name registers a new address and points this order at it — stored addresses are shared between orders, so they are never renamed in place. Sent with a known `id` and no address it is ignored, so a GET response can be echoed back safely.","default":"","examples":["Point Lisas Warehouse 14"]},"street1":{"type":"string","title":"Street1","default":"","examples":["Point Lisas Industrial Estate"]},"street2":{"type":"string","title":"Street2","default":"","examples":["Warehouse 14"]},"city":{"type":"string","title":"City","default":"","examples":["Couva"]},"state":{"type":"string","title":"State","default":"","examples":[""]},"zip":{"type":"string","title":"Zip","default":"","examples":[""]},"country":{"type":"string","title":"Country","description":"ISO 3166-1 alpha-2 country code. The full country name is still accepted.","default":"","examples":["TT"]},"region":{"type":"string","title":"Region","description":"ISO 3166-2 subdivision code within the country (`POS`). The full ISO form (`TT-POS`) and the region name are also accepted. Left unset when omitted — it is no longer derived from the country.","default":"","examples":["POS"]},"supplier_id":{"type":"string","title":"Supplier Id","description":"The supplier this pick-up address belongs to — always a string, even when numeric.","default":"","examples":["200000004"]}},"type":"object","title":"PickupAddressUpdate","description":"A pick-up address for a partial update — additionally accepts the supplier."},"PurchaseOrderResult":{"properties":{"reference":{"type":"string","title":"Reference","description":"Submission reference for this call (audit).","examples":["PO-000042"]},"customer_po_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Po Number","examples":["4500123456"]},"order_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Reference","description":"The created/updated order reference (ORD).","examples":["ORD00001"]},"action":{"type":"string","title":"Action","description":"`created` or `updated`.","examples":["created"]},"status":{"type":"string","title":"Status","default":"processed","examples":["processed"]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal mapping notes (e.g. a party that couldn't be matched)."}},"type":"object","required":["reference","action"],"title":"PurchaseOrderResult","description":"Result of creating or updating a purchase order.","examples":[{"action":"created","customer_po_number":"4500123456","order_reference":"ORD00001","reference":"PO-000042","status":"processed","warnings":[]}]},"PurchaseOrderUpdate":{"properties":{"customer_reference":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Customer Reference","description":"Your **Freight Order Number** — your own reference for this order.","examples":["FO-2026-00045"]},"freight_unit_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Freight Unit Number","description":"Your Freight Unit reference number — updatable on its own or together with `freight_order_type`.","examples":["FU-8100412345"]},"freight_unit_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Freight Unit Type","description":"The Freight Unit's own type code (e.g. `Z001`) — distinct from `freight_order_type` below.","examples":["Z001"]},"freight_order_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Freight Order Type","description":"Your Freight Order type code — `ZFO5` for EPCM and return orders, blank otherwise. Updatable on its own or together with `freight_unit_number`.","examples":["ZFO5"]},"source_location_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Source Location Id","description":"Your location ID of the source (pick-up) location — stored with the Freight Unit details.","examples":["1000123"]},"destination_location_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Destination Location Id","description":"Your location ID of the destination (delivery) location — stored with the Freight Unit details.","examples":["1005678"]},"delivery_address":{"anyOf":[{"$ref":"#/components/schemas/AddressUpdate"},{"type":"null"}],"description":"New delivery address. Send a Ship-To `id` alone to switch to a registered location, or an address (with or without `id`) to set it explicitly."},"pickup_address":{"anyOf":[{"$ref":"#/components/schemas/PickupAddressUpdate"},{"type":"null"}],"description":"New pick-up address (may carry `supplier_id`)."},"special_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Special Instructions","examples":["Delivery At Place"]},"order_details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Details","description":"Free-text order notes."},"cargo_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cargo Description","examples":["Industrial valves"]},"cargo_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cargo Value","examples":[45000.0]},"hazardous":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Hazardous","examples":[false]},"incoterms":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incoterms","description":"Standard code, e.g. FOB, CIF.","examples":["FOB"]},"incoterms_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incoterms Location","description":"Named place for the incoterm.","examples":["Point Lisas, Trinidad"]},"company_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Code","examples":["TT01"]},"mode_of_transport":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode Of Transport","description":"Stored as `air_freight` (Air), `ocean_freight` (Ocean), `road` (Road), `mode_of_transport_not_set` (International Mode Of Transport Not Set). The shorthands `AIR`, `OCEAN`, `SEA`, `ROAD` and `TRUCK` are accepted on submit and normalised.","examples":["OCEAN"]},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction","description":"IMPORT or EXPORT.","examples":["import"]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","examples":["USD"]},"total_pieces":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Pieces","examples":[8.0]},"total_weight":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Weight","examples":[2450.0]},"total_volume":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Volume","examples":[12.5]},"dates":{"anyOf":[{"$ref":"#/components/schemas/OrderDatesUpdate"},{"type":"null"}]},"po_details":{"anyOf":[{"items":{"$ref":"#/components/schemas/POLineUpdate"},"type":"array"},{"type":"null"}],"title":"Po Details","description":"**Replaces** the order's line items (PO Details and cargo lines) with exactly what you send — same shape as `po_details[]` on submit. `lines` is accepted as a legacy alias."}},"type":"object","title":"PurchaseOrderUpdate","description":"Partial update — send **only** the field(s) you want to change; everything\nelse on the order is left untouched. To change the full order data (line\nitems, parties …), re-submit the purchase order via POST (the same customer\nPO number updates in place).","examples":[{"delivery_address":{"city":"Couva","country":"TT","id":"TA33","location_name":"Point Lisas Warehouse 20","region":"CTT","street1":"Point Lisas Industrial Estate","street2":"Warehouse 20"}},{"customer_reference":"FO-2026-00045"},{"cargo_value":45000.0,"special_instructions":"Deliver to gate 3"}]},"PurchaseOrderUpdateResult":{"properties":{"updated":{"type":"boolean","title":"Updated","default":true,"examples":[true]},"order_reference":{"type":"string","title":"Order Reference","description":"Our order reference (ORD number).","examples":["ORD00001"]},"customer_po_number":{"type":"string","title":"Customer Po Number","description":"Customer PO number on the order.","default":"","examples":["4500123456"]},"updated_fields":{"items":{"type":"string"},"type":"array","title":"Updated Fields","description":"Which fields this request changed.","examples":[["delivery_address"]]},"customer_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Reference","description":"The Freight Order Number now stored on the order (present when it was part of the update).","examples":["FO-2026-00045"]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal notes (e.g. address fields that could not be matched)."}},"type":"object","required":["order_reference"],"title":"PurchaseOrderUpdateResult","description":"Result of a partial update.","examples":[{"customer_po_number":"4500123456","order_reference":"ORD00001","updated":true,"updated_fields":["delivery_address"],"warnings":[]}]},"RetryResult":{"properties":{"requeued":{"type":"boolean","title":"Requeued","default":true},"message_id":{"type":"string","title":"Message Id"},"status":{"type":"string","title":"Status","examples":["queued"]}},"type":"object","required":["message_id","status"],"title":"RetryResult"},"SupplierInfo":{"properties":{"id":{"type":"string","title":"Id","description":"Your supplier ID (the partner's Internal Reference).","default":"","examples":["200000004"]},"name":{"type":"string","title":"Name","default":"","examples":["Gulf Coast Industrial Supplies Inc."]},"email":{"type":"string","title":"Email","default":"","examples":["orders@gulfcoastindustrial.com"]},"phone":{"type":"string","title":"Phone","default":"","examples":["+1 780 555 0142"]},"street1":{"type":"string","title":"Street1","default":"","examples":["9915 108 Street NW"]},"street2":{"type":"string","title":"Street2","default":"","examples":["6th Floor South Petroleum Plaza"]},"city":{"type":"string","title":"City","default":"","examples":["Edmonton"]},"state":{"type":"string","title":"State","default":"","examples":["Alberta"]},"zip":{"type":"string","title":"Zip","default":"","examples":["T5K 2G8"]},"country":{"type":"string","title":"Country","description":"ISO 3166-1 alpha-2 country code.","default":"","examples":["CA"]}},"type":"object","title":"SupplierInfo","description":"The supplier (shipper) on the order, with their stored details."},"TokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"JWT bearer token. Send it as `Authorization: Bearer <token>`.","examples":["eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyYW1wc18uLi4ifQ.sig"]},"token_type":{"type":"string","title":"Token Type","default":"Bearer","examples":["Bearer"]},"expires_in":{"type":"integer","title":"Expires In","description":"Token lifetime in seconds.","examples":[1800]},"scope":{"type":"string","title":"Scope","description":"Space-separated scopes actually granted to this token.","examples":["orders:read orders:write shipments:read"]}},"type":"object","required":["access_token","expires_in","scope"],"title":"TokenResponse","description":"A successfully issued OAuth2 access token.","examples":[{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","expires_in":1800,"scope":"orders:read orders:write shipments:read shipments:write","token_type":"Bearer"}]},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"orders:read":"Read and list purchase orders","orders:write":"Create and update purchase orders"},"tokenUrl":"/api/v1/oauth/token"}}}}},"tags":[{"name":"Authentication","description":"Obtain an OAuth2 access token (start here)."},{"name":"Purchase Orders","description":"Create, read, and update purchase orders (a purchase order is an order in our system — one resource)."},{"name":"meta","description":"Health and connectivity checks."}]}