Etsy API Client Library for Python

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
  • Install from PyPI
  • Install from Source
  • Dependencies
• Quick Start
  • 1. Authentication Setup
  • 2. Initialize Client Session
  • 3. Make API Calls
• Usage Examples
  • Managing Listings
  • Working with Receipts
  • Uploading Images
  • Handling Shipping Profiles
  • Token Management with Callback
• API Resources
  • Core Resources
  • Media Resources
  • Commerce Resources
  • Shop Management
• Error Handling
• Environment Configuration
• Project Structure
• Contributing
  • Development Setup
• Support
• License
• Changelog

---

Overview

A comprehensive Python client library for the Etsy API v3, providing a modern, type-safe interface for interacting with the Etsy marketplace. This SDK simplifies OAuth 2.0 authentication, automatic token refresh, and provides complete coverage of Etsy's API endpoints.

Features

✨ Complete API Coverage - Full support for Etsy API v3 endpoints including:

• Listings management (create, update, delete, search)
• Shop operations (sections, policies, production partners)
• Receipt and transaction handling
• Shipping profiles and destinations
• Product taxonomy and attributes
• File, image, and video uploads
• Reviews and payment processing

🔐 Robust Authentication - OAuth 2.0 with PKCE support:

• Secure authorization code flow
• Automatic token refresh before expiry
• Custom token synchronization callbacks
• Session management with timezone-aware expiry handling

🏗️ Developer-Friendly Architecture:

• Type-safe request/response models using dataclasses
• Comprehensive enum definitions for API parameters
• Consistent error handling with detailed exceptions
• Rate limiting information in responses
• Clean separation of concerns with resource-based structure

⚡ Production Ready:

• Built-in retry logic for failed requests
• Configurable environments (production/staging)
• Extensive error handling and validation
• Support for file uploads and multipart requests

Requirements

• Python 3.10 or higher
• An Etsy App API Key (get one at Etsy Developers)

Installation

Install from PyPI

pip install etsy-python

Install from Source

git clone https://github.com/amitray007/etsy-python-sdk.git
cd etsy-python-sdk
pip install -e .

Dependencies

The SDK requires:

• requests>=2.32.2 - HTTP client library
• requests-oauthlib>=1.3.1 - OAuth 2.0 support

Quick Start

1. Authentication Setup

frometsy_python.v3.auth.OAuthimportEtsyOAuth# Initialize OAuth clientoauth=EtsyOAuth(
keystring="your_api_key",
redirect_uri="http://localhost:8000/callback",
scopes=["listings_r", "listings_w", "shops_r", "shops_w"]
)
# Get authorization URLauth_url, state=oauth.get_auth_code()
print(f"Visit this URL to authorize: {auth_url}")
# After user authorizes, set the authorization codeoauth.set_authorisation_code(code="auth_code_from_callback", state=state)
# Get access tokentoken_data=oauth.get_access_token()

2. Initialize Client Session

fromdatetimeimportdatetimefrometsy_python.v3.resources.SessionimportEtsyClient# Create client with tokensclient=EtsyClient(
keystring="your_api_key",
access_token=token_data["access_token"],
refresh_token=token_data["refresh_token"],
expiry=datetime.utcnow() +timedelta(seconds=token_data["expires_in"])
)

3. Make API Calls

frometsy_python.v3.resources.ListingimportListingResourcefrometsy_python.v3.enums.ListingimportState, SortOn, SortOrder# Initialize resourcelisting_resource=ListingResource(session=client)
# Get active listings for a shopresponse=listing_resource.get_listings_by_shop(
shop_id=12345,
state=State.ACTIVE,
limit=25,
sort_on=SortOn.CREATED,
sort_order=SortOrder.DESC
)
print(f"Found {len(response.message['results'])} listings")

Usage Examples

Managing Listings

frometsy_python.v3.models.ListingimportCreateDraftListingRequestfrometsy_python.v3.enums.ListingimportWhoMade, WhenMade# Create a draft listingdraft_listing=CreateDraftListingRequest(
title="Handmade Ceramic Mug",
description="Beautiful handcrafted ceramic mug",
price=25.00,
quantity=10,
who_made=WhoMade.I_DID,
when_made=WhenMade.MADE_TO_ORDER,
taxonomy_id=1234,
tags=["ceramic", "mug", "handmade"]
)
response=listing_resource.create_draft_listing(
shop_id=12345,
listing=draft_listing
)

Working with Receipts

frometsy_python.v3.resources.ReceiptimportReceiptResourcefrometsy_python.v3.models.ReceiptimportCreateReceiptShipmentRequestreceipt_resource=ReceiptResource(session=client)
# Get shop receiptsreceipts=receipt_resource.get_shop_receipts(
shop_id=12345,
limit=50
)
# Create shipment for a receiptshipment_request=CreateReceiptShipmentRequest(
tracking_number="1Z999AA10123456784",
carrier_name="USPS",
notification_sent=True
)
receipt_resource.create_receipt_shipment(
shop_id=12345,
receipt_id=67890,
shipment=shipment_request
)

Uploading Images

frometsy_python.v3.resources.ListingImageimportListingImageResourcefrometsy_python.v3.models.ListingimportUploadListingImageRequestimage_resource=ListingImageResource(session=client)
# Upload image to listingwithopen("product_photo.jpg", "rb") asimage_file:
upload_request=UploadListingImageRequest(
image=image_file,
alt_text="Front view of ceramic mug"
)
response=image_resource.upload_listing_image(
shop_id=12345,
listing_id=67890,
image=upload_request
)

Handling Shipping Profiles

frometsy_python.v3.resources.ShippingProfileimportShippingProfileResourcefrometsy_python.v3.models.ShippingProfileimportCreateShopShippingProfileRequestfrometsy_python.v3.enums.ShippingProfileimportProcessingTimeUnitshipping_resource=ShippingProfileResource(session=client)
# Create shipping profileprofile_request=CreateShopShippingProfileRequest(
title="Standard Shipping",
processing_time_value=3,
processing_time_unit=ProcessingTimeUnit.BUSINESS_DAYS,
origin_country_iso="US",
primary_cost=5.00,
secondary_cost=2.00
)
response=shipping_resource.create_shop_shipping_profile(
shop_id=12345,
profile=profile_request
)

Token Management with Callback

defsave_tokens_to_database(access_token, refresh_token, expiry):
"""Custom function to persist tokens"""# Your database logic herepass# Initialize client with token sync callbackclient=EtsyClient(
keystring="your_api_key",
access_token=access_token,
refresh_token=refresh_token,
expiry=expiry,
sync_refresh=save_tokens_to_database
)
# Tokens will be automatically refreshed and saved when expired

API Resources

The SDK provides comprehensive coverage of Etsy API v3 resources:

Core Resources

• Listing - Create, read, update, delete listings
• Shop - Manage shop information and settings
• Receipt - Handle orders and transactions
• ReceiptTransactions - Individual transaction details
• User - User profiles and addresses
• UserAddress - User address management
• ShippingProfile - Configure shipping options and destinations

Media Resources

• ListingImage - Upload and manage listing images
• ListingVideo - Upload and manage listing videos
• ListingFile - Digital file management
• ListingVariationImages - Variation-specific images

Commerce Resources

• ListingInventory - Stock and SKU management
• ListingOffering - Product offering details
• ListingProduct - Product variant management
• Payment - Payment processing
• PaymentLedgerEntry - Payment ledger entries
• Review - Customer reviews management

Shop Management

• ShopSection - Organize listings into sections
• ShopReturnPolicy - Define return policies
• ShopProductionPartner - Manage production partners
• HolidayPreferences - Shop holiday schedule
• ProcessingProfile - Processing time profiles

Taxonomy & Translation

• BuyerTaxonomy / SellerTaxonomy - Product categories and attributes
• ListingTranslation - Listing localization
• Miscellaneous - Ping and other utility endpoints

Error Handling

The SDK provides detailed error information through custom exceptions:

frometsy_python.v3.exceptions.RequestExceptionimportRequestExceptiontry:
response=listing_resource.get_listing(listing_id=12345)
exceptRequestExceptionase:
print(f"Error Code: {e.code}")
print(f"Error Message: {e.error}")
print(f"Error Description: {e.type}")
# Rate limit information (if available)ife.rate_limits:
print(f"Daily Limit: {e.rate_limits.limit_per_day}")
print(f"Remaining Today: {e.rate_limits.remaining_today}")

Environment Configuration

Configure the SDK environment using environment variables:

# Set environment (defaults to PROD)export ETSY_ENV=PROD

Project Structure

etsy-python-sdk/
├── etsy_python/
│ ├── _version.py # Single source of truth for version
│ └── v3/
│ ├── auth/ # OAuth 2.0 PKCE authentication
│ ├── common/ # Shared utilities and HTTP constants
│ ├── enums/ # Type-safe API parameter constants
│ ├── exceptions/ # Custom exceptions with rate limit info
│ ├── models/ # Request data models with validation
│ └── resources/ # ~28 API endpoint resource classes
├── tests/ # pytest test suite
│ └── fixtures/ # Shared test fixtures and mock responses
├── scripts/ # Maintenance and release scripts
├── specs/ # OAS spec files and audit reports
├── .github/
│ ├── workflows/ # CI/CD and PR automation
│ └── CODEOWNERS # Required reviewers for sensitive files
├── setup.py # Package configuration
├── requirements-dev.txt # Development/testing dependencies
└── README.md # Documentation

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Automatic Versioning

This project uses automatic semantic versioning based on commit messages:

• Commits with breaking: or BREAKING CHANGE → Major version bump (1.0.0 → 2.0.0)
• Commits with feat: or containing feature → Minor version bump (1.0.0 → 1.1.0)
• All other commits → Patch version bump (1.0.0 → 1.0.1)

The version is automatically bumped when changes are pushed to the master branch, and the package is automatically published to PyPI.

Skipping CI/CD

To skip the automatic versioning and publishing workflow, include one of these phrases in your commit message:

• [skip ci]
• [ci skip]
• skip ci
• [no ci]

Example:

git commit -m "docs: update README [skip ci]"

Manual Release (for maintainers)

For local testing or manual releases:

# Install development dependencies
pip install -e .# Create a patch release
python scripts/release.py patch
# Create a minor release
python scripts/release.py minor
# Create a major release
python scripts/release.py major
# Dry run (local only, no push)
python scripts/release.py patch --no-push

Development Setup

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/yourusername/etsy-python-sdk.git
   cd etsy-python-sdk

3. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate # On Windows: venv\Scripts\activate

4. Install dependencies:

   pip install -r etsy_python/requirements.txt
   pip install -r requirements-dev.txt

5. Run the test suite:

   pytest -v
   pytest --cov=etsy_python --cov-report=term-missing

6. Create a feature branch:

   git checkout -b feature/your-feature-name

7. Make your changes and commit:

   git commit -m "feat: add your feature"

8. Push and create a pull request

CI on Pull Requests

Pull requests automatically trigger:

• pr-tests.yml — Runs the full test suite with coverage reporting (posts/updates a comment on the PR)
• pr-coverage.yml — SDK coverage audit against the Etsy OAS spec (triggered by the sdk-check label)

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Etsy API Docs: developers.etsy.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See Releases for full changelog.

---

Made with ❤️ for the Etsy developer community