Authenticate via OAuth 2.0 with the listings_w scope; Etsy Open API v3 uses per-user access tokens obtained through the Authorization Code PKCE flow
Create a draft listing via POST /v3/application/shops/{shop_id}/listings with required fields quantity, title, description, price (amount, divisor, currency_code), who_made, when_made, and taxonomy_id
Upload images to the listing using POST /v3/application/shops/{shop_id}/listings/{listing_id}/images with a multipart upload containing image data; the first image becomes the primary thumbnail
Add listing variations (properties like size or color) by POSTing to /v3/application/shops/{shop_id}/listings/{listing_id}/variation-images and creating listing inventory via the inventory endpoint
Activate the listing by sending PATCH /v3/application/shops/{shop_id}/listings/{listing_id} with state set to active
Retrieve the shop's active listings for sync via GET /v3/application/shops/{shop_id}/listings/active with pagination using limit and offset parameters
Known gotchas
Etsy requires a valid taxonomy_id for every listing; use GET /v3/application/seller-taxonomy/nodes to browse the taxonomy tree and find the correct leaf node ID
Images must be uploaded separately after listing creation; the create listing endpoint does not accept image data directly
Access tokens expire after one hour; use the refresh token flow to obtain new tokens and handle 401 responses with an automatic retry after refresh
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp