Sending documents

You can send three documents with an order: a commercial invoice, a packing list and a materials safety data sheet. Send them in the same request as Create an order. The API has no call to add or replace one afterwards.

Sending files with the order

A request carrying files is sent as multipart/form-data instead of JSON. Each document is a file part, and every other field of the order becomes a form field named the way its JSON is nested:

JSON	Form field
order.quote_estimate_id	order[quote_estimate_id]
order.origin_address.city	order[origin_address][city]
each item in order.hs_codes	order[hs_codes][][code], order[hs_codes][][description], …
the commercial invoice	order[commercial_invoice] (a file)
the packing list	order[packaging_list] (a file)
the materials safety data sheet	order[materials_safety_data_sheet] (a file)

Let your HTTP library set the Content-Type header for a multipart request. Don't send Content-Type: application/json with it.

• Items: write every item in hs_codes with empty brackets, order[hs_codes][][code], and keep the fields in the same order for each item. Numbered brackets such as order[hs_codes][0][code] make the order fail.
• Items are added to the quote's. Items you send with the order are declared alongside the quote's. An item the quote already has is refused as a duplicate.
• Ids come from the environment you are calling. In the example, country_id 226 and 70 are the sandbox's South Africa and United Kingdom. Take quote_estimate_id from your own Create a quote, and purpose_of_shipment_id from List purposes of shipment.

curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/orders" \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "order[quote_estimate_id]=55788" \
  -F "order[purpose_of_shipment_id]=12" \
  -F "order[customer_reference]=GTC-PO-20417" \
  -F "order[description_of_contents]=Cotton shirts and denim trousers" \
  -F "order[origin_address][country_id]=226" \
  -F "order[origin_address][name]=Thandi Mokoena" \
  -F "order[origin_address][company]=Global Trade Corp" \
  -F "order[origin_address][address_1]=14 Bree Street" \
  -F "order[origin_address][city]=Cape Town" \
  -F "order[origin_address][postal_code]=8001" \
  -F "order[origin_address][phone]=+27 21 555 0142" \
  -F "order[destination_address][country_id]=70" \
  -F "order[destination_address][name]=Oliver Bennett" \
  -F "order[destination_address][company]=Bennett & Hale Ltd" \
  -F "order[destination_address][address_1]=221 Shoreditch High Street" \
  -F "order[destination_address][city]=London" \
  -F "order[destination_address][postal_code]=E1 6PJ" \
  -F "order[destination_address][phone]=+44 20 7946 0321" \
  -F "order[commercial_invoice]=@commercial_invoice.pdf;type=application/pdf" \
  -F "order[packaging_list]=@packing_list.pdf;type=application/pdf"

Files we accept

• Send a PDF. We turn a Word or Excel commercial invoice (.docx, .doc, .xlsx, .xls) into a PDF for you.
• Keep the commercial invoice under 2,000,000 bytes. We try to shrink a bigger PDF, but if it is still that big we can't use it, and the order waits in awaiting_additional_documentation.
• Send one file per document.

When you don't send a commercial invoice

We make one for you from the order, when the shipment crosses a border and you sent its items (hs_codes) with the quote or the order. Without items we can't make one, and the order can stop at awaiting_additional_documentation.

Reading documents back

Get an order returns a link for each document the order has, as <document>_link: commercial_invoice_link, packaging_list_link, waybill_document_link and so on. A document the order doesn't have yet comes back as "".

A document you forgot

Send it to your account manager, and once they have added it, call Create a waybill again if the order is at awaiting_additional_documentation. See Order statuses.