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 change and its range of Etsy calls without sending it.

​
Pick variants with select

Each entry’s select picks one variant by its property values, such as {"Size": "A4", "Color": "Red"}. Case and surrounding spaces are ignored. Naming one property is enough when that picks one variant. On a listing without variations, {} picks its only product. The entry then sets any of price, quantity, sku, is_enabled and processing_profile_id. Every other product and field stays as Etsy holds it. A select that picks no product, more than one, or one another entry picked answers 400 naming the entry (such as offerings.2), and nothing is sent.
Variants are picked by property values, never by ID. Etsy can issue new product and offering IDs on any inventory write, and does when variants are added or removed.
Alura reads the inventory on Etsy right before the write and applies your change to it, never to its own copy. An edit made on Etsy since the last sync is kept.

​
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. Revert change restores the prices, SKUs and enabled flags, never quantities. To add or remove variants, use Replace inventory. For a listing without variations, Update listing also sets the price, quantity and SKU. The inventory guide has more examples. 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
​
offerings
object[]
required

The offerings to change, 1-400; every other product and field stays as Etsy holds it.

Required array length: 1 - 400 elements

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.