A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Etsy API is how an app or AI agent works with an Etsy shop: reading shop and listing details, creating and updating listings and their inventory, reading orders, and adding tracking to a sale. Access is granted through an app key on every call plus an access token whose scopes decide what each call can read or write, such as listings_r to read listings or transactions_r to read orders, and an agent is limited to the one shop that authorized it. Etsy does not push events, so an agent checks for new orders by polling rather than being notified.
How an app or AI agent connects to Etsy determines what it can reach. Every call carries an app API key, and most of the seller methods also need an access token whose scopes set what that call can read or write.
The Etsy Open API v3 answers at https://api.etsy.com under the path /v3/application. Every call sends the app API key in the x-api-key header, and seller methods add an OAuth bearer token.
Etsy's own Dev MCP server at https://mcp.api.etsycloud.com/mcp gives an AI assistant the v3 spec knowledge, the endpoints, schemas, and auth rules, to help build integrations. It does not call the Etsy API or perform shop actions itself.
Every request carries the app's keystring in the x-api-key header. On its own it reaches only public data, such as active listings and public shop details, and it sets the rate limit the calls count against.
A shop owner authorizes the app through the authorization-code flow with PKCE, granting a chosen set of scopes. The app receives an access token valid for one hour and a refresh token valid for ninety days, and the access token is sent as a bearer token on seller methods.
The Etsy API is split into areas an agent can act on, such as shops, listings and their inventory, orders and the money behind them. Each area has its own methods and its own scopes, and some grant access to far more than others.
Find a shop by name, read a shop by its id or by its owner, and update a shop's settings.
Read active listings, read a shop's listings, read a single listing, and create, update, or delete a listing.
Read and update a listing's inventory, including its variations, quantities, and prices.
List a shop's receipts, read a single receipt, update a receipt, and add tracking to a shipment.
List the transactions in a shop and read a single transaction, the line items inside an order.
Read a shop's payments and its payment-account ledger entries, the money in and out of the shop.
List a shop's sections, read a single section, and create a new section to organize listings.
Read the authenticated user and read a user by id.
List the reviews left on a shop and the reviews left on a single listing.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ShopsFind a shop by name, read a shop by its id or by its owner, and update a shop's settings.4 | ||||||
| GET | /v3/application/shops | Search for shops by name. | read | — | Current | |
Public data, so it needs only the app API key in the x-api-key header, no OAuth token or scope. Acts onshop Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/shops/{shop_id} | Get a shop's details by its shop id. | read | — | Current | |
Public data, so it needs only the app API key, no OAuth token or scope. Acts onshop Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/users/{user_id}/shops | Get the shop owned by a given user id. | read | — | Current | |
Public data, so it needs only the app API key, no OAuth token or scope. Acts onshop Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/application/shops/{shop_id} | Update a shop's settings, such as its title, announcement, and policies. | write | shops_w | Current | |
Needs an OAuth token from the shop owner. The shops_w scope grants write access to the shop's settings. Acts onshop Permission (capability) shops_wVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ListingsRead active listings, read a shop's listings, read a single listing, and create, update, or delete a listing.6 | ||||||
| GET | /v3/application/listings/active | Find all active listings across Etsy, with filters such as keywords, category, and price. | read | — | Current | |
Public catalog data, so it needs only the app API key, no OAuth token or scope. Acts onlisting Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/shops/{shop_id}/listings | Get the listings that belong to a shop, filtered by state such as active or draft. | read | listings_r | Current | |
Active listings are public and need only the app API key. A token with listings_r is required to see draft, expired, or other non-public states. Acts onlisting Permission (capability) listings_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/listings/{listing_id} | Get a single listing by its id. | read | — | Current | |
Public for an active listing, so the app API key alone is enough; a token with listings_r is needed to read a listing that is not public. Acts onlisting Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/application/shops/{shop_id}/listings | Create a new draft listing in a shop. | write | listings_w | Current | |
Needs an OAuth token from the shop owner. The listings_w scope grants create and edit access to listings. Acts onlisting Permission (capability) listings_wVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/application/shops/{shop_id}/listings/{listing_id} | Update a listing, such as its title, description, price, or state. | write | listings_w | Current | |
The earlier full-replacement form of this method used PUT and is now deprecated; PATCH is the current partial-update method. Classic scope: listings_w. Acts onlisting Permission (capability) listings_wVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/application/listings/{listing_id} | Delete a listing. | write | listings_d | Current | |
Deleting needs the separate listings_d scope, not listings_w, so delete can be withheld from a token that can still edit. Acts onlisting Permission (capability) listings_dVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InventoryRead and update a listing's inventory, including its variations, quantities, and prices.2 | ||||||
| GET | /v3/application/listings/{listing_id}/inventory | Get a listing's inventory, including its variations, quantities, SKUs, and prices. | read | listings_r | Current | |
A token with listings_r is required to read the full inventory record. Classic scope: listings_r. Acts oninventory Permission (capability) listings_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/application/listings/{listing_id}/inventory | Update a listing's inventory, replacing its variations, quantities, and prices. | write | listings_w | Current | |
This replaces the whole inventory record, so the full set of products must be sent each time. Classic scope: listings_w. Acts oninventory Permission (capability) listings_wVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Receipts & ordersList a shop's receipts, read a single receipt, update a receipt, and add tracking to a shipment.4 | ||||||
| GET | /v3/application/shops/{shop_id}/receipts | List a shop's receipts, the order records, with filters such as paid and shipped status. | read | transactions_r | Current | |
A receipt is Etsy's record of a sale, with the buyer, items, and shipping. The transactions_r scope grants read access to orders. Acts onreceipt Permission (capability) transactions_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/shops/{shop_id}/receipts/{receipt_id} | Get a single receipt by its id. | read | transactions_r | Current | |
Returns the buyer's name and shipping address, so it exposes personal data. Classic scope: transactions_r. Acts onreceipt Permission (capability) transactions_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/application/shops/{shop_id}/receipts/{receipt_id} | Update a receipt's status, marking it as paid or shipped. | write | transactions_w | Current | |
Needs an OAuth token from the shop owner. The transactions_w scope grants write access to orders. Acts onreceipt Permission (capability) transactions_wVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking | Add a carrier and tracking number to a receipt, which submits the shipment and can notify the buyer. | write | transactions_w | Current | |
Submitting tracking can email the buyer, so it has an outside effect beyond the order record. Classic scope: transactions_w. Acts onshipment Permission (capability) transactions_wVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TransactionsList the transactions in a shop and read a single transaction, the line items inside an order.2 | ||||||
| GET | /v3/application/shops/{shop_id}/transactions | List the transactions in a shop, the individual line items across its orders. | read | transactions_r | Current | |
A transaction is one item sold within a receipt. The transactions_r scope grants read access. Classic scope: transactions_r. Acts ontransaction Permission (capability) transactions_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/shops/{shop_id}/transactions/{transaction_id} | Get a single transaction by its id. | read | transactions_r | Current | |
Classic scope: transactions_r. Acts ontransaction Permission (capability) transactions_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PaymentsRead a shop's payments and its payment-account ledger entries, the money in and out of the shop.2 | ||||||
| GET | /v3/application/shops/{shop_id}/payments | Get a shop's payments by their ids, the amounts collected on sales after fees, shipping, and taxes. | read | transactions_r | Current | |
Exposes a shop's revenue and fee figures. The transactions_r scope grants read access to payment data. Acts onpayment Permission (capability) transactions_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/shops/{shop_id}/payment-account/ledger-entries | List a shop's payment-account ledger entries, the running record of money in and out. | read | transactions_r | Current | |
The ledger holds every credit and debit against the shop's balance, so it exposes detailed financial history. Classic scope: transactions_r. Acts onledger entry Permission (capability) transactions_rVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Shop sectionsList a shop's sections, read a single section, and create a new section to organize listings.3 | ||||||
| GET | /v3/application/shops/{shop_id}/sections | List a shop's sections, the named groups a shop uses to organize its listings. | read | — | Current | |
Public data, so it needs only the app API key, no OAuth token or scope. Acts onsection Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/shops/{shop_id}/sections/{shop_section_id} | Get a single shop section by its id. | read | — | Current | |
Public data, so it needs only the app API key, no OAuth token or scope. Acts onsection Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/application/shops/{shop_id}/sections | Create a new section in a shop. | write | shops_w | Current | |
Needs an OAuth token from the shop owner. The shops_w scope grants write access to shop organization. Acts onsection Permission (capability) shops_wVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the authenticated user and read a user by id.2 | ||||||
| GET | /v3/application/users/me | Get the user that the access token belongs to. | read | — | Current | |
Needs an OAuth token to identify the user, but no extra scope beyond the basic grant. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/users/{user_id} | Get a user's profile by their user id. | read | — | Current | |
Returns the basic profile fields the user has made available. Needs the app API key and a valid token. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReviewsList the reviews left on a shop and the reviews left on a single listing.2 | ||||||
| GET | /v3/application/shops/{shop_id}/reviews | Get the reviews buyers have left on a shop. | read | — | Current | |
Public data, so it needs only the app API key, no OAuth token or scope. Acts onreview Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/application/listings/{listing_id}/reviews | Get the reviews buyers have left on a single listing. | read | — | Current | |
Public data, so it needs only the app API key, no OAuth token or scope. Acts onreview Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Etsy does not push events to an app or AI agent. To learn about new orders or changes, an agent polls the order and listing methods on a schedule instead of being notified.
| Event | What it signals | Triggered by |
|---|
Etsy limits how fast and how much an app or AI agent can call, through a per-second cap and a rolling daily quota that both apply to the app API key.
Etsy applies two limits to each app, both counted against the app API key. A per-second cap allows up to 10 requests per second, and a daily quota allows up to 10,000 requests across a rolling 24-hour window, measured with a sliding-window algorithm rather than a fixed midnight reset. Every successful response reports the current state through the x-limit-per-second, x-remaining-this-second, x-limit-per-day, and x-remaining-today headers. Exceeding either limit returns 429 with a retry-after header giving the seconds to wait, and an app can request a higher daily quota through the developer portal.
List methods use offset pagination through the limit and offset query parameters. The limit defaults to 25 and can be set up to 100 records per call, and the offset can reach up to 12,000. Each response carries a count field with the total number of records available, so a caller pages by raising the offset until it reaches that total.
Requests and responses are JSON. List results are capped at 100 records per call through the limit parameter, and the offset cannot exceed 12,000, so very large result sets are reached by narrowing filters rather than paging endlessly. Image and file uploads use multipart form data with their own per-file size limits.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a field is invalid, such as a value outside an allowed range or a reference to a property that no longer exists. | Read the error body, correct the named field, and resend. |
| 401 | Unauthorized | Authentication is missing or invalid, such as a missing API key, or an access token that is absent, expired, or wrong. | Send a valid x-api-key, and for seller methods refresh and send a valid bearer token. |
| 403 | Forbidden | The credentials are valid but the token lacks the scope for this method, or the app is not permitted to act on this shop. | Grant the missing scope, such as transactions_r or listings_w, and confirm the token belongs to the right shop. |
| 404 | Not Found | The resource does not exist at that path, or a deprecated endpoint that has been removed was called. | Confirm the path and the id, and check the release notes for any removed endpoint. |
| 409 | Conflict | The request conflicts with the current state of the resource, such as an update that clashes with the listing's present state. | Refetch the current state, then retry once the conflict is resolved. |
| 429 | Too Many Requests | A rate limit was exceeded, either the per-second cap or the rolling daily quota for the app API key. | Wait for the time given in the retry-after header before retrying. |
| 500 | Internal Server Error | An unexpected error occurred on Etsy's side while handling the request. | Retry after a short backoff, and report it if it persists. |
| 503 | Service Unavailable | The service is temporarily unavailable, often during maintenance or heavy load. | Retry after a short delay with exponential backoff. |
Etsy runs a single, continuously updated version of its Open API, v3, and ships dated changes through release notes rather than minting a new version string. The current version is v3.
Etsy runs a single live version of its Open API, v3, which replaced the retired v2. It is not versioned by a dated string; instead Etsy ships dated changes through release notes, typically every two weeks, and announces breaking changes in advance. The entries below are notable dated changes from those notes, newest first.
A release note dated 24 March 2026 fixed a 500 error returned by the listing video upload endpoint and resolved a duplicate image ranking issue.
A release note dated 24 October 2025 corrected an invalid value returned in the retry-after header when a client exceeds its daily rate limit.
A release note dated 14 October 2025 made documentation type fixes for enum fields and removed long-deprecated endpoints, which now return 404 Not Found.
From 15 April 2025, Etsy no longer accepted references to the property_ids of deprecated listing properties in get, create, or update requests. Existing variations linked to those properties were converted to custom variations, so cached property ids had to be refreshed.
A release note dated 20 November 2024 restricted fulfillment access for new personal and commercial API keys in Canada.
Breaking changes are announced in advance through the release notes, and an integration moves with them rather than pinning a number.
Etsy Open API release notes ↗Bollard AI sits between a team's AI agents and Etsy. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.