Etsy
Purpose
Read the user's Etsy shop: receipts (orders), active listings, transactions, and the payment-account ledger. Create listings on confirmation. Use when the user mentions Etsy, their shop, or listing management.
Tooling
All commands go through bin/etsy.py; every command needs --shop-id:
bashbin/etsy.py auth --shop-id 12345678 # verify OAuth token and keystring bin/etsy.py receipts --shop-id 12345678 --limit 25 # list receipts (orders) bin/etsy.py listings --shop-id 12345678 --limit 25 # list active listings bin/etsy.py listing-create --shop-id 12345678 --json '{...}' # create a listing (confirm first) bin/etsy.py transactions --shop-id 12345678 --limit 25 # list transactions bin/etsy.py ledger --shop-id 12345678 --limit 25 # list payment-account ledger entries
Auth
- Provider id:
etsy(credential is collected ascustom.etsy) - Collection: OAuth 2.0 via the secure credential flow (
credentials.request_api_access); register an app at etsy.com/developers. The app keystring is collected alongside the token as a second credential entry. The key must be approved in the Etsy developer portal before any call works. - Allowed hosts:
openapi.etsy.com - Status check:
bin/etsy.py auth --shop-id <id>(must return"ok": true)
Operating Rules
- Fee warning: creating a listing costs $0.20 per listing; sales carry a 6.5% transaction fee plus roughly 3% + 25c payment processing. Renewals, inventory changes, and price updates can cost money too.
listing-create(and any listing renewal, inventory, or price update) must be confirmed with the user before running, unless standing permission exists. Never create listings automatically.- Reading (receipts, listings, transactions, ledger) needs no confirmation.
- The exact auth scheme is
Authorization: Bearer <token>plus the keystring in thex-api-keyheader. - Never exfiltrate the credential: the CLI only ever handles surrogates (see
bin/etsy.py). Do not print, log, or transmit the token or keystring value.
Files
- SKILL.md
- bin/etsy.py
Maturity
🧪 Draft: written from Etsy's public Open API v3 docs; not yet live-tested end-to-end.


