Etsy Open API v3
★ Only Publicly Available OpenAPI DocumentE CommerceStorefrontapiKey, oauth2103 EndpointsREST
For 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.
Use for: I need to create a new listing in my Etsy shop with multiple images, Retrieve all open order receipts for my shop from the last week, Update the inventory quantity for a specific listing variation, Get the shipping tracking information for a customer's order
Not supported: Does not handle payment processing, advertising campaigns, or buyer account management - use for seller-side shop and listing operations only.
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.
Install Jentic One Beta
Connect the Etsy Open API v3 to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Etsy Open API v3, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fetsy.com%2Fetsy" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fetsy.com%2Fetsy" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Etsy Open API v3 API.
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
Patterns agents use Etsy Open API v3 API for, with concrete tasks.
★ 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.
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.
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.
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.
Get the current inventory for listing ID 9876543 across all variations, then update the 'Small/Blue' variation to quantity 5
Key Endpoints
103 endpoints — jentic publishes the only available openapi specification for etsy open api v3, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Complementary
Stripe API
Payment processing for standalone shops that complement an Etsy presence
Use when the seller runs a separate direct-to-consumer site alongside Etsy and needs unified payment processing, subscription billing, or custom checkout experiences.
FAQs
Specific to using Etsy Open API v3 API through Jentic.
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.
GET STARTED