Skip to main content
cURL

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.

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
​
title
string

The title, 1-140 characters.

Required string length: 1 - 140
​
description
string

The description; replaces the whole text.

Maximum string length: 50000
​
tags
string[]

Every tag, at most 13; replaces them all (an empty list removes every tag). Not with tags_add or tags_remove.

Maximum array length: 13
Required string length: 1 - 30
​
tags_add
string[]

Tags to add to the tags the listing has on Etsy right now (read live when the write runs, not from Alura's copy); one already there is kept once. The result may have at most 13 tags.

Required array length: 1 - 13 elements
Required string length: 1 - 30
​
tags_remove
string[]

Tags to remove from the tags the listing has on Etsy right now, case-insensitive; one the listing does not have is ignored.

Required array length: 1 - 13 elements
Required string length: 1 - 30
​
materials
string[]

Every material, at most 13; replaces them all.

Maximum array length: 13
Required string length: 1 - 45
​
category_id
string

Etsy's category (its taxonomy_id), from browse_categories or GET /v1/categories.

Pattern: ^[1-9][0-9]{0,9}$
​
who_made
enum<string>

Etsy's who_made.

Available options:
i_did,
someone_else,
collective
​
when_made
string

Etsy's when_made, for example made_to_order, 2020_2026 or before_2007.

Pattern: ^[a-z0-9_]{1,20}$
​
is_supply
boolean

true: a craft supply or tool; false: a finished product.

​
section_id
string | null

A section of the listing's shop; null takes the listing out of its section. A section of another shop is 404.

Pattern: ^[0-9]{1,20}$
​
shipping_profile_id
string

A shipping profile of the listing's shop. A profile of another shop is 404.

Pattern: ^[0-9]{1,20}$
​
return_policy_id
string | null

A return policy of the listing's shop; null removes the listing's policy. A policy of another shop is 404.

Pattern: ^[0-9]{1,20}$
​
processing_profile_id
string

A processing profile of the listing's shop (list them with GET /v1/workspace/processing-profiles); set on every offering, so a listing with variations is 409 listing_has_variations without apply_to: "all_variants". A profile of another shop is 404.

Pattern: ^[0-9]{1,20}$
​
production_partner_ids
string[]

Every production partner who helps make the item; replaces them all (an empty list removes them).

Maximum array length: 50

A production partner of the listing's shop. A partner of another shop is 404.

Pattern: ^[0-9]{1,20}$
​
should_auto_renew
boolean

true: Etsy renews the listing automatically when it expires (a listing fee each time).

​
state
enum<string>

inactive deactivates the listing on Etsy. Publishing (active) is not available through this operation yet.

Available options:
inactive,
active
​
price

The new price of every offering in the listing's own currency, as a decimal string such as "24.99" (a number with at most 2 decimals is accepted too); above 0 and at most 50,000 in the listing's currency.

​
adjust_price
object

A relative price change of every offering. Needs a request key (REST Idempotency-Key, MCP request_id), so a retry never applies it twice.

​
quantity
integer

The quantity in stock of every offering, 0-999.

Required range: 0 <= x <= 999
​
adjust_quantity
integer

Add this many (negative to remove; never below 0) to every offering's quantity. Needs a request key, so a retry never applies it twice.

Required range: -999 <= x <= 999
​
sku
string

The SKU of every offering, at most 32 characters. Only on a listing without variations.

Required string length: 1 - 32
​
apply_to
enum<string>

all_variants: apply price, adjust_price, quantity, adjust_quantity or processing_profile_id to every variant of a listing with variations (without it such a listing is 409 listing_has_variations). Never for sku.

Available options:
all_variants

Response

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

​
object
string
required
Allowed value: "workspace.listing"
​
id
string
required

Etsy ID, as a string.

​
shop_id
string
required

Etsy ID, as a string.

​
title
string | null
required
​
description
string | null
required
​
url
string | null
required

The listing on Etsy.

​
state
string | null
required

Etsy's listing state, for example active, inactive or draft.

​
price
object | null
required

The listing's price as Etsy answered; usd is null unless the listing is priced in USD.

​
quantity
integer | null
required

The listing's total quantity across its enabled offerings, as Etsy and get_my_listing count it (not the per-offering value a request sends: 3 on each of 2 variants is 6).

​
skus
string[] | null
required
​
tags
string[] | null
required
​
materials
string[] | null
required
​
category
object | null
required

Etsy's category (category_id in the request).

​
section
object | null
required

The shop section; null when the listing is in none.

​
shipping_profile_id
string | null
required

Etsy ID, as a string.

​
return_policy_id
string | null
required

Etsy ID, as a string.

​
processing_profile_id
string | null
required

The processing profile every offering has; null when they differ or Etsy did not say.

​
production_partner_ids
string[] | null
required

Etsy ID, as a string.

​
who_made
string | null
required
​
when_made
string | null
required
​
is_supply
boolean | null
required
​
should_auto_renew
boolean | null
required
​
updated_at
string | null
required

When Etsy last changed the listing.

​
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.