How to Automate Etsy Customer Messages using the API

Understanding Etsy Customer Communication via the API

Setting Up Etsy API Authentication (OAuth 2.0 + PKCE)

Etsy mandates PKCE on every OAuth 2.0 authorization flow — it is not optional as with some other platforms. Every API request requires both the `Authorization: Bearer <access_token>` header AND the `x-api-key: <keystring>` header. Access tokens expire in 1 hour; you must use the refresh token to mint new access tokens. Apps inactive for 6 months are banned.

1. 1Register your app at https://www.etsy.com/developers/your-apps — enable 2FA on your Etsy account first.
2. 2Note your app's keystring (client ID) and secret from the app settings.
3. 3Request 'transactions_r' scope; also request 'buyer_email' access separately if you need the buyer's email address.
4. 4Build the PKCE flow: generate a 43-128 character code verifier from [A-Za-z0-9._~-], compute code_challenge = base64url(SHA256(verifier)).
5. 5Redirect user to: https://www.etsy.com/oauth/connect?response_type=code&client_id={keystring}&redirect_uri={url}&scope=transactions_r&state={random}&code_challenge={challenge}&code_challenge_method=S256
6. 6After redirect, exchange the code for tokens at POST https://api.etsy.com/v3/public/oauth/token with code_verifier included.
7. 7Store the access_token (1 hour) and refresh_token (90 days) securely.
8. 8For commercial use across multiple sellers' shops, submit a 'Request Commercial Access' application in the developer portal.

1import os, secrets, hashlib, base64, requests
2
3KEYSTRING = os.environ['ETSY_KEYSTRING']
4SECRET = os.environ['ETSY_SECRET']
5REDIRECT_URI = os.environ['ETSY_REDIRECT_URI']
6
7# Step 1: Generate PKCE code verifier and challenge
8code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode().rstrip('=')
9code_challenge = base64.urlsafe_b64encode(
10    hashlib.sha256(code_verifier.encode()).digest()
11).decode().rstrip('=')
12
13# Step 2: Build authorization URL
14auth_url = (f'https://www.etsy.com/oauth/connect?'
15            f'response_type=code&client_id={KEYSTRING}'
16            f'&redirect_uri={REDIRECT_URI}&scope=transactions_r'
17            f'&state={secrets.token_hex(16)}'
18            f'&code_challenge={code_challenge}&code_challenge_method=S256')
19print(f'Visit: {auth_url}')
20
21# Step 3: Exchange code for tokens (after redirect)
22def exchange_code(auth_code, verifier):
23    resp = requests.post('https://api.etsy.com/v3/public/oauth/token', data={
24        'grant_type': 'authorization_code',
25        'client_id': KEYSTRING,
26        'redirect_uri': REDIRECT_URI,
27        'code': auth_code,
28        'code_verifier': verifier
29    })
30    resp.raise_for_status()
31    return resp.json()  # {access_token, refresh_token, token_type, expires_in}
32
33def refresh_access_token(refresh_token):
34    resp = requests.post('https://api.etsy.com/v3/public/oauth/token', data={
35        'grant_type': 'refresh_token',
36        'client_id': KEYSTRING,
37        'refresh_token': refresh_token
38    })
39    resp.raise_for_status()
40    return resp.json()

Key endpoints

1GET https://api.etsy.com/v3/application/shops/12345678/receipts?was_paid=true&min_created=1714000000&limit=25

1{"count": 1, "results": [{"receipt_id": 9876543, "buyer_user_id": 44556677, "buyer_email": "buyer@example.com", "name": "Jane Smith", "status": "paid", "total_price": {"amount": 2999, "divisor": 100, "currency_code": "USD"}, "transactions": [{"title": "Handmade Ring", "quantity": 1}], "message_from_buyer": "No rush!"}]}

1GET https://api.etsy.com/v3/application/shops/12345678/receipts/9876543

1{"receipt_id": 9876543, "buyer_email": "buyer@example.com", "name": "Jane Smith", "first_line": "123 Main St", "city": "Portland", "state": "OR", "zip": "97201", "country_iso": "US", "status": "paid", "total_price": {"amount": 2999, "divisor": 100, "currency_code": "USD"}, "transactions": [{"title": "Handmade Ring", "quantity": 1, "price": {"amount": 2999, "divisor": 100}}], "message_from_buyer": "No rush!"}

1Configure via Etsy Developer Portal at https://www.etsy.com/developers/your-apps → select app → Webhooks tab

1{"webhook_id": "evt_abc123", "shop_id": 12345678, "fetch_url": "https://api.etsy.com/v3/application/shops/12345678/receipts/9876543"}

Step-by-step automation

1# Exchange authorization code for tokens (after OAuth redirect)
2curl -X POST 'https://api.etsy.com/v3/public/oauth/token' \
3  -d 'grant_type=authorization_code' \
4  -d 'client_id=your_keystring' \
5  -d 'redirect_uri=https://yourapp.com/oauth/callback' \
6  -d 'code=auth_code_from_redirect' \
7  -d 'code_verifier=your_pkce_verifier'

1# Webhook verification: build signed_content = webhook-id + "." + webhook-timestamp + "." + raw_body
2# Decode whsec_ secret, compute HMAC-SHA256, compare base64 to webhook-signature header
3# No direct cURL example — register webhook via the Developer Portal UI

1# Fetch single receipt
2curl -X GET 'https://api.etsy.com/v3/application/shops/12345678/receipts/9876543' \
3  -H 'Authorization: Bearer your_access_token' \
4  -H 'x-api-key: your_keystring'

1# Poll for orders created in the last 5 minutes
2TIMESTAMP=$(date -v-5M +%s)  # 5 minutes ago (macOS)
3curl -X GET "https://api.etsy.com/v3/application/shops/12345678/receipts?was_paid=true&min_created=${TIMESTAMP}" \
4  -H 'Authorization: Bearer your_access_token' \
5  -H 'x-api-key: your_keystring'

Complete working code

This complete webhook handler receives Etsy order.paid events, verifies the signature, fetches order details from the receipts API, and sends a personalized post-purchase email via SendGrid — replicating the effect of an Etsy message without the non-existent messaging API.

1import os, hmac, hashlib, base64, time, logging, requests
2from flask import Flask, request, abort
3
4logging.basicConfig(level=logging.INFO)
5app = Flask(__name__)
6
7KEYSTRING = os.environ['ETSY_KEYSTRING']
8WEBHOOK_SECRET = os.environ['ETSY_WEBHOOK_SECRET']
9REFRESH_TOKEN = os.environ['ETSY_REFRESH_TOKEN']
10SENDGRID_KEY = os.environ['SENDGRID_API_KEY']
11TEMPLATE_ID = os.environ['SENDGRID_TEMPLATE_ID']
12
13_token_cache = {'token': None, 'expires_at': 0, 'refresh': REFRESH_TOKEN}
14
15def get_token():
16    if time.time() < _token_cache['expires_at'] - 60:
17        return _token_cache['token']
18    resp = requests.post('https://api.etsy.com/v3/public/oauth/token',
19                         data={'grant_type': 'refresh_token', 'client_id': KEYSTRING, 'refresh_token': _token_cache['refresh']})
20    resp.raise_for_status()
21    d = resp.json()
22    _token_cache.update({'token': d['access_token'], 'expires_at': time.time() + d['expires_in']})
23    return d['access_token']
24
25def etsy_get(path, params=None):
26    resp = requests.get(f'https://api.etsy.com/v3/application{path}',
27                        headers={'Authorization': f'Bearer {get_token()}', 'x-api-key': KEYSTRING}, params=params)
28    resp.raise_for_status()
29    return resp.json()
30
31def verify_webhook(raw_body, headers):
32    wid = headers.get('webhook-id', '')
33    wts = headers.get('webhook-timestamp', '')
34    wsig = headers.get('webhook-signature', '')
35    if abs(time.time() - int(wts)) > 300:
36        return False
37    signed = f'{wid}.{wts}.{raw_body.decode()}'
38    secret = base64.b64decode(WEBHOOK_SECRET.replace('whsec_', ''))
39    expected = base64.b64encode(hmac.new(secret, signed.encode(), hashlib.sha256).digest()).decode()
40    return any(hmac.compare_digest(expected, s.strip()) for s in wsig.split())
41
42def format_price(p):
43    return p['amount'] / p['divisor']
44
45@app.route('/webhooks/etsy-order', methods=['POST'])
46def order_paid():
47    raw = request.get_data()
48    if not verify_webhook(raw, request.headers):
49        abort(401)
50    payload = request.get_json()
51    shop_id = payload.get('shop_id')
52    fetch_url = payload.get('fetch_url', '')
53    receipt_id = fetch_url.rstrip('/').split('/')[-1]
54    if not receipt_id:
55        return '', 200
56    try:
57        receipt = etsy_get(f'/shops/{shop_id}/receipts/{receipt_id}')
58        email = receipt.get('buyer_email')
59        if not email:
60            logging.info(f'No buyer email for receipt {receipt_id}')
61            return '', 200
62        items = [{'title': t['title'], 'qty': t['quantity'], 'price': format_price(t['price'])} for t in receipt.get('transactions', [])]
63        data = {'buyer_name': receipt.get('name', 'there'), 'total': format_price(receipt['total_price']), 'items': items}
64        sg_payload = {'from': {'email': 'orders@yourshop.com'}, 'personalizations': [{'to': [{'email': email}], 'dynamic_template_data': data}], 'template_id': TEMPLATE_ID}
65        sg_resp = requests.post('https://api.sendgrid.com/v3/mail/send', json=sg_payload, headers={'Authorization': f'Bearer {SENDGRID_KEY}'})
66        logging.info(f'Email sent to {email}: {sg_resp.status_code}')
67    except Exception as e:
68        logging.error(f'Error processing receipt {receipt_id}: {e}')
69    return '', 200
70
71if __name__ == '__main__':
72    app.run(port=3000)

Error handling

Rate Limits for Etsy API

1import time
2
3def etsy_get_with_retry(path, params=None, max_retries=4):
4    delay = 0.2
5    for attempt in range(max_retries):
6        resp = requests.get(
7            f'https://api.etsy.com/v3/application{path}',
8            headers={'Authorization': f'Bearer {get_token()}', 'x-api-key': KEYSTRING},
9            params=params
10        )
11        if resp.status_code == 429:
12            print(f'Rate limited (attempt {attempt+1}), waiting {delay}s')
13            time.sleep(delay)
14            delay = min(delay * 2, 10)
15            continue
16        if resp.status_code == 401:
17            # Token expired — refresh and retry once
18            _token_cache['expires_at'] = 0
19            continue
20        resp.raise_for_status()
21        return resp.json()
22    raise RuntimeError('Etsy API retries exhausted')

• Add 150ms delays between batch requests to stay safely under the 10 req/sec limit.
• Cache receipt data for 30 minutes — don't re-fetch the same receipt for multi-step email sequences.
• Use the order.paid webhook instead of polling — it uses zero daily quota for event detection.
• For polling fallback, check once every 5 minutes (288 calls/day) rather than every minute.
• Email developers@etsy.com with your app's use case to request higher rate limits once you're operational.

Security checklist

Automation use cases

No-code alternatives

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

Best practices

• Accept that there is no Etsy messaging API — design your workflow around external email delivery from the start.
• Always include both Authorization: Bearer and x-api-key headers on every request — missing x-api-key is the most common integration failure.
• Implement automatic token refresh: access tokens expire in 1 hour, so build refresh logic into your API wrapper before hitting the first expiry.
• Always divide Etsy monetary values by their divisor — `amount: 2999, divisor: 100` = $29.99. Never display raw amounts.
• Use the order.paid webhook (2025 addition) instead of polling receipts — webhooks are real-time and consume zero daily API quota.
• Store processed receipt IDs to prevent sending duplicate emails — webhooks can be delivered more than once.
• Request Commercial access early if your app will serve multiple sellers — the review takes days to weeks and is the critical path.
• Apply for buyer_email permission separately — without it, receipt data contains buyer user IDs but not email addresses.

Ask AI to help

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

Related automations