Etsy Open API v3 Skill

Use this skill when you need to read or modify Etsy shop resources using Etsy Open API v3, including:

• 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

This skill package includes reference docs and scripts to make correct, rate-limit-aware requests.

Authentication model (critical)

Etsy uses:

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

Required headers

All requests must include:

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

Scoped endpoints additionally require:

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

See:

• references/02_authentication.md
• references/03_request_standards.md

Rate limits (must follow)

Etsy enforces per-application rate limits:

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

When you receive HTTP 429, honor the retry-after header and use exponential backoff.

See:

• references/04_rate_limits.md

Scripts you can run (code_execution)

All scripts are under skills/etsy-api/scripts/.

1) Make requests safely

Use the CLI to perform an arbitrary request with proper headers:

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

You can pass a body for POST/PUT with --data (JSON) or --form (x-www-form-urlencoded).

2) OAuth helpers (PKCE + token exchange)

Generate a PKCE verifier/challenge and an authorization URL:

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

Exchange an authorization code for tokens:

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

Refresh a token:

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

3) Webhook verification

Verify a webhook signature locally:

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.