Implement OAuth 2.0 with PKCE: generate a `code_verifier` and `code_challenge`, then redirect the user to Etsy's authorization endpoint with `client_id`, `redirect_uri`, `response_type=code`, `scope`, `state`, and `code_challenge`.
Exchange the returned `code` for tokens by POSTing to Etsy's token endpoint with `grant_type=authorization_code`, `client_id`, `redirect_uri`, `code`, and `code_verifier`; store the `access_token` and `refresh_token`.
Create a draft listing by POSTing to `/v3/application/shops/{shop_id}/listings` with required fields: `quantity`, `title`, `description`, `price` (as an object with `amount` and `divisor`), `who_made`, `when_made`, and `taxonomy_id`.
Upload listing images by POSTing image files to `/v3/application/shops/{shop_id}/listings/{listing_id}/images` using multipart form data.
Activate the listing by sending a PATCH to `/v3/application/shops/{shop_id}/listings/{listing_id}` with `state: active`.
Refresh the access token (which expires in one hour) using the refresh token via the token endpoint with `grant_type=refresh_token`.
Known gotchas
Etsy's v3 API requires PKCE for all OAuth flows — the older implicit or code-without-PKCE flows are not supported and will fail.
The `taxonomy_id` must be a valid Etsy taxonomy leaf node ID from Etsy's taxonomy reference; using an invalid or non-leaf ID results in a validation error.
Physical listings require shipping profile information; attempting to activate a physical listing without a valid shipping profile associated will return an error.
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