# List orders `GET /client_api/v2/orders` Your company's orders, newest first, ten to a page unless you ask for more. Every filter is optional, and they combine. ## Parameters - `q` (string): Only orders whose waybill, reference number, customer reference or invoice number contains this text, or that were placed by a login whose email contains it, in any case. - `status` (string): Only orders with a shipment in this status, such as `in_transit`. List order statuses has every value. - `created_at_date_range_from` (string): The first day of a date range, as `YYYY-MM-DD`. With `created_at_date_range_to`, only orders created from this day to that one, both days included. Send both or neither. - `created_at_date_range_to` (string): The last day of the range, as `YYYY-MM-DD`. Send it with `created_at_date_range_from`. - `page` (integer): Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. - `items_per_page` (integer): How many orders a page holds. 10 if you leave it out. ## Returns Returns a list of orders. - `orders` (array of objects, required): The orders on this page, newest first. - `id` (integer, required): The order's id, for every call about the order. - `assigned_admin` (object, nullable, required): The email address of the person on our team looking after the order. Empty until one is assigned. - `battery_declaration_link` (string, required): A link to download the battery declaration. Empty until there is one. - `broker_address` (object, nullable, required): The customs broker clearing the goods, when one is appointed. Empty otherwise. - `ccd_status` (enum, required): Where we stand on the destination's customs clearance document (CCD), for orders where we get one. Possible enum values: `ccd_not_required`, `ccd_required`, `voucher_of_correction_requested`, `voucher_of_correction_received`, `ccd_acquired`. - `commercial_invoice_link` (string, required): A link to download the commercial invoice. Empty until there is one. - `created_at` (string, required): When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. - `customer_reference` (string, required): Your own reference for the order. - `customs_clearance_document_link` (string, required): A link to download the customs clearance document. Empty until there is one. - `date_delivered` (object, nullable, required): When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. - `description_of_contents` (string, required): What is in the shipment. - `destination_address` (object, required): Where the goods are delivered. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (object, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (object, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `draft_bill_of_lading_link` (string, required): A link to download the draft bill of lading. Empty until there is one. - `eei_eligible` (boolean, required): `true` when the shipment needs an Electronic Export Information filing with US customs. - `eei_request_document_link` (string, required): A link to download the export filing request. Empty until there is one. - `export_permit_link` (string, required): A link to download the export permit. Empty until there is one. - `final_bill_of_lading_link` (string, required): A link to download the final bill of lading. Empty until there is one. - `importer_of_record_address` (object, nullable, required): The importer of record, when the shipment has one. Empty otherwise. - `internal_transaction_number` (object, nullable, required): The US customs reference (ITN) for the export filing. Empty unless one was filed. - `invoice_data` (object, required): The booked estimate, with its weights and charges. Empty until an estimate is booked. - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units. - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `kg`. - `distance_unit` (string, required): Always `cm`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet. - `packages` (integer, required): How many packages there are. - `mass_unit` (string, required): Always `lb`. - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`. - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size. - `weight` (number, required): What the packages weigh together. - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. - `volume` (number, required): The packages' volume together. - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`. - `line_items` (array of objects, required): What the price is made of, one charge per line. - `cost` (number, required): What the charge costs, in `currency_id`. - `currency_id` (string, required): The currency the company is billed in. - `description` (string, required): The charge, such as freight or fuel surcharge. - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote. - `shipping_company` (string, required): The carrier. - `shipping_service` (string, required): The carrier's service, such as International Priority. - `invoice_number` (object, nullable, required): Our invoice number for the order. Empty until we invoice it. - `materials_safety_data_sheet_link` (string, required): A link to download the materials safety data sheet. Empty until there is one. - `measured_weight` (number, required): What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. - `origin_address` (object, required): Where the carrier collects the goods. - `id` (integer, required): The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. - `address_1` (string, required): The street address. At most 34 characters. - `address_2` (string, required): A second address line, such as a floor or unit. At most 34 characters. - `address_3` (object, nullable, required): A third address line. - `city` (string, required): The city or town. At most 20 characters. - `classification` (enum, required): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`. - `company` (string, required): The company at the address. At most 35 characters. - `country` (object, required): The country, in full. - `id` (integer, required): The country's id, for an address's `country_id`. - `default_postal_code` (object, nullable, required): The postal code we give the carrier for an address in this country that has none. - `dhl_export_code` (object, nullable, required): DHL's export code for the country. Usually empty. - `dhl_import_code` (object, nullable, required): DHL's import code for the country. Usually empty. - `dhl_tax_code` (object, nullable, required): DHL's tax code for the country. Usually empty. - `export_code_label` (string, required): What the country calls an exporter number. - `import_code_label` (string, required): What the country calls an importer number. - `iso_code_2` (string, required): The two-letter ISO code, such as `GB`. - `iso_code_3` (string, required): The three-letter ISO code, such as `GBR`. - `name` (string, required): The country's name in English. - `postal_code_required` (boolean, required): `false` for the countries that have no postal codes. - `tax_number_label` (string, required): What the country calls a tax number. - `vat_rate` (number, required): The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. - `country_id` (integer, required): The country. Take the id from List countries. - `email` (string, required): An email address for the person at the address. Carriers use it for delivery notices. - `import_code` (object, nullable, required): The importer number of the party at the address. The country's `import_code_label` says what it is called there. - `latitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `longitude` (object, nullable, required): Where the address is, filled in by us shortly after the address is saved. Empty until then. - `name` (string, required): The person to ask for. At most 35 characters. - `phone` (string, required): A phone number for the person at the address. At most 15 characters. - `postal_code` (string, required): The postal code. Some countries, such as Ireland, refuse an address without one. - `province` (string, required): The province, state or county. - `summary` (string, required): The country's name. - `tax_number` (object, nullable, required): The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. - `time_zone_id` (object, nullable, required): The address's time zone, filled in by us shortly after the address is saved. Empty until then. - `packaging_list_link` (string, required): A link to download the packing list you uploaded. Empty until there is one. - `pickup_date` (object, nullable, required): The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. - `pickup_instructions` (string, required): What the driver was told when the pickup was booked. Empty when none is booked. - `proof_of_delivery_link` (string, required): A link to download the proof of delivery. Empty until there is one. - `purpose_of_shipment_id` (integer, required): The incoterm the goods move under. - `quote_id` (integer, required): The quote the order was booked from. - `reference_number` (string, required): Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. - `scheduled_pickup` (string, required): The pickup booked for the order. An empty string, not an empty object, when none is booked. - `send_consignee_tracking_details` (boolean, required): `true` when the receiver is sent the tracking details. - `shipments` (array of objects, required): Each leg of the shipment, in route order. Most orders have one. - `shipping_service` (string, required): The carrier's service for this leg. - `status` (enum, required): Where this leg is. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `tracking_link` (object, nullable, required): The carrier's tracking page for this leg. Empty until there is a waybill. - `waybill` (object, nullable, required): The carrier's waybill number for this leg. Empty until there is one. - `waybill_document_link` (string, required): A link to download this leg's waybill. Empty until there is one. - `shippers_letter_of_instruction_link` (string, required): A link to download the shipper's letter of instruction. Empty until there is one. - `status` (enum, required): Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. Possible enum values: `incomplete`, `order_received`, `awaiting_additional_documentation`, `awaiting_prepayment`, `awaiting_waybill_generation`, `awaiting_schedule_pickup`, `awaiting_pickup`, `awaiting_swap_out`, `pickup_missed`, `in_transit`, `partially_delivered`, `delivered`, `invoice_to_be_paid`, `invoice_paid`, `cancelled`, `lost_in_transit`, `awaiting_consolidation`, `consolidated`. - `stream_packing_list_link` (string, required): A link to download the packing list we made. Empty until there is one. - `tracking_link` (object, nullable, required): The carrier's tracking page for the shipment. Empty until there is a waybill. - `value_of_goods` (number, required): What the goods are worth in total. - `value_of_goods_currency` (string, required): The currency of `value_of_goods`, as a three-letter code. - `waybill` (object, nullable, required): The carrier's waybill number. Empty until Create a waybill has run. - `waybill_document_link` (string, required): A link to download the waybill. Empty until there is one. - `meta` (object, required): How many pages and records the list has. - `page_count` (integer, required): How many pages the list has. Ask for another with `?page=`. - `record_count` (integer, required): How many records the list has across all pages. ## Errors - `401 Unauthorized`: The token is missing, expired or invalid. Sign in again. ## Example request (curl) ```bash curl -X GET "https://sandbox-api.vatit-stream.com/client_api/v2/orders?q=GTC-PO-20417&status=order_received&created_at_date_range_from=2026-10-23&created_at_date_range_to=2026-10-23&page=1&items_per_page=10" \ -H "Authorization: Bearer $API_TOKEN" ``` ## Example response (200) ```json { "orders": [ { "id": 22, "assigned_admin": null, "battery_declaration_link": "", "broker_address": null, "ccd_status": "ccd_not_required", "commercial_invoice_link": "", "created_at": "2026/10/23 07:14:46 UTC", "customer_reference": "GTC-PO-20417", "customs_clearance_document_link": "", "date_delivered": null, "description_of_contents": "Cotton shirts and denim trousers", "destination_address": { "id": 104, "address_1": "221 Shoreditch High Street", "address_2": "Floor 2", "address_3": null, "city": "London", "classification": "business", "company": "Bennett & Hale Ltd", "country": { "id": 18, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "GB", "iso_code_3": "GBR", "name": "United Kingdom", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 18, "email": "goods-in@bennetthale.example", "import_code": null, "latitude": null, "longitude": null, "name": "Oliver Bennett", "phone": "+442079460321", "postal_code": "E1 6PJ", "province": "Greater London", "summary": "United Kingdom", "tax_number": null, "time_zone_id": null }, "draft_bill_of_lading_link": "", "eei_eligible": false, "eei_request_document_link": "", "export_permit_link": "", "final_bill_of_lading_link": "", "importer_of_record_address": null, "internal_transaction_number": null, "invoice_data": { "billable_weights": { "metric": { "packages": 1, "mass_unit": "kg", "distance_unit": "cm", "volumetric_weight": 16.8, "weight": 12.5, "billable_weight": 16.8, "volume": 0.084 }, "imperial": { "packages": 1, "mass_unit": "lb", "distance_unit": "inches", "volumetric_weight": 37.04, "weight": 27.56, "billable_weight": 37.04, "volume": 2.9664316254643865 } }, "estimate_id": 17, "line_items": [ { "cost": 2184.5, "currency_id": "ZAR", "description": "Freight" }, { "cost": 393.21, "currency_id": "ZAR", "description": "Fuel surcharge" }, { "cost": 450, "currency_id": "ZAR", "description": "Customs clearance" } ], "quote_expired": false, "shipping_company": "FedEx South Africa", "shipping_service": "International Priority" }, "invoice_number": null, "materials_safety_data_sheet_link": "", "measured_weight": 0, "origin_address": { "id": 103, "address_1": "14 Bree Street", "address_2": "Unit 3", "address_3": null, "city": "Cape Town", "classification": "business", "company": "Global Trade Corp", "country": { "id": 17, "default_postal_code": null, "dhl_export_code": null, "dhl_import_code": null, "dhl_tax_code": null, "export_code_label": "Export Number", "import_code_label": "Importer Code", "iso_code_2": "ZA", "iso_code_3": "ZAF", "name": "South Africa", "postal_code_required": true, "tax_number_label": "Tax Number", "vat_rate": 0.17 }, "country_id": 17, "email": "dispatch@globaltradecorp.example", "import_code": null, "latitude": null, "longitude": null, "name": "Thandi Mokoena", "phone": "+27215550142", "postal_code": "8001", "province": "Western Cape", "summary": "South Africa", "tax_number": null, "time_zone_id": null }, "packaging_list_link": "", "pickup_date": null, "pickup_instructions": "", "proof_of_delivery_link": "", "purpose_of_shipment_id": 50, "quote_id": 22, "reference_number": "MYSGLO001000001", "scheduled_pickup": "", "send_consignee_tracking_details": false, "shipments": [ { "shipping_service": "International Priority", "status": "order_received", "tracking_link": null, "waybill": null, "waybill_document_link": "" } ], "shippers_letter_of_instruction_link": "", "status": "order_received", "stream_packing_list_link": "", "tracking_link": null, "value_of_goods": 18500, "value_of_goods_currency": "ZAR", "waybill": null, "waybill_document_link": "" } ], "meta": { "page_count": 1, "record_count": 1 } } ```