Request Standards

Etsy API endpoints are accessible at URLs starting with or The two hostnames are equivalent and you can use either. Throughout this document we use but may be substituted instead.

Making Requests#

Every request to a v3 endpoint must include:

endpointprotocolhttps://Etsy Open API endpoints require SSL/TLS requests which must use an https:// prefix. API endpoints are accessible at URLs starting with
headerAPI keyx-api-key: ...Your Etsy App API Key keystring, which you can find in Your Apps.
headeroauth tokenAuthorization: Bearer ...Any request that requires an oauth2 scope (e.g., listings_w) requires an authorization header. The value following Bearer combines a numeric user id with an oauth2 token, separted by a period (.). See Authentication for details.

For example, if your

  • client ID is exJeyZtXODeekHfX8VRgMQ,
  • numeric user ID is 12345678
  • access token is VJTv9qyjwJbYlARxdFmEEQ

the following is a valid request:

curl --request GET '' \
--header 'x-api-key: exJeyZtXODeekHfX8VRgMQ' \
--header 'authorization: Bearer 12345678.VJTv9qyjwJbYlARxdFmEEQ' \


All network communication with Open API v3 uses UTF-8 encoding. When creating HTTP requests for a REST API application, specify UTF-8 encoding support. For example, to set the UTF-8 encoding support in an HTTP header for a POST request, include charset=utf-8 in the content-type field, as shown in the following code:

POST /v3/application/shops/12345/listings HTTPS/1.3
Content-Type: application/x-www-form-urlencoded; charset=utf-8

When creating application code for a REST API application, provide UTF-8 encoding support using the language-specific content type settings. For example, to set the content type to UTF-8 in a Java HttpURLConnection object called conn, use the following code:

conn.setRequestProperty("contentType", "application/json; charset=utf-8");