canonical: https://jentic.com/apis/etsy.com/etsy

# Etsy Open API v3

Jentic publishes the only available OpenAPI specification for Etsy Open API v3, keeping it validated and agent-ready. Access Etsy's handmade and vintage marketplace with 103 endpoints covering shop management, product listings with images and inventory, order receipts, payment ledgers, shipping profiles, reviews, and buyer taxonomy. Supports the full seller lifecycle from listing creation through fulfillment and financial reconciliation.

## For AI agents

Manage Etsy shops, listings, orders, and payments across the handmade and vintage marketplace. Provides 103 endpoints for the complete seller lifecycle from product creation to fulfillment.

## Scope

Does not handle payment processing, advertising campaigns, or buyer account management - use for seller-side shop and listing operations only.

## Capabilities

- Create and update product listings with images, videos, inventory tracking, and personalization options
- Retrieve order receipts with line-item transactions and shipping tracking details
- Configure shipping profiles with destinations, rates, and carrier-specific upgrade options
- Access payment ledger entries and reconcile shop revenue against individual transactions
- Browse buyer and seller taxonomy nodes to assign correct categories and item attributes
- Manage shop sections, return policies, and holiday preferences for store organization
- Upload listing images and videos with position ordering for storefront display

## Use cases

### AI Agent Listing Management

AI agents use the Etsy Open API through Jentic to automate listing creation and updates for handmade sellers. An agent can create listings with proper taxonomy classification, upload product images, set inventory quantities per variation, configure personalization options, and manage pricing - all without manual interaction with Etsy's seller tools. The 103-endpoint surface covers the complete listing lifecycle.

Example prompt: Create a new listing in shop ID 12345 with title 'Handmade Silver Ring', taxonomy ID 6648, price 45.00 USD, quantity 10, and upload a product image

### Order Fulfillment and Tracking

Process Etsy orders and provide shipping updates through the receipts and tracking endpoints. Retrieve pending orders with buyer shipping addresses, mark orders as shipped with carrier and tracking number, and access transaction-level details for each line item. Supports multi-item orders with individual fulfillment tracking per receipt.

Example prompt: Retrieve all receipts with status 'open' for shop ID 12345, then add tracking with carrier 'usps' and tracking code '9400111899223100012345' to receipt ID 2345678

### Shop Financial Reconciliation

Reconcile Etsy shop finances using the payment ledger and transaction endpoints. Access individual ledger entries showing listing fees, transaction fees, shipping label costs, and deposit amounts. Match payment entries to specific order receipts for accurate bookkeeping and tax preparation across reporting periods.

Example prompt: Retrieve all payment ledger entries for shop ID 12345 for the month of April 2026 and calculate total fees versus gross revenue

### Multi-Channel Inventory Sync

Synchronize Etsy inventory with other sales channels by reading and updating listing quantities through the inventory endpoints. Each listing supports multiple product variations (size, color) with independent stock tracking. Pull current quantities, push updates after external sales, and monitor stock levels to prevent overselling across platforms.

Example prompt: Get the current inventory for listing ID 9876543 across all variations, then update the 'Small/Blue' variation to quantity 5

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v3/application/shops/{shop_id}/listings | Create a new listing in a shop |
| GET | /v3/application/shops/{shop_id}/receipts | List order receipts for a shop |
| GET | /v3/application/listings/{listing_id}/inventory | Get inventory for a listing |
| POST | /v3/application/shops/{shop_id}/listings/{listing_id}/images | Upload an image to a listing |
| POST | /v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking | Add shipping tracking to a receipt |
| GET | /v3/application/shops/{shop_id}/payment-account/ledger-entries | List payment ledger entries |
| GET | /v3/application/listings/active | Search active listings across Etsy |
| GET | /v3/application/buyer-taxonomy/nodes | Get buyer taxonomy categories |

## Key resources

- **Listings** — Create, update, and search product listings with images, inventory, and properties
- **Receipts** — Retrieve order receipts with buyer details, line items, and fulfillment status
- **Inventory** — Track stock quantities per listing variation with offering-level pricing
- **Payments** — Access payment ledger entries and reconcile shop financial records
- **Shipping Profiles** — Configure shipping rates, destinations, and carrier upgrade options
- **Taxonomy** — Browse category trees for proper listing classification and attribute assignment

## Why Jentic

- **Setup:** Wiring the Etsy Open API v3 by hand means running its OAuth 2.0 PKCE flow, refreshing tokens, injecting the x-api-key header, and mapping shop and listing operations yourself. Through Jentic you install once, import the Etsy Open API v3 from the API Directory, store the API key and OAuth credentials once, and your agent calls it.
- **Permission scoping:** Etsy puts the shop id in the URL path (/shops/{shop_id}/...), so a rule can pin your agent to one shop: it manages listings and receipts for that shop and nothing else. You choose the operations it may call, so a write like creating a listing is not included unless you add it.
- **Credential handling:** Your Etsy API key and OAuth 2.0 tokens are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an Etsy listing with images' or 'list a shop's receipts', and Jentic returns the matching Etsy operation with its input schema so the agent calls the right endpoint without navigating the developer documentation.

## Related APIs

- **Shopify REST Admin API** — Full-featured e-commerce platform for merchants who need their own branded storefront beyond Etsy's marketplace
- **eBay Catalog API** — Cross-list Etsy products on eBay with catalog-matched structured data
- **Shippo API** — Multi-carrier shipping label generation and rate comparison for Etsy orders
- **Stripe API** — Payment processing for standalone shops that complement an Etsy presence

## FAQ

### Why is there no official OpenAPI spec for Etsy Open API v3?

Etsy does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Etsy Open API v3 via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Etsy Open API v3 use?

Etsy uses a two-tier auth model: an x-api-key header for public read operations and OAuth 2.0 with PKCE for shop-specific write operations. Through Jentic, both credentials are stored encrypted in your Jentic One instance - agents receive pre-authenticated requests without managing the OAuth PKCE flow or key rotation.

### Can I create listings with multiple variations and inventory tracking?

Yes. POST to /v3/application/shops/{shop_id}/listings to create a listing, then use the inventory endpoints to set up product variations (e.g., size and color combinations) with independent pricing and quantity per offering. Each variation gets its own SKU and stock count.

### What are the rate limits for the Etsy Open API?

Etsy enforces a rate limit of 10 requests per second per API key for most endpoints. Some endpoints like search have lower limits. Exceeding limits returns a 429 response. The API returns X-RateLimit-Remaining and X-RateLimit-Limit headers with each response for proactive throttling.

### How do I process orders and add tracking through Jentic?

Search Jentic for 'get Etsy order receipts' to discover GET /v3/application/shops/{shop_id}/receipts. Filter by was_shipped=false for unfulfilled orders. Then search for 'add tracking to Etsy order' to find the POST tracking endpoint. Pass carrier_name and tracking_code to mark the receipt as shipped.

### Does the API support uploading listing images?

Yes. POST to /v3/application/shops/{shop_id}/listings/{listing_id}/images with a multipart form containing the image file. You can upload up to 10 images per listing and control display order via the rank parameter. Supported formats include JPEG, PNG, and GIF up to 10MB.

### Can I browse Etsy's category taxonomy programmatically?

Yes. GET /v3/application/buyer-taxonomy/nodes returns the full category tree. Use /v3/application/buyer-taxonomy/nodes/{taxonomy_id}/properties to get required and optional attributes for a specific category. This ensures listings are created with correct classification and item specifics.

### Can I limit what my agent is allowed to do with the Etsy Open API v3?

Yes. Because you self-host Jentic One, your own rules decide which Etsy operations and credentials the agent may use. Etsy puts the shop id in the URL path (/shops/{shop_id}/...), so a rule can pin the agent to a single shop, letting it read receipts and manage listings for that shop and nothing else. You also choose the specific operations it may call, so a write such as creating a listing or adding tracking to a receipt is off limits until you explicitly allow it.