--- openapi: 3.0.3 info: title: Stream API version: '2' description: | Our client API lets your own system quote, book and track shipments with us. Sign in to get a token, then send it as a bearer token on every other call. A missing, expired or invalid token answers 401. Try calls against the sandbox first: its carriers are stand-ins, so nothing is really shipped. **Dates.** All times are UTC. Most dates come as `YYYY/MM/DD HH:MM:SS UTC`, for example `2026/10/23 07:14:46 UTC`. A pickup's `scheduled_date` always shows midnight, so read only its date. `pickup_date` is a plain `YYYY-MM-DD` date, and webhook payloads use ISO 8601 (`2026-10-23T07:14:46Z`). servers: - url: https://sandbox-api.vatit-stream.com description: Sandbox - url: https://orders-production.vatit-stream.com description: Production paths: "/client_api/v2/auth/sign_in": post: summary: Sign in tags: - Authentication security: [] requestBody: content: application/json: schema: type: object properties: api_user: type: object properties: email: type: string description: The login's email address. password: type: string description: The login's password. required: - email - password description: The login to sign in with. required: - api_user example: api_user: email: integrations@globaltradecorp.example password: your-password responses: '200': description: answers a token to send as a bearer token on every other call content: application/json: schema: type: object properties: token: type: string description: 'The token to send as `Authorization: Bearer ` on every other call. It lasts a week.' required: - token example: token: eyJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImludGVncmF0aW9uc0BnbG9iYWx0cmFkZWNvcnAuZXhhbXBsZSIsInN1YiI6IjkiLCJzY3AiOiJhcGlfdXNlciIsImF1ZCI6bnVsbCwiaWF0IjoxNzkyNzM5Njg2LCJleHAiOiIxNzkzMzQ0NDg2IiwianRpIjoiM2YxYzJhOWUtNmI0ZC00ZThhLTljNzEtMGQ1ZThiMmY0YTE2In0.tQ3m0Yk9v1S7bT2n5Zq8Lw4HcXr6JdPaUeVgNiOfMhA '401': description: answers 401 for a wrong password content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: Invalid email or password errors: [] description: Swap a login's email and password for a token. Send the token as a bearer token on every other call. It lasts a week. "/client_api/v2/companies": get: summary: List companies tags: - Companies parameters: - name: q in: query required: false schema: type: string example: Karoo description: Only companies whose name contains this text, best match first. - name: account_status in: query required: false schema: type: string example: active description: Only companies in this account status, `active`, `suspended` or `dormant`. - name: page in: query required: false schema: type: integer example: 1 description: Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. responses: '200': description: lists the companies the customer can see content: application/json: schema: type: object properties: companies: type: array items: type: object properties: id: type: integer description: The company's id. account_number: type: string description: The company's account number. Order reference numbers start with it. account_status: type: string description: Whether the company can ship. A suspended or dormant company gets no waybills. enum: - active - suspended - dormant address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: nullable: true description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: The company's address. api_users: type: array items: type: object properties: id: type: integer description: The login's id. email: type: string description: The login's email address. identity: type: string description: The login's name, or its email address when it has no name. required: - id - email - identity description: The company's logins. code: type: string description: The company's code with us, the same as its account number. company_billing: type: boolean description: "`true` when we invoice the company directly, `false` when we invoice you as its reseller." currency_id: type: string description: The currency the company is billed in. name: type: string description: The company's name. required: - id - account_number - account_status - address - api_users - code - company_billing - currency_id - name description: The companies on this page. meta: type: object properties: page_count: type: integer description: How many pages the list has. Ask for another with `?page=`. record_count: type: integer description: How many records the list has across all pages. required: - page_count - record_count description: How many pages and records the list has. required: - companies - meta example: companies: - id: 10 account_number: MYSKAR001 account_status: active address: id: 160 address_1: 8 Church Street address_2: address_3: city: Prince Albert classification: business company: Karoo Leather Works country_id: 20 email: pieter@karooleather.example import_code: latitude: longitude: name: Pieter van Wyk phone: "+27235550198" postal_code: '6930' province: Western Cape summary: South Africa tax_number: time_zone_id: api_users: - id: 14 email: admin@karooleather.example identity: admin@karooleather.example code: MYSKAR001 company_billing: true currency_id: ZAR name: Karoo Leather Works meta: page_count: 1 record_count: 1 '401': "$ref": "#/components/responses/Unauthorized" description: For resellers. The client companies you can see. post: summary: Create a company tags: - Companies requestBody: content: application/json: schema: type: object properties: name: type: string description: The company's name. It has to be unique across our accounts. email: type: string description: The email for the company's own API and portal login. Left out, no login is made. password: type: string description: The password for that login. Left out, we make one up. contact_name: type: string description: The person we talk to at the company. contact_email: type: string description: That person's email address. contact_number: type: string description: That person's phone number. currency_id: type: string description: The currency the company is billed in, as a three-letter code from List currencies. industry: type: string description: What the company does. enum: - aerospace_defense - airlines_aviation - apparel_fashion - arts_crafts - automotive - aviation_aerospace - broadcast_media - chemicals - civil_engineering - computer_hardware - computer_software - construction - consumer_electronics - consumer_goods - defense_space - electrical_electronic_manufacturing - entertainment - events_services - fine_art - food_beverages - furniture - health_wellness_fitness - healthcare_services - hospital_health_care - industrial_automation - information_technology_and_services - investment_management - leisure_travel_tourism - logistics_supply_chain - luxury_goods_jewelry - machinery - manufacturing - mechanical_or_industrial_engineering - medical_devices - oil_energy - package_freight_delivery - paper_forest_products - pharmaceuticals - photography - printing - professional_training_coaching - publishing - retail - sporting_goods - telecommunications - textiles - transportation_trucking_railroad - utilities - wireless - other markup_multiplier: type: number format: float description: What the company pays as a multiple of our price to you. `1.5` adds 50%. validate_address: type: boolean description: "`true` to have the carrier check the address before the company is created. The call answers 422 when it finds a problem." account_enquiry_contact_name: type: string description: The person we send account questions to, such as about invoices. account_enquiry_contact_email: type: string description: That person's email address. account_enquiry_contact_phone: type: string description: That person's phone number. account_enquiry_contact_additional_emails: type: array items: type: string description: More email addresses to copy on account questions. address_attributes: type: object properties: name: type: string description: The person to ask for. At most 35 characters. company: type: string description: The company at the address. At most 35 characters. address_1: type: string description: The street address. At most 34 characters. city: type: string description: The city or town. At most 20 characters. province: type: string description: The province, state or county. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. phone: type: string description: A phone number for the person at the address. At most 15 characters. required: - country_id description: The company's address. Its country decides which bank details the company's invoices show. required: - name - currency_id - address_attributes example: name: Karoo Leather Works email: admin@karooleather.example password: choose-a-password contact_name: Pieter van Wyk contact_email: pieter@karooleather.example contact_number: "+27 23 555 0198" currency_id: ZAR industry: consumer_goods markup_multiplier: 1.5 validate_address: false account_enquiry_contact_name: Annelie Botha account_enquiry_contact_email: accounts@karooleather.example account_enquiry_contact_phone: "+27 23 555 0199" account_enquiry_contact_additional_emails: - finance@karooleather.example address_attributes: name: Pieter van Wyk company: Karoo Leather Works address_1: 8 Church Street city: Prince Albert province: Western Cape postal_code: '6930' country_id: 20 email: pieter@karooleather.example phone: "+27 23 555 0198" responses: '201': description: onboards a client company and answers 201 with it content: application/json: schema: type: object properties: company: type: object properties: id: type: integer description: The company's id. account_number: type: string description: The company's account number. Order reference numbers start with it. account_status: type: string description: Whether the company can ship. A suspended or dormant company gets no waybills. enum: - active - suspended - dormant address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: nullable: true description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: The company's address. api_users: type: array items: type: object properties: id: type: integer description: The login's id. email: type: string description: The login's email address. identity: type: string description: The login's name, or its email address when it has no name. required: - id - email - identity description: The company's logins. code: type: string description: The company's code with us, the same as its account number. company_billing: type: boolean description: "`true` when we invoice the company directly, `false` when we invoice you as its reseller." currency_id: type: string description: The currency the company is billed in. name: type: string description: The company's name. required: - id - account_number - account_status - address - api_users - code - company_billing - currency_id - name description: The company. required: - company example: company: id: 11 account_number: MYSKAR001 account_status: active address: id: 161 address_1: 8 Church Street address_2: address_3: city: Prince Albert classification: business company: Karoo Leather Works country_id: 20 email: pieter@karooleather.example import_code: latitude: longitude: name: Pieter van Wyk phone: "+27235550198" postal_code: '6930' province: Western Cape summary: South Africa tax_number: time_zone_id: api_users: - id: 15 email: admin@karooleather.example identity: admin@karooleather.example code: MYSKAR001 company_billing: true currency_id: ZAR name: Karoo Leather Works '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" description: For resellers. Sets up a client company under your reseller account, and a login for it when you send an email. "/client_api/v2/countries": get: summary: List countries tags: - Reference data security: [] parameters: - name: q in: query required: false schema: type: string example: United description: Only countries whose name contains this text, in any case. - name: page in: query required: false schema: type: integer example: 1 description: Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. - name: show_all in: query required: false schema: type: boolean example: false description: Send `true` to get every country on one page. responses: '200': description: lists countries, filtered by name content: application/json: schema: type: object properties: countries: type: array items: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. maximum_duty_rate: type: number format: float description: The highest customs duty rate the country charges, as a fraction. name: type: string description: The country's name in English. part_of_eu_union: type: boolean description: "`true` for a member of the European Union." postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." signed_civil_aircraft_agreement: type: boolean description: "`true` for a signatory of the WTO Agreement on Trade in Civil Aircraft, an EU member included. Civil aircraft parts cross between signatories duty free." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - maximum_duty_rate - name - part_of_eu_union - postal_code_required - signed_civil_aircraft_agreement - tax_number_label - vat_rate description: The countries on this page, by name. meta: type: object properties: page_count: type: integer description: How many pages the list has. Ask for another with `?page=`. record_count: type: integer description: How many records the list has across all pages. required: - page_count - record_count description: How many pages and records the list has. required: - countries - meta example: countries: - id: 16 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: export_code_label: Export Number import_code_label: Importer Code iso_code_2: GB iso_code_3: GBR maximum_duty_rate: 0.5 name: United Kingdom part_of_eu_union: false postal_code_required: true signed_civil_aircraft_agreement: true tax_number_label: Tax Number vat_rate: 0.17 meta: page_count: 1 record_count: 1 description: Every country, with its id for addresses and the labels its customs numbers go by. Needs no token. "/client_api/v2/currencies": get: summary: List currencies tags: - Reference data security: [] parameters: - name: show_all in: query required: false schema: type: boolean example: true description: Send `true` to get every currency on one page. - name: page in: query required: false schema: type: integer example: 1 description: Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. responses: '200': description: lists currencies content: application/json: schema: type: object properties: currencies: type: array items: type: object properties: id: type: string description: The currency's three-letter code, the same as `code`. code: type: string description: The currency's three-letter ISO code, such as `ZAR`. name: type: string description: The currency's name. required: - id - code - name description: The currencies on this page, by code. meta: type: object properties: page_count: type: integer description: How many pages the list has. Ask for another with `?page=`. record_count: type: integer description: How many records the list has across all pages. required: - page_count - record_count description: How many pages and records the list has. required: - currencies - meta example: currencies: - id: CAD code: CAD name: Canadian Dollar - id: EUR code: EUR name: Euro - id: GBP code: GBP name: Pound - id: USD code: USD name: Dollar - id: ZAR code: ZAR name: Rand meta: page_count: 1 record_count: 5 description: The currencies we price in. Needs no token. "/client_api/v2/line_item_types": get: summary: List line item types tags: - Reference data parameters: - name: show_archived in: query required: false schema: type: boolean example: false description: Send `true` to include the kinds we no longer use. Left out, only the ones in use. responses: '200': description: lists the line item types a cost can have content: application/json: schema: type: object properties: line_item_types: type: array items: type: object properties: id: type: integer description: The line item type's id. accounting_dimension: nullable: true description: The accounting group we book this charge under. Usually empty. description: type: string description: The kind of charge, such as freight. required: - id - accounting_dimension - description description: Every line item type. required: - line_item_types example: line_item_types: - id: 16 accounting_dimension: description: Freight '401': "$ref": "#/components/responses/Unauthorized" description: The kinds of charge an estimate's line items can be. "/client_api/v2/nature_of_transactions": get: summary: List natures of transaction tags: - Reference data parameters: - name: code in: query required: false schema: type: integer example: 11 description: Only the code given, such as `11`. responses: '200': description: lists the natures of transaction for a declared item content: application/json: schema: type: object properties: nature_of_transactions: type: array items: type: object properties: code: type: string description: The two-digit customs code for the kind of deal. enum: - '11' - '12' - '21' - '22' - '23' - '31' - '32' - '33' - '34' - '41' - '42' - '51' - '52' - '71' - '72' - '80' - '91' - '99' description: type: string description: What the code means. label: type: string description: The code and its meaning together, for showing in a list. required: - code - description - label description: Every nature of transaction. required: - nature_of_transactions example: nature_of_transactions: - code: '11' description: Outright sale/purchase except direct trade with/by private consumers label: 11 - Outright sale/purchase except direct trade with/by private consumers '401': "$ref": "#/components/responses/Unauthorized" description: The customs codes for the kind of deal behind a declared item, such as a sale or a return. "/client_api/v2/order_statuses": get: summary: List order statuses tags: - Reference data responses: '200': description: lists the order statuses content: application/json: schema: type: array items: type: object properties: id: type: string description: The status, as it appears on an order or shipment. enum: - 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 description: type: string description: The status in words. value: type: string description: The same as `id`. enum: - 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 required: - id - description - value example: - id: incomplete description: Incomplete value: incomplete - id: order_received description: Order received value: order_received - id: awaiting_additional_documentation description: Awaiting additional documentation value: awaiting_additional_documentation - id: awaiting_prepayment description: Awaiting prepayment value: awaiting_prepayment - id: awaiting_waybill_generation description: Awaiting waybill generation value: awaiting_waybill_generation - id: awaiting_schedule_pickup description: Awaiting schedule pickup value: awaiting_schedule_pickup - id: awaiting_pickup description: Awaiting pickup value: awaiting_pickup - id: awaiting_swap_out description: Awaiting swap out value: awaiting_swap_out - id: pickup_missed description: Pickup missed value: pickup_missed - id: in_transit description: In transit value: in_transit - id: partially_delivered description: Partially delivered value: partially_delivered - id: delivered description: Delivered value: delivered - id: invoice_to_be_paid description: Invoice to be paid value: invoice_to_be_paid - id: invoice_paid description: Invoice paid value: invoice_paid - id: cancelled description: Cancelled value: cancelled - id: lost_in_transit description: Lost in transit value: lost_in_transit - id: awaiting_consolidation description: Awaiting consolidation value: awaiting_consolidation - id: consolidated description: Consolidated value: consolidated '401': "$ref": "#/components/responses/Unauthorized" description: Every status an order or shipment can have. "/client_api/v2/orders": get: summary: List orders tags: - Orders parameters: - name: q in: query required: false schema: type: string example: GTC-PO-20417 description: 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. - name: status in: query required: false schema: type: string example: order_received description: Only orders with a shipment in this status, such as `in_transit`. List order statuses has every value. - name: created_at_date_range_from in: query required: false schema: type: string example: '2026-10-23' description: 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. - name: created_at_date_range_to in: query required: false schema: type: string example: '2026-10-23' description: The last day of the range, as `YYYY-MM-DD`. Send it with `created_at_date_range_from`. - name: page in: query required: false schema: type: integer example: 1 description: Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. - name: items_per_page in: query required: false schema: type: integer example: 10 description: How many orders a page holds. 10 if you leave it out. responses: '200': description: lists the customer's orders, filtered and a page at a time content: application/json: schema: type: object properties: orders: type: array items: type: object properties: id: type: integer description: The order's id, for every call about the order. assigned_admin: nullable: true description: The email address of the person on our team looking after the order. Empty until one is assigned. battery_declaration_link: type: string description: A link to download the battery declaration. Empty until there is one. broker_address: nullable: true description: The customs broker clearing the goods, when one is appointed. Empty otherwise. ccd_status: type: string description: Where we stand on the destination's customs clearance document (CCD), for orders where we get one. enum: - ccd_not_required - ccd_required - voucher_of_correction_requested - voucher_of_correction_received - ccd_acquired commercial_invoice_link: type: string description: A link to download the commercial invoice. Empty until there is one. created_at: type: string description: When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. customer_reference: type: string description: Your own reference for the order. customs_clearance_document_link: type: string description: A link to download the customs clearance document. Empty until there is one. date_delivered: nullable: true description: When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. description_of_contents: type: string description: What is in the shipment. destination_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the goods are delivered. draft_bill_of_lading_link: type: string description: A link to download the draft bill of lading. Empty until there is one. eei_eligible: type: boolean description: "`true` when the shipment needs an Electronic Export Information filing with US customs." eei_request_document_link: type: string description: A link to download the export filing request. Empty until there is one. export_permit_link: type: string description: A link to download the export permit. Empty until there is one. final_bill_of_lading_link: type: string description: A link to download the final bill of lading. Empty until there is one. importer_of_record_address: nullable: true description: The importer of record, when the shipment has one. Empty otherwise. internal_transaction_number: nullable: true description: The US customs reference (ITN) for the export filing. Empty unless one was filed. invoice_data: type: object properties: billable_weights: type: object properties: metric: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `kg`. distance_unit: type: string description: Always `cm`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in kilograms, the sizes in centimetres and the volume in cubic metres. imperial: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `lb`. distance_unit: type: string description: Always `inches`. A request spells the same unit `inch`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in pounds, the sizes in inches and the volume in cubic feet. required: - metric - imperial description: The weights the carrier charges on, in metric and in imperial units. estimate_id: type: integer description: The estimate's id. Book it by sending it as an order's `quote_estimate_id`. line_items: type: array items: type: object properties: cost: type: number format: float description: What the charge costs, in `currency_id`. currency_id: type: string description: The currency the company is billed in. description: type: string description: The charge, such as freight or fuel surcharge. required: - cost - currency_id - description description: What the price is made of, one charge per line. quote_expired: type: boolean description: "`true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote." shipping_company: type: string description: The carrier. shipping_service: type: string description: The carrier's service, such as International Priority. required: - billable_weights - estimate_id - line_items - quote_expired - shipping_company - shipping_service description: The booked estimate, with its weights and charges. Empty until an estimate is booked. invoice_number: nullable: true description: Our invoice number for the order. Empty until we invoice it. materials_safety_data_sheet_link: type: string description: A link to download the materials safety data sheet. Empty until there is one. measured_weight: type: number format: float description: What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. origin_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the carrier collects the goods. packaging_list_link: type: string description: A link to download the packing list you uploaded. Empty until there is one. pickup_date: nullable: true description: The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. pickup_instructions: type: string description: What the driver was told when the pickup was booked. Empty when none is booked. proof_of_delivery_link: type: string description: A link to download the proof of delivery. Empty until there is one. purpose_of_shipment_id: type: integer description: The incoterm the goods move under. quote_id: type: integer description: The quote the order was booked from. reference_number: type: string description: Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. scheduled_pickup: type: string description: The pickup booked for the order. An empty string, not an empty object, when none is booked. send_consignee_tracking_details: type: boolean description: "`true` when the receiver is sent the tracking details." shipments: type: array items: type: object properties: shipping_service: type: string description: The carrier's service for this leg. status: type: string description: Where this leg is. List order statuses has every value. enum: - 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: nullable: true description: The carrier's tracking page for this leg. Empty until there is a waybill. waybill: nullable: true description: The carrier's waybill number for this leg. Empty until there is one. waybill_document_link: type: string description: A link to download this leg's waybill. Empty until there is one. required: - shipping_service - status - tracking_link - waybill - waybill_document_link description: Each leg of the shipment, in route order. Most orders have one. shippers_letter_of_instruction_link: type: string description: A link to download the shipper's letter of instruction. Empty until there is one. status: type: string description: Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. enum: - 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: type: string description: A link to download the packing list we made. Empty until there is one. tracking_link: nullable: true description: The carrier's tracking page for the shipment. Empty until there is a waybill. value_of_goods: type: number format: float description: What the goods are worth in total. value_of_goods_currency: type: string description: The currency of `value_of_goods`, as a three-letter code. waybill: nullable: true description: The carrier's waybill number. Empty until Create a waybill has run. waybill_document_link: type: string description: A link to download the waybill. Empty until there is one. required: - id - assigned_admin - battery_declaration_link - broker_address - ccd_status - commercial_invoice_link - created_at - customer_reference - customs_clearance_document_link - date_delivered - description_of_contents - destination_address - draft_bill_of_lading_link - eei_eligible - eei_request_document_link - export_permit_link - final_bill_of_lading_link - importer_of_record_address - internal_transaction_number - invoice_data - invoice_number - materials_safety_data_sheet_link - measured_weight - origin_address - packaging_list_link - pickup_date - pickup_instructions - proof_of_delivery_link - purpose_of_shipment_id - quote_id - reference_number - scheduled_pickup - send_consignee_tracking_details - shipments - shippers_letter_of_instruction_link - status - stream_packing_list_link - tracking_link - value_of_goods - value_of_goods_currency - waybill - waybill_document_link description: The orders on this page, newest first. meta: type: object properties: page_count: type: integer description: How many pages the list has. Ask for another with `?page=`. record_count: type: integer description: How many records the list has across all pages. required: - page_count - record_count description: How many pages and records the list has. required: - orders - meta example: orders: - id: 25 assigned_admin: battery_declaration_link: '' broker_address: 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: description_of_contents: Cotton shirts and denim trousers destination_address: id: 122 address_1: 221 Shoreditch High Street address_2: Floor 2 address_3: city: London classification: business company: Bennett & Hale Ltd country: id: 18 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: 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: latitude: longitude: name: Oliver Bennett phone: "+442079460321" postal_code: E1 6PJ province: Greater London summary: United Kingdom tax_number: time_zone_id: draft_bill_of_lading_link: '' eei_eligible: false eei_request_document_link: '' export_permit_link: '' final_bill_of_lading_link: '' importer_of_record_address: internal_transaction_number: 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: 20 line_items: - cost: 2184.5 currency_id: ZAR description: Freight - cost: 393.21 currency_id: ZAR description: Fuel surcharge - cost: 450.0 currency_id: ZAR description: Customs clearance quote_expired: false shipping_company: FedEx South Africa shipping_service: International Priority invoice_number: materials_safety_data_sheet_link: '' measured_weight: 0.0 origin_address: id: 121 address_1: 14 Bree Street address_2: Unit 3 address_3: city: Cape Town classification: business company: Global Trade Corp country: id: 17 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: 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: latitude: longitude: name: Thandi Mokoena phone: "+27215550142" postal_code: '8001' province: Western Cape summary: South Africa tax_number: time_zone_id: packaging_list_link: '' pickup_date: pickup_instructions: '' proof_of_delivery_link: '' purpose_of_shipment_id: 50 quote_id: 25 reference_number: MYSGLO001000001 scheduled_pickup: '' send_consignee_tracking_details: false shipments: - shipping_service: International Priority status: order_received tracking_link: waybill: waybill_document_link: '' shippers_letter_of_instruction_link: '' status: order_received stream_packing_list_link: '' tracking_link: value_of_goods: 18500.0 value_of_goods_currency: ZAR waybill: waybill_document_link: '' meta: page_count: 1 record_count: 1 '401': "$ref": "#/components/responses/Unauthorized" description: Your company's orders, newest first, ten to a page unless you ask for more. Every filter is optional, and they combine. post: summary: Create an order tags: - Orders requestBody: content: application/json: schema: type: object properties: order: type: object properties: quote_estimate_id: type: integer description: The estimate to book, an `estimate_id` from the `estimates` that Create a quote answers with. purpose_of_shipment_id: type: integer description: The incoterm the goods move under. Take the id from List purposes of shipment. customer_reference: type: string description: Your own reference for the order, such as a purchase order number. We show it back on the order. description_of_contents: type: string description: What is in the shipment, in a few words a customs officer understands. Replaces the quote's description. At most 70 characters. origin_address: type: object properties: name: type: string description: The person to ask for. At most 35 characters. company: type: string description: The company at the address. At most 35 characters. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. city: type: string description: The city or town. At most 20 characters. province: type: string description: The province, state or county. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. phone: type: string description: A phone number for the person at the address. At most 15 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential required: - country_id description: The collection address in full. Wins over `origin_address_id` when both are sent. destination_address: type: object properties: name: type: string description: The person to ask for. At most 35 characters. company: type: string description: The company at the address. At most 35 characters. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. city: type: string description: The city or town. At most 20 characters. province: type: string description: The province, state or county. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. phone: type: string description: A phone number for the person at the address. At most 15 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential required: - country_id description: The delivery address in full. Wins over `destination_address_id` when both are sent. send_consignee_tracking_details: type: boolean description: "`true` to email the recipient at `destination_address` the tracking details once the shipment is in transit." importer_of_record_address: type: object properties: name: type: string description: The person to ask for. At most 35 characters. company: type: string description: The company at the address. At most 35 characters. address_1: type: string description: The street address. At most 34 characters. city: type: string description: The city or town. At most 20 characters. province: type: string description: The province, state or county. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. country_id: type: integer description: The country. Take the id from List countries. phone: type: string description: A phone number for the person at the address. At most 15 characters. tax_number: type: string description: The tax or VAT number of the party at the address. The country's `tax_number_label` says what it is called there. import_code: type: string description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. required: - country_id description: The party that imports the goods and answers to customs at the destination, when it is not the recipient. broker_address: type: object properties: name: type: string description: The person to ask for. At most 35 characters. company: type: string description: The company at the address. At most 35 characters. address_1: type: string description: The street address. At most 34 characters. city: type: string description: The city or town. At most 20 characters. province: type: string description: The province, state or county. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. country_id: type: integer description: The country. Take the id from List countries. phone: type: string description: A phone number for the person at the address. At most 15 characters. required: - country_id description: The customs broker that clears the goods at the destination, when you appoint your own. clearance_detail: type: object properties: invoice_number: type: string description: Your invoice number for the goods, printed on the commercial invoice. purchase_order_number: type: string description: The buyer's purchase order number, printed on the commercial invoice. commercial_invoice_placeholder_text: type: string description: Extra text printed on the commercial invoice, such as a declaration of origin. description: Details for the commercial invoice. hs_codes: type: array items: type: object properties: code: type: string description: The item's tariff code (HS code), at least six digits. country_id: type: integer description: The country the item was made in. Take the id from List countries. description: type: string description: What the item is, in plain words. At most 250 characters. quantity: type: integer description: How many of this item are in the shipment. item_value: type: integer description: What one item is worth, in `value_of_goods_currency_id`. item_mass: type: number format: float description: What one item weighs, in `mass_unit`. nature_of_transaction: type: string description: The two-digit customs code for the kind of deal, such as `11` for an outright sale. List natures of transaction has every code. eccn: type: string description: The item's export control classification number, such as `EAR99`, when it has one. sku: type: string description: Your stock code for the item. model_number: type: string description: The item's model number. barcode: type: string description: The item's barcode number. description: More items to declare, added to the quote's. Each kind of item, as customs sees it. origin_address_id: type: integer description: The id of an address we already hold, such as an earlier order's `origin_address.id` from Get an order, to collect from instead of sending `origin_address`. destination_address_id: type: integer description: The id of an address we already hold, such as an earlier order's `destination_address.id` from Get an order, to deliver to instead of sending `destination_address`. required: - quote_estimate_id - purpose_of_shipment_id description: The order to place. required: - order example: order: quote_estimate_id: 17 purpose_of_shipment_id: 50 customer_reference: GTC-PO-20417 description_of_contents: Cotton shirts and denim trousers origin_address: name: Thandi Mokoena company: Global Trade Corp address_1: 14 Bree Street address_2: Unit 3 city: Cape Town province: Western Cape postal_code: '8001' country_id: 17 email: dispatch@globaltradecorp.example phone: "+27 21 555 0142" classification: business destination_address: name: Oliver Bennett company: Bennett & Hale Ltd address_1: 221 Shoreditch High Street address_2: Floor 2 city: London province: Greater London postal_code: E1 6PJ country_id: 18 email: goods-in@bennetthale.example phone: "+44 20 7946 0321" classification: business responses: '201': description: places an order from a quote's estimate and answers 201 with the order content: application/json: schema: type: object properties: order: type: object properties: id: type: integer description: The order's id, for every call about the order. assigned_admin: nullable: true description: The email address of the person on our team looking after the order. Empty until one is assigned. battery_declaration_link: type: string description: A link to download the battery declaration. Empty until there is one. broker_address: nullable: true type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: nullable: true description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: nullable: true description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: The customs broker clearing the goods, when one is appointed. Empty otherwise. ccd_status: type: string description: Where we stand on the destination's customs clearance document (CCD), for orders where we get one. enum: - ccd_not_required - ccd_required - voucher_of_correction_requested - voucher_of_correction_received - ccd_acquired commercial_invoice_link: type: string description: A link to download the commercial invoice. Empty until there is one. created_at: type: string description: When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. customer_reference: type: string nullable: true description: Your own reference for the order. customs_clearance_document_link: type: string description: A link to download the customs clearance document. Empty until there is one. date_delivered: nullable: true description: When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. description_of_contents: type: string nullable: true description: What is in the shipment. destination_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true type: string description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true type: string description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the goods are delivered. draft_bill_of_lading_link: type: string description: A link to download the draft bill of lading. Empty until there is one. eei_eligible: type: boolean description: "`true` when the shipment needs an Electronic Export Information filing with US customs." eei_request_document_link: type: string description: A link to download the export filing request. Empty until there is one. export_permit_link: type: string description: A link to download the export permit. Empty until there is one. final_bill_of_lading_link: type: string description: A link to download the final bill of lading. Empty until there is one. importer_of_record_address: nullable: true type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: nullable: true description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: nullable: true description: An email address for the person at the address. Carriers use it for delivery notices. import_code: type: string description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: type: string description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: The importer of record, when the shipment has one. Empty otherwise. internal_transaction_number: nullable: true description: The US customs reference (ITN) for the export filing. Empty unless one was filed. invoice_data: type: object properties: billable_weights: type: object properties: metric: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `kg`. distance_unit: type: string description: Always `cm`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in kilograms, the sizes in centimetres and the volume in cubic metres. imperial: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `lb`. distance_unit: type: string description: Always `inches`. A request spells the same unit `inch`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in pounds, the sizes in inches and the volume in cubic feet. required: - metric - imperial description: The weights the carrier charges on, in metric and in imperial units. estimate_id: type: integer description: The estimate's id. Book it by sending it as an order's `quote_estimate_id`. line_items: type: array items: type: object properties: cost: type: number format: float description: What the charge costs, in `currency_id`. currency_id: type: string description: The currency the company is billed in. description: type: string description: The charge, such as freight or fuel surcharge. required: - cost - currency_id - description description: What the price is made of, one charge per line. quote_expired: type: boolean description: "`true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote." shipping_company: type: string description: The carrier. shipping_service: type: string description: The carrier's service, such as International Priority. required: - billable_weights - estimate_id - line_items - quote_expired - shipping_company - shipping_service description: The booked estimate, with its weights and charges. Empty until an estimate is booked. invoice_number: nullable: true description: Our invoice number for the order. Empty until we invoice it. materials_safety_data_sheet_link: type: string description: A link to download the materials safety data sheet. Empty until there is one. measured_weight: type: number format: float description: What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. origin_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true type: string description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true type: string description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the carrier collects the goods. packaging_list_link: type: string description: A link to download the packing list you uploaded. Empty until there is one. pickup_date: nullable: true type: string description: The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. pickup_instructions: type: string description: What the driver was told when the pickup was booked. Empty when none is booked. proof_of_delivery_link: type: string description: A link to download the proof of delivery. Empty until there is one. purpose_of_shipment_id: type: integer description: The incoterm the goods move under. quote_id: type: integer description: The quote the order was booked from. reference_number: type: string description: Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. scheduled_pickup: type: string description: The pickup booked for the order. An empty string, not an empty object, when none is booked. send_consignee_tracking_details: type: boolean description: "`true` when the receiver is sent the tracking details." shipments: type: array items: type: object properties: shipping_service: type: string description: The carrier's service for this leg. status: type: string description: Where this leg is. List order statuses has every value. enum: - 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: nullable: true description: The carrier's tracking page for this leg. Empty until there is a waybill. waybill: nullable: true type: string description: The carrier's waybill number for this leg. Empty until there is one. waybill_document_link: type: string description: A link to download this leg's waybill. Empty until there is one. required: - shipping_service - status - tracking_link - waybill - waybill_document_link description: Each leg of the shipment, in route order. Most orders have one. shippers_letter_of_instruction_link: type: string description: A link to download the shipper's letter of instruction. Empty until there is one. status: type: string description: Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. enum: - 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: type: string description: A link to download the packing list we made. Empty until there is one. tracking_link: nullable: true description: The carrier's tracking page for the shipment. Empty until there is a waybill. value_of_goods: type: number format: float description: What the goods are worth in total. value_of_goods_currency: type: string description: The currency of `value_of_goods`, as a three-letter code. waybill: nullable: true type: string description: The carrier's waybill number. Empty until Create a waybill has run. waybill_document_link: type: string description: A link to download the waybill. Empty until there is one. required: - id - assigned_admin - battery_declaration_link - broker_address - ccd_status - commercial_invoice_link - created_at - customer_reference - customs_clearance_document_link - date_delivered - description_of_contents - destination_address - draft_bill_of_lading_link - eei_eligible - eei_request_document_link - export_permit_link - final_bill_of_lading_link - importer_of_record_address - internal_transaction_number - invoice_data - invoice_number - materials_safety_data_sheet_link - measured_weight - origin_address - packaging_list_link - pickup_date - pickup_instructions - proof_of_delivery_link - purpose_of_shipment_id - quote_id - reference_number - scheduled_pickup - send_consignee_tracking_details - shipments - shippers_letter_of_instruction_link - status - stream_packing_list_link - tracking_link - value_of_goods - value_of_goods_currency - waybill - waybill_document_link description: The order. required: - order example: order: id: 22 assigned_admin: battery_declaration_link: '' broker_address: 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: description_of_contents: Cotton shirts and denim trousers destination_address: id: 104 address_1: 221 Shoreditch High Street address_2: Floor 2 address_3: city: London classification: business company: Bennett & Hale Ltd country: id: 18 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: 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: latitude: longitude: name: Oliver Bennett phone: "+442079460321" postal_code: E1 6PJ province: Greater London summary: United Kingdom tax_number: time_zone_id: draft_bill_of_lading_link: '' eei_eligible: false eei_request_document_link: '' export_permit_link: '' final_bill_of_lading_link: '' importer_of_record_address: internal_transaction_number: 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.0 currency_id: ZAR description: Customs clearance quote_expired: false shipping_company: FedEx South Africa shipping_service: International Priority invoice_number: materials_safety_data_sheet_link: '' measured_weight: 0.0 origin_address: id: 103 address_1: 14 Bree Street address_2: Unit 3 address_3: city: Cape Town classification: business company: Global Trade Corp country: id: 17 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: 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: latitude: longitude: name: Thandi Mokoena phone: "+27215550142" postal_code: '8001' province: Western Cape summary: South Africa tax_number: time_zone_id: packaging_list_link: '' pickup_date: 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: waybill: waybill_document_link: '' shippers_letter_of_instruction_link: '' status: order_received stream_packing_list_link: '' tracking_link: value_of_goods: 18500.0 value_of_goods_currency: ZAR waybill: waybill_document_link: '' '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: type: string description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: Couldn't find QuoteEstimate with 'id'=0 errors: - Couldn't find QuoteEstimate with 'id'=0 description: answers a refused order with the reason as a list description: Book one of a quote's estimates. The order starts as `order_received`; ask for its waybill next. "/client_api/v2/orders/{id}": delete: summary: Cancel an order tags: - Orders parameters: - name: id in: path required: true schema: type: integer example: 21 description: The order's id, from Create an order or List orders. responses: '200': description: cancels an order that has not gone live content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: true error: '' errors: [] '401': "$ref": "#/components/responses/Unauthorized" description: Cancels an order that has not gone live yet. Otherwise the call answers 422. get: summary: Get an order tags: - Orders parameters: - name: id in: path required: true schema: oneOf: - type: integer - type: string example: 0 description: The order's id, from Create an order or List orders. A reference number does not work here. responses: '200': content: application/json: schema: type: object properties: order: type: object properties: id: type: integer description: The order's id, for every call about the order. assigned_admin: nullable: true description: The email address of the person on our team looking after the order. Empty until one is assigned. battery_declaration_link: type: string description: A link to download the battery declaration. Empty until there is one. broker_address: nullable: true description: The customs broker clearing the goods, when one is appointed. Empty otherwise. ccd_status: type: string description: Where we stand on the destination's customs clearance document (CCD), for orders where we get one. enum: - ccd_not_required - ccd_required - voucher_of_correction_requested - voucher_of_correction_received - ccd_acquired commercial_invoice_link: type: string description: A link to download the commercial invoice. Empty until there is one. created_at: type: string description: When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. customer_reference: nullable: true type: string description: Your own reference for the order. customs_clearance_document_link: type: string description: A link to download the customs clearance document. Empty until there is one. date_delivered: nullable: true description: When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. description_of_contents: nullable: true type: string description: What is in the shipment. destination_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: type: string nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: type: string nullable: true description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the goods are delivered. draft_bill_of_lading_link: type: string description: A link to download the draft bill of lading. Empty until there is one. eei_eligible: type: boolean description: "`true` when the shipment needs an Electronic Export Information filing with US customs." eei_request_document_link: type: string description: A link to download the export filing request. Empty until there is one. export_permit_link: type: string description: A link to download the export permit. Empty until there is one. final_bill_of_lading_link: type: string description: A link to download the final bill of lading. Empty until there is one. importer_of_record_address: nullable: true description: The importer of record, when the shipment has one. Empty otherwise. internal_transaction_number: nullable: true description: The US customs reference (ITN) for the export filing. Empty unless one was filed. invoice_data: type: object properties: billable_weights: type: object properties: metric: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `kg`. distance_unit: type: string description: Always `cm`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in kilograms, the sizes in centimetres and the volume in cubic metres. imperial: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `lb`. distance_unit: type: string description: Always `inches`. A request spells the same unit `inch`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in pounds, the sizes in inches and the volume in cubic feet. required: - metric - imperial description: The weights the carrier charges on, in metric and in imperial units. estimate_id: type: integer description: The estimate's id. Book it by sending it as an order's `quote_estimate_id`. line_items: type: array items: type: object properties: cost: type: number format: float description: What the charge costs, in `currency_id`. currency_id: type: string description: The currency the company is billed in. description: type: string description: The charge, such as freight or fuel surcharge. required: - cost - currency_id - description description: What the price is made of, one charge per line. quote_expired: type: boolean description: "`true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote." shipping_company: type: string description: The carrier. shipping_service: type: string description: The carrier's service, such as International Priority. required: - billable_weights - estimate_id - line_items - quote_expired - shipping_company - shipping_service description: The booked estimate, with its weights and charges. Empty until an estimate is booked. invoice_number: nullable: true description: Our invoice number for the order. Empty until we invoice it. materials_safety_data_sheet_link: type: string description: A link to download the materials safety data sheet. Empty until there is one. measured_weight: type: number format: float description: What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. origin_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: type: string nullable: true description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: type: string nullable: true description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the carrier collects the goods. packaging_list_link: type: string description: A link to download the packing list you uploaded. Empty until there is one. pickup_date: type: string nullable: true description: The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. pickup_instructions: type: string description: What the driver was told when the pickup was booked. Empty when none is booked. proof_of_delivery_link: type: string description: A link to download the proof of delivery. Empty until there is one. purpose_of_shipment_id: type: integer description: The incoterm the goods move under. quote_id: type: integer description: The quote the order was booked from. reference_number: type: string description: Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. scheduled_pickup: type: string description: The pickup booked for the order. An empty string, not an empty object, when none is booked. send_consignee_tracking_details: type: boolean description: "`true` when the receiver is sent the tracking details." shipments: type: array items: type: object properties: shipping_service: type: string description: The carrier's service for this leg. status: type: string description: Where this leg is. List order statuses has every value. enum: - 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: nullable: true description: The carrier's tracking page for this leg. Empty until there is a waybill. waybill: type: string nullable: true description: The carrier's waybill number for this leg. Empty until there is one. waybill_document_link: type: string description: A link to download this leg's waybill. Empty until there is one. required: - shipping_service - status - tracking_link - waybill - waybill_document_link description: Each leg of the shipment, in route order. Most orders have one. shippers_letter_of_instruction_link: type: string description: A link to download the shipper's letter of instruction. Empty until there is one. status: type: string description: Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. enum: - 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: type: string description: A link to download the packing list we made. Empty until there is one. tracking_link: nullable: true description: The carrier's tracking page for the shipment. Empty until there is a waybill. value_of_goods: type: number format: float description: What the goods are worth in total. value_of_goods_currency: type: string description: The currency of `value_of_goods`, as a three-letter code. waybill: type: string nullable: true description: The carrier's waybill number. Empty until Create a waybill has run. waybill_document_link: type: string description: A link to download the waybill. Empty until there is one. required: - id - assigned_admin - battery_declaration_link - broker_address - ccd_status - commercial_invoice_link - created_at - customer_reference - customs_clearance_document_link - date_delivered - description_of_contents - destination_address - draft_bill_of_lading_link - eei_eligible - eei_request_document_link - export_permit_link - final_bill_of_lading_link - importer_of_record_address - internal_transaction_number - invoice_data - invoice_number - materials_safety_data_sheet_link - measured_weight - origin_address - packaging_list_link - pickup_date - pickup_instructions - proof_of_delivery_link - purpose_of_shipment_id - quote_id - reference_number - scheduled_pickup - send_consignee_tracking_details - shipments - shippers_letter_of_instruction_link - status - stream_packing_list_link - tracking_link - value_of_goods - value_of_goods_currency - waybill - waybill_document_link description: The order. required: - order example: order: id: 24 assigned_admin: battery_declaration_link: '' broker_address: 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: description_of_contents: Cotton shirts and denim trousers destination_address: id: 116 address_1: 221 Shoreditch High Street address_2: Floor 2 address_3: city: London classification: business company: Bennett & Hale Ltd country: id: 18 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: 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: latitude: longitude: name: Oliver Bennett phone: "+442079460321" postal_code: E1 6PJ province: Greater London summary: United Kingdom tax_number: time_zone_id: draft_bill_of_lading_link: '' eei_eligible: false eei_request_document_link: '' export_permit_link: '' final_bill_of_lading_link: '' importer_of_record_address: internal_transaction_number: 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: 19 line_items: - cost: 2184.5 currency_id: ZAR description: Freight - cost: 393.21 currency_id: ZAR description: Fuel surcharge - cost: 450.0 currency_id: ZAR description: Customs clearance quote_expired: false shipping_company: FedEx South Africa shipping_service: International Priority invoice_number: materials_safety_data_sheet_link: '' measured_weight: 0.0 origin_address: id: 115 address_1: 14 Bree Street address_2: Unit 3 address_3: city: Cape Town classification: business company: Global Trade Corp country: id: 17 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: 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: latitude: longitude: name: Thandi Mokoena phone: "+27215550142" postal_code: '8001' province: Western Cape summary: South Africa tax_number: time_zone_id: packaging_list_link: '' pickup_date: pickup_instructions: '' proof_of_delivery_link: '' purpose_of_shipment_id: 50 quote_id: 24 reference_number: MYSGLO001000001 scheduled_pickup: '' send_consignee_tracking_details: false shipments: - shipping_service: International Priority status: order_received tracking_link: waybill: waybill_document_link: '' shippers_letter_of_instruction_link: '' status: order_received stream_packing_list_link: '' tracking_link: value_of_goods: 18500.0 value_of_goods_currency: ZAR waybill: waybill_document_link: '' description: reads one order '400': description: answers a crash that is not a RuntimeError with the same shape and reports it content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: Unexpected error occurred, please check inputs errors: [] '401': "$ref": "#/components/responses/Unauthorized" '404': content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: Couldn't find Order with 'id'=0 errors: [] description: answers a missing record with a sentence and no reasons "/client_api/v2/orders/{order_id}/pickup_availabilities": get: summary: List pickup slots tags: - Waybills and pickups parameters: - name: order_id in: path required: true schema: type: integer example: 1 description: The order's id, from Create an order or List orders. responses: '200': description: lists the collection slots the carrier offers content: application/json: schema: type: array items: type: object properties: earliest_pickup_time: type: string description: The earliest the goods can be ready, as `HH:MM`. latest_pickup_end_time: type: string description: The latest the collection point can close, as `HH:MM`. latest_pickup_start_time: type: string description: The latest the goods can be ready, as `HH:MM`. minimum_access_duration_minutes: type: integer description: How long, at least, the driver needs between ready time and closing time. pickup_date: type: string description: A day the carrier can collect, as `YYYY-MM-DD`. time_zone_id: nullable: true description: The time zone the times are in. Usually empty, in which case they are local to the collection address. required: - earliest_pickup_time - latest_pickup_end_time - latest_pickup_start_time - minimum_access_duration_minutes - pickup_date - time_zone_id example: - earliest_pickup_time: '09:00' latest_pickup_end_time: '16:30' latest_pickup_start_time: '15:00' minimum_access_duration_minutes: 90 pickup_date: '2026-10-26' time_zone_id: '401': "$ref": "#/components/responses/Unauthorized" description: The days and times the carrier can collect the order. Pick a slot from here before you book a pickup. "/client_api/v2/orders/{order_id}/schedule_pickups": get: summary: List pickups tags: - Waybills and pickups parameters: - name: order_id in: path required: true schema: type: integer example: 5 description: The order's id, from Create an order or List orders. - name: page in: query required: false schema: type: integer example: 1 description: Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. responses: '200': description: lists the order's pickups content: application/json: schema: type: object properties: scheduled_pickups: type: array items: type: object properties: id: type: integer description: The pickup's id. cancellable: type: boolean description: "`true` while the booking can still be cancelled with the carrier." confirmation_number: type: string description: The carrier's confirmation number for the booking. error_message: type: string description: "`Invalid postal code` when the carrier refused the booking over the postal code. Empty for every other outcome, including other refusals." freight_confirmation_number: nullable: true description: The carrier's second confirmation number, for freight collected separately. Usually empty. order_status: type: string description: Where the order is. List order statuses has every value. enum: - 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 scheduled_date: type: string description: The collection day, as `YYYY/MM/DD HH:MM:SS UTC`. The time is always midnight, so read only the date. status: type: string description: Where the booking stands. `system_to_schedule` means we are still booking it with the carrier. enum: - scheduled - cancelled - errored - system_to_schedule - missed time_from: type: string description: When the goods are ready, as `HH:MM:SS`. time_to: type: string description: When the collection point closes, as `HH:MM:SS`. required: - id - cancellable - confirmation_number - error_message - freight_confirmation_number - order_status - scheduled_date - status - time_from - time_to description: The order's pickups, newest first. meta: type: object properties: page_count: type: integer description: How many pages the list has. Ask for another with `?page=`. record_count: type: integer description: How many records the list has across all pages. required: - page_count - record_count description: How many pages and records the list has. required: - scheduled_pickups - meta example: scheduled_pickups: - id: 2 cancellable: true confirmation_number: FDX-PU-4417823 error_message: '' freight_confirmation_number: order_status: awaiting_pickup scheduled_date: 2026/10/26 00:00:00 UTC status: scheduled time_from: '10:00:00' time_to: '16:00:00' meta: page_count: 1 record_count: 1 '401': "$ref": "#/components/responses/Unauthorized" description: Every pickup booked for the order, newest first, including cancelled ones. post: summary: Book a pickup tags: - Waybills and pickups parameters: - name: order_id in: path required: true schema: type: integer example: 4 description: The order's id, from Create an order or List orders. requestBody: content: application/json: schema: type: object properties: scheduled_pickup: type: object properties: scheduled_date: type: string description: The day to collect, as `YYYY-MM-DD`. It has to be a day from List pickup slots. time_from: type: string description: When the goods are ready, as `HH:MM` in the collection address's local time. No earlier than the slot's `earliest_pickup_time` and no later than its `latest_pickup_start_time`. time_to: type: string description: When the collection point closes, as `HH:MM`. No later than the slot's `latest_pickup_end_time`, and at least `minimum_access_duration_minutes` after `time_from`. pickup_instructions: type: string description: Anything the driver needs to know, such as which door to use. required: - scheduled_date - time_from - time_to description: The pickup to book. required: - scheduled_pickup example: scheduled_pickup: scheduled_date: '2026-10-26' time_from: '10:00' time_to: '16:00' pickup_instructions: Collect from reception and ask for Thandi responses: '201': description: books the pickup and answers 201 with it content: application/json: schema: type: object properties: scheduled_pickup: type: object properties: id: type: integer description: The pickup's id. cancellable: type: boolean description: "`true` while the booking can still be cancelled with the carrier." confirmation_number: type: string description: The carrier's confirmation number for the booking. error_message: type: string description: "`Invalid postal code` when the carrier refused the booking over the postal code. Empty for every other outcome, including other refusals." freight_confirmation_number: nullable: true description: The carrier's second confirmation number, for freight collected separately. Usually empty. pickup_instructions: type: string description: What the driver was told. scheduled_date: type: string description: The collection day, as `YYYY/MM/DD HH:MM:SS UTC`. The time is always midnight, so read only the date. status: type: string description: Where the booking stands. `system_to_schedule` means we are still booking it with the carrier. enum: - scheduled - cancelled - errored - system_to_schedule - missed time_from: type: string description: When the goods are ready, as `HH:MM:SS`. time_to: type: string description: When the collection point closes, as `HH:MM:SS`. required: - id - cancellable - confirmation_number - error_message - freight_confirmation_number - pickup_instructions - scheduled_date - status - time_from - time_to description: The pickup. required: - scheduled_pickup example: scheduled_pickup: id: 1 cancellable: true confirmation_number: FDX-PU-4417823 error_message: '' freight_confirmation_number: pickup_instructions: Collect from reception and ask for Thandi scheduled_date: 2026/10/26 00:00:00 UTC status: scheduled time_from: '10:00:00' time_to: '16:00:00' '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" description: Books the carrier to collect the order, inside one of the slots from List pickup slots. Booking again cancels the earlier pickup. "/client_api/v2/orders/{order_id}/tracking": get: summary: List tracking events tags: - Tracking parameters: - name: order_id in: path required: true schema: type: integer example: 3 description: The order's id, from Create an order or List orders. - name: page in: query required: false schema: type: integer example: 1 description: Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. responses: '200': description: lists the tracking events, newest first content: application/json: schema: type: object properties: shipment_events: type: array items: type: object properties: id: type: integer description: The event's id. date_time: type: string description: When it happened, as `YYYY/MM/DD HH:MM:SS UTC`. description: type: string description: What happened, in the carrier's words. latitude: nullable: true description: Where it happened, when the carrier says. Usually empty. location: type: string description: Where it happened, as the carrier reports it. longitude: nullable: true description: Where it happened, when the carrier says. Usually empty. order_id: type: integer description: The order the event belongs to. required: - id - date_time - description - latitude - location - longitude - order_id description: The tracking events on this page, newest first. meta: type: object properties: page_count: type: integer description: How many pages the list has. Ask for another with `?page=`. record_count: type: integer description: How many records the list has across all pages. required: - page_count - record_count description: How many pages and records the list has. required: - shipment_events - meta example: shipment_events: - id: 3 date_time: 2026/10/28 09:12:00 UTC description: Arrived at FedEx hub latitude: location: STANSTED, GB longitude: order_id: 3 - id: 2 date_time: 2026/10/27 03:40:00 UTC description: Departed FedEx hub latitude: location: JOHANNESBURG, ZA longitude: order_id: 3 - id: 1 date_time: 2026/10/26 14:05:00 UTC description: Picked up latitude: location: CAPE TOWN, ZA longitude: order_id: 3 meta: page_count: 1 record_count: 3 '401': "$ref": "#/components/responses/Unauthorized" description: What the carrier has reported about the shipment, newest first. "/client_api/v2/orders/{order_id}/waybills": post: summary: Create a waybill tags: - Waybills and pickups parameters: - name: order_id in: path required: true schema: type: integer example: 11 description: The order's id, from Create an order or List orders. requestBody: content: application/json: schema: type: object properties: {} example: {} responses: '201': description: answers 201 with the order when the waybill is generated content: application/json: schema: type: object properties: order: type: object properties: id: type: integer description: The order's id, for every call about the order. assigned_admin: nullable: true description: The email address of the person on our team looking after the order. Empty until one is assigned. battery_declaration_link: type: string description: A link to download the battery declaration. Empty until there is one. broker_address: nullable: true description: The customs broker clearing the goods, when one is appointed. Empty otherwise. ccd_status: type: string description: Where we stand on the destination's customs clearance document (CCD), for orders where we get one. enum: - ccd_not_required - ccd_required - voucher_of_correction_requested - voucher_of_correction_received - ccd_acquired commercial_invoice_link: type: string description: A link to download the commercial invoice. Empty until there is one. created_at: type: string description: When the order was placed, as `YYYY/MM/DD HH:MM:SS UTC`. customer_reference: type: string nullable: true description: Your own reference for the order. customs_clearance_document_link: type: string description: A link to download the customs clearance document. Empty until there is one. date_delivered: nullable: true description: When the goods were delivered, as `YYYY/MM/DD HH:MM:SS UTC`. Empty until then. description_of_contents: type: string nullable: true description: What is in the shipment. destination_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true type: string description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true type: string description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the goods are delivered. draft_bill_of_lading_link: type: string description: A link to download the draft bill of lading. Empty until there is one. eei_eligible: type: boolean description: "`true` when the shipment needs an Electronic Export Information filing with US customs." eei_request_document_link: type: string description: A link to download the export filing request. Empty until there is one. export_permit_link: type: string description: A link to download the export permit. Empty until there is one. final_bill_of_lading_link: type: string description: A link to download the final bill of lading. Empty until there is one. importer_of_record_address: nullable: true description: The importer of record, when the shipment has one. Empty otherwise. internal_transaction_number: nullable: true description: The US customs reference (ITN) for the export filing. Empty unless one was filed. invoice_data: type: object properties: billable_weights: type: object properties: metric: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `kg`. distance_unit: type: string description: Always `cm`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in kilograms, the sizes in centimetres and the volume in cubic metres. imperial: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `lb`. distance_unit: type: string description: Always `inches`. A request spells the same unit `inch`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in pounds, the sizes in inches and the volume in cubic feet. required: - metric - imperial description: The weights the carrier charges on, in metric and in imperial units. estimate_id: type: integer description: The estimate's id. Book it by sending it as an order's `quote_estimate_id`. line_items: type: array items: type: object properties: cost: type: number format: float description: What the charge costs, in `currency_id`. currency_id: type: string description: The currency the company is billed in. description: type: string description: The charge, such as freight or fuel surcharge. required: - cost - currency_id - description description: What the price is made of, one charge per line. quote_expired: type: boolean description: "`true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote." shipping_company: type: string description: The carrier. shipping_service: type: string description: The carrier's service, such as International Priority. required: - billable_weights - estimate_id - line_items - quote_expired - shipping_company - shipping_service description: The booked estimate, with its weights and charges. Empty until an estimate is booked. invoice_number: nullable: true description: Our invoice number for the order. Empty until we invoice it. materials_safety_data_sheet_link: type: string description: A link to download the materials safety data sheet. Empty until there is one. measured_weight: type: number format: float description: What the carrier weighed the shipment at, in kilograms. `0` until the carrier weighs it. origin_address: type: object properties: id: type: integer description: The address's id. Send it as `origin_address_id` or `destination_address_id` to use the address again. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. address_3: nullable: true type: string description: A third address line. city: type: string description: The city or town. At most 20 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential company: type: string description: The company at the address. At most 35 characters. country: type: object properties: id: type: integer description: The country's id, for an address's `country_id`. default_postal_code: nullable: true description: The postal code we give the carrier for an address in this country that has none. dhl_export_code: nullable: true description: DHL's export code for the country. Usually empty. dhl_import_code: nullable: true description: DHL's import code for the country. Usually empty. dhl_tax_code: nullable: true description: DHL's tax code for the country. Usually empty. export_code_label: type: string description: What the country calls an exporter number. import_code_label: type: string description: What the country calls an importer number. iso_code_2: type: string description: The two-letter ISO code, such as `GB`. iso_code_3: type: string description: The three-letter ISO code, such as `GBR`. name: type: string description: The country's name in English. postal_code_required: type: boolean description: "`false` for the countries that have no postal codes." tax_number_label: type: string description: What the country calls a tax number. vat_rate: type: number format: float description: The country's standard VAT or sales tax rate, as a fraction. `0.15` is 15%. required: - id - default_postal_code - dhl_export_code - dhl_import_code - dhl_tax_code - export_code_label - import_code_label - iso_code_2 - iso_code_3 - name - postal_code_required - tax_number_label - vat_rate description: The country, in full. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. import_code: nullable: true type: string description: The importer number of the party at the address. The country's `import_code_label` says what it is called there. latitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. longitude: nullable: true description: Where the address is, filled in by us shortly after the address is saved. Empty until then. name: type: string description: The person to ask for. At most 35 characters. phone: type: string description: A phone number for the person at the address. At most 15 characters. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. province: type: string description: The province, state or county. summary: type: string description: The country's name. tax_number: nullable: true description: 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: nullable: true description: The address's time zone, filled in by us shortly after the address is saved. Empty until then. required: - id - address_1 - address_2 - address_3 - city - classification - company - country - country_id - email - import_code - latitude - longitude - name - phone - postal_code - province - summary - tax_number - time_zone_id description: Where the carrier collects the goods. packaging_list_link: type: string description: A link to download the packing list you uploaded. Empty until there is one. pickup_date: nullable: true type: string description: The day the carrier collected the goods, as `YYYY-MM-DD`. Empty until then. pickup_instructions: type: string description: What the driver was told when the pickup was booked. Empty when none is booked. proof_of_delivery_link: type: string description: A link to download the proof of delivery. Empty until there is one. purpose_of_shipment_id: type: integer description: The incoterm the goods move under. quote_id: type: integer description: The quote the order was booked from. reference_number: type: string description: Our reference for the order, the one our team and the client portal use, for example `MYSGLO001000001`. scheduled_pickup: type: string description: The pickup booked for the order. An empty string, not an empty object, when none is booked. send_consignee_tracking_details: type: boolean description: "`true` when the receiver is sent the tracking details." shipments: type: array items: type: object properties: shipping_service: type: string description: The carrier's service for this leg. status: type: string description: Where this leg is. List order statuses has every value. enum: - 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: type: string nullable: true description: The carrier's tracking page for this leg. Empty until there is a waybill. waybill: type: string nullable: true description: The carrier's waybill number for this leg. Empty until there is one. waybill_document_link: type: string description: A link to download this leg's waybill. Empty until there is one. required: - shipping_service - status - tracking_link - waybill - waybill_document_link description: Each leg of the shipment, in route order. Most orders have one. shippers_letter_of_instruction_link: type: string description: A link to download the shipper's letter of instruction. Empty until there is one. status: type: string description: Where the shipment is. For an order with more than one leg, the last leg's status. List order statuses has every value. enum: - 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: type: string description: A link to download the packing list we made. Empty until there is one. tracking_link: type: string nullable: true description: The carrier's tracking page for the shipment. Empty until there is a waybill. value_of_goods: type: number format: float description: What the goods are worth in total. value_of_goods_currency: type: string description: The currency of `value_of_goods`, as a three-letter code. waybill: type: string nullable: true description: The carrier's waybill number. Empty until Create a waybill has run. waybill_document_link: type: string description: A link to download the waybill. Empty until there is one. required: - id - assigned_admin - battery_declaration_link - broker_address - ccd_status - commercial_invoice_link - created_at - customer_reference - customs_clearance_document_link - date_delivered - description_of_contents - destination_address - draft_bill_of_lading_link - eei_eligible - eei_request_document_link - export_permit_link - final_bill_of_lading_link - importer_of_record_address - internal_transaction_number - invoice_data - invoice_number - materials_safety_data_sheet_link - measured_weight - origin_address - packaging_list_link - pickup_date - pickup_instructions - proof_of_delivery_link - purpose_of_shipment_id - quote_id - reference_number - scheduled_pickup - send_consignee_tracking_details - shipments - shippers_letter_of_instruction_link - status - stream_packing_list_link - tracking_link - value_of_goods - value_of_goods_currency - waybill - waybill_document_link description: The order. required: - order example: order: id: 7 assigned_admin: battery_declaration_link: '' broker_address: ccd_status: ccd_not_required commercial_invoice_link: '' created_at: 2026/10/23 07:14:46 UTC customer_reference: customs_clearance_document_link: '' date_delivered: description_of_contents: destination_address: id: 3 address_1: Destination Address 1 address_2: aa address_3: aa city: aa classification: business company: aa country: id: 5 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: export_code_label: Export Number import_code_label: Importer Code iso_code_2: ISO5 iso_code_3: ISO5 name: random postal_code_required: true tax_number_label: Tax Number vat_rate: 0.17 country_id: 5 email: aa@aa.com import_code: Import code Destination latitude: longitude: name: aa phone: MyString postal_code: aa province: aa summary: random tax_number: time_zone_id: draft_bill_of_lading_link: '' eei_eligible: false eei_request_document_link: '' export_permit_link: '' final_bill_of_lading_link: '' importer_of_record_address: internal_transaction_number: invoice_data: billable_weights: metric: packages: 0 mass_unit: kg distance_unit: cm volumetric_weight: 0 weight: 0 billable_weight: 0 volume: 0.0 imperial: packages: 0 mass_unit: lb distance_unit: inches volumetric_weight: 0.0 weight: 0.0 billable_weight: 0.0 volume: 0.0 estimate_id: 7 line_items: [] quote_expired: false shipping_company: ShippingCo1 shipping_service: Express invoice_number: materials_safety_data_sheet_link: '' measured_weight: 0.0 origin_address: id: 2 address_1: Origin Address 1 address_2: aa address_3: aa city: aa classification: business company: aa country: id: 3 default_postal_code: dhl_export_code: dhl_import_code: dhl_tax_code: export_code_label: Export Number import_code_label: Importer Code iso_code_2: ISO3 iso_code_3: ISO3 name: random postal_code_required: true tax_number_label: Tax Number vat_rate: 0.17 country_id: 3 email: aa@aa.com import_code: Import code Origin latitude: longitude: name: aa phone: MyString postal_code: aa province: aa summary: random tax_number: time_zone_id: packaging_list_link: '' pickup_date: '2026-10-23' pickup_instructions: '' proof_of_delivery_link: '' purpose_of_shipment_id: 26 quote_id: 7 reference_number: MYSABC001000001 scheduled_pickup: '' send_consignee_tracking_details: false shipments: - shipping_service: Express status: order_received tracking_link: waybill: waybill_document_link: '' shippers_letter_of_instruction_link: '' status: order_received stream_packing_list_link: '' tracking_link: value_of_goods: 100.0 value_of_goods_currency: USD waybill: waybill_document_link: '' '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: answers 403 when a policy refuses the user content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: You are not authorized to perform that action errors: [] '422': description: answers 422 with the carrier's message for staff content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: 'Provider error: address is invalid' errors: [] description: | Asks the carrier for the order's waybill and answers with the order, now holding the waybill number and a link to its document. If the carrier refuses, or a document or payment is missing, the call answers 422 with the reason. Never send it twice without checking: a second call books the carrier again, even when the first one worked. After a timeout, read the order with Get an order and call again only if it has no waybill. Read the order with Get an order first, and call this again only if it has no waybill. "/client_api/v2/orders_by_status": get: summary: List order ids by status tags: - Orders parameters: - name: status in: query required: false schema: type: string example: in_transit description: A shipment status, such as `in_transit`. List order statuses has every value. responses: '200': description: lists the customer's orders whose shipment is in that status content: application/json: schema: type: object properties: order_ids: type: array items: type: integer description: The ids of the matching orders, each once. required: - order_ids example: order_ids: - 14 '401': "$ref": "#/components/responses/Unauthorized" description: The ids of your company's orders that have a shipment in the given status. Read each one with Get an order. "/client_api/v2/purpose_of_shipments": get: summary: List purposes of shipment tags: - Reference data parameters: - name: code in: query required: false schema: type: string example: ddp description: Only the incoterm with this code, such as `DDP`, in any case. - name: page in: query required: false schema: type: integer example: 1 description: Which page to read, from 1. `meta.page_count` in the answer says how many pages there are. - name: show_all in: query required: false schema: type: boolean example: false description: Send `true` to get every incoterm on one page. responses: '200': description: lists the purposes of shipment the customer may quote with, or finds one by its code in any case content: application/json: schema: type: object properties: purpose_of_shipments: type: array items: type: object properties: id: type: integer description: The purpose's id, for a quote's or order's `purpose_of_shipment_id`. code: type: string description: The incoterm's code, such as `DDP` or `DAP`. description: type: string description: The incoterm's name. explanation: nullable: true description: What the incoterm means for who pays what. Often empty. required: - id - code - description - explanation description: The purposes of shipment on this page. meta: type: object properties: page_count: type: integer description: How many pages the list has. Ask for another with `?page=`. record_count: type: integer description: How many records the list has across all pages. required: - page_count - record_count description: How many pages and records the list has. required: - purpose_of_shipments - meta example: purpose_of_shipments: - id: 1 code: DDP description: Delivered Duty Paid explanation: meta: page_count: 1 record_count: 1 '401': "$ref": "#/components/responses/Unauthorized" description: The incoterms your company may quote with. A quote's and an order's `purpose_of_shipment_id` comes from here. To find one incoterm's id, send its code, such as `?code=DDP`. "/client_api/v2/quotes": post: summary: Create a quote tags: - Quotes responses: '201': description: prices the shipment and answers 201 with each carrier's estimate content: application/json: schema: type: object properties: quote: type: object properties: id: type: integer description: The quote's id. dirty: type: boolean description: Always `false`. Nothing sets it. errors: type: array items: {} description: Why a carrier could not price the shipment, one message per carrier that refused. Empty when every carrier priced it. estimate_taxes_and_duties: type: boolean description: "`true` when the estimates include the destination's duties and taxes." estimates: type: array items: type: object properties: billable_weights: type: object properties: metric: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `kg`. distance_unit: type: string description: Always `cm`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in kilograms, the sizes in centimetres and the volume in cubic metres. imperial: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `lb`. distance_unit: type: string description: Always `inches`. A request spells the same unit `inch`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in pounds, the sizes in inches and the volume in cubic feet. required: - metric - imperial description: The weights the carrier charges on, in metric and in imperial units. estimate_id: type: integer description: The estimate's id. Book it by sending it as an order's `quote_estimate_id`. line_items: type: array items: type: object properties: cost: type: number format: float description: What the charge costs, in `currency_id`. currency_id: type: string description: The currency the company is billed in. description: type: string description: The charge, such as freight or fuel surcharge. required: - cost - currency_id - description description: What the price is made of, one charge per line. quote_expired: type: boolean description: "`true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote." shipping_company: type: string description: The carrier. shipping_service: type: string description: The carrier's service, such as International Priority. required: - billable_weights - estimate_id - line_items - quote_expired - shipping_company - shipping_service description: One estimate per carrier service that could take the shipment. Book one with Create an order. hub_transit: type: boolean description: "`true` when the shipment goes through one of our hubs on the way." required: - id - dirty - errors - estimate_taxes_and_duties - estimates - hub_transit description: The quote. required: - quote example: quote: id: 42 dirty: false errors: [] estimate_taxes_and_duties: false estimates: - 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: 37 line_items: - cost: 2184.5 currency_id: ZAR description: Freight - cost: 393.21 currency_id: ZAR description: Fuel surcharge - cost: 450.0 currency_id: ZAR description: Customs clearance quote_expired: false shipping_company: FedEx shipping_service: International Priority hub_transit: false '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': description: returns 422 naming the field when it is missing content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: type: string description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: Purpose of shipment can't be blank errors: - Purpose of shipment can't be blank '429': description: answers too many requests with a message instead of an empty body content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: Too many requests, please wait and try again errors: [] requestBody: content: application/json: schema: type: object properties: purpose_of_shipment_id: type: integer description: The incoterm the goods move under, which settles who pays duties and taxes. Take the id from List purposes of shipment. reason_for_shipment_id: type: integer description: Why the goods are moving, for customs. Take the id from List reasons for shipment. Left out, we use documents for a document shipment and our default reason for anything else. value_of_goods: type: integer description: What the goods are worth in total, at least 1. Customs duties and insurance are worked out from it. value_of_goods_currency_id: type: string description: The currency of `value_of_goods` and of each item's value, as a three-letter code from List currencies. description_of_contents: type: string description: What is in the shipment, in a few words a customs officer understands. At most 70 characters. mass_unit: type: string description: The unit every weight in this request is in. enum: - kg - lb distance_unit: type: string description: The unit every package size in this request is in. enum: - cm - inch is_document: type: boolean description: "`true` when the shipment holds only papers. Documents need no items declared." is_stackable: type: boolean description: "`true` when other freight may be stacked on top of the packages." is_liftgate_required: type: boolean description: "`true` when the vehicle needs a lift to load or unload, because there is no loading dock." is_shipment_protection_required: type: boolean description: "`true` to insure the goods for their declared value." origin_address: type: object properties: name: type: string description: The person to ask for. At most 35 characters. company: type: string description: The company at the address. At most 35 characters. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. city: type: string description: The city or town. At most 20 characters. province: type: string description: The province, state or county. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. phone: type: string description: A phone number for the person at the address. At most 15 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential required: - country_id description: Where the carrier collects the goods. Needed to price the shipment. destination_address: type: object properties: name: type: string description: The person to ask for. At most 35 characters. company: type: string description: The company at the address. At most 35 characters. address_1: type: string description: The street address. At most 34 characters. address_2: type: string description: A second address line, such as a floor or unit. At most 34 characters. city: type: string description: The city or town. At most 20 characters. province: type: string description: The province, state or county. postal_code: type: string description: The postal code. Some countries, such as Ireland, refuse an address without one. country_id: type: integer description: The country. Take the id from List countries. email: type: string description: An email address for the person at the address. Carriers use it for delivery notices. phone: type: string description: A phone number for the person at the address. At most 15 characters. classification: type: string description: Whether the address is a business or a home. Carriers charge more to deliver to a home. enum: - business - residential required: - country_id description: Where the goods are delivered. Needed to price the shipment. packages: type: array items: type: object properties: weight: type: number format: float description: What the package weighs, in `mass_unit`. length: type: integer description: The package's length, in `distance_unit`. width: type: integer description: The package's width, in `distance_unit`. height: type: integer description: The package's height, in `distance_unit`. required: - weight - width - height - length description: Each box or pallet in the shipment. Needed to price the shipment. hs_codes: type: array items: type: object properties: code: type: string description: The item's tariff code (HS code), at least six digits. country_id: type: integer description: The country the item was made in. Take the id from List countries. description: type: string description: What the item is, in plain words. At most 250 characters. quantity: type: integer description: How many of this item are in the shipment. item_value: type: number format: float description: What one item is worth, in `value_of_goods_currency_id`. item_mass: type: number format: float description: What one item weighs, in `mass_unit`. eccn: type: string description: The item's export control classification number, such as `EAR99`, when it has one. nature_of_transaction: type: string description: The two-digit customs code for the kind of deal, such as `11` for an outright sale. List natures of transaction has every code. sku: type: string description: Your stock code for the item. model_number: type: string description: The item's model number. barcode: type: string description: The item's barcode number. required: - code - description - item_mass - item_value - country_id description: Each kind of item in the shipment, as customs sees it. Leave out for a document shipment. estimate_taxes_and_duties: type: boolean description: "`true` to add the import duties and taxes we estimate to each estimate. The Taxes and duties guide explains when they apply." hub_transit: type: boolean description: "`true` to route the shipment through one of our hubs, as two legs. The call answers 422 when no hub serves the route. The Hub shipments guide explains it." is_rotatable: type: boolean description: "`false` when the packages have to stay the right way up." iata_approved: type: boolean description: "`true` when dangerous goods are packed to IATA's rules. Carriers only take dangerous goods that are." importer_of_record_appointed: type: boolean description: "`true` when an importer of record has been appointed for the goods at the destination." next_flight_out: type: boolean description: "`true` for a next-flight-out shipment, which our team prices and books by hand, so the quote has no carrier estimates." dangerous_goods: type: array items: type: object properties: un_code: type: string description: The goods' UN number, such as `UN3481` for lithium-ion batteries with equipment. pi_code: type: string description: The IATA packing instruction the goods are packed under, such as `PI967`. pieces: type: integer description: How many pieces of these goods are in the shipment. safe_weight: type: boolean description: "`true` when the batteries are within the safe weight limit. Asked for every battery except lithium metal." safe_wattage: type: boolean description: "`true` when the batteries are within the safe watt-hour limit. Asked for lithium-ion batteries." safe_lithium_metal_content: type: boolean description: "`true` when the batteries are within the safe lithium content limit. Asked for lithium metal batteries." description: Each kind of dangerous good in the shipment, such as lithium batteries. Leave out when there are none. dry_ice: type: object properties: total_weight: type: integer description: How much dry ice there is, in this object's `mass_unit`. package_count: type: integer description: How many packages hold dry ice. mass_unit: type: string description: The unit `total_weight` is in. description: The dry ice packed with the goods. Leave out when there is none. export_licence: type: object properties: export_code: type: string description: The export licence's number. description: The export licence the goods leave under, when they need one. clearance_detail: type: object properties: invoice_number: type: string description: Your invoice number for the goods, printed on the commercial invoice. purchase_order_number: type: string description: The buyer's purchase order number, printed on the commercial invoice. commercial_invoice_placeholder_text: type: string description: Extra text printed on the commercial invoice, such as a declaration of origin. description: Details for the commercial invoice. required: - purpose_of_shipment_id - value_of_goods - mass_unit - distance_unit example: purpose_of_shipment_id: 73 reason_for_shipment_id: 45 value_of_goods: 18500 value_of_goods_currency_id: ZAR description_of_contents: Cotton shirts and denim trousers mass_unit: kg distance_unit: cm is_document: false is_stackable: true is_liftgate_required: false is_shipment_protection_required: false origin_address: name: Thandi Mokoena company: Global Trade Corp address_1: 14 Bree Street address_2: Unit 3 city: Cape Town province: Western Cape postal_code: '8001' country_id: 23 email: dispatch@globaltradecorp.example phone: "+27 21 555 0142" classification: business destination_address: name: Oliver Bennett company: Bennett & Hale Ltd address_1: 221 Shoreditch High Street address_2: Floor 2 city: London province: Greater London postal_code: E1 6PJ country_id: 24 email: goods-in@bennetthale.example phone: "+44 20 7946 0321" classification: business packages: - weight: 12.5 length: 60 width: 40 height: 35 hs_codes: - code: '620342' country_id: 23 description: Men's cotton trousers quantity: 40 item_value: 250 item_mass: 0.2 - code: '620520' country_id: 23 description: Men's cotton shirts quantity: 60 item_value: 141.67 item_mass: 0.075 description: Describe the shipment, and we price it with each carrier that can take it. Each estimate in the answer can be booked with Create an order. "/client_api/v2/quotes/{id}": get: summary: Get a quote tags: - Quotes parameters: - name: id in: path required: true schema: type: integer example: 41 description: The quote's id, from Create a quote. responses: '200': content: application/json: schema: type: object properties: quote: type: object properties: id: type: integer description: The quote's id. dirty: type: boolean description: Always `false`. Nothing sets it. errors: type: array items: {} description: Why a carrier could not price the shipment, one message per carrier that refused. Empty when every carrier priced it. estimate_taxes_and_duties: type: boolean description: "`true` when the estimates include the destination's duties and taxes." estimates: type: array items: type: object properties: billable_weights: type: object properties: metric: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `kg`. distance_unit: type: string description: Always `cm`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in kilograms, the sizes in centimetres and the volume in cubic metres. imperial: type: object properties: packages: type: integer description: How many packages there are. mass_unit: type: string description: Always `lb`. distance_unit: type: string description: Always `inches`. A request spells the same unit `inch`. volumetric_weight: type: number format: float description: The weight the carrier works out from the packages' size. weight: type: number format: float description: What the packages weigh together. billable_weight: type: number format: float description: The weight the carrier charges on, the larger of `weight` and `volumetric_weight`. volume: type: number format: float description: The packages' volume together. required: - packages - mass_unit - distance_unit - volumetric_weight - weight - billable_weight - volume description: The weights in pounds, the sizes in inches and the volume in cubic feet. required: - metric - imperial description: The weights the carrier charges on, in metric and in imperial units. estimate_id: type: integer description: The estimate's id. Book it by sending it as an order's `quote_estimate_id`. line_items: type: array items: type: object properties: cost: type: number format: float description: What the charge costs, in `currency_id`. currency_id: type: string description: The currency the company is billed in. description: type: string description: The charge, such as freight or fuel surcharge. required: - cost - currency_id - description description: What the price is made of, one charge per line. quote_expired: type: boolean description: "`true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote." shipping_company: type: string description: The carrier. shipping_service: type: string description: The carrier's service, such as International Priority. required: - billable_weights - estimate_id - line_items - quote_expired - shipping_company - shipping_service description: One estimate per carrier service that could take the shipment. Book one with Create an order. hub_transit: type: boolean description: "`true` when the shipment goes through one of our hubs on the way." required: - id - dirty - errors - estimate_taxes_and_duties - estimates - hub_transit description: The quote. required: - quote example: quote: id: 41 dirty: false errors: [] estimate_taxes_and_duties: false estimates: - 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: 36 line_items: - cost: 2184.5 currency_id: ZAR description: Freight - cost: 393.21 currency_id: ZAR description: Fuel surcharge - cost: 450.0 currency_id: ZAR description: Customs clearance quote_expired: false shipping_company: FedEx shipping_service: International Priority hub_transit: false description: reads the quote again later '401': "$ref": "#/components/responses/Unauthorized" description: Read a quote again, with its estimates. "/client_api/v2/reason_for_shipments": get: summary: List reasons for shipment tags: - Reference data parameters: - name: q in: query required: false schema: type: string example: gift description: Only reasons whose name contains this text, in any case, such as `gift`. responses: '200': description: lists the reasons for shipment content: application/json: schema: type: object properties: reason_for_shipments: type: array items: type: object properties: id: type: integer description: The reason's id, for a quote's `reason_for_shipment_id`. enabled: type: boolean description: Whether the reason is switched on. name: type: string description: The reason, as customs sees it. product_identifiers_required: type: boolean description: "`true` when each item needs a product code, such as a SKU, model number or barcode." return: type: boolean description: "`true` when the goods are coming back, for example after a repair." sort_index: type: integer description: Where the reason sits in a list shown to people. required: - id - enabled - name - product_identifiers_required - return - sort_index description: The reasons for shipment, by name. required: - reason_for_shipments example: reason_for_shipments: - id: 1 enabled: true name: Gift product_identifiers_required: false return: false sort_index: 2 '401': "$ref": "#/components/responses/Unauthorized" description: Why goods can be moving, for customs. A quote's `reason_for_shipment_id` comes from here. "/client_api/v2/system_configs/{id}": get: summary: Get a setting tags: - Reference data parameters: - name: id in: path required: true schema: type: string example: document_descriptions description: | The setting's name. A client may read `document_descriptions`, `commercial_invoice_placeholders`, `broker_optional_channels`, `bill_of_lading_applicable_shipping_company_ids`, `export_permit_origin_country_ids`, `whats_new_client_ui` and `whats_new_reseller_ui`. responses: '200': description: reads one system setting a client may see content: application/json: schema: type: array items: type: string example: - Commercial invoice - Packing list '401': "$ref": "#/components/responses/Unauthorized" description: Reads one of our settings that a client may see. The answer's shape depends on the setting. "/client_api/v2/webhooks": post: summary: Create a webhook tags: - Webhooks responses: '201': description: registers an endpoint for the events the customer wants and answers 201 content: application/json: schema: type: object properties: webhook: type: object properties: events: type: array items: type: string enum: - shipment.updated.status - shipment.updated.waybill description: | The events to send, written exactly as below. `shipment.updated.status` fires when a shipment reaches `order_received`, `in_transit` or `delivered`. `shipment.updated.waybill` fires whenever a shipment's waybill number changes, including when it is cleared. id: type: integer description: The webhook's id. status: type: string description: "`failing` when an event could not be delivered after five tries. A failing webhook gets no more events, and the API can't switch it back on: delete it and create a new one." enum: - active - failing target_url: type: string description: The http or https URL we send events to. token: type: string description: A secret we send with every event, so your system can tell the event came from us. required: - events - id - status - target_url - token description: The webhook. required: - webhook example: webhook: events: - shipment.updated.status - shipment.updated.waybill id: 3 status: active target_url: https://hooks.globaltradecorp.example/stream token: q7Vt2mX9pL4sKe8RzW1nYg '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': description: refuses an event nothing sends, with a 422 content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: type: string description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: 'Events not permitted: shipment.created.shipment_event' errors: - 'Events not permitted: shipment.created.shipment_event' requestBody: content: application/json: schema: type: object properties: webhook: type: object properties: target_url: type: string description: The http or https URL we send events to. events: type: array items: type: string enum: - shipment.updated.status - shipment.updated.waybill description: | The events to send, written exactly as below. `shipment.updated.status` fires when a shipment reaches `order_received`, `in_transit` or `delivered`. `shipment.updated.waybill` fires whenever a shipment's waybill number changes, including when it is cleared. required: - target_url description: The webhook's settings. required: - webhook example: webhook: target_url: https://hooks.globaltradecorp.example/stream events: - shipment.updated.status - shipment.updated.waybill description: Registers a URL that we send a POST to whenever one of the chosen events happens. "/client_api/v2/webhooks/{id}": delete: summary: Delete a webhook tags: - Webhooks parameters: - name: id in: path required: true schema: type: integer example: 2 description: The webhook's id, from Create a webhook. responses: '200': description: deletes an endpoint content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: {} description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: true error: '' errors: [] '401': "$ref": "#/components/responses/Unauthorized" description: Stops the webhook. We send it nothing more. get: summary: Get a webhook tags: - Webhooks parameters: - name: id in: path required: true schema: type: integer example: 1 description: The webhook's id, from Create a webhook. responses: '200': description: reads an endpoint content: application/json: schema: type: object properties: webhook: type: object properties: events: type: array items: type: string enum: - shipment.updated.status - shipment.updated.waybill description: | The events to send, written exactly as below. `shipment.updated.status` fires when a shipment reaches `order_received`, `in_transit` or `delivered`. `shipment.updated.waybill` fires whenever a shipment's waybill number changes, including when it is cleared. id: type: integer description: The webhook's id. status: type: string description: "`failing` when an event could not be delivered after five tries. A failing webhook gets no more events, and the API can't switch it back on: delete it and create a new one." enum: - active - failing target_url: type: string description: The http or https URL we send events to. token: type: string description: A secret we send with every event, so your system can tell the event came from us. required: - events - id - status - target_url - token description: The webhook. required: - webhook example: webhook: events: - shipment.updated.status - shipment.updated.waybill id: 1 status: active target_url: https://hooks.globaltradecorp.example/stream token: q7Vt2mX9pL4sKe8RzW1nYg '401': "$ref": "#/components/responses/Unauthorized" put: summary: Update a webhook tags: - Webhooks parameters: - name: id in: path required: true schema: type: integer example: 5 description: The webhook's id, from Create a webhook. requestBody: content: application/json: schema: type: object properties: webhook: type: object properties: events: type: array items: type: string enum: - shipment.updated.status - shipment.updated.waybill description: | The events to send, written exactly as below. `shipment.updated.status` fires when a shipment reaches `order_received`, `in_transit` or `delivered`. `shipment.updated.waybill` fires whenever a shipment's waybill number changes, including when it is cleared. description: The webhook's settings. required: - webhook example: webhook: events: - shipment.updated.status responses: '200': description: changes an endpoint's events content: application/json: schema: type: object properties: webhook: type: object properties: events: type: array items: type: string enum: - shipment.updated.status - shipment.updated.waybill description: | The events to send, written exactly as below. `shipment.updated.status` fires when a shipment reaches `order_received`, `in_transit` or `delivered`. `shipment.updated.waybill` fires whenever a shipment's waybill number changes, including when it is cleared. id: type: integer description: The webhook's id. status: type: string description: "`failing` when an event could not be delivered after five tries. A failing webhook gets no more events, and the API can't switch it back on: delete it and create a new one." enum: - active - failing target_url: type: string description: The http or https URL we send events to. token: type: string description: A secret we send with every event, so your system can tell the event came from us. required: - events - id - status - target_url - token description: The webhook. required: - webhook example: webhook: events: - shipment.updated.status id: 4 status: active target_url: https://hooks.globaltradecorp.example/stream token: q7Vt2mX9pL4sKe8RzW1nYg '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': description: answers a refused webhook update with each reason in the list and all of them in one sentence content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. errors: type: array items: type: string description: Each reason the request was refused, one per entry. Often empty, in which case `error` says it all. required: - success - error - errors example: success: false error: Target url can't be blank and Target url is invalid errors: - Target url can't be blank - Target url is invalid description: Changes a webhook's URL or events. Send only what changes. PATCH works the same way. components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT responses: Unauthorized: description: 'The token is missing, expired, revoked or invalid. Sign in again. `error` names the reason: the example below for a missing token, or `Signature has expired`, `revoked token`, `Signature verification failed` or `Invalid base64 encoding`.' content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. required: - error example: error: You need to sign in or sign up before continuing. BadRequest: description: The request body is not valid JSON. content: application/json: schema: type: object properties: success: type: boolean description: Always `false` on an error. A successful delete answers `true`. error: type: string description: What went wrong, in one sentence. Empty on success. required: - error example: success: false error: Malformed request body tags: - name: Authentication description: Sign in and get the token every other call needs. - name: Quotes description: Price a shipment with each carrier before you book it. - name: Orders description: Book a shipment from a quote, list and read your orders, and cancel one before it goes live. - name: Waybills and pickups description: Get the carrier's waybill, see when the carrier can collect, and book the collection. - name: Tracking description: Follow a shipment's progress, as the carrier reports it. - name: Companies description: For resellers. Set up the client companies you ship for, and list them. - name: Webhooks description: Have us tell your system when a shipment changes, instead of asking. - name: Reference data description: The lists other calls take their ids and codes from. security: - BearerAuth: []