Skip to main content
cURL
Cost: 1 API credit per write.
Changes the live listing on Etsy. Take the IDs from images in Get listing. Needs the listings:write scope and the Listing optimization workspace permission. Send dry_run=true to see what would be sent without sending it.
Name every image of the listing. Etsy deletes any image an order leaves out, so a partial order answers 400 naming the missing images, and nothing is sent. Images can’t be reverted (not_revertable_reason: "images").
An image of another listing answers 404, and nothing is sent.

​
How the order is applied

Alura reads the listing’s images on Etsy again just before the change, then moves each named image to its place, in one change. An image added on Etsy since Alura’s last sync is kept, after the ones you named. The answer is 202 with the write’s change, outcome: "applying". Poll Get change at Location. A retry under the same Idempotency-Key, once the write has finished, answers what landed, with the new order. See Idempotency.
A named image Etsy no longer holds is skipped, and the next image on Etsy takes its place, which can be one added since the last sync. The change is then partial. When no named image is left, the answer is 422 naming images.image_target_not_on_listing.
Another write to the listing still running answers 409 listing_busy: retry after Retry-After.
Credits and limits says when a write is charged.

Authorizations

​
Authorization
string
header
required

An API key: Authorization: Bearer alura_sk_....

Headers

​
Idempotency-Key
string

Makes a retry safe: the same key with the same request within 24 hours answers from the first write (with Idempotent-Replayed: true) and never writes to Etsy twice; a write that failed with nothing written (Retry-After set) is tried again under it. The same key with a different request is a 409 conflict; while the first request still runs, 409 idempotency_processing (or the same 202). Required for relative changes such as adjust_price, and to add a listing file, image or video, or to change the alt text of an image (each uploads to Etsy, so a blind retry would upload again); a dry_run=true needs none.

Required string length: 1 - 255

Path Parameters

​
id
string
required

The Etsy listing ID. A listing outside the workspace is 404.

Pattern: ^[0-9]{1,20}$
Example:

"1834720561"

Query Parameters

​
dry_run
boolean

true: plan the write and send nothing: what it would change, the Etsy calls it would make, and nothing reserved, charged or recorded. Free; counts toward the per-minute write limit.

Body

application/json
​
image_ids
string[]
required

Every image of the listing, in the new order (the first is the listing's main photo). Each one must be named: Etsy deletes an image left out of an order, so a partial order is 400, nothing sent.

Required array length: 1 - 20 elements
Pattern: ^[1-9][0-9]{0,18}$

Response

OK: the write landed on Etsy (or, with dry_run=true, what it would do).

​
object
string
required
Allowed value: "workspace.listing_images"
​
listing_id
string
required

Etsy ID, as a string.

​
shop_id
string
required

Etsy ID, as a string.

​
added
object[]
required

The images added.

​
removed
string[]
required

The images removed.

Etsy ID, as a string.

​
order
string[] | null
required

The listing's images in their new order, after a reorder; null otherwise.

Etsy ID, as a string.

​
replaced
object[]
required

Images whose alt text changed. Etsy has no image update, so the image is uploaded again with the new alt text and the old one deleted: its ID changes; its position and any variation that showed it are kept. An image whose ID changed while the new alt text was not applied (at Etsy's image limit, the old image deleted to make room and the photo uploaded again without it) is listed too, with an alt_text_not_changed notice.

​
as_of
string
required

When Etsy answered the write.

​
change
object
required

The write: its change ID and what landed.

​
notices
object[]
required

What the answer leaves out and why; empty when nothing is.