Skip to main content
cURL
Cost: 1 API credit per write.
Uploads to the live listing on Etsy. name is the file’s name buyers see, and rank places it (without it, the file goes last). Needs the listings:write scope and the Listing optimization workspace permission. Send dry_run=true to see what would be sent without sending it.
File changes can’t be reverted (not_revertable_reason: "files"). Remove an unwanted file with Remove file.

​
Always send an Idempotency-Key

An add without Idempotency-Key answers 400 invalid_request. Each add uploads a new file, so a retry must reuse the key: it then answers the first write instead of uploading again. See Idempotency.

​
What is accepted

Get listing with expand=files lists the files a listing holds.

​
The answer

The answer is 202 with the write’s change, outcome: "applying". Poll Get change at Location. A retry under the same key, once the write has finished, answers what landed: added, and the listing’s files after it (ID, name, size and rank, never their content). 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 of a digital listing. 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
​
url
string
required

An https URL of the file Alura fetches (a public address, no redirects, at most 20 MB; its host name at most 128 characters: letters, digits, ., - and _).

Maximum string length: 2048
​
name
string
required

The file's name as buyers see it, at most 70 characters with its extension, for example pattern-a4.pdf. Etsy allows letters, digits, -, _ and .: any other character is replaced with _.

Required string length: 1 - 70
​
rank
integer

Its position among the listing's files, 1-5; without it the file goes last.

Required range: 1 <= x <= 5

Response

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

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

Etsy ID, as a string.

​
shop_id
string
required

Etsy ID, as a string.

​
added
object | null
required

The file this write added; null for a remove, or when it did not land.

​
removed
string[]
required

The files this write deleted on Etsy.

Etsy ID, as a string.

​
files
object[] | null
required

The listing's files on Etsy after the write, in order; null when Etsy's list could not be read after it (notices says so). Never the files' content.

​
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 could not say, or a no-op; empty when nothing.