Amazon Easy Ship — Retrieving the Shipping Label

This guide explains how to retrieve the Amazon Easy Ship shipping label for an order through EcartAPI v2: what Easy Ship is, in which marketplaces it applies, how the retrieval works, how to detect from an order whether the label is available, and exactly when it can be obtained.

1. What is Amazon Easy Ship?

Amazon Easy Ship is a hybrid fulfillment model, sitting between selling on your own (pure MFN — Merchant Fulfilled Network) and letting Amazon store your inventory (FBA — Fulfillment by Amazon):

• The product stays in the seller's warehouse (Amazon does not store it, unlike FBA).
• The seller packs the order.
• Amazon sends a carrier to pick it up at the seller's registered address.
• Amazon coordinates the shipment to the buyer.

In short: the seller packs, Amazon picks up. The seller does not choose the carrier or buy the freight; Amazon assigns the carrier and generates the shipping label.

The shipping label in this flow

The label is the sticker the seller prints and attaches to the package before Amazon picks it up. It is generated by Amazon only after the package is scheduled (via createScheduledPackage in Seller Central or the Easy Ship API). It does not exist at the moment the order is placed.

Addresses involved

The seller does not send the pickup address per order; Amazon already knows it from the account configuration.

2. Where does Easy Ship apply? (Marketplaces)

Easy Ship exists only in select Amazon stores, and support for each operation varies. For shipping label retrieval — which is what this resource does — it is supported in 6 marketplaces:

Marketplaces with Easy Ship but without label support (only Bulk Package Scheduling), where this resource does not apply:

Note on document types: India is the only marketplace that additionally supports Invoice and Warranty documents. The other five (including Mexico) support ShippingLabel only. EcartAPI requests ShippingLabel, which is the common denominator across all six supported marketplaces.

Reference: Amazon SP-API — Easy Ship API marketplace support.

3. How does the retrieval work? (Two-phase, asynchronous)

Amazon has no synchronous "give me the label PDF" endpoint. EcartAPI drives Amazon SP-API's asynchronous Feeds (POST_EASYSHIP_DOCUMENTS) and Reports APIs under the hood, and normalizes everything behind a single route:

GET /api/v2/orders/documents

→ API reference: Get All Order Documents (Amazon v2)

Because Amazon processing is asynchronous and can take from seconds to minutes, the resource works in two phases over the same endpoint — the request never blocks waiting for Amazon, which previously caused timeouts.

Phase 1 — Request the label

Pass the orderIds query parameter (the AmazonOrderId):

GET /api/v2/orders/documents?orderIds=701-9649707-7361850

EcartAPI creates the Amazon feed and returns immediately with a requestId:

{
  "success": true,
  "document": {
    "binary": null,
    "url": null,
    "requestId": "50123018909",
    "status": "PROCESSING",
    "type": null
  }
}

Phase 2 — Poll for the label

Pass the requestId returned by Phase 1:

GET /api/v2/orders/documents?requestId=50123018909

While Amazon is still processing:

{
  "success": true,
  "document": {
    "binary": null,
    "url": null,
    "requestId": "50123018909",
    "status": "IN_PROGRESS",
    "type": null
  }
}

Once ready, the label PDF is returned as base64:

{
  "success": true,
  "document": {
    "binary": "JVBERi0xLjQKJ...==",
    "url": null,
    "requestId": null,
    "status": null,
    "type": "application/pdf"
  }
}

Standardized response schema

Every response returns the same five keys, using null for the ones that do not apply to the current phase:

Errors surfaced from Amazon

If Amazon cannot produce the label, EcartAPI extracts the underlying reason from the feed processing report and returns a 404:

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Amazon could not retrieve the Easy Ship label: Order is already shipped (MSF_ERROR_CODE_610004)",
  "ecartapiError": true
}

These errors typically mean the order is outside the retrievable window — not scheduled yet, or already shipped/cancelled. See the timeline below.

Authentication

Send the EcartAPI store access token in the Authorization header — this is the token your app obtained when the Amazon store was connected via EcartAPI's OAuth flow, not any Amazon credential. EcartAPI resolves the Amazon store from that token, so no ecommerce query param is required.

This endpoint requires v2. Make sure your app is configured to use Amazon v2. See Amazon — API Version Setup.

4. How to identify an order that can return the label

Read the order from Get All Orders or Get a Single Order and check two conditions:

Condition A — It is an Easy Ship order

The raw Amazon order programs array includes AMAZON_EASY_SHIP. In the normalized EcartAPI order this is surfaced as:

{ "logistic": { "mode": "AMAZON_EASY_SHIP" } }

Note: Amazon omits the programs array entirely when an order has no special programs. If logistic.mode is absent or not "AMAZON_EASY_SHIP", the order is simply not Easy Ship.

Condition B — The package is scheduled and not yet handed to the carrier

The label only exists once the package is scheduled, and Amazon only serves it until the carrier takes the package. EcartAPI evaluates this internally — you do not need to read a detailedStatus field from the API response. The practical signal is in Condition A's result below.

Context only: Internally EcartAPI checks Amazon's package detailedStatus. The label is considered available when it is PENDING_PICK_UP (carrier collects from the seller) or PENDING_DROP_OFF (seller hands to carrier). All other statuses — including post-shipment states like PICKED_UP, IN_TRANSIT, or DELIVERED — are treated as not retrievable.

When both conditions are true

EcartAPI exposes the label URL directly on the order response. This is the only field you need to check in practice:

{
  "shippingLabel": "https://api.ecartapi.com/api/v2/orders/documents?orderIds=701-9649707-7361850",
  "documents": {
    "shippingLabels": [
      "https://api.ecartapi.com/api/v2/orders/documents?orderIds=701-9649707-7361850"
    ]
  }
}

If shippingLabel and documents.shippingLabels are absent (or null) on the order, the label is not retrievable yet (or anymore) — no need to call the documents endpoint.

5. When is the label available? (Timeline)

1. Order created — fulfillmentStatus = UNSHIPPED, no packages yet → not scheduled → no label. shippingLabel will be absent on the order.
2. Package scheduled → label available. shippingLabel appears on the order. This is the retrievable window and the moment your integration should fetch and print the label.
3. Carrier takes the package — package enters shipment → Amazon stops serving the label → no label. shippingLabel disappears from the order.
4. Label cancelled or order cancelled → no label.

In one sentence: the label is available from the moment the package is scheduled until just before it is handed to the carrier. Outside that window Amazon does not serve it, and EcartAPI will not expose shippingLabel on the order.

6. Quick recap

Related resources

• Get All Order Documents (Amazon v2) — API reference for the endpoint
• Get All Orders (Amazon v2) — retrieve the order list to find Easy Ship orders
• Get a Single Order (Amazon v2) — retrieve full order details including logistic.mode and packages
• Amazon — API Version Setup — how to configure v2 for your app
• Orders Resource Guide — EcartAPI normalized order schema reference