ACTION REQUIRED: Multiple Videos per Listing — Migration for uploadListingVideo

[openapi-support[bot]]

Hello developers!

We are introducing multi-video support for listings. The uploadListingVideo endpoint (POST /shops/{shop_id}/listings/{listing_id}/videos) will change its default behavior. You have 30 days from September 21st, 2026 to update your integration before the new behavior becomes permanent.

What's Changing

Currently, calling uploadListingVideo replaces any existing video on a listing — the previous video is automatically deactivated. After the migration period, the endpoint will instead add a video alongside existing ones (up to 2 per listing), and the replace behavior will be permanently disabled.

Migration Timeline

Date	Event
Sep 21st	Grace period begins — is_multi_video=true optional query param available for manual opt-in
Oct 21st	Migration complete — legacy replace behavior disabled permanently

Required Action: Before the Deadline

During the 30-day grace period, update your calls to uploadListingVideo to pass is_multi_video=true. This opts your integration into the new multi-video behavior immediately, so you can test and adapt before it becomes mandatory.

POST /shops/{shop_id}/listings/{listing_id}/videos?is_multi_video=true

Parameter	Type	Description
is_multi_video	boolean	Set to true to adopt the new behavior now. After the migration deadline, this parameter has no effect — the new behavior is always active.

After the grace period ends, is_multi_video will be ignored and the new behavior will apply to all requests unconditionally.

New Behavior (with is_multi_video=true, and after migration)

• The first video uploaded becomes the primary video for the listing. A second video uploaded is placed at the end of the listing's media (images and videos) as displayed on the Etsy website and app.
• If the listing already has 2 active videos, the request returns 409 Conflict.
• If the provided video_id is already actively linked to the listing, the request returns 409 Conflict.

New Error Responses

HTTP Status	When it occurs
409 Conflict	The listing already has 2 active videos (maximum allowed).
409 Conflict	The provided video_id is already actively linked to this listing.

Legacy Behavior (during grace period only, when is_multi_video is omitted or false)

No changes to your current behavior — uploading or associating a video deactivates any previously active videos on the listing. This behavior will be disabled after the 30-day grace period.

Questions or Feedback

Please reply to this discussion or reach out to developer@etsy.com if you have any questions or run into issues during the grace period. We are actively monitoring feedback before the deadline.

[JackySw]

That's great, looking forward to it! Why not start grace period right away btw, instead of 21st? If you don't pass the 'is_multi_video', nothing would change right now. Or do you need to complete something on your side?

[cyrilchandelier]

It's great that we can now manage the second video, but can we also control the order of videos and their placement among images?

In Etsy’s dashboard, we can place a video between images. With the API, however, videos seem to be added only at the end, with no way to change their position in the media list.