How to Automate Etsy Product Listings using the API

Understanding Etsy Listings API

Setting Up Etsy API Authentication for Listings

OAuth 2.0 with mandatory PKCE is required. Both the Bearer token and the x-api-key header must appear on every request. Access tokens expire in 1 hour — build automatic refresh logic into your API wrapper before making the first listing creation call.

1. 1Register your app at https://www.etsy.com/developers/your-apps with 2FA enabled.
2. 2Note your keystring (client ID) and client secret.
3. 3Generate PKCE pair: code_verifier (43-128 random chars), code_challenge = base64url(SHA256(verifier)).
4. 4Authorize with scopes: listings_r listings_w
5. 5Exchange auth code for access_token and refresh_token using code_verifier.
6. 6Store refresh_token securely — it lasts 90 days.
7. 7Implement auto-refresh: call token endpoint with grant_type=refresh_token when access_token is within 60s of expiry.

1import os, time, requests
2
3KEYSTRING = os.environ['ETSY_KEYSTRING']
4_cache = {'token': None, 'exp': 0, 'refresh': os.environ['ETSY_REFRESH_TOKEN']}
5
6def get_token():
7    if time.time() < _cache['exp'] - 60:
8        return _cache['token']
9    r = requests.post('https://api.etsy.com/v3/public/oauth/token',
10                      data={'grant_type': 'refresh_token', 'client_id': KEYSTRING, 'refresh_token': _cache['refresh']})
11    r.raise_for_status()
12    d = r.json()
13    _cache.update({'token': d['access_token'], 'exp': time.time() + d['expires_in']})
14    return d['access_token']
15
16def etsy(method, path, **kwargs):
17    headers = {'Authorization': f'Bearer {get_token()}', 'x-api-key': KEYSTRING}
18    resp = getattr(requests, method)(f'https://api.etsy.com/v3/application{path}', headers=headers, **kwargs)
19    resp.raise_for_status()
20    return resp.json()

Key endpoints

1{"quantity": 10, "title": "Handmade Silver Ring", "description": "Sterling silver ring, made to order", "price": {"amount": 2999, "divisor": 100}, "who_made": "i_did", "when_made": "made_to_order", "taxonomy_id": 68,  "is_supply": false, "shipping_profile_id": 12345678, "tags": ["silver", "ring", "handmade"]}

1{"listing_id": 99887766, "state": "draft", "title": "Handmade Silver Ring", "price": {"amount": 2999, "divisor": 100, "currency_code": "USD"}, "quantity": 10, "taxonomy_id": 68}

1{"state": "active", "title": "Updated Title", "price": {"amount": 3499, "divisor": 100}}

1{"listing_id": 99887766, "state": "active", "title": "Updated Title", "price": {"amount": 3499, "divisor": 100, "currency_code": "USD"}}

1GET https://api.etsy.com/v3/application/shops/12345678/listings?state=draft&limit=100

1{"count": 3, "results": [{"listing_id": 99887766, "state": "draft", "title": "Ring", "price": {"amount": 2999, "divisor": 100}}]}

1{"products": [{"property_values": [{"property_id": 200, "property_name": "Size", "values": ["S"]}], "offerings": [{"price": {"amount": 2999, "divisor": 100}, "quantity": 5, "is_enabled": true}]}]}

1{"listing_id": 99887766, "products": [{"product_id": 12345, "offerings": [{"offering_id": 67890, "quantity": 5, "is_enabled": true}]}]}

Step-by-step automation

1# Fetch all seller taxonomy categories
2curl -X GET 'https://api.etsy.com/v3/application/seller-taxonomy/nodes' \
3  -H 'x-api-key: your_keystring'

1curl -X POST 'https://api.etsy.com/v3/application/shops/12345678/listings' \
2  -H 'Authorization: Bearer your_access_token' \
3  -H 'x-api-key: your_keystring' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "quantity": 10,
7    "title": "Handmade Silver Ring",
8    "description": "Sterling silver ring, made to order in your size.",
9    "price": {"amount": 2999, "divisor": 100},
10    "who_made": "i_did",
11    "when_made": "made_to_order",
12    "taxonomy_id": 68,
13    "is_supply": false,
14    "shipping_profile_id": 12345678,
15    "tags": ["silver ring", "handmade jewelry", "sterling silver"]
16  }'

1curl -X PUT 'https://api.etsy.com/v3/application/shops/12345678/listings/99887766' \
2  -H 'Authorization: Bearer your_access_token' \
3  -H 'x-api-key: your_keystring' \
4  -H 'Content-Type: application/json' \
5  -d '{"state": "active"}'

1# Update price and title in one call
2curl -X PUT 'https://api.etsy.com/v3/application/shops/12345678/listings/99887766' \
3  -H 'Authorization: Bearer your_access_token' \
4  -H 'x-api-key: your_keystring' \
5  -H 'Content-Type: application/json' \
6  -d '{"price": {"amount": 3499, "divisor": 100}, "title": "Handmade Silver Ring - Updated"}'

Complete working code

Complete pipeline that reads a CSV product feed, fetches the taxonomy tree once, creates draft listings with full validation, and activates them after a configurable delay.

1import os, csv, time, json, logging, requests
2
3logging.basicConfig(level=logging.INFO)
4KEYSTRING = os.environ['ETSY_KEYSTRING']
5SHOP_ID = os.environ['ETSY_SHOP_ID']
6_cache = {'token': None, 'exp': 0, 'refresh': os.environ['ETSY_REFRESH_TOKEN']}
7
8def get_token():
9    if time.time() < _cache['exp'] - 60: return _cache['token']
10    r = requests.post('https://api.etsy.com/v3/public/oauth/token',
11                      data={'grant_type': 'refresh_token', 'client_id': KEYSTRING, 'refresh_token': _cache['refresh']})
12    r.raise_for_status(); d = r.json()
13    _cache.update({'token': d['access_token'], 'exp': time.time() + d['expires_in']})
14    return d['access_token']
15
16def etsy(method, path, **kwargs):
17    resp = getattr(requests, method)(f'https://api.etsy.com/v3/application{path}',
18                                     headers={'Authorization': f'Bearer {get_token()}', 'x-api-key': KEYSTRING}, **kwargs)
19    resp.raise_for_status(); return resp.json()
20
21def price(usd): return {'amount': round(float(usd) * 100), 'divisor': 100}
22
23def create_draft(shop_id, row):
24    return etsy('post', f'/shops/{shop_id}/listings', json={
25        'quantity': int(row['quantity']), 'title': row['title'], 'description': row['description'],
26        'price': price(row['price_usd']), 'who_made': row['who_made'], 'when_made': row['when_made'],
27        'taxonomy_id': int(row['taxonomy_id']), 'is_supply': row.get('is_supply','false').lower()=='true',
28        'tags': [t.strip() for t in row.get('tags','').split(',') if t.strip()][:13]
29    })
30
31def activate(shop_id, listing_id):
32    return etsy('put', f'/shops/{shop_id}/listings/{listing_id}', json={'state': 'active'})
33
34def main():
35    created_ids = []
36    with open('products.csv') as f:
37        for row in csv.DictReader(f):
38            try:
39                result = create_draft(SHOP_ID, row)
40                created_ids.append(result['listing_id'])
41                logging.info(f'Draft created: {result["listing_id"]} - {row["title"]}')
42            except Exception as e:
43                logging.error(f'Failed: {row.get("title")} — {e}')
44            time.sleep(0.2)
45    
46    # Save draft IDs before activation (review period)
47    with open('draft_ids.json', 'w') as f:
48        json.dump(created_ids, f)
49    logging.info(f'Created {len(created_ids)} drafts. Review in Etsy dashboard, then run activation.')
50    
51    # Activate all (run this after review)
52    for lid in created_ids:
53        try:
54            activate(SHOP_ID, lid)
55            logging.info(f'Activated {lid}')
56        except Exception as e:
57            logging.error(f'Activation failed {lid}: {e}')
58        time.sleep(0.2)
59
60if __name__ == '__main__': main()

Error handling

Rate Limits for Etsy Listings API

1import time
2
3def etsy_with_retry(method, path, max_retries=4, **kwargs):
4    delay = 0.2
5    for attempt in range(max_retries):
6        resp = getattr(requests, method)(f'https://api.etsy.com/v3/application{path}',
7                                         headers={'Authorization': f'Bearer {get_token()}', 'x-api-key': KEYSTRING}, **kwargs)
8        if resp.status_code == 429:
9            print(f'Rate limited, waiting {delay}s')
10            time.sleep(delay); delay = min(delay * 2, 10); continue
11        if resp.status_code == 401:
12            _cache['exp'] = 0  # Force token refresh
13            continue
14        resp.raise_for_status()
15        return resp.json()
16    raise RuntimeError('Retries exhausted')

• Add 150ms between each API call in bulk operations — safe buffer under the 10 req/sec limit.
• Cache the taxonomy tree locally — it rarely changes and calling it on every import wastes quota.
• For 100+ listings, spread creation across multiple days to avoid consuming the full daily 10,000 quota.
• Create drafts first, review in Etsy dashboard, then activate — avoids wasting activation calls on listings that need edits.
• Monitor daily quota consumption — 200 calls (100 listings) = 2% of daily limit, but large shops can hit the cap.

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

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).

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations