↑↓ selectEnter openEsc close

    1. Elbuz
    2. US marketplaces

    How to connect Etsy: listings, orders and stock in one catalog

    28 min readUpdated

    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

    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

    1. 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”.
    2. Click “Connect”, approve access in the Etsy window and copy the code.
    3. Paste the code into the form right away: it expires quickly.
    4. Click “Test connection”: the response should include your shop ID.
    5. 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

    FieldWhat it's for
    Shop Your shop's ID. You can leave it empty: Elbuz will find it on its own
    Shipping profile IDYour 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 dataProduct field in Elbuz
    listing titleName
    descriptionDescription
    SKU
    offering pricePrice
    quantityStock
    listing stateStatus: active means an enabled product
    listing tagsTags
    materialsThe “Material” attribute
    taxonomy (Etsy category)Category
    photosPhotos (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.

    Left branch: a new title means a new card. On the right, two card flags decide what from Etsy gets into it
    NoYesYesNoYesNoListing from EtsyIs there a card in the catalogwith the same title?A new card is createdphotos only if “Photo” is tickedIs “Do not update”on in the card?The card doesn't changeName, description, quantity, tags,SKUare overwritten from EtsyIs “Fixed Price”on in the card?Prices stay yoursThe price comes from Etsy
    • 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”.

    Related settings card with schedule and status mapping buttons
    1Schedule setup
    2Order statuses
    1. Schedule setup — the schedule of catalog runs.
    2. 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.
    What happens to a receipt whose document already exists: three checks in a row, and only the last one lets your processing status change
    NoYesYesNoYesNoYesNoReceipt from EtsyDoes a document with thisreceipt number exist?New “Customer order”not posted, with the receipt linesIs the last import datein the template still empty?The document doesn't changeIs the document posted?Has the receipt state on Etsychangedsince the last import?Processing status follows themappingan unmapped state won't change itYour processing status staysPayment and delivery follow themappingdocument lines don't change
    • 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.
    Left branch: products not linked to a listing are either skipped or published. Right branch: linked ones are updated
    NoNoYesYesYesNoProduct in the export template'sfiltered setIs it linkedto an Etsy listing?Is “Publish new products”on?The product is skipped silentlyAfter linked listings are updated,it goes to publishing as a new listingElbuz reads the listing's inventoryblockWrites the block again: your priceand stock,the same for all listing variationsDid Etsy accept the write?The listing counts in “listingsupdated”A red line in the logwith the product name and Etsy'stext
    • 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”.

    Requirements have different effects: some stop publishing or skip the product, others leave the listing as a draft
    NoYesNoYesNoYesNoYesThe “Publish new products”checkbox is onIs “Shipping profile ID” filled inin the importor export template?Publishing doesn't start:a red line in the logIs the category mappedto the Etsy taxonomy?The product is skipped silently,the log shows how manyAre required propertiesfilled in?The listing isn't created,the log names the propertiesA draft listing is createdElbuz downloads the photo from itslinkand uploads it to the listingIs there a photo, stock above 0,properties accepted?The listing stays a draft:fix it and publish manuallyPrice, stock, SKUThe listing becomes active
    • 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

    WhatHow much
    Catalog page100 listings; written to the catalog in batches of 500; no cap on the total
    Orders page100 receipts with their line items
    Response timeoutup 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 listingprice 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.

    Template header with name, state pill and Import button
    1State pill (Disabled)
    2Import button
    1. State pill — removes the template from the schedule when disabled.
    2. 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

    Common problems
    What you seeWhyWhat 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
    Etsy connection card with Shop ID and Shipping profile ID fields
    1Shop ID field
    2Shipping profile ID field
    1. Shop ID — can be left empty; it is resolved automatically.
    2. Shipping profile ID — required for publishing listings.

    How import templates work in general: data import overview.

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free