Skip to main content
cURL
Cost: 1 API credit per write.
Changes the live listing on Etsy. Needs the listings:write scope and the Listing optimization workspace permission. Send dry_run=true to see the planned write and its range of Etsy calls without sending it. A listing has one product per combination of variation values. Each product has a SKU and one offering: price, quantity, enabled, and processing profile.
This is a full replace, like Etsy’s own inventory write. A product you leave out is removed from the listing. A price_on_property, quantity_on_property, sku_on_property or processing_profile_on_property you leave out is cleared. Read the current inventory with Get listing and expand=inventory, and send back every product you want to keep.
To change a few variants without restating the rest, use Patch offerings.

​
Add or remove variations

  • Adding a product adds a variation value.
  • Removing every product of a value removes the value, and with it the value’s variation images on Etsy.
  • property_id is a category property from Get category properties, or 513 and 514 for the shop’s own variations.
  • Every offering of a physical listing needs a processing_profile_id. Without one, the answer is 400 before anything is sent.
Etsy can issue new product and offering IDs on any inventory write, and does when variants are added or removed. Never keep them to address a variant: select variants by their property values with Patch offerings.

​
The answer

Send an Idempotency-Key with every write: a retry under the same key answers from the first write and never writes twice. See Idempotency.

​
Undo a change

Revert change restores the prices, SKUs and enabled flags. It never restores quantities or variation images, and a change that added or removed variants can’t be reverted. The inventory guide walks through a full replace. 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
​
products
object[]
required

Every product of the listing, 1-400: a product left out is removed from the listing.

Required array length: 1 - 400 elements
​
price_on_property
string[]

The properties whose values set the price (each must be a property of the products); empty or left out: one price for every variant.

Maximum array length: 2
Pattern: ^[1-9][0-9]{0,18}$
​
quantity_on_property
string[]

The properties whose values set the quantity (each must be a property of the products); empty or left out: one quantity for every variant.

Maximum array length: 2
Pattern: ^[1-9][0-9]{0,18}$
​
sku_on_property
string[]

The properties whose values set the SKU (each must be a property of the products); empty or left out: one SKU for every variant.

Maximum array length: 2
Pattern: ^[1-9][0-9]{0,18}$
​
processing_profile_on_property
string[]

The properties whose values set the processing profile (each must be a property of the products); empty or left out: one processing profile for every variant.

Maximum array length: 2
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_inventory"
​
listing_id
string
required

Etsy ID, as a string.

​
shop_id
string
required

Etsy ID, as a string.

​
products
object[] | null
required

Every product as Etsy answered the write, with Etsy's new IDs; null when Etsy's answer carried none (notice inventory_not_returned).

​
price_on_property
string[] | null
required

The properties whose values set the price; [] for one price for every variant; null when Etsy did not say.

Etsy ID, as a string.

​
quantity_on_property
string[] | null
required

The properties whose values set the quantity; [] for one quantity for every variant; null when Etsy did not say.

Etsy ID, as a string.

​
sku_on_property
string[] | null
required

The properties whose values set the SKU; [] for one SKU for every variant; null when Etsy did not say.

Etsy ID, as a string.

​
processing_profile_on_property
string[] | null
required

The properties whose values set the processing profile; [] for one profile for every variant; null when Etsy did not say.

Etsy ID, as a string.

​
as_of
string
required

When Etsy answered the write.

​
change
object
required

The write: its change ID and what landed.

​
notices
object[]
required

Why a part of the answer is unknown; empty when nothing is.