# How to Automate Etsy Product Listings using the API

- Tool: API Automations
- Difficulty: Intermediate
- Fix time: 30-60 minutes
- Compatibility: Etsy v3 API; OAuth 2.0 with PKCE; scopes: listings_w, listings_r; Commercial Access for multi-seller tools
- Last updated: May 2026

## TL;DR

Automate Etsy bulk listing creation and updates using `POST /v3/application/shops/{shop_id}/listings` (createDraftListing) and `PUT /shops/{shop_id}/listings/{listing_id}` (updateListing). Critical gotcha: six fields are mandatory on creation (`quantity`, `price`, `who_made`, `when_made`, `is_supply`, `taxonomy_id`) and prices use sub-units (`amount: 1099, divisor: 100` = $10.99). Both `Authorization: Bearer` and `x-api-key` headers are required on every request. Daily limit: 10,000 req/day.

## Best practices

- Always validate the six required fields (quantity, price, who_made, when_made, is_supply, taxonomy_id) before calling createDraftListing to avoid wasting quota on 400 errors.
- Use Etsy's sub-unit price format correctly: convert dollars to cents (`amount = round(usd * 100), divisor = 100`) — never pass decimal prices.
- Look up taxonomy_id once and cache it — querying the taxonomy tree on every import wastes API calls.
- Create all listings as drafts first, review in the Etsy dashboard, then activate in bulk — this prevents publishing listings with errors.
- Add 150ms delays between bulk listing API calls to stay safely under the 10 req/sec limit.
- Tags are limited to 13 per listing — prioritize highest-search-volume keywords.
- For print-on-demand sellers, the listing description needs to match Etsy's handmade policies — review before bulk activation.
- Monitor your 10,000/day quota when doing large imports — 100 listings ≈ 200 API calls (create + inventory update per listing).

## Frequently asked questions

### What are all six required fields for createDraftListing?

The six required fields are: (1) `quantity` (integer, available stock), (2) `price` (object with `amount` in sub-units and `divisor`, e.g., `{amount: 2999, divisor: 100}` for $29.99), (3) `who_made` (one of: `i_did`, `collective`, `someone_else`), (4) `when_made` (e.g., `made_to_order`, `2020_2024`, `2010_2019`), (5) `is_supply` (boolean, true for craft supplies), (6) `taxonomy_id` (numeric ID from /seller-taxonomy/nodes). Missing any one returns 400.

### How do I find the correct taxonomy_id for my product category?

Call `GET https://api.etsy.com/v3/application/seller-taxonomy/nodes` with only your `x-api-key` header (no auth required). This returns Etsy's full category hierarchy. Search for your product type and use the lowest-level (most specific) node's `id` value. For jewelry rings, taxonomy_id is typically 68. Cache this response — the taxonomy changes rarely.

### Why does Etsy use sub-unit prices instead of decimal values?

Etsy uses integer sub-units to avoid floating-point precision issues in financial calculations. The `amount` is the price in the smallest currency denomination (e.g., cents for USD), and `divisor` is how many sub-units make one unit (always 100 for USD/EUR/GBP). So $29.99 = `{amount: 2999, divisor: 100}`. Always use `amount / divisor` to display prices — never show the raw `amount`.

### What happens to listing fees when I create listings via API?

The same Etsy listing fees apply regardless of how the listing is created (API vs manual): $0.20 per listing for 4 months, plus transaction and payment processing fees. Creating draft listings does NOT incur the listing fee — you're only charged when the listing is activated (state changes to active). So you can create and edit drafts for free.

### What happens when I hit the rate limit?

Etsy returns HTTP 429. The daily limit of 10,000 requests uses a sliding 24-hour window — it doesn't fully reset at midnight. If you exhaust your quota, you'll need to wait up to 24 hours for it to replenish. Implement 150ms delays between requests, and consider spreading large imports over multiple days. For higher limits, email developers@etsy.com after your app is operational.

### Is the Etsy API free?

The Etsy API is free to use — there are no API usage fees. Personal access is free for up to 5 shops you own or that grant you access. Commercial access (for building tools that serve multiple sellers) is also free but requires manual approval from Etsy. Your normal Etsy seller fees (listing fees, transaction fees) still apply when you activate listings.

### Can RapidDev help build a custom Etsy listing management tool?

Yes. RapidDev has built 600+ apps including Etsy seller tools with bulk listing creation, CSV import pipelines, and print-on-demand integrations. We handle the full PKCE OAuth implementation, the taxonomy lookup system, and price format conversion correctly. Book a free consultation at rapidevelopers.com.

---

Source: https://www.rapidevelopers.com/api-automations/how-to-automate-etsy-product-listings-using-the-api
© RapidDev — https://www.rapidevelopers.com/api-automations/how-to-automate-etsy-product-listings-using-the-api