Skip to main content
cURL
Cost: 1 API credit per write.
Deletes the file from the live listing on Etsy. Take the ID from Get listing with expand=files, or from the files of a file write’s answer. 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"). Etsy doesn’t let an active digital listing stay without a file.
The answer is 202 with the write’s change, outcome: "applying". Poll Get change at Location. A retry under the same Idempotency-Key, once the write has finished, answers what landed, with the listing’s files after it (ID, name, size and rank, never their content). See Idempotency.
While Alura’s copy of the listing’s files is less than a day old, a file it doesn’t list answers 404: a file of another listing, or one added on Etsy since. The shop’s syncs don’t fetch files; Alura fetches them again after a file write through Alura. With an older or unknown copy there is no such 404. Remove file always checks Etsy’s own list when it runs, and a file the listing no longer holds there is a no-op.
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"

​
file_id
string
required

The file to remove: its ID from GET /v1/workspace/listings/{id}?expand=files, or from a files write's files. A file of another listing is 404.

Pattern: ^[1-9][0-9]{0,18}$
Example:

"7001"

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.

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.