Etsy Open API v3

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.