Skip to main content
cURL
Cost: 1 API credit per write.
This creates a real listing on Etsy, a draft unless you send state: "active". Needs the listings:write scope and the Listing optimization workspace permission. A source listing outside the workspace answers 404.
state: "active" publishes the copy on Etsy, last, inside the same write. Publishing costs the seller Etsy’s $0.20 listing fee, and a publish can’t be reverted. Send dry_run=true first to see what would be sent.

​
What can be published

To go active, the copy needs what Etsy needs from the source: at least one image, a shipping profile, a processing profile and, outside the EU, a return policy. When one is missing, the answer is 400 listing_not_publishable, its missing names what, and nothing is sent. A digital listing is copied without its files, so only as a draft. Add its files with Add file, then publish it with Update listing.

​
How the write runs

The answer is 202 with the write’s change, outcome: "applying". Poll Get change at Location. Once it has succeeded, its target is the copy. If a step fails after the copy exists, the copy stays: the change names it and what landed. Finish it with Update listing, never by duplicating again. A retry under the same Idempotency-Key answers the same change and never makes another copy. Once the write has finished, that retry answers 200 with the copy’s id, url, state, source_listing_id and change. See Idempotency.
The same duplicate within 10 minutes (longer while the earlier write’s outcome is still being checked: then 409 write_outcome_unknown, and for up to 24 hours after Alura stops checking, until the time that answer names) answers the earlier write, and the Alura-Write-Deduplicated header names that write’s change. To copy it again on purpose, send allow_duplicate: true under a new Idempotency-Key. Two different source listings always make two copies.
The copy is always made in the source listing’s shop. shop_id is optional; a shop_id other than the source listing’s shop answers 404.
On Alura’s test shop, a publish counts toward its cap on listings activated through the API at once. Past it, the answer is 409 test_shop_active_cap with cap and active, and nothing is sent.
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 of the listing to copy. 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
​
shop_id
string

The connected shop to create the listing in. Optional when the workspace has one connected shop; with several, 400 shop_id_required lists them.

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

draft (the default): the listing is created unpublished. active: it is published, last, inside the same write. Publishing costs the seller Etsy's $0.20 listing fee (re-activating a listing too), and a publish cannot be reverted.

Available options:
draft,
active
​
allow_duplicate
boolean

true: make the listing even when the same request was made in the last 10 minutes, or for up to about 48 hours while the earlier outcome is unknown (by default a repeat within 10 minutes answers that earlier write instead of creating twice). Only with a new request key.

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 | null
required

The new listing on Etsy; null when nothing was created (notices says so).

​
shop_id
string
required

Etsy ID, as a string.

​
url
string | null
required

The listing on Etsy.

​
state
enum<string> | null
required

active when the write published it; draft otherwise (a publish that did not land leaves a draft); null when no listing was created.

Available options:
draft,
active
​
source_listing_id
string | null
required

The listing it was duplicated from; null for a create.

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

​
as_of
string
required

When Etsy answered the write.