Elbuz pulls your Etsy shop's active listings and orders, keeps a single stock level for all channels, and sends prices, stock and new listings back to Etsy.
When you need this:
- You sell on Etsy and on your website or social media: with one stock level, an item sold in one channel can't sell twice.
- Orders from all channels go together: Etsy receipts join the same document queue.
- You change prices and stock in Elbuz: the export updates your listings.
- New products go on Etsy: Elbuz creates a listing with photo, price and SKU.
Where to start: link your shop with a code in an import template of type “Etsy”.
What the Etsy connection can do
- Imports active listings: title, description, SKU, price, stock, tags, materials, category and photos.
- Pulls orders: Etsy receipts become “Customer order” documents with the buyer and address.
- Updates prices and stock in linked listings through a separate export template.
- Publishes new listings from your cards, with photo, price and SKU.
- Runs on its own: orders every 5 minutes, the catalog on a schedule; on the server, with no browser open.
What you need from Etsy: a link code
You don't need to register an app with Etsy or deal with keys. You approve access to your shop and enter a short link code. After that the token is refreshed automatically: Etsy access tokens are short-lived, and renewing them by hand would be a daily chore.
How to connect, step by step
- Create a template of type “Etsy” and save it: linking works only for a saved template. “Active” and “Orders” are already on in a new template: 5 minutes after linking, Elbuz starts picking up orders. Elbuz maps marketplace statuses to yours by itself, by name; what arrived and how it was mapped is shown in the template's “Order statuses” window. Want to check first? Untick “Orders”.
- Click “Connect”, approve access in the Etsy window and copy the code.
- Paste the code into the form right away: it expires quickly.
- Click “Test connection”: the response should include your shop ID.
- Tick products and photos and start a run manually. Compare a few cards and orders with your Etsy account, then put the catalog on a schedule.
There is one link per Etsy account, and it is stored at the level of your Elbuz account, not the template. Linked in the import template? The export template uses the same access, and vice versa. Disabling or deleting one template doesn't break the link.
Fields of the “Connection” card
| Field | What it's for |
|---|---|
| Shop | Your shop's ID. You can leave it empty: Elbuz will find it on its own |
| Shipping profile ID | Your Etsy shipping profile. Needed only for publishing new listings |
The marketplace's documentation for sellers: Etsy Open API v3. You create a shipping profile in your seller account, in the shipping settings.
What goes into the card
Elbuz pulls your shop's active listings together with their photos and inventory data.
| Etsy data | Product field in Elbuz |
|---|---|
| listing title | Name |
| description | Description |
| SKU | |
| offering price | Price |
| quantity | Stock |
| listing state | Status: active means an enabled product |
| listing tags | Tags |
| materials | The “Material” attribute |
| taxonomy (Etsy category) | Category |
| photos | Photos (if the checkbox is on) |
Price and stock come from the listing's inventory block, the one Etsy shows the buyer. Only if it's missing does Elbuz take the values from the listing itself.
Category: the Etsy taxonomy dictionary
Etsy sends the category as a numeric taxonomy code. Elbuz takes the readable name from a dictionary that you load separately: the “Marketplace Category and Attribute Mapping” window → the Etsy toggle → “Load marketplace dictionary”.
Until the dictionary is loaded, products land in the service category “Products - etsy”, which is disabled and excluded from exports. No data is lost: move the products into your own tree, and they will keep updating there. More: service categories.
What a repeat run does with your edits
A product is recognized by its name: Elbuz looks for a card created under the same listing title. If it finds one, it overwrites it; if not, it creates a new one. The SKU and listing number play no part in the search.
- Overwritten: name, description, price, quantity, stock status, the “enabled” flag, tags, SKU.
- Empty values from Etsy don't erase yours: the old (strikethrough) price and the barcode, which Etsy doesn't send, stay; a listing without tags or SKU won't wipe yours.
- Left alone on an existing card: photos and the “Material” attribute (only new cards get them), and the place in the category tree.
- A product you disabled by hand gets enabled again: only active listings come from Etsy, so the run writes “enabled”.
You can lock a card in the “Import protection” section: “Do not update” makes the run skip it entirely, “Fixed Price” keeps only the prices. More: how to lock your own value.
- Action or result
- Decision: the path depends on the answer
If you change a listing title in your Etsy account, the next run won't recognize the old card and will create a new one, while the previous card keeps the old numbers. If you change the name in Elbuz, the run finds the card by the original title and restores the name from Etsy.
A listing disappeared from Etsy
Elbuz asks Etsy for active listings only. A listing that was deactivated, hidden, is a draft or sold out doesn't get into the run, and nothing happens to its card:
- the last price, last stock and the “enabled” flag stay;
- zero stock won't arrive, because a sold-out item isn't in the run;
- the log has no line about it, and the Etsy template has no checkbox for deleting missing products.
Remove such cards by hand in the “Products” window using the “Source - name” column. The general rule: a product disappeared from the source.
In the other direction, Elbuz never deactivates a listing. If you remove a product from the export, the Etsy listing stops updating and stays active with the last numbers. You can deactivate it only in your Etsy account.
How to receive Etsy orders
On Etsy, orders are receipts; line items come with them. The first run imports the history; later runs request receipts created after the last import date, which Elbuz stores in the template on its own.
A receipt becomes a “Customer order” document, not posted: stock and reservations don't change until the document is posted. The document gets:
- the receipt number, created and updated dates, currency, receipt status, the paid flag and payment method;
- the buyer: first and last name (Etsy sends them as one line, Elbuz splits it), email, the buyer's message;
- the shipping address with city, postcode and country code;
- line items with SKU, price and quantity.
Etsy doesn't send the buyer's phone number. The buyer is recognized by email and Etsy ID, so repeat orders from one person are grouped under one contact.
Statuses
Elbuz maps the document status to yours automatically, by receipt state name; the “Order statuses”, “Payment statuses” and “Delivery statuses” buttons in “Related settings” refine it. The key is the Etsy receipt state; if there is none, Elbuz uses shipped for shipped or paid for paid receipts. Payment has two codes: paid and unpaid. An unrecognized state gets “New”.
1
Schedule setup2
Order statuses- Schedule setup — the schedule of catalog runs.
- Order statuses — maps the receipt state to the document status.
What a repeat import updates
There won't be a duplicate: the document is found by receipt number. But not everything is overwritten:
- your processing status changes only if the receipt state on Etsy has changed since the last time;
- a posted document doesn't change at all: not the status, not payment, not delivery;
- lines in an existing document are neither added nor overwritten.
- Action or result
- Decision: the path depends on the answer
Changes to an old receipt (a cancellation, a refund, a new status a week later) aren't picked up: receipts are taken from the last import date. The connection doesn't create return documents; you create them by hand. The general mechanics: two statuses of one order.
How to update prices and stock on Etsy
The reverse direction is a separate export template of type “Etsy”. For each linked listing, Elbuz reads its inventory block, puts in your price and stock and writes it back. Etsy accepts the block only as a whole, so Elbuz rebuilds it every time, keeping the SKU and variation properties.
- Only products linked to a listing are updated: the link is set by the catalog import or by publishing. The run silently skips a product without a link unless “Publish new products” is on.
- A product gets into the filtered set if it has the “Export to file (to website)” flag and sits in an enabled category that takes part in exports. The service category “Products - etsy” is disabled, so move products into your own categories.
- Variations get the same price and quantity: the export doesn't send a separate price per variation.
- Action or result
- Decision: the path depends on the answer
For every 50 updated listings the log writes “Etsy: listings updated: N”, and at the end “Etsy: prices and stock updated, listings: N (errors: M)”. When Etsy rejects a listing, it explains why in its own words, in a separate red line with the product name. How to set up an export template: export templates.
How to publish new listings
With the “Publish new products” checkbox on in the export template, Elbuz creates Etsy listings from your cards: it creates a draft, uploads a photo from its link, sets price, stock and SKU, and only then makes the listing active.
- A shipping profile. The export takes “Shipping profile ID” and Shop ID from the Etsy import template where the profile is filled in (if there are several, the enabled one first). You can also set them in the export template, in the “API version (marketplace parameters)” field:
Shop ID|Shipping profile ID; values entered here take priority. Without a profile, the log shows “Etsy: Shop ID or Shipping profile ID is missing - publishing is not possible. Fill them in the template”, and no listings are created. - A mapped Etsy taxonomy for the product's category. Products without one are skipped silently; the log shows how many.
- At least one photo and non-zero stock. With no image or with stock 0, Elbuz doesn't activate the listing: it stays a draft in your account; fix it and publish manually.
- Required taxonomy properties (color, size with a scale, material) are mapped in the category mapping window. Without them the listing isn't created: “Etsy: "…" — required properties are empty: …”.
If Etsy didn't accept a property, the listing stays a draft and the log names it: “Etsy: "…" — property "…" not saved (…), listing left as a draft”.
- Action or result
- Decision: the path depends on the answer
You can check readiness in advance: in the “Marketplace Category and Attribute Mapping” window, select the Etsy toggle and click “Publish readiness”. You'll see three numbers: how many products are ready, how many lack a mapped marketplace category and how many have no photo, and below them the categories with unmapped required properties.
Required Etsy fields that the card doesn't have are filled with fixed values: “made by me”, “made to order”, physical item. For vintage or craft supplies, correct this in the listing after publishing. The title is cut to 140 characters, the description to 5,000 and stripped of , and the quantity is at least one.
The summary in the log: “Etsy: new listings created: N (errors: M). Publishing a listing on Etsy is paid ($0.20)”: the marketplace charges this fee for each listing.
Build the Etsy sales fee into the price with a formula in the price field: the “Export fields” button in the “Related settings” card of the export template. The Etsy fee calculator helps you work it out.
Scheduled updates
Etsy works by polling: Elbuz picks up orders itself every 5 minutes if “Orders” is ticked in the template and the shop is linked. It's the shared “Marketplace orders” task in the “Job schedule” window, where the interval is set. This pass doesn't import the catalog, and orders also taken by the template's own schedule aren't duplicated.
The catalog is updated by the template's own schedule — the “Schedule setup” button in the “Related settings” section. Once a day, for example at night, is enough: while the catalog is running, the orders pass is skipped until the next one. Everything runs on the server; no browser is needed.
Limits of a single run
| What | How much |
|---|---|
| Catalog page | 100 listings; written to the catalog in batches of 500; no cap on the total |
| Orders page | 100 receipts with their line items |
| Response timeout | up to 120 s per request, up to 30 s to connect |
| “Too many requests” | up to three attempts; the pause is as long as Etsy specifies (up to 30 s), otherwise 2, then 4 s; after that the error “HTTP 429: rate limit” |
| Requests per listing | price update: 2, publishing: 5 |
Disable the template
The “Active” / “Disabled” badge in the card header takes the template off the schedule and out of automatic order pickup, and that's all. The “Import” button works on a disabled template too.
1
State pill (Disabled)2
Import button- State pill — removes the template from the schedule when disabled.
- Import — manual run; works on a disabled template too.
The link, settings, cards and listing links stay. While the template is idle, the date from which receipts are taken doesn't move, so the first run after you enable it picks up everything missed. Price export is a different template with its own badge: disabling the import doesn't stop it.
Scenarios
Move your catalog from Etsy to Elbuz and keep it up to date
What to turn on. An “Etsy” import template, the “Products” checkbox, “Photo” for photos, and a schedule via the “Schedule setup” button.
What you get. Each active listing becomes a card; a familiar title updates the existing one. Cards of vanished listings stay as they were (a listing disappeared).
Receive Etsy orders without moving stock until they're checked
What to turn on. The “Orders” checkbox and receipt state mapping with the “Order statuses”, “Payment statuses” and “Delivery statuses” buttons. No template schedule is needed: receipts arrive on their own every 5 minutes.
What you get. Each new receipt becomes an unposted “Customer order” document with line items, buyer and address. Stock moves when you post the document.
Keep stock in Elbuz and send prices and stock to Etsy
What to turn on. An “Etsy” export template with the “Products” checkbox; for the products and their categories, “Export to file (to website)”. The link to a listing comes from an earlier catalog import.
What you get. Each linked listing gets your price and stock; the log totals the updates and errors.
Refine cards in Elbuz so the import doesn't overwrite them
What to turn on. In the product card, “Import protection” section: “Do not update” or “Fixed Price”.
What you get. With “Do not update” the run skips the card, stock included; with “Fixed Price” it updates everything except prices. Protection doesn't help if the listing is renamed in your Etsy account (repeat run).
What to do when Etsy won't import or update
| What you see | Why | What to do |
|---|---|---|
| Linking failed; the test doesn't return the shop ID | The link code is short-lived and has expired | Connect again and paste the code right away (how to connect) |
| “Etsy: API error -” followed by the marketplace's text | Etsy rejected the request; the catalog import stops there, the run's orders are still imported | Read the reason and start the run again (run broke off) |
| Fewer products were imported than you have in your account | Only active listings come in: drafts, hidden and sold-out listings don't | Nothing is lost; for what happens to existing cards, see a listing disappeared |
| Products landed in the “Products - etsy” category | The Etsy taxonomy dictionary isn't loaded | Load the dictionary and move the products into your own tree (category) |
| The export ran, but prices on Etsy are old | The product didn't get into the filtered set (the “Export to file (to website)” flag is off or the category is disabled) or has no link to a listing | Check the product's flag and category (updating prices) |
| “Etsy: Shop ID or Shipping profile ID is missing - publishing is not possible. Fill them in the template” | The shipping profile isn't filled in, either in the import template or in the export | Enter the “Shipping profile ID” (publishing requirements) |
| A new listing stayed a draft in your Etsy account | The product had no usable photo, stock was 0, or Etsy didn't accept a property: the log names the reason | Fix it and publish the listing manually, or run the export again (publishing) |
| “HTTP 429: rate limit” | Etsy answered “too many requests” three times in a row | Start the run later or schedule it less often (run limits) |
If a run broke off
The catalog is written in batches of 500: everything already written stays updated, and the next run picks up the unfinished batch. Rerunning is safe; there won't be duplicates. The last log line is still “Data import completed!”, so judge success by the lines above it. The general mechanics: if a run broke off.
The “Stop” button lets the run finish reading and writing the current Etsy page, but it won't request the next one, in both the catalog and orders.
After each saved page of receipts, Elbuz moves forward the date from which it takes receipts next time. If the first, historical import broke off, the old receipts the run didn't reach are never requested again. Pull them with a new Etsy template: its date is empty, and documents already imported are matched by receipt number, with no duplicates.
If a run did the wrong thing
A mistaken import. Cards created by the connection can be found in “Products” by the “Source - name” and “Source - code” columns (for Etsy, etsy); overwritten ones by today's “Date updated”. What can be restored: if you imported the wrong data.
A mistaken export. The inventory block is written as a whole, and Elbuz doesn't keep the previous prices and quantities, so there is no “undo” button. Correct the prices in Elbuz, narrow the template's filtered set to the products you need and run the export again. Which listings were affected is shown in the log and in “Run history”.
FAQ
What do I enter in the Shop ID field?
You can leave it empty: Elbuz will find the shop ID on its own. Fill in the field if the account has several shops or the log says the Shop ID couldn't be resolved.
Why do Etsy orders have no phone number?
Etsy doesn't send it: the receipt has the email, name and address. The buyer is recognized by email and Etsy ID, so repeat orders from one person are grouped under one contact.
I deactivated a listing on Etsy. Will the product be disabled in Elbuz?
No. A deactivated listing doesn't get into the run, and the card stays enabled with the last price and stock. Disable or delete it by hand in the “Products” window (a listing disappeared).
I disabled a product in Elbuz, and it got enabled again. Why?
Only active listings come from Etsy, so the run writes “enabled” to the card. To keep the card disabled, set “Do not update” on it (repeat run).
Can Elbuz deactivate a listing on Etsy?
No. A product removed from the export simply stops updating on Etsy and stays active. You deactivate a listing in your Etsy account.
Will a cancellation or refund come through for an order that's already imported?
No. Receipts are taken from the last import date, so changes to old receipts aren't picked up, and the connection doesn't create return documents: create them by hand (repeat import).
Where to find it and who has access
- Menu
- Directories → Operations → Data import
- Template
- new template → type “Etsy”; no file needed
- Prices and publishing
- the “Data export” window → a template of type “Etsy”
- Access right
- the “Import” window in “Group permissions”
- Have ready
- access to your Etsy seller account; for publishing, a shipping profile
1
Shop ID field2
Shipping profile ID field- Shop ID — can be left empty; it is resolved automatically.
- Shipping profile ID — required for publishing listings.
How import templates work in general: data import overview.
Related topics
- If you need to understand how an import template handles any source: Importing data into the catalog.
- If you also connect other marketplaces via API: Catalog import via API.
- If Etsy orders need to be combined with other channels: Importing orders from marketplaces.
- If you're setting up the export filtered set and schedule for Etsy: Export templates.
