Customer-Supplied Labels: Send by API or Upload in the Warehouse

Some customers buy their own shipping labels and send the PDF with the order. Register that PDF as the order label — by API when the order is created, or by uploading it on the order page — and the warehouse will print and stick it as-is, without buying another label.

A customer-supplied label only counts as a label when three things come with the PDF: the tracking number, the carrier, and a standard 4×6 inch single-page label file. A PDF without a tracking number is just a file — the system will not treat it as a label. Once registered, the label card on the order shows the carrier, service and tracking number, and batch shipping (WMS → Outbound Orders → Label-first batch shipping) will use this label first and charge no freight for the order — only the warehouse handling of printing and sticking applies.

Option A: the customer sends the label with the order (API)#

1. When creating the order through the orders API, add the label block: the PDF (as a file reference or base64), the tracking number and the carrier code; the service code is optional. Your integration team can find the exact fields in the API documentation for creating an order.
2. The order is always created. If the label cannot be registered — wrong size, more than one page, or the tracking number is already used by another order — the response says so plainly in the label result, and the order itself stays valid. Fix the file and register it afterwards from the order page (Option B) instead of re-creating the order.
3. One tracking number can belong to only one order at a time. If the same number arrives twice, the second registration is refused with a clear message — check whether the file was sent to the wrong order before trying again.

Option B: upload it in the warehouse#

1. Open the order (OMS → Orders → open the order) or its outbound order (WMS → Outbound Orders → open the order). Both pages carry the same “Customer-supplied label” card — what you upload on one side shows on the other.
2. Choose the PDF file, confirm the tracking number and carrier (the card pre-fills what the order already declares — check it against the paper label), then upload. A new upload replaces the current label automatically; the old one stops being valid, so there is never a mix-up about which label is live.
3. Wrong file? Use “Void” on the card to release the tracking number, then upload the right one. If the tracking number on the label differs from what the order declared, the registered label wins and the order is updated to the label number — the number on the physical label is the one the carrier recognises.

Features used in this article#

• Customer-supplied label card (view, upload, replace, void) — OMS → Orders → order detail (/oms/orders) and WMS → Outbound Orders → order detail (/wms/orders)
• Label block on the create-order API — see the API documentation for creating an order (/api/oms/orders)
• Label-first batch shipping uses the registered label first — WMS → Outbound Orders → Label-first batch shipping (/wms/orders)