Etsy API Only Uploads One Video Per Listing (While the UI Allows Two)

If you manage Etsy listings through the API, you may notice a mismatch: Etsy's own UI lets a seller attach two videos to a listing, but the Etsy Open API v3 uploadListingVideo endpoint behaves as one video per listing. So a listing that visibly shows two videos on Etsy can't be reproduced end-to-end through the public API alone. This isn't a bug in your integration — it's an API-vs-UI parity gap.

The discrepancy

Etsy's official help documentation states a seller can add up to two videos per listing through the Etsy interface. The API, however, exposes a single upload path — POST /v3/application/shops/{shop_id}/listings/{listing_id}/videos — that operates on the one-video model. Uploading through it doesn't accumulate a second video the way adding a second image would; the endpoint is built around a listing having a video, not a collection of them.

Why this happens

This is the classic pattern of a platform feature shipping on the UI ahead of the public API. Etsy raised the per-listing video limit for sellers, but the corresponding API surface hasn't reached parity. A telling signal is in the endpoint naming: the read endpoint is getListingVideos (plural) and returns a list, which means the underlying data model can already represent multiple videos per listing — yet the write path (uploadListingVideo) is still capped at the older one-video behavior. The capability exists in the schema before it's fully exposed for writing.

How to handle it

1. Design your integration around one video per listing via the API. Don't build logic that assumes a second uploadListingVideo call will add rather than conflict.
2. Use getListingVideos to read the full set of videos on a listing — including any second video a seller added manually through the UI — so your sync logic reflects reality even when your app can only write one.
3. If a listing genuinely needs two videos, treat the second as a manual UI step for the seller, and don't surface it as an API-writable field in your tooling until Etsy ships parity.
4. Watch Etsy's changelog for updates to the endpoint — a rollout like this is usually completed on the API later, at which point the write path may accept multiple videos.

Sources: Etsy's How to Add Listing Videos help page (UI limit) and the uploadListingVideo / getListingVideos API reference.

Having built multi-channel integrations across 20+ sales channels — Etsy, Amazon SP-API, eBay, Shopify, TikTok Shop and more — I run into these UI-vs-API parity gaps constantly and know how to design around them cleanly. If you need help with eCommerce support or marketplace API integration, check out Netalith's eCommerce support service or reach out to me directly on LinkedIn.