Authenticate with OAuth 2.0 and request the `transactions_r` and `transactions_w` scopes plus your `x-api-key` header.
List open receipts by calling `GET /v3/application/shops/{shop_id}/receipts` with query parameter `was_shipped=false` to filter unfulfilled orders.
Retrieve full receipt details including buyer address and line items via `GET /v3/application/shops/{shop_id}/receipts/{receipt_id}`.
When the order ships, call `POST /v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking` (createReceiptShipment) with `tracking_code` and `carrier_name` in the request body.
A successful call triggers an automatic shipping notification email to the buyer with a tracking link; verify by checking the receipt's `is_shipped` field in a subsequent GET.
Handle partial shipments by submitting multiple tracking records to the same receipt if different items ship separately.
Known gotchas
The `transactions_w` scope is required to submit tracking; apps authenticated with read-only scopes will receive a 403 when calling the createReceiptShipment endpoint.
Carrier name values must match Etsy's recognized carrier list; an unrecognized carrier name may be accepted but will not generate a live tracking link for the buyer.
Etsy rate limits API requests per key; high-volume shops processing hundreds of orders per hour can hit these limits — check the current rate limit values in the official developer documentation and implement backoff.
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