Connect your Etsy shop to EcomCentral using the Etsy Open API v3 with OAuth2 bearer authentication and an app keystring.
x-api-key: {keystring} (your app's API key) and
Authorization: Bearer {access_token} (an OAuth2 user token for the seller account).
Using only one of the two will result in a 401 error.
refresh_token returned during the OAuth2 flow and use it to
obtain a new access token before it expires. EcomCentral stores the token you provide; it does not
automatically refresh it.
api_keyaccess_token valueGET https://openapi.etsy.com/v3/application/users/me with your token — the response includes shop_idshop_id, api_key, and access_token/users/me and confirms the credentials are valid| Scope | Used For |
|---|---|
transactions_r |
Read orders (receipts) and their transactions |
transactions_w |
Add tracking / create shipments on receipts |
listings_r |
Read listings (products) and their inventory |
| Key | Required | Description | Example |
|---|---|---|---|
shop_id |
Required | Numeric Etsy shop ID — found in /users/me response or your shop admin URL. Must be a number, not the shop slug. |
12345678 |
api_key |
Required | App keystring from your Etsy developer app dashboard (also called the "Keystring" or "App ID") | a1b2c3d4e5f6… |
access_token |
Required | OAuth2 bearer token for the seller account. Expires after 3600 seconds — update the connection when the token is refreshed. | ExAmPlEtOkEn… |
shopId for the shop ID; apiKey or key for the API key;
token for the access token.
| Operation | Method | Endpoint |
|---|---|---|
| Test connection | GET | /users/me |
| List orders (receipts) | GET | /shops/{shop_id}/receipts?limit=N&offset=N |
| Order detail | GET | /shops/{shop_id}/receipts/{receipt_id} |
| List listings | GET | /shops/{shop_id}/listings?limit=N&offset=N&state=active |
| Listing detail + images | GET | /listings/{listing_id}?includes=Images,MainImage |
| Listing inventory | GET | /listings/{listing_id}/inventory |
| Add tracking | POST | /shops/{shop_id}/receipts/{receipt_id}/tracking with tracking_code, carrier_name |
https://openapi.etsy.com/v3/application.
Tracking is submitted as application/x-www-form-urlencoded; all other write bodies use JSON.
| Status | Meaning |
|---|---|
| paid | Payment has been received; order is being prepared |
| payment processing | Payment is in progress but not yet confirmed |
| open | Order is open and awaiting fulfillment |
| completed | Order has been fulfilled and marked complete |
| shipped | Order has been dispatched with tracking |
| canceled | Order has been cancelled by the buyer or seller |
| refunded | Payment has been refunded to the buyer |
status. Note that Etsy uses "canceled" (one L, US spelling).
| Feature | Supported | Notes |
|---|---|---|
| View orders / receipts (paginated) | ✅ | Receipt ID, date (UNIX timestamp), status, customer name, grand total |
| View order detail | ✅ | Customer, shipping address, shipments, line-item transactions, subtotal/shipping/grandtotal |
| Add tracking | ✅ | Requires carrier_name + tracking_code; uses transactions_w scope. Defaults carrier to other if not provided. |
| View listings (paginated) | ✅ | Listing ID, title, price, quantity, state |
| View listing detail + inventory | ✅ | Title, price, SKUs, images, description, tags, per-variant inventory quantities |
| Update stock quantity | ❌ | Not supported — see Limitations below |
| Test connection | ✅ | Calls GET /users/me; verifies both x-api-key and access_token are valid |
The Etsy PUT /listings/{listing_id}/inventory endpoint requires the caller to supply
the complete and current products array — every SKU, every offering, every
property_values entry — on every update. Etsy replaces the entire inventory object
atomically; there is no patch or partial-update endpoint.
A naive single-SKU write that omits other offerings would silently delete those offerings.
To update one quantity safely, the caller must first GET /inventory, mutate the target
offering's quantity in-memory, then PUT the full modified array back.
update_stock on Etsy v3
connections to prevent accidental data loss. Use the Etsy seller dashboard or a dedicated
inventory management tool that implements the full read-modify-write cycle.
The access_token has expired (Etsy tokens live for 3600 seconds) or is invalid.
Re-run the OAuth2 flow for your seller account to obtain a fresh token, then update the connection
in EcomCentral. Also verify the api_key (keystring) matches the app you used during
the OAuth2 flow.
The access token was granted without one of the required scopes (transactions_r,
transactions_w, or listings_r). Scopes cannot be added to an existing
token — re-run the OAuth2 authorization flow and explicitly request all three scopes, then update
the connection with the new token.
The shop_id must be the numeric ID for your Etsy shop, not the
shop slug or URL name (e.g. 12345678, not MyHandmadeStore).
To find your numeric shop ID, call GET /users/me with a valid token — the response
body includes a shop_id field with the correct value.
Etsy requires both tracking_code and carrier_name to be non-empty
strings. If you leave the carrier field blank in EcomCentral the value other is
used automatically. Verify the receipt ID is correct and that the receipt is in a shippable state
(paid or open) — already-shipped receipts may reject duplicate tracking entries.