Etsy Open API v3 Skill

• Listings: create drafts, update listing metadata, upload images/files, manage videos, update inventory/offerings
• Shop: retrieve/update shop settings, shop sections, shipping profiles, processing profiles, return policies
• Receipts/orders: retrieve receipts and transactions, post-purchase workflows
• Taxonomy: seller/buyer taxonomy nodes and properties
• Webhooks: create/rotate endpoints, subscribe to events, verify signatures

Authentication model (critical)

• API key header on all requests
• OAuth 2.0 user tokens (Authorization Code + PKCE) for scoped/private endpoints

Required headers

• x-api-key: <ETSY_KEYSTRING>:<ETSY_SHARED_SECRET>

• Authorization: Bearer <ETSY_OAUTH_USER_ID>.<ETSY_OAUTH_ACCESS_TOKEN>

Note: Etsy’s Bearer token format includes the numeric user id, a dot (

.

), and then the access token.

• references/02_authentication.md

• references/03_request_standards.md

Rate limits (must follow)

• QPS (queries per second)
• QPD (queries per day) using a rolling 24-hour sliding window

429

retry-after

• references/04_rate_limits.md

Scripts you can run (code_execution)

skills/etsy-api/scripts/

1) Make requests safely

python skills/etsy-api/scripts/etsy_cli.py request GET /v3/application/listings?state=active

--data

--form

2) OAuth helpers (PKCE + token exchange)

python skills/etsy-api/scripts/oauth_pkce.py auth-url --scopes "listings_r listings_w shops_r shops_w"

python skills/etsy-api/scripts/oauth_pkce.py exchange-code --code "<AUTH_CODE>"

python skills/etsy-api/scripts/oauth_pkce.py refresh-token

3) Webhook verification

python skills/etsy-api/scripts/webhook_verify.py verify --secret "$ETSY_WEBHOOK_SIGNING_SECRET" --headers-json headers.json --body-file body.json

How to use this skill effectively

1. Prefer reading references/ for policy, rate limits, and authentication details before coding.
2. Use

   scripts/etsy_cli.py

   for exploratory calls and to validate request shapes.
3. Cache responses where appropriate to reduce QPS/QPD usage.
4. Be careful when testing: follow Etsy’s API testing policy (draft listings, test prices, etc.). See

   references/11_terms_and_policies.md

   .

Safety and compliance

• Never print or log secrets (shared secret, access token, refresh token).
• Avoid creating “real” listings/orders during testing; follow Etsy testing policy guidance.
• If uncertain about an endpoint’s parameters, consult the OpenAPI reference site or the OpenAPI spec.