Extracts the shipping address (shippingAddress) from Etsy order documents — PDF receipts or CSV exports — submitted as base64-encoded content. No call is made to the Etsy API; the address is parsed directly from the uploaded document.
This endpoint solves a specific Etsy restriction: when third-party shipping is enabled, Etsy hides the buyer's address in its API. However, the address remains accessible in the downloadable PDF receipts and the official EtsySoldOrders.csv export. By uploading those documents directly, EcartAPI returns the shippingAddress in the unified canonical format.
Note: This endpoint is exclusive to Etsy. Authentication uses a JWT ecommerce token bound to an Etsy store — the platform is resolved from the token, not from a path parameter.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Available platforms
This endpoint is supported by 1 platform.
How it works
Submit one or more documents (PDF or CSV) base64-encoded in the orders array. EcartAPI decodes each document, locates the shipping block, and returns a canonical shippingAddress for every order found.
| Format | Source | Orders produced |
|---|---|---|
pdf | Etsy order receipt or label | 1 per document |
csv | EtsySoldOrders.csv official export | 1 per data row |
Results from all documents are flattened into a single orders array, preserving input order. You can mix PDF and CSV documents in the same request.
Request payload
{
"orders": [
{
"content": "<BASE64_ENCODED_DOCUMENT>",
"format": "pdf"
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
orders | array | Yes | Array of documents. Minimum 1 item. Maximum request body: 20 MB. |
orders[].content | string | Yes | Full document encoded in base64. |
orders[].format | string | Yes | Document format. Accepted values: pdf or csv. |
Response shape
{
"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
}
}
]
}shippingAddress field notes
| Field | CSV | Notes | |
|---|---|---|---|
firstName | Full name from "Ship to" block | Full Name (or First Name + Last Name) | Etsy provides a single name field |
lastName | null | null | Always null — name is not split |
email | Extracted from buyer line NAME ([email protected]) | null | CSV exports do not include buyer email |
address1 | First address line | Street 1 column | |
address2 | Second address line | Street 2 column | null when not present |
city | City from address block | Ship City column | |
state | State resolved to ISO codes | Ship State resolved to ISO codes | |
postalCode | ZIP/postal code | Ship Zipcode column | |
country | Country resolved to ISO codes | Ship Country resolved to ISO codes | |
phone, company, references, latitude, longitude | null | null | Not available in Etsy documents |
Error responses
400 Bad Request
Returned when the document is valid but the shipping address block cannot be located, the base64 content is not decodable, or a PDF has no extractable text layer.
{
"statusCode": 400,
"error": "Bad Request",
"message": "The shipping address could not be located in the document"
}422 Unprocessable Entity
Returned when request validation fails — for example, an unsupported format value.
{
"statusCode": 422,
"error": "Unprocessable Entity",
"message": "\"orders[0].format\" must be one of [pdf, csv]",
"ecartapiError": true
}