Getting Started with Etsy API

Overview

Before you can make any API calls, you need to:

1. Register as an Etsy developer
2. Create an application to get API credentials
3. Set up your development environment

This chapter walks through each step.

Registering as an Etsy Developer

Step 1: Access the Developer Portal

Navigate to Etsy’s Developer Portal and sign in with your Etsy account. You must use the same account that owns your shop.

Step 2: Accept the API Terms of Use

Etsy requires you to accept their API Terms of Use before creating applications. Read through them carefully—they include important restrictions on:

• How you can use customer data
• Rate limits and fair usage
• Prohibited uses of the API

Step 3: Create a New Application

1. Click “Create a New App”
2. Fill in the application details:

1. Submit and wait for approval (usually instant for basic access)

Step 4: Get Your Credentials

Once approved, you’ll receive:

• Keystring (API Key): Your public application identifier
• Shared Secret: Your private key for OAuth signing

⚠️ Never share your Shared Secret or commit it to public repositories.

Understanding Etsy API v3

Etsy currently uses Open API v3, which replaced the older v2 API. Key characteristics:

• RESTful: Standard HTTP methods (GET, POST, PUT, DELETE)
• JSON: All responses are JSON formatted
• OAuth 2.0: Authentication uses OAuth 2.0 PKCE flow
• Base URL: https://openapi.etsy.com/v3/

API Scopes

When authenticating, you request specific permissions (scopes):

For digital products management, you’ll typically need:

listings_r listings_w listings_d transactions_r shops_r

Setting Up Your Project

Directory Structure

Create a clean project structure:

etsy-automation/
├── .env                 # Credentials (never commit!)
├── .gitignore          # Exclude sensitive files
├── requirements.txt    # Python dependencies
├── config.py           # Configuration management
├── auth.py             # OAuth authentication
├── client.py           # API client wrapper
└── scripts/            # Your automation scripts
    └── update_prices.py

Environment Variables

Store your credentials in a .env file:

# .env
ETSY_API_KEY=your_keystring_here
ETSY_API_SECRET=your_shared_secret_here
ETSY_REDIRECT_URI=http://localhost:3000/callback
ETSY_SHOP_ID=your_shop_id

Git Ignore

Always exclude sensitive files:

# .gitignore
.env
*.pyc
__pycache__/
tokens.json

Dependencies

Create a requirements.txt:

requests>=2.28.0
python-dotenv>=1.0.0

Install with:

pip install -r requirements.txt

Configuration Module

The first piece of code we need is a configuration manager. See the complete implementation in code/config.py.

Here’s the key part:

import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    API_KEY = os.getenv("ETSY_API_KEY")
    API_SECRET = os.getenv("ETSY_API_SECRET")
    REDIRECT_URI = os.getenv("ETSY_REDIRECT_URI")
    SHOP_ID = os.getenv("ETSY_SHOP_ID")
    BASE_URL = "https://openapi.etsy.com/v3"

This pattern keeps your credentials separate from your code.

Finding Your Shop ID

You’ll need your Shop ID for most API operations. There are two ways to find it:

Method 1: From Your Shop URL

Your shop URL format is etsy.com/shop/YourShopName. The shop ID is different from the name—you need to look it up via the API.

Method 2: Via API Call

Once authenticated, you can find your shop ID:

# After authentication (covered in next chapter)
response = requests.get(
    f"{BASE_URL}/application/shops",
    headers={"Authorization": f"Bearer {access_token}"}
)
shop_id = response.json()["results"][0]["shop_id"]
print(f"Your Shop ID: {shop_id}")

Testing Your Setup

Before moving to authentication, verify your setup:

# test_setup.py
from config import Config

# Check all required variables are set
required = ["API_KEY", "API_SECRET", "REDIRECT_URI"]
missing = [var for var in required if not getattr(Config, var)]

if missing:
    print(f"❌ Missing configuration: {', '.join(missing)}")
else:
    print("✅ Configuration complete!")
    print(f"   API Key: {Config.API_KEY[:8]}...")

Run it:

python test_setup.py

API Rate Limits

Etsy enforces rate limits to prevent abuse:

For digital product shops with hundreds of listings, these limits are usually sufficient. We’ll cover handling rate limits in the Error Handling chapter.

Common Setup Issues

“Invalid API Key” Error

• Double-check your keystring in .env
• Ensure there are no extra spaces or quotes
• Verify your app is approved in the developer portal

“Application Not Found”

• Your app may still be pending approval
• Check the developer portal for status

Environment Variables Not Loading

• Ensure .env is in your project root
• Call load_dotenv() before accessing variables
• Check file permissions

What’s Next

With your credentials ready and project structure in place, the next chapter covers OAuth 2.0 authentication—the process of obtaining an access token that lets you make API calls on behalf of your shop.

← Back to Table of Contents