# Eto API

> REST/JSON API for Etsy sellers: search and research listings, build and publish them, and read orders, finance and traffic for the shops connected to an Eto account. 127 operations, base URL https://eto.tools/api/v1/, one API key in the X-Eto-API-Key header.

Read llms-full.txt below if you want the whole reference in one fetch; it is about 527 KB. Otherwise follow the per-endpoint links: each one is a self-contained page with the operation ID, parameters, a runnable curl/Python/JavaScript request and the errors it can return. Every path is relative to https://eto.tools/api/v1/ and every request needs `X-Eto-API-Key: eto_your_key`, generated in the API console at https://eto.tools/dashboard/api/. The API is an Enterprise feature; keys on other plans are refused with INVALID_API_KEY.

Endpoints marked "connected store" need the Etsy shop linked to the account: call GET /api/v1/stores first and use the shop_id values it returns. Rate limits are 2 requests/second and 5,000/day; on a 429 obey the Retry-After header. Do not guess paths or field names from memory — this API is not the Etsy API, and the endpoint pages below are the current contract.

Questions about the Eto app rather than the API — "where is X", "which page changes Y" — are answered by the feature map under "Where everything is" below: 1104 features across 16 pages, each with the exact path through the interface.

## Machine-readable

- [OpenAPI 3.1 (JSON)](https://eto.tools/dev/docs/openapi.json): every operation, parameter, schema and error, ready to turn into tool definitions.
- [OpenAPI 3.1 (YAML)](https://eto.tools/dev/docs/openapi.yaml): the same document in YAML.
- [llms-full.txt](https://eto.tools/dev/docs/llms-full.txt): this entire reference as one Markdown file.
- [index.md](https://eto.tools/dev/docs/index.md): the Markdown twin of the HTML reference page — the same document as llms-full.txt.
- [MCP server](https://mcp.eto.tools/mcp): the same API as MCP tools, one per operation.

## Getting started

- [API reference (HTML)](https://eto.tools/dev/docs/): the human page. Endpoint anchors are `#ep-` plus the endpoint slug.
- [API console](https://eto.tools/dashboard/api/): generate, rotate and revoke keys; configure webhooks.
- [MCP setup guide](https://eto.tools/mcp/): connecting Claude, ChatGPT or Perplexity.

## Where everything is

- [Where everything is](https://eto.tools/dev/docs/where-everything-is.md): every page, feature and control in the Eto app, with its UI path. Read this to answer "where do I change X".
- [feature-map.json](https://eto.tools/dev/docs/feature-map.json): the same map as JSON, with `path`, `url` and `api_operation_id` on every feature.
- [Dashboard](https://eto.tools/dev/docs/where/dashboard.md): The account home page: a store header, four tabs, a live order feed, a money statement with a chart, and boards for out-of-stock listings and listing performance.
- [Analytics](https://eto.tools/dev/docs/where/analytics.md): A ten-tab reporting page over orders, money, stores, listings and operations, with a KPI strip, a live event stream and an orders map.
- [Orders](https://eto.tools/dev/docs/where/orders.md): One list of every Etsy order across your connected stores, with costs, tracking, notes and supplier sharing.
- [Finance](https://eto.tools/dev/docs/where/finance.md): Your Etsy money by day or date range: balance, payouts, sales, fees, ads, refunds, COGS and profit, with the ledger behind every figure.
- [Stores](https://eto.tools/dev/docs/where/stores.md): Connect Etsy shops to Eto and control what each one shows on the rest of the app.
- [Listing Manager](https://eto.tools/dev/docs/where/listing-manager.md): Browse, filter and bulk edit every listing across your connected Etsy shops.
- [Quick upload](https://eto.tools/dev/docs/where/quick-upload.md): Build Etsy listings in Eto and push them to one or more connected stores as drafts.
- [VA Admin](https://eto.tools/dev/docs/where/va-admin.md): Create virtual assistant logins, set what each one may do per store, and review what they have done.
- [Product Hunt](https://eto.tools/dev/docs/where/product-hunt.md): Searches the Etsy marketplace for a keyword, scores every listing for 24h demand, and shows the results as a filterable card grid.
- [Shop Spy](https://eto.tools/dev/docs/where/shop-spy.md): Takes any Etsy listing link and pulls that whole shop, then lets you sort and filter every active listing it has.
- [Gallery](https://eto.tools/dev/docs/where/gallery.md): Chat with Gemini to generate, edit and keep product imagery for your listings.
- [Workflow](https://eto.tools/dev/docs/where/workflow.md): Puts Product Hunt, AI Studio and Quick Upload side by side in three resizable panes so a product can go from research to published without changing page.
- [Developer API console](https://eto.tools/dev/docs/where/developer-api-console.md): Where an Enterprise account creates its API key, connects an MCP client, and configures and watches outbound webhooks.
- [Settings](https://eto.tools/dev/docs/where/settings.md): Seven tabs holding account, billing, AI provider, notification, order integration, theme and affiliate settings.
- [Sidebar](https://eto.tools/dev/docs/where/sidebar.md): The rail down the left of every dashboard page: navigation, the theme switch, and the quick panels that float research tools over whatever page you are on.
- [Command palette](https://eto.tools/dev/docs/where/command-palette.md): Cmd+K from anywhere: one box that jumps to a page, runs a control on the page you are on, or searches your listings, orders and stores.

## Listing Builder

Create a complete Etsy listing from one JSON payload, and fetch the category schema and store profiles it needs. [All 6 as one page](https://eto.tools/dev/docs/listing-builder.md).

- [GET /api/v1/categories/{category_id}/listing-schema](https://eto.tools/dev/docs/listing-builder/listing-schema.md): Get category listing schema
- [POST /api/v1/listings/create](https://eto.tools/dev/docs/listing-builder/listing-create.md): Create a listing
- [GET /api/v1/listings/create/{job_id}](https://eto.tools/dev/docs/listing-builder/listing-create-status.md): Poll listing creation job status
- [GET /api/v1/stores/{shop_id}/details](https://eto.tools/dev/docs/listing-builder/store-details-cached.md): Get cached store details (zero Etsy calls)
- [POST /api/v1/stores/{shop_id}/sync](https://eto.tools/dev/docs/listing-builder/store-sync.md): Sync store data from Etsy
- [POST /api/v1/uploads](https://eto.tools/dev/docs/listing-builder/file-upload.md): Upload a file (image, video, or digital file)

## Search

Search active Etsy listings across the marketplace. [All 1 as one page](https://eto.tools/dev/docs/search.md).

- [GET /api/v1/listings/search](https://eto.tools/dev/docs/search/listings-search.md): Search active Etsy listings

## Listings

Read and edit single listings: detail, images, inventory, reviews. [All 11 as one page](https://eto.tools/dev/docs/listings.md).

- [GET /api/v1/listings/{listing_id}](https://eto.tools/dev/docs/listings/listing-detail.md): Get listing details
- [DELETE /api/v1/listings/{listing_id}](https://eto.tools/dev/docs/listings/listing-delete.md): Delete a listing
- [GET /api/v1/listings/{listing_id}/images](https://eto.tools/dev/docs/listings/listing-images.md): Get listing images
- [GET /api/v1/listings/{listing_id}/reviews](https://eto.tools/dev/docs/listings/listing-reviews.md): Get listing reviews
- [GET /api/v1/listings/{listing_id}/inventory](https://eto.tools/dev/docs/listings/listing-inventory-get.md): Get listing inventory
- [PUT /api/v1/listings/{listing_id}/inventory](https://eto.tools/dev/docs/listings/listing-inventory-update.md): Update listing inventory
- [GET /api/v1/listings/{listing_id}/videos](https://eto.tools/dev/docs/listings/listing-videos.md): Get listing videos
- [GET/POST/DELETE /api/v1/listings/{listing_id}/personalization](https://eto.tools/dev/docs/listings/listing-personalization.md): Manage listing personalization
- [GET /api/v1/listings/batch](https://eto.tools/dev/docs/listings/listings-batch.md): Batch get listings
- [GET /api/v1/listings/{listing_id}/products/{product_id}/offerings/{offering_id}](https://eto.tools/dev/docs/listings/listing-offering.md): Get a listing offering
- [GET /api/v1/listings/{listing_id}/inventory/products/{product_id}](https://eto.tools/dev/docs/listings/listing-product.md): Get a product variant

## Shops

Public shop lookups: details, sections, reviews, production partners. [All 8 as one page](https://eto.tools/dev/docs/shops.md).

- [GET /api/v1/shops/{shop_id}](https://eto.tools/dev/docs/shops/shop-detail.md): Get shop details
- [GET /api/v1/shops/{shop_id}/reviews](https://eto.tools/dev/docs/shops/shop-reviews.md): Get shop reviews
- [GET /api/v1/shops/{shop_id}/sections](https://eto.tools/dev/docs/shops/shop-sections-get.md): Get shop sections
- [POST /api/v1/shops/{shop_id}/sections](https://eto.tools/dev/docs/shops/shop-sections-create.md): Create shop section
- [PUT /api/v1/shops/{shop_id}](https://eto.tools/dev/docs/shops/shop-update.md): Update shop details
- [GET /api/v1/shops](https://eto.tools/dev/docs/shops/shop-search.md): Search shops
- [GET/PUT/DELETE /api/v1/shops/{shop_id}/sections/{section_id}](https://eto.tools/dev/docs/shops/shop-section-detail.md): Get, update, or delete a section
- [GET /api/v1/shops/{shop_id}/section-listings](https://eto.tools/dev/docs/shops/section-listings.md): Get listings by section

## Store Management

Create and edit listings inside a shop you own. [All 5 as one page](https://eto.tools/dev/docs/store-management.md).

- [GET/POST /api/v1/shops/{shop_id}/listings](https://eto.tools/dev/docs/store-management/shop-listings.md): List or create shop listings
- [PATCH /api/v1/shops/{shop_id}/listings/{listing_id}](https://eto.tools/dev/docs/store-management/shop-listing-update.md): Update a listing
- [GET /api/v1/shops/{shop_id}/listings/active](https://eto.tools/dev/docs/store-management/shop-active-listings.md): Get active listings only
- [GET /api/v1/shops/{shop_id}/listings/featured](https://eto.tools/dev/docs/store-management/shop-featured-listings.md): Get featured listings
- [GET/POST/PUT /api/v1/shops/{shop_id}/listings/{listing_id}/translations/{language}](https://eto.tools/dev/docs/store-management/listing-translation.md): Manage listing translations

## Finance

Eto’s own revenue, fee, refund and profit figures for a connected store. [All 3 as one page](https://eto.tools/dev/docs/finance.md).

- [GET /api/v1/finance/{shop_id}](https://eto.tools/dev/docs/finance/finance.md): Get all finance metrics
- [POST /api/v1/finance/{shop_id}/sync](https://eto.tools/dev/docs/finance/finance-sync.md): Re-fetch finance data from Etsy
- [GET /api/v1/finance/software-expenses](https://eto.tools/dev/docs/finance/finance-software-expenses.md): Get logged software expenses (subscriptions)

## Images & Media

Listing images, videos and digital files. [All 9 as one page](https://eto.tools/dev/docs/images-and-media.md).

- [POST /api/v1/shops/{shop_id}/listings/{listing_id}/images](https://eto.tools/dev/docs/images-and-media/listing-image-upload.md): Upload listing image
- [DELETE /api/v1/shops/{shop_id}/listings/{listing_id}/images/{image_id}](https://eto.tools/dev/docs/images-and-media/listing-image-delete.md): Delete listing image
- [POST /api/v1/shops/{shop_id}/listings/{listing_id}/videos](https://eto.tools/dev/docs/images-and-media/listing-video-upload.md): Upload listing video
- [DELETE /api/v1/shops/{shop_id}/listings/{listing_id}/videos/{video_id}](https://eto.tools/dev/docs/images-and-media/listing-video-delete.md): Delete listing video
- [GET/POST /api/v1/shops/{shop_id}/listings/{listing_id}/variation-images](https://eto.tools/dev/docs/images-and-media/listing-variation-images.md): Manage variation images
- [GET/POST /api/v1/shops/{shop_id}/listings/{listing_id}/files](https://eto.tools/dev/docs/images-and-media/listing-file-upload.md): List or upload digital files
- [GET/DELETE /api/v1/shops/{shop_id}/listings/{listing_id}/files/{file_id}](https://eto.tools/dev/docs/images-and-media/listing-file-detail.md): Get or delete a digital file
- [GET /api/v1/listings/{listing_id}/images/{image_id}](https://eto.tools/dev/docs/images-and-media/listing-image-detail.md): Get a single image
- [GET /api/v1/listings/{listing_id}/videos/{video_id}](https://eto.tools/dev/docs/images-and-media/listing-video-detail.md): Get a single video

## Listing Properties

Category attributes on a listing. [All 4 as one page](https://eto.tools/dev/docs/listing-properties.md).

- [GET/PUT /api/v1/shops/{shop_id}/listings/{listing_id}/properties/{property_id}](https://eto.tools/dev/docs/listing-properties/listing-property.md): Get or update listing property
- [GET /api/v1/listings/{listing_id}/properties/{property_id}](https://eto.tools/dev/docs/listing-properties/listing-property-public.md): Get a listing property (public)
- [GET /api/v1/shops/{shop_id}/listings/{listing_id}/properties](https://eto.tools/dev/docs/listing-properties/listing-properties-all.md): Get all listing properties
- [DELETE /api/v1/shops/{shop_id}/listings/{listing_id}/properties/{property_id}](https://eto.tools/dev/docs/listing-properties/listing-property-delete.md): Delete a listing property

## Shipping

Shipping profiles, destinations, upgrades and carriers. [All 7 as one page](https://eto.tools/dev/docs/shipping.md).

- [GET/POST /api/v1/shops/{shop_id}/shipping-profiles](https://eto.tools/dev/docs/shipping/shipping-profiles.md): List or create shipping profiles
- [PUT/DELETE /api/v1/shops/{shop_id}/shipping-profiles/{profile_id}](https://eto.tools/dev/docs/shipping/shipping-profile-detail.md): Update or delete shipping profile
- [GET/POST /api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations](https://eto.tools/dev/docs/shipping/shipping-destinations.md): List or add shipping destinations
- [PUT/DELETE /api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations/{destination_id}](https://eto.tools/dev/docs/shipping/shipping-destination-detail.md): Update or delete a shipping destination
- [GET/POST /api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades](https://eto.tools/dev/docs/shipping/shipping-upgrades.md): List or add shipping upgrades
- [GET/PUT/DELETE /api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades/{upgrade_id}](https://eto.tools/dev/docs/shipping/shipping-upgrade-detail.md): Get, update, or delete a shipping upgrade
- [GET /api/v1/shipping-carriers](https://eto.tools/dev/docs/shipping/shipping-carriers.md): Get shipping carriers

## Categories

The Etsy taxonomy and the properties each category allows. [All 4 as one page](https://eto.tools/dev/docs/categories.md).

- [GET /api/v1/categories](https://eto.tools/dev/docs/categories/categories.md): Get product categories
- [GET /api/v1/categories/{category_id}/properties](https://eto.tools/dev/docs/categories/category-properties.md): Get category properties
- [GET /api/v1/buyer-categories](https://eto.tools/dev/docs/categories/buyer-categories.md): Get buyer categories
- [GET /api/v1/buyer-categories/{category_id}/properties](https://eto.tools/dev/docs/categories/buyer-category-properties.md): Get buyer category properties

## User

The authenticated Etsy user and the shops they own. [All 3 as one page](https://eto.tools/dev/docs/user.md).

- [GET /api/v1/users/me](https://eto.tools/dev/docs/user/users-me.md): Get current user
- [GET /api/v1/users/{user_id}/shops](https://eto.tools/dev/docs/user/user-shops.md): Get user shops
- [GET /api/v1/users/{user_id}](https://eto.tools/dev/docs/user/user-profile.md): Get user profile

## Shop Policies

Return policies, shop sections and listing requirements. [All 14 as one page](https://eto.tools/dev/docs/shop-policies.md).

- [GET /api/v1/shops/{shop_id}/return-policies](https://eto.tools/dev/docs/shop-policies/shop-return-policies.md): Get return policies
- [GET /api/v1/shops/{shop_id}/production-partners](https://eto.tools/dev/docs/shop-policies/shop-production-partners.md): Get production partners
- [GET/POST /api/v1/shops/{shop_id}/listing-requirements](https://eto.tools/dev/docs/shop-policies/shop-listing-requirements.md): Listing requirements
- [POST /api/v1/shops/{shop_id}/return-policies](https://eto.tools/dev/docs/shop-policies/return-policy-create.md): Create return policy
- [GET/PUT/DELETE /api/v1/shops/{shop_id}/return-policies/{policy_id}](https://eto.tools/dev/docs/shop-policies/return-policy-detail.md): Get, update, or delete a return policy
- [POST /api/v1/shops/{shop_id}/return-policies/consolidate](https://eto.tools/dev/docs/shop-policies/return-policy-consolidate.md): Consolidate return policies
- [GET /api/v1/shops/{shop_id}/return-policies/{policy_id}/listings](https://eto.tools/dev/docs/shop-policies/return-policy-listings.md): Get listings with a return policy
- [GET /api/v1/shops/{shop_id}/holiday-preferences](https://eto.tools/dev/docs/shop-policies/shop-holidays.md): Get holiday preferences
- [PUT /api/v1/shops/{shop_id}/holiday-preferences/{holiday_id}](https://eto.tools/dev/docs/shop-policies/shop-holiday-update.md): Update a holiday preference
- [GET/PUT/DELETE /api/v1/shops/{shop_id}/listing-requirements/{requirement_id}](https://eto.tools/dev/docs/shop-policies/listing-requirement-detail.md): Get, update, or delete a listing requirement
- [GET /api/v1/stores/{shop_id}/shipping-profiles/live](https://eto.tools/dev/docs/shop-policies/shipping-profiles-live.md): Get current shipping profiles (live, no cache)
- [GET /api/v1/stores/{shop_id}/return-policies/live](https://eto.tools/dev/docs/shop-policies/return-policies-live.md): Get current return policies (live, no cache)
- [GET /api/v1/stores/{shop_id}/processing-profiles/live](https://eto.tools/dev/docs/shop-policies/processing-profiles-live.md): Get current processing profiles (live, no cache)
- [GET /api/v1/stores/{shop_id}/shop-sections/live](https://eto.tools/dev/docs/shop-policies/shop-sections-live.md): Get current shop sections (live, no cache)

## Orders

Receipts and fulfilment, both Eto’s synced copy and the live Etsy passthrough. [All 9 as one page](https://eto.tools/dev/docs/orders.md).

- [GET /api/v1/shops/{shop_id}/orders](https://eto.tools/dev/docs/orders/shop-orders.md): List shop orders
- [GET /api/v1/shops/{shop_id}/orders/{order_id}](https://eto.tools/dev/docs/orders/shop-order-detail.md): Get order details
- [POST /api/v1/shops/{shop_id}/orders/{order_id}/tracking](https://eto.tools/dev/docs/orders/shop-order-tracking.md): Update order tracking
- [PUT /api/v1/shops/{shop_id}/orders/{order_id}/update](https://eto.tools/dev/docs/orders/order-update.md): Update an order
- [GET /api/v1/shops/{shop_id}/orders/{order_id}/listings](https://eto.tools/dev/docs/orders/order-listings.md): Get listings in an order
- [GET /api/v1/shops/{shop_id}/orders/{order_id}/payments](https://eto.tools/dev/docs/orders/order-payments.md): Get order payments
- [GET /api/v1/orders/{shop_id}](https://eto.tools/dev/docs/orders/orders-list.md): List orders for a store
- [GET /api/v1/orders/{shop_id}/{receipt_id}](https://eto.tools/dev/docs/orders/order-detail.md): Get one order
- [POST /api/v1/orders/{shop_id}/sync](https://eto.tools/dev/docs/orders/orders-sync.md): Sync orders from Etsy

## Finances

Raw Etsy ledger data: transactions, payments, sales. [All 8 as one page](https://eto.tools/dev/docs/finances.md).

- [GET /api/v1/shops/{shop_id}/finance/transactions](https://eto.tools/dev/docs/finances/shop-finance-transactions.md): Get financial transactions
- [GET /api/v1/shops/{shop_id}/finance/payments](https://eto.tools/dev/docs/finances/shop-finance-payments.md): Get payment details
- [GET /api/v1/shops/{shop_id}/finance/sales](https://eto.tools/dev/docs/finances/shop-finance-sales.md): Get sales history
- [GET /api/v1/shops/{shop_id}/listings/{listing_id}/sales](https://eto.tools/dev/docs/finances/listing-sales.md): Get sales for a listing
- [GET /api/v1/shops/{shop_id}/orders/{order_id}/transactions](https://eto.tools/dev/docs/finances/order-transactions.md): Get transactions for an order
- [GET /api/v1/shops/{shop_id}/finance/sales/{transaction_id}](https://eto.tools/dev/docs/finances/single-transaction.md): Get a single sale
- [GET /api/v1/shops/{shop_id}/finance/transactions/{entry_id}](https://eto.tools/dev/docs/finances/single-ledger-entry.md): Get a single financial transaction
- [GET /api/v1/shops/{shop_id}/finance/all-payments](https://eto.tools/dev/docs/finances/shop-all-payments.md): Get all payments

## Analytics

Shop traffic statistics. [All 1 as one page](https://eto.tools/dev/docs/analytics.md).

- [GET /api/v1/shops/{shop_id}/stats/traffic](https://eto.tools/dev/docs/analytics/shop-traffic-stats.md): Shop views & favorites (lifetime)

## Stores

The Etsy stores connected to your Eto account. [All 2 as one page](https://eto.tools/dev/docs/stores.md).

- [GET /api/v1/stores](https://eto.tools/dev/docs/stores/stores-list.md): List connected stores
- [GET /api/v1/stores/{shop_id}](https://eto.tools/dev/docs/stores/store-detail.md): Get a connected store

## Research

Product research: demand signals and AI ranking for a keyword. [All 1 as one page](https://eto.tools/dev/docs/research.md).

- [POST /api/v1/product-hunt](https://eto.tools/dev/docs/research/product-hunt.md): Run product research (Product Hunt)

## AI Studio

Generate listing titles, descriptions and images, and analyse product photos. [All 6 as one page](https://eto.tools/dev/docs/ai-studio.md).

- [POST /api/v1/ai/chat](https://eto.tools/dev/docs/ai-studio/ai-chat.md): AI chat
- [POST /api/v1/ai/generate-title](https://eto.tools/dev/docs/ai-studio/ai-generate-title.md): AI: generate a listing title
- [POST /api/v1/ai/generate-description](https://eto.tools/dev/docs/ai-studio/ai-generate-description.md): AI: generate a listing description
- [POST /api/v1/ai/generate-image](https://eto.tools/dev/docs/ai-studio/ai-generate-image.md): AI: generate an image (async)
- [GET /api/v1/ai/generate-image/status](https://eto.tools/dev/docs/ai-studio/ai-generate-image-status.md): AI: image generation status
- [POST /api/v1/ai/analyze-image](https://eto.tools/dev/docs/ai-studio/ai-analyze-image.md): AI: analyze a product image

## Webhooks

Inspect and re-send the order events Eto pushes to your server. [All 2 as one page](https://eto.tools/dev/docs/webhooks.md).

- [GET /api/v1/webhooks/deliveries](https://eto.tools/dev/docs/webhooks/webhooks-deliveries.md): List webhook deliveries
- [POST /api/v1/webhooks/deliveries/{delivery_id}/retry](https://eto.tools/dev/docs/webhooks/webhook-delivery-retry.md): Re-send one webhook delivery

## Optional

- [v2 preview reference](https://eto.tools/eto-dev-api-v2/): a fuller document covering the same v1 routes alongside the whole Etsy marketplace data model. A documentation preview, not a second API.
- [Sitemap](https://eto.tools/sitemap.xml): every public page and artefact.
- [Site overview](https://eto.tools/llms.txt): what Eto is, for readers who arrived at the API without context.