Orders Extract (Etsy)

What is Orders Extract?

Orders Extract is a helper resource that reads an Etsy order document you already have — the official Orders CSV export or an order PDF — and returns the buyer's shipping address mapped into the canonical EcartAPI order shape.

It exists to solve a very specific Etsy limitation: unless your app is an approved third-party shipping provider, Etsy's API hides the buyer's full shipping details. As a result, a normal GET /api/v2/orders/{id} on Etsy will not include the complete address you need to print a label or request a rate. Orders Extract works around this by parsing a document you download from your own Etsy shop — no special partnership required and no outbound call to fetch the document.

Strongly recommended: use CSV. The CSV export already contains clean, column-based shipping data for many orders at once, so parsing is exact and you can process a whole batch in a single request. PDF parsing is also supported for individual Etsy order documents, but it relies on reading the "Ship to" text block and is more sensitive to layout/formatting. Prefer CSV whenever possible; use PDF only for one-off orders.

Do you need this?

You only need Orders Extract if Etsy is hiding the shipping address from your integration — which depends on when your integration was created and the marketplace (country you ship from). Older integrations (created before the cutoff date for their country) keep receiving the address normally and do not need this resource.

➡️ For the full background, the per-marketplace cutoff dates, and how to tell if you're affected, see Why is my Etsy shipping address missing?.

API endpoint

• Authentication: standard ecommerce JWT — send Authorization: Bearer <token>. The platform (Etsy) is resolved from the token; you do not pass it in the body.
• No order id in the path. This resource does not depend on an existing order id and performs no outbound request to fetch the document — you upload the content yourself.
• Maximum payload size: 10 MB. The document(s) travel as base64 inside the JSON body, which inflates their size by roughly 33%. Requests larger than 10 MB are rejected with 413 Request Entity Too Large. Because PDFs are heavy, only a couple fit per request — another reason to prefer CSV.

Request

Body

{
  "orders": [
    { "content": "<BASE64_OF_THE_DOCUMENT>", "format": "csv" },
    { "content": "<BASE64_OF_THE_DOCUMENT>", "format": "pdf" }
  ]
}

How results are counted

• A PDF document represents one order → yields one order in the response.
• A CSV document (Etsy "Orders" export) represents many orders → yields one order per data row.
• All results across all documents are flattened into a single orders array, in the same order they were sent (each PDF contributes 1, each CSV contributes N).

Response

200 OK

{
  "success": true,
  "orders": [
    {
      "id": "1000000001",
      "number": "1000000001",
      "shippingAddress": {
        "id": null,
        "firstName": "MARIA EXAMPLE",
        "lastName": null,
        "dni": null,
        "identificationNumber": null,
        "address1": "FALSE STREET 123",
        "address2": null,
        "interiorNumber": null,
        "address3": null,
        "country": { "code": "MX", "name": "Mexico", "codeIso2": "MX", "codeIso3": "MEX" },
        "state": { "code": "CO", "name": "Coahuila de Zaragoza", "codeIso2": "CO", "codeIso3": "COA" },
        "city": "SAMPLE CITY",
        "postalCode": "00000",
        "phone": null,
        "email": "[email protected]",
        "company": null,
        "references": null,
        "latitude": null,
        "longitude": null
      }
    }
  ]
}

Notes:

• Each order uses the same canonical schema as the orders response. Only the fields that can be recovered from the document are populated (id, number, shippingAddress); every other order field defaults to its usual value (mostly null).
• Country and state ISO codes are normalized by the internal address validator.
• email: extracted from the PDF (Etsy prints it next to the buyer name as NAME ([email protected])). The CSV export does not include the buyer email, so email is null for CSV-derived orders.

Store validation (important behavior)

To make sure the uploaded document actually belongs to your connected Etsy shop, the resource validates the extracted data against Etsy before returning it. This applies to both CSV and PDF requests:

1. It takes the first and the last extracted order of the whole result set (at most 2 lookups; a single order is checked once).
2. For each, it performs a getSingle (fetches the order/receipt by id) on your Etsy shop.
3. If both are found (Etsy responds 200), the full result is returned.
4. If any of them cannot be retrieved from the store, the whole request fails with 400 Bad Request confirming the ids could not be recovered from the shop.

This adds up to two extra calls to Etsy and a small amount of latency, but it guarantees that the ids/addresses you receive are real orders in your shop.

Errors

All business errors from this resource are returned with "ecartapiError": false (to distinguish them from framework request-validation errors, which use true).

Example error body:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "The extracted order ids could not be retrieved from the store: 1000000001",
  "ecartapiError": false
}

How to get the CSV from Etsy

Etsy provides an official export of your sold orders. To download it:

1. Sign in to Etsy.com and open Shop Manager.
2. Go to Settings → Options.
3. Open the Download Data tab.
4. Under Orders, choose the type Order Item Data / Sold Orders (the "Orders" export, downloaded as EtsySoldOrders.csv). Optionally pick a month and year, or leave it to export everything available.
5. Click Download CSV. Etsy generates the file EtsySoldOrders.csv.
6. Base64-encode the file and send it as content with format: "csv".

The Etsy Orders export includes (among others) these columns, which the resource maps to the canonical address:

Header matching is case-insensitive; column order does not matter. A CSV whose header has none of the address columns is rejected with 400.

CSV formatting tip: fields that contain commas (e.g. AVENIDA 2, 905) must be quoted ("AVENIDA 2, 905"), which is how Etsy exports them. If you edit the file and remove the quotes, the columns will misalign.

How to get the PDF from Etsy

For a single order, open the order in Shop Manager → Orders & Shipping, and use Print → Order receipt / packing slip (or your browser's "Save as PDF"). Base64-encode that PDF and send it with format: "pdf". Remember the PDF must contain a real text layer (a scanned image without OCR cannot be parsed).

Quick recipe (base64)

Encoding a file to base64 before sending it:

# CSV
base64 -i EtsySoldOrders.csv | tr -d '\n'

# PDF
base64 -i order-2098218716.pdf | tr -d '\n'

Then place the resulting string into content and POST to /api/v2/orders/extract.