Etsy Getting Started: API Access and First Request (2026)

Getting started overview

Etsy provides an API for developers to interact with the Etsy platform, enabling programmatic management of shop activities such as listing creation, inventory updates, order retrieval, and shop data analysis. The API uses an OAuth 2.0 authorization flow to secure access to user data. Before making API calls, developers must establish an Etsy shop, register a developer account, and create an application to obtain API keys.

This guide outlines the steps required to begin using the Etsy API, from initial account setup to making a successful first request. It covers the necessary prerequisites, the process for obtaining API credentials, and a basic example of an authenticated API call.

Prerequisites

• Etsy Shop: A seller account with an active shop is required, as API access is tied to shop operations. To set up an Etsy shop, users typically provide details about their products, payment methods, and shop policies, as outlined in the official Etsy selling guide.
• Developer Account: Access to the Etsy Developer Portal is necessary for registering applications and managing API keys.
• Basic Programming Knowledge: Familiarity with HTTP requests, JSON data structures, and a programming language capable of handling OAuth 2.0 (e.g., Python, Node.js, Ruby) will be beneficial.

Create an account and get keys

To access the Etsy API, developers need to follow a multi-step process that involves setting up an Etsy shop, registering as a developer, and creating an application to obtain OAuth 2.0 credentials.

Step 1: Set up an Etsy shop

1. Navigate to the Etsy "Sell on Etsy" page.
2. Click "Open your Etsy shop" and follow the prompts to create a seller account. This includes choosing your shop language, country, currency, and shop name.
3. Complete the initial shop setup, including adding at least one listing (even a draft listing can suffice for initial setup), and setting up billing details. The Etsy API primarily serves existing shop owners, so an operational shop is a fundamental requirement.

Step 2: Register as an Etsy Developer

1. Go to the Etsy Developer Portal.
2. Sign in with your Etsy shop account credentials.
3. Accept the developer terms of service. This registers your account as a developer, granting access to the application creation interface.

Step 3: Create an application and obtain API keys

1. From the Etsy Developer Portal dashboard, click "Create an App".
2. Application Name: Provide a descriptive name for your application.
3. Application Description: Detail the purpose of your application. This helps Etsy understand how you intend to use the API.
4. Application Website: If your application has a public website, provide its URL. Otherwise, you can use your Etsy shop URL.
5. Redirect URI: This is crucial for OAuth 2.0. For testing purposes, you can use http://localhost:8080/oauth/callback or a similar local address. For production, this should be the URL where your application will handle the OAuth callback. OAuth 2.0 is an industry-standard protocol for authorization and is detailed by the IETF.
6. Scopes: Select the necessary permissions your application requires. For a first request, consider basic read-only scopes like transactions_r or shops_r to access shop information. You can modify scopes later if needed.
7. Justification: Clearly explain why your application needs API access and the specific scopes requested. Etsy reviews these justifications.
8. Submit the application for review. Once approved, you will receive your Client ID (API Key) and Client Secret (shared secret). These credentials are vital for initiating the OAuth 2.0 flow.

Your first request

The Etsy API uses OAuth 2.0 for authentication. This involves obtaining an access token that authorizes your application to make requests on behalf of a user (the shop owner). The following steps detail a simplified client-side example, though server-side implementation is generally recommended for production applications to secure the client secret.

Understanding the OAuth 2.0 flow

The standard OAuth 2.0 authorization code grant flow for Etsy involves:

1. Directing the user to Etsy's authorization URL with your client ID and desired scopes.
2. The user granting permission to your application on Etsy.
3. Etsy redirecting the user back to your specified Redirect URI with an authorization code.
4. Your application exchanging this authorization code for an access token and a refresh token by making a server-to-server request to Etsy's token endpoint, including your client ID and client secret.
5. Using the access token to make authenticated API calls.

Example: Retrieving shop information via Python

This example demonstrates how to initiate the OAuth flow and make an authenticated request using Python, assuming you have obtained your client_id, client_secret, and set up a redirect_uri.

1. Install requests library

pip install requests

2. Initiate OAuth authorization

Open this URL in your browser, replacing placeholders:

https://www.etsy.com/oauth/connect?response_type=code&redirect_uri=YOUR_REDIRECT_URI&scope=transactions_r%20shops_r&client_id=YOUR_CLIENT_ID&state=YOUR_UNIQUE_STATE_STRING

After granting permission, your browser will redirect to YOUR_REDIRECT_URI with a code and state parameter in the URL. Copy the code value.

3. Exchange authorization code for access token

Use the copied code to request an access token. This is a server-side operation.

import requests

client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
redirect_uri = "YOUR_REDIRECT_URI"
authorization_code = "THE_CODE_FROM_REDIRECT"

token_url = "https://api.etsy.com/v3/public/oauth/token"

payload = {
    "grant_type": "authorization_code",
    "client_id": client_id,
    "client_secret": client_secret,
    "redirect_uri": redirect_uri,
    "code": authorization_code,
}

response = requests.post(token_url, data=payload)
token_data = response.json()

access_token = token_data.get("access_token")
refresh_token = token_data.get("refresh_token")
expires_in = token_data.get("expires_in")

print(f"Access Token: {access_token}")
print(f"Refresh Token: {refresh_token}")
print(f"Expires In: {expires_in} seconds")

4. Make an authenticated API call

Now, use the access_token to fetch your shop's information. Replace YOUR_ACCESS_TOKEN and YOUR_SHOP_ID (you can find your shop ID in your Etsy shop settings or by making a call to /users/me/shops if you have the right scope).

shop_id = "YOUR_SHOP_ID"  # Example: 12345678
api_url = f"https://api.etsy.com/v3/application/shops/{shop_id}"

headers = {
    "x-api-key": client_id,
    "Authorization": f"Bearer {access_token}"
}

response = requests.get(api_url, headers=headers)

if response.status_code == 200:
    shop_info = response.json()
    print("Successfully retrieved shop information:")
    print(shop_info)
else:
    print(f"Error: {response.status_code} - {response.text}")

A successful response will return a JSON object containing details about your Etsy shop. This confirms your setup is correct and you can make authenticated requests.

Common next steps

After successfully making your first API call, you can explore various functionalities offered by the Etsy API:

• Listing Management: Create, update, and delete product listings programmatically. This can be useful for bulk operations or integrating with inventory management systems. Refer to the Etsy Listing API documentation.
• Order Processing: Retrieve new orders, update order statuses, and manage shipping labels. This helps automate fulfillment workflows.
• Shop Sections & Variations: Manage shop categories and product variations to keep your shop organized and detailed.
• Payments & Refunds: While direct payment processing is typically handled by Etsy Payments, you can retrieve transaction details.
• Webhooks: Implement webhooks to receive real-time notifications about events in your shop, such as new orders or listing updates. This avoids constant polling and improves efficiency, as described in Mozilla's WebHook API overview.
• Refreshing Access Tokens: Implement logic to use the refresh_token to obtain new access tokens once they expire, ensuring continuous API access without re-authenticating the user.

Troubleshooting the first call

Issues during the initial API setup are common. Here are some troubleshooting tips:

Common errors

• Invalid Client ID or Secret: Double-check that your client_id and client_secret are copied exactly from your Etsy developer application. Mismatches will result in authentication failures.
• Incorrect Redirect URI: The redirect_uri used in your authorization request must precisely match one of the Redirect URIs configured in your Etsy developer application. Even a trailing slash can cause a mismatch.
• Expired Authorization Code: Authorization codes are short-lived. If you wait too long after getting the code from the redirect to exchange it for an access token, it will expire, leading to an error.
• Insufficient Scopes: If you receive a permission denied error, ensure your application has requested (and the user has granted) the necessary OAuth 2.0 scopes for the API endpoint you are trying to access. For example, reading shop data requires the shops_r scope.
• Missing X-API-Key Header: For Etsy API v3, the x-api-key header with your client_id is required alongside the Authorization: Bearer YOUR_ACCESS_TOKEN header for authenticated requests.
• API Rate Limits: While less common for a first call, be aware that Etsy imposes rate limits. Exceeding these limits will result in 429 Too Many Requests errors. Check the Etsy API rate limiting documentation for details.
• Network Issues: Verify your internet connection and ensure no firewalls or proxies are blocking your outbound requests to api.etsy.com.

Debugging strategies

• Examine API Responses: Carefully read the error messages returned in the API response body. They often provide specific clues about what went wrong.
• Check Server Logs: If you are running a server-side application, review your server logs for any errors during the token exchange or API call.
• Use a Tool like Postman: Tools like Postman or Insomnia can help you test API endpoints and OAuth flows step-by-step, isolating where an error might occur.
• Consult Documentation: Refer to the Etsy API Reference for specific endpoint requirements, expected parameters, and response formats.
• Etsy Developer Community: The Etsy Developer Forums can be a resource for finding solutions to common problems or asking specific questions.

Quick reference table