Authenticate with Etsy's OAuth 2.0 flow obtaining a token with the listings_w and transactions_r scopes.
When a transaction webhook fires (or you poll GET /v3/application/shops/{shop_id}/transactions), extract the listingId and quantitySold from the receipt.
Retrieve the current inventory snapshot: GET /v3/application/listings/{listing_id}/inventory — this returns a products array with offerings that include quantity and price.
Decrement the quantity for the sold offering: from the getListingInventory response, remove the read-only fields (product_id, offering_id, scale_name, is_deleted, value_pairs) and change the target offering's quantity, then PUT /v3/application/listings/{listing_id}/inventory with the full modified products array.
If you need to update or add a shipping profile, call POST /v3/application/shops/{shop_id}/shipping-profiles to create one, then PATCH /v3/application/listings/{listing_id} with the new shipping_profile_id.
To update processing time, use a processing profile (createShopReadinessStateDefinition) and pass the readiness_state_id when updating the listing inventory; note that min_processing_time and max_processing_time are deprecated and will be removed in Q1 2026.
Known gotchas
Etsy's updateListingInventory endpoint requires you to send the complete products array on every write — partial updates are not supported; fetch the current inventory first and merge your changes before submitting.
The min_processing_time and max_processing_time fields are in deprecation — omit them from new integrations and migrate to processing profiles using readiness_state_id to avoid breakage when they are removed.
Etsy rate limits the Listings API — batch updates to many listings concurrently can trigger 429 responses; implement token-bucket throttling and honor the Retry-After response header.
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