Zinc
All Blogs
Guides

Etsy API: Seller Docs vs How to Search and Buy in Code (2026)

Etsy Open API v3 is built for sellers, not buyers. Compare Etsy v3, scrapers, and UCP, then search listings and place real Etsy orders via API with Zinc.

Short answer: Etsy's official Open API v3 (developers.etsy.com) is built for Etsy shop owners managing their own listings, inventory, and seller receipts—it has no endpoint to place a buyer order. Third-party Etsy scrapers only return read-only product data, and ChatGPT Instant Checkout only works inside ChatGPT's chat interface. To search Etsy listings and place real orders from your own application or AI agent, use Zinc: call GET /search?q=personalized+leather+journal&retailer=etsy, check variations and shop status with GET /products/{listing_id}?retailer=etsy, and place the purchase via POST /orders with variant, is_gift, and max_price.

Etsy hosts tens of millions of handmade, vintage, and personalized listings from independent makers. That catalog makes Etsy a top destination for corporate gifting platforms, AI gift-finder agents, wedding and milestone concierges, and employee recognition apps.

When developers search for an Etsy API to buy those items programmatically, they hit an immediate mismatch: every endpoint on Etsy's developer portal assumes you are the seller running the shop, not the customer checking out.

This guide breaks down every Etsy API and commerce integration, explains why Etsy checkout automation fails when built on scrapers, and shows how to search, inspect, and buy from Etsy programmatically with Zinc.


Every Etsy API and commerce integration, explained

Etsy exposes several technical integrations, each scoped to a different role in the transaction.

1. Etsy Open API v3 (developers.etsy.com)

Etsy Open API v3 is Etsy's official REST API. It uses OAuth 2.0 (authorization_code with PKCE) and requires registering an application and passing Etsy's developer review before moving beyond personal shop access.

What it covers: Creating and updating seller listings (createDraftListing, updateListingInventory), managing shop sections and shipping profiles, and reading inbound orders (getShopReceipts) placed at the authenticated seller's shop.

The catch: There is no createReceipt, addToCart, or buyer checkout endpoint anywhere in Open API v3. Even if your app passes Etsy's commercial access review, Open API v3 cannot purchase an item from another maker's Etsy shop.

2. Etsy Affiliate Program feeds (Awin)

Etsy runs its affiliate program through Awin, offering product data feeds and deep-linking tools for content publishers, gift blogs, and deal sites.

The catch: Affiliate feeds are strictly read-only merchandising files. Your user still has to click out to etsy.com, pick variations manually, enter their shipping address, and pay in a browser.

3. ChatGPT Instant Checkout (ACP) and Google UCP

Etsy was a launch partner for OpenAI's Agentic Commerce Protocol (ACP) powering Instant Checkout inside ChatGPT, as well as Google's Universal Commerce Protocol (UCP) for AI Mode and Gemini.

The catch: Those integrations let human consumers click Buy inside ChatGPT or Google Search surfaces. Etsy does not expose a self-serve ACP or UCP checkout endpoint that an independent SaaS backend, internal workflow, or custom AI agent can call directly with its own wallet, gift-slip rules, and webhook pipeline.

4. Multi-channel seller connectors (API2Cart, LitCommerce, CedCommerce)

Unified seller APIs like API2Cart wrap Etsy Open API v3 alongside Shopify, WooCommerce, and eBay so multi-channel merchants can sync stock levels and pull seller orders into a warehouse management system.

The catch: Because they sit on top of Open API v3, they inherit the exact same boundary: seller shop management only, never shopper checkout.


Third-party Etsy scraper APIs vs purchasing APIs

Developers who only need public listing data often turn to scraping actors and proxy APIs. Here is how they compare when your workflow needs to move from discovery to an actual shipped order:

ProviderWhat it returnsCan it place an order?Best for
Etsy Open API v3Authenticated seller shop listings, inventory, and inbound seller receiptsNoTools built for Etsy shop owners
API2CartNormalized seller catalog and order sync across Etsy + storefrontsNoMulti-channel inventory & WMS software
Apify (Etsy actors)Scraped search results, listing descriptions, images, and seller reviewsNoBatch catalog research and trend analysis
ScraperAPI / Bright DataRaw HTML or parsed JSON from etsy.com URLs through residential proxiesNoCustom read-only data pipelines
ZincDirect Etsy search, listing availability & vacation checks, automated order placement, gift receipts, and carrier trackingYesApps and AI agents that search and buy

Why Etsy checkout is harder to automate than big-box retail

Even teams that have built headless browser scripts for standardized retail catalogs run into Etsy-specific edge cases right away:

  1. Seller vacation mode on active listings. An Etsy listing can show positive stock while the maker's shop is temporarily on vacation—meaning checkout will fail unless you check shop vacation state first.
  2. Digital downloads mixed with physical goods. Searches for prints, planners, or templates return instant digital downloads alongside shipped physical products. Sending a shipping address for a digital-only listing breaks fulfillment workflows.
  3. Unstandardized maker variations. Unlike standardized UPC catalogs on Amazon or Walmart, each Etsy seller defines custom option dropdowns (Finish, Engraving Font, Chain Length, Gift Box Color).
  4. Gift-receipt price privacy. Because Etsy is heavily used for gifting, shipping an order where the packing slip reveals the item price to the recipient ruins the customer experience.
  5. Variable maker lead times and multi-carrier tracking. Independent studios ship via USPS, UPS, FedEx, DHL, Royal Mail, and Canada Post on custom production schedules (handling_days_max), requiring ongoing post-purchase tracking extraction.

For the broader engineering tradeoffs, see Web Scraping vs. Ecommerce APIs.


Zinc: search, inspect, and buy from Etsy via API

Zinc's Etsy integration is an active, production purchasing integration backed by live REST endpoints and an OAuth MCP server across Etsy, Amazon, Walmart, Best Buy, Home Depot, Lowe's, and 20+ retailers.

1. Search Etsy listings directly

Pass retailer=etsy to GET /search to query Etsy listings directly, with an optional max_price filter in cents so every returned item fits your budget:

curl "https://api.zinc.com/search?q=handmade+ceramic+mug&retailer=etsy&max_price=4500" \
  -H "Authorization: Bearer $ZINC_API_KEY"

Note an important design detail: Etsy (along with individual Shopify stores) is searched only when explicitly named via retailer=etsy—an unfiltered big-box search will not mix Etsy listings in unless you ask for them.

Want to test live Etsy search in your browser with zero setup? Open Zinc AI (handmade ceramic mug on Etsy) or connect the Zinc MCP server (https://mcp.zinc.com/mcp) in Claude, ChatGPT, or Cursor.

2. Inspect shop vacation status, listing type, and variations

Before placing an order on an Etsy listing ID (returned as product_id by /search), call GET /products/{product_id}?retailer=etsy:

curl "https://api.zinc.com/products/1748291042?retailer=etsy" \
  -H "Authorization: Bearer $ZINC_API_KEY"

Zinc returns Etsy-specific fields designed to prevent bad orders before checkout:

  • listing_type: "physical", "download", or "both"—so your app never tries to ship a digital PDF.
  • available and shop_is_vacation: available checks both item stock and whether the maker's shop is on vacation, while shop_is_vacation tells you specifically why an in-stock listing is paused.
  • shop_review_average and shop_review_count: Reports the seller's shop rating over the trailing 12 months (rather than conflating shop ratings with single-SKU stars).
  • has_variations: Indicates whether the listing requires selecting options (such as size or glaze color) from the listing page and passing them in variant on POST /orders.

3. Place an Etsy order with variant, is_gift, and max_price

Submit POST /orders to Create Order with the etsy.com listing URL, any required variant selections, max_price in cents, and optional gift parameters:

curl -X POST https://api.zinc.com/orders \
  -H "Authorization: Bearer $ZINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "client_gift_mug_2026_11",
    "products": [
      {
        "url": "https://www.etsy.com/listing/1748291042/speckled-stoneware-coffee-mug",
        "quantity": 1,
        "variant": [
          { "label": "Glaze Color", "value": "Moss Green" }
        ]
      }
    ],
    "shipping_address": {
      "first_name": "Elena",
      "last_name": "Rostova",
      "address_line1": "742 Evergreen Terrace",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97205",
      "country": "US",
      "phone_number": "5035550148"
    },
    "is_gift": true,
    "gift_message": "Congrats on the launch! Enjoy your morning coffee — The Acme Team",
    "handling_days_max": 5,
    "max_price": 4500
  }'

Three safeguards protect automated Etsy orders in production:

  • Strict gift-price suppression (is_gift: true). If a checkout offers no free gift option to hide prices on the packing slip, Zinc fails the order cleanly with gift_option_unavailable rather than shipping a gift with prices visible to your recipient.
  • Lead-time ceiling (handling_days_max). Caps seller processing and handling days so made-to-order items with three-week queues do not miss an event date.
  • Total price cap (max_price). Covers item price, shipping, and tax in cents (4500 = $45.00), halting checkout if shipping or option surcharges push the total above budget.

You can test search, product lookups, and order creation for free using a synthetic zn_test_ key (POST https://api.zinc.com/sandbox/keys) in Zinc test mode.

4. Receive carrier tracking via webhooks

Because placement is asynchronous, POST /orders returns 201 with status: "pending" while Zinc completes checkout. Poll GET /orders/{order_id} or subscribe to Zinc webhooks (order.placed, order.tracking_received, order.delivered) to capture USPS, UPS, FedEx, or international tracking numbers automatically as soon as the maker prints the shipping label.


What teams build with Etsy and Zinc

AI gift finders that actually ship the gift

Most AI gift recommenders stop at brainstorming ideas or handing the user an affiliate link. Pairing LLM gift curation with GET /search?retailer=etsy and POST /orders lets your app propose a real artisan item, confirm the recipient's address, and ship it with is_gift: true. Read How to Build an AI Gift Finder That Actually Buys for the end-to-end architecture.

Automated corporate and client gifting

Sales, customer-success, and HR platforms trigger curated gifts from CRM milestones—closed deals, renewals, work anniversaries, or new-baby packages—without warehousing branded swag. See our Corporate Gifting API guide and Send Physical Gifts via API.

Concierge and hospitality procurement

Boutique hotels, interior-design studios, and executive-assistant agents source vintage decor, custom signage, and small-batch welcome amenities from Etsy alongside everyday essentials from Amazon and Home Depot through one unified billing and tracking pipeline.


FAQ

Does Etsy have an API to buy products?

No. Etsy Open API v3 (developers.etsy.com) is designed for Etsy sellers managing their own shop listings, inventory, and incoming receipts. It has no cart or buyer order-placement endpoint. To buy products from Etsy programmatically, use a purchasing API like Zinc (POST https://api.zinc.com/orders).

How do I search Etsy products via API without owning an Etsy shop?

Call Zinc's search endpoint with retailer=etsy (GET https://api.zinc.com/search?q=ceramic+mug&retailer=etsy). Note that Etsy must be named explicitly in the retailer query parameter—unfiltered searches only query big-box discovery retailers.

How do Etsy product variations and vacation mode work in Zinc's API?

Call GET https://api.zinc.com/products/{listing_id}?retailer=etsy before ordering. The response includes available, shop_is_vacation (whether the seller paused their shop), listing_type (physical, download, or both), and has_variations. When has_variations is true, pass your chosen options as variant: [{ "label": "...", "value": "..." }] on POST /orders.

Can I send Etsy orders as gifts without prices showing on the packing slip?

Yes. Pass "is_gift": true and an optional "gift_message" (up to 240 characters) on POST /orders. If a checkout does not offer free gift-price suppression, Zinc fails the order with gift_option_unavailable rather than exposing prices to your recipient.

Can ChatGPT or Claude buy from Etsy?

ChatGPT supports Instant Checkout for participating US Etsy sellers inside ChatGPT's consumer interface. To search and buy from Etsy in Claude, Cursor, or your own custom agent—and compare Etsy side-by-side with Amazon, Walmart, and Best Buy—connect Zinc's MCP server at https://mcp.zinc.com/mcp.


Next steps

Search and buy artisan gifts on Etsy with an AI agent

Install the Universal Checkout skill in Claude Code, Cursor, or OpenClaw, then paste this prompt to search Etsy, verify availability, and test a gift order.