Connect Etsy: pull orders in, push fulfillment out
Find your numeric Shop ID in your Etsy shop admin URL, copy the API key from Etsy Developers, paste both plus your OAuth access token into Integration, test, map, activate — orders flow in and fulfillment flows back.
The Etsy connector pulls orders from your Etsy shop into OMS, and pushes fulfillment back to Etsy. It can also push products and inventory, so listings, stock, and shipping stay in sync on both sides.
Prerequisites#
- An Etsy shop, with access to its shop admin so you can read the shop admin URL.
- Access to Etsy Developers → Your apps, where the API key (KEYSTRING) for your app is shown.
- Ability to complete the OAuth authorization flow for that shop — the access token is obtained only after that flow finishes.
Get your credentials#
- Find your Shop ID: open your Etsy shop admin and look at the shop admin URL — the Shop ID is the numeric ID in that URL, for example 12345678. Copy the number only, not the shop name.
- Copy the API key: go to Etsy Developers → Your apps → copy the API key (KEYSTRING) for your app. Save it somewhere safe — you will paste it into the API key field in Integration.
- Get the OAuth access token: complete the OAuth authorization flow for your shop, then copy the access token obtained after the flow. You will paste it into the OAuth access token field in Integration.
Fill it into Integration#
- Open Integration → Connector Marketplace → Etsy → New connection.
- Shop ID: fill in the numeric ID from your Etsy shop admin URL, for example 12345678. Do not fill in the shop name — the field takes the number only.
- API key — required: paste the API key (KEYSTRING) you copied from Etsy Developers → Your apps. It is encrypted at rest and never echoed back.
- OAuth access token: paste the access token obtained after the OAuth authorization flow. Keep it with the same shop as the Shop ID above — a token for a different shop will not match.
Test the connection#
Click Test connection. The test checks the Shop ID, the API key, and the OAuth access token together, then shows a document-level preview with one real order so you can see platform fields next to the standard order. If the shop has no orders yet, place a test order in Etsy first — the preview needs one real document. If the test fails, note the error and check the FAQ below before changing anything else.
Mapping / pick a template#
Pick the Etsy standard template. It maps order number, line SKUs, quantities, ship-to address, and fulfillment status. Check the mapping preview with one real order before activating — especially that every Etsy SKU is paired to an OMS product, so orders, products, and inventory line up on both sides.
Activate#
After activation, Integration pulls new orders on the schedule you set, pushes fulfillment with tracking numbers back to Etsy, and pushes product and inventory changes to Etsy. Watch the first few orders in Runs / Logs before trusting it unattended.
FAQ#
Test fails: shop not found
The Shop ID is wrong. Most often the shop name was filled in instead of the numeric ID, so the connection looks for a shop that does not match any real shop ID.
Open your Etsy shop admin, read the numeric ID in the shop admin URL (for example 12345678), replace the Shop ID field with that number only, and test again.
Test fails with an API credential error
The API key does not match your app. It was copied incompletely, with an extra space, or it is the key of a different app in Etsy Developers, so Etsy rejects the call.
Go to Etsy Developers → Your apps, copy the API key (KEYSTRING) for the correct app again exactly as shown, paste it into the API key field without extra spaces, and test again.
Authorization has expired
The OAuth access token is no longer valid. The authorization behind it has expired, so calls that need that token are refused until the shop is authorized again.
Complete the OAuth authorization flow for the same shop again, copy the new access token obtained after the flow, replace the OAuth access token field, and test again.
Connected but no orders are pulled in
The connection itself is fine. The shop simply has no new orders in the pull range, so there is nothing to import yet.
Place a test order in your Etsy shop, check that its time falls inside the pull range, then run a manual pull and confirm the order appears in the preview or in Runs / Logs.