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:

bin/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 as custom.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

1. 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.
2. 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.
3. Reading (receipts, listings, transactions, ledger) needs no confirmation.
4. The exact auth scheme is Authorization: Bearer <token> plus the keystring in the x-api-key header.
5. 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.