Merchant API: retrieve order documents

About this article

This article explains how to retrieve, download, and acknowledge order documents via the Merchant API, including shipping labels, return labels, channel invoices, packing slips, and fiscal notes.

Introduction

Some channels attach documents to orders as part of the fulfillment process — such as shipping labels, customs forms, return labels, or compliance documents. The Merchant API provides three endpoints to work with these files: one to retrieve a list of available documents, one to download the file itself, and one to acknowledge receipt.

Acknowledging a document marks it as received on the merchant side and removes it from the unacknowledged queue. For polling-based integrations, use the OnlyUnacknowledgedByMerchant filter on GET /v2/orders/documents to retrieve only documents you have not yet processed, then acknowledge each one after successfully downloading and storing the file.

It is possible to download: 

• Shipping labels
• Return labels
• Invoices from the channel
• Packing slips
• Fiscal notes

Always consult your channel's specific guide to determine if you should use the /v2/orders/documents endpoint to retrieve the channel's documents. 

Available endpoints

Some channels attach documents to orders — such as labels, customs forms, or compliance documents. The documents endpoints let you retrieve and acknowledge these files.

• Retrieve documents: GET /v2/orders/documents
  Retrieves a collection of order documents matching your filters. Parameters: OnlyUnacknowledgedByMerchant (boolean) — when true, returns only documents you have not yet acknowledged; ChannelIds (array) — filter by channel; CreatedDateRange.FromDate / CreatedDateRange.ToDate (string) — filter by document creation date range; PageNumber / PageSize (integer) — pagination controls.
• Download a document file: GET /v2/orders/documents/file
  Downloads the actual file for a specific order document. Parameters: DocumentId (integer) — the ID of the document to download; ChannelId (integer) — the channel the document belongs to. Returns 200 OK when the file is returned, 404 Not Found if the document does not exist, or 410 Gone if the document has expired and is no longer available.
• Acknowledge a document: POST /v2/orders/documents/acknowledge
  Confirms that you have received a document. After a successful call, the document is marked as Merchant Acknowledged and will no longer appear when OnlyUnacknowledgedByMerchant is true. Fields: DocumentId (integer, required) — the ID of the document to acknowledge; ChannelId (integer, optional) — the channel the document belongs to.