Order API developer guide

Send structured orders to Packlistly and read their document-checking results. Starter, Expert, Pro and Enterprise include the Order API, including eligible card-free trials. Free does not include API keys.

Authentication and access

1. The company owner signs in and sets up two-step verification.
2. Open Integrations. Give the integration key a name and select import to create/update orders and/or read to read results and download documents.
3. Use Authorization: Bearer YOUR_INTEGRATION_KEY. Treat the key as a secret, keep it in your server or automation credential settings, and revoke it from Integrations when no longer needed.

Requests run within the key owner's company. The account must retain the relevant plan, two-step verification and create/export permissions.

POST /api/v1/orders

Send JSON with exactly two top-level fields: external_id (non-empty string, at most 160 characters) and shipment (object). Maximum request body: 2 MiB (2,097,152 bytes); maximum 2000 lines and 2000 packing rows. Keep a stable external reference for retries. Repeating an unchanged payload with the same external_id returns 200 and changed=false; a new or changed payload returns 201 and changed=true. Changed data updates the same saved shipment and requires checks/approval to be reviewed again.

201: created/changed. 200: unchanged retry. 401: invalid key, scope, account or permissions. 409: allowance/quota refusal. 413: body over 2 MiB. 422: malformed or unsupported input. These routes do not declare an additional per-minute request count; body/row limits and plan shipment allowances still apply. Infrastructure limits may also apply.

Fictional request

{"external_id":"fictional-cedar-24017","shipment":{"seller":{"name":"Fictional Cedar Machinery LLC","address":"100 Example Road","country":"US"},"buyer":{"name":"Fictional Buyer","address":"200 Example Road","country":"CA"},"terms":{"invoice_no":"FC-24017","invoice_date":"2026-10-30","currency":"USD"},"lines":[{"sku":"PUMP-01","description":"Fictional pump assembly","qty":"24","unit":"pcs","unit_price":"10.00","origin":"US"}]}}

Response excerpt (other report fields described below):

{"changed":true,"report":{"shipment_id":"fictional-sample","status":"needs_attention","review_required":true}}

Complete import field reference

Optional means a model default exists, not that the shipment is ready to export. Missing business data is assessed by the rule engine. Decimal fields accept JSON numbers or decimal strings. Fields ending _kg use kilograms, _cm use centimetres; *_in_file values use weight_unit_in_file (kg/lb) or dim_unit_in_file (cm/in). Monetary values use terms.currency. Date strings are documented in the field names/schema; model types alone do not establish customs validity.

Only the shipment fields listed here can be imported; server metadata and other Shipment model fields are not accepted. In particular forwarder_instructions, usmca, vgm, components and display-unit settings are not Order API input fields. Download the exact input JSON schema.

shipment fields

Field	Required	Type, default and constraints
seller	No	{"$ref": "#/$defs/Party"}
buyer	No	{"$ref": "#/$defs/Party"}
consignee	No	{"$ref": "#/$defs/Party"}
importer_of_record	No	{"$ref": "#/$defs/Party"}
terms	No	{"$ref": "#/$defs/Terms"}
marks	No	{"$ref": "#/$defs/Marks"}
notes	No	{"items": {"type": "string"}, "title": "Notes", "type": "array"}
lines	No	{"items": {"$ref": "#/$defs/LineItem"}, "title": "Lines", "type": "array"}
packing	No	{"items": {"$ref": "#/$defs/PackingLine"}, "title": "Packing", "type": "array"}
flags	No	{"items": {"$ref": "#/$defs/Flag"}, "title": "Flags", "type": "array"}

Flag fields

Field	Required	Type, default and constraints
path	Yes	{"title": "Path", "type": "string"}
reason	Yes	{"title": "Reason", "type": "string"}
resolved	No	{"default": false, "title": "Resolved", "type": "boolean"}

LineItem fields

Field	Required	Type, default and constraints
id	No	{"title": "Id", "type": "string"}
sku	No	{"default": "", "title": "Sku", "type": "string"}
description	No	{"default": "", "title": "Description", "type": "string"}
hs_code	No	{"default": "", "title": "Hs Code", "type": "string"}
origin	No	{"default": "", "title": "Origin", "type": "string"}
qty	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Qty"}
unit	No	{"default": "pcs", "title": "Unit", "type": "string"}
unit_price	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Unit Price"}
no_charge	No	{"default": false, "title": "No Charge", "type": "boolean"}
customs_value_per_unit	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Customs Value Per Unit"}
stated_line_total	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Stated Line Total"}
eccn	No	{"default": "", "title": "Eccn", "type": "string"}
license_type	No	{"default": "", "maxLength": 80, "title": "License Type", "type": "string"}
lot_no	No	{"default": "", "title": "Lot No", "type": "string"}
expiry_date	No	{"default": "", "title": "Expiry Date", "type": "string"}
un_number	No	{"default": "", "title": "Un Number", "type": "string"}
dg_class	No	{"default": "", "title": "Dg Class", "type": "string"}
packing_group	No	{"default": "", "title": "Packing Group", "type": "string"}
proper_shipping_name	No	{"default": "", "title": "Proper Shipping Name", "type": "string"}
declaration	No	{"default": "", "title": "Declaration", "type": "string"}
usmca_criterion	No	{"default": "", "enum": ["", "A", "B", "C", "D"], "title": "Usmca Criterion", "type": "string"}
usmca_confirmed	No	{"default": false, "title": "Usmca Confirmed", "type": "boolean"}

Marks fields

Field	Required	Type, default and constraints
consignee_mark	No	{"default": "", "title": "Consignee Mark", "type": "string"}
destination	No	{"default": "", "title": "Destination", "type": "string"}
po_number	No	{"default": "", "title": "Po Number", "type": "string"}
handling	No	{"items": {"type": "string"}, "title": "Handling", "type": "array"}
extra_lines	No	{"items": {"type": "string"}, "title": "Extra Lines", "type": "array"}
language	No	{"default": "en", "enum": ["en", "en_es"], "title": "Language", "type": "string"}
paper	No	{"default": "Letter", "enum": ["Letter", "A4"], "title": "Paper", "type": "string"}
label_size	No	{"default": "4x6", "enum": ["4x6", "letter_2", "a4_4"], "title": "Label Size", "type": "string"}
temperature	No	{"default": "", "title": "Temperature", "type": "string"}

PackingLine fields

Field	Required	Type, default and constraints
shares_cartons_with_previous	No	{"default": false, "title": "Shares Cartons With Previous", "type": "boolean"}
pallet	No	{"default": "", "title": "Pallet", "type": "string"}
weight_unit_unconfirmed	No	{"additionalProperties": {"type": "string"}, "title": "Weight Unit Unconfirmed", "type": "object"}
id	No	{"title": "Id", "type": "string"}
sku	No	{"default": "", "title": "Sku", "type": "string"}
carton_from	No	{"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "title": "Carton From"}
carton_to	No	{"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "title": "Carton To"}
cartons	No	{"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "title": "Cartons"}
per_carton	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Per Carton"}
packed_qty	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Packed Qty"}
unit	No	{"default": "pcs", "title": "Unit", "type": "string"}
length_cm	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Length Cm"}
width_cm	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Width Cm"}
height_cm	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Height Cm"}
net_kg	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Net Kg"}
gross_kg	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Gross Kg"}
weight_unit_in_file	No	{"default": "kg", "enum": ["kg", "lb"], "title": "Weight Unit In File", "type": "string"}
net_in_file	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Net In File"}
gross_in_file	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Gross In File"}
dim_unit_in_file	No	{"default": "cm", "enum": ["cm", "in"], "title": "Dim Unit In File", "type": "string"}
length_in_file	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Length In File"}
width_in_file	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Width In File"}
height_in_file	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Height In File"}
tare_kg_per_carton	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Tare Kg Per Carton"}
glaze_pct	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Glaze Pct"}
kit_part	No	{"default": "", "title": "Kit Part", "type": "string"}
package	No	{"default": "", "title": "Package", "type": "string"}
lot_no	No	{"default": "", "title": "Lot No", "type": "string"}
expiry_date	No	{"default": "", "title": "Expiry Date", "type": "string"}

Party fields

Field	Required	Type, default and constraints
name	No	{"default": "", "title": "Name", "type": "string"}
address	No	{"default": "", "title": "Address", "type": "string"}
country	No	{"default": "", "title": "Country", "type": "string"}
tax_id	No	{"default": "", "title": "Tax Id", "type": "string"}
phone	No	{"default": "", "title": "Phone", "type": "string"}
email	No	{"default": "", "title": "Email", "type": "string"}

Terms fields

Field	Required	Type, default and constraints
tracking_number	No	{"default": "", "title": "Tracking Number", "type": "string"}
carrier_name	No	{"default": "", "title": "Carrier Name", "type": "string"}
invoice_no	No	{"default": "", "title": "Invoice No", "type": "string"}
invoice_date	No	{"default": "", "title": "Invoice Date", "type": "string"}
incoterm	No	{"default": "", "title": "Incoterm", "type": "string"}
named_place	No	{"default": "", "title": "Named Place", "type": "string"}
transport_mode	No	{"default": "", "enum": ["sea", "inland_waterway", "air", "road", "rail", "multimodal", "courier", ""], "title": "Transport Mode", "type": "string"}
currency	No	{"default": "USD", "title": "Currency", "type": "string"}
payment_terms	No	{"default": "", "title": "Payment Terms", "type": "string"}
destination_country	No	{"default": "", "title": "Destination Country", "type": "string"}
stated_total	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Stated Total"}
stated_cartons	No	{"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "title": "Stated Cartons"}
stated_net_kg	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Stated Net Kg"}
stated_gross_kg	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Stated Gross Kg"}
itn	No	{"default": "", "title": "Itn", "type": "string"}
eei_note	No	{"default": "", "title": "Eei Note", "type": "string"}
discount	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Discount"}
freight	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Freight"}
insurance	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Insurance"}
other_charges	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Other Charges"}
other_charges_label	No	{"default": "", "title": "Other Charges Label", "type": "string"}
charges_scope	No	{"default": "", "title": "Charges Scope", "type": "string"}
pallets	No	{"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "title": "Pallets"}
pallet_kg	No	{"anyOf": [{"type": "number"}, {"type": "string"}, {"type": "null"}], "default": null, "title": "Pallet Kg"}
reason_for_export	No	{"default": "Sale", "title": "Reason For Export", "type": "string"}
signer_name	No	{"default": "", "title": "Signer Name", "type": "string"}
signer_title	No	{"default": "", "title": "Signer Title", "type": "string"}

GET /api/v1/shipments/{id}

Use a read-scoped key. Returns 200 with {"report":{...},"shipment":{...}}, or 404 when the company has no such shipment; authentication failures return 401. The shipment contains saved model data, including server metadata, which must not be copied wholesale into an import request.

Report structure

Fields: shipment_id, invoice_no, status, version, content_fingerprint, approved, prepared_by, approved_by, documents_current, review_required, checks, not_checked, revision_count, generated_at and scope. status is needs_attention, awaiting_approval, approved or checked. checks is an array of objects containing id, kind (fix/answer/pass/info), title, detail, compare (triples of strings), options (id/label/input_label/input_placeholder), accepted_exception and source. not_checked lists checks outside the tool's scope. Results describe document consistency; the exporter remains responsible for review.

GET /api/v1/shipments/{id}/documents.zip

Use a read-scoped key. Returns a ZIP named checked_documents.zip containing the applicable generated PDFs and control_report.json. Returns 409 with an error and report while blocking checks or required approval are outstanding; 404 for a missing shipment; 401 for authentication failure. Generation uses the account's existing document allowance and approval rules.

Connect with Zapier or Make

Use generic HTTP tools; no dedicated Packlistly app is needed for these steps.

Webhooks by Zapier

1. Add your order trigger, then Webhooks by Zapier → Custom Request.
2. Choose POST and your Packlistly origin followed by /api/v1/orders.
3. Add the Authorization header shown above and Content-Type: application/json. Keep the key private.
4. Map external_id and a nested shipment JSON body using the example. Keep nested arrays intact and leave automatic unflattening off when using an already nested raw JSON body.
5. Test with fictional data in your own authorized test workspace. Inspect changed and report.review_required; retrieve results with GET using the returned shipment_id. Retain the same external_id on retries.

Zapier's sending-webhooks instructions

Make

1. Add your order trigger, then HTTP → Make a request.
2. Choose POST and your Packlistly origin followed by /api/v1/orders. Configure Authorization: Bearer using a private credential/header configuration.
3. Select application/json and map the nested external_id/shipment body, including line and packing arrays.
4. Parse the response. Route review_required orders to a person; do not assume every 201 result is ready for release.
5. Use a read-scoped GET step for results or documents.zip after checks and approval. Keep the external reference stable when retrying.

Make HTTP documentation