cURL
curl -X DELETE "https://api.alura.io/v1/workspace/listings/1834720561" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c"const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561",
method="DELETE",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
"Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "workspace.listing",
"id": "1834720561",
"shop_id": "22841907",
"title": null,
"description": null,
"url": null,
"state": "deleted",
"price": null,
"quantity": null,
"skus": null,
"tags": null,
"materials": null,
"category": null,
"section": null,
"shipping_profile_id": null,
"return_policy_id": null,
"processing_profile_id": null,
"production_partner_ids": null,
"who_made": null,
"when_made": null,
"is_supply": null,
"should_auto_renew": null,
"updated_at": null,
"as_of": "2026-10-17T12:00:00.000Z",
"change": {
"id": "chn_01JMOCK000000000000000DELETE",
"status": "succeeded",
"applied_fields": [
"state"
],
"failed_fields": []
},
"notices": [
{
"code": "listing_deleted",
"detail": "Etsy deleted the listing, so it has no fields left to show; the change records it."
}
]
}{
"object": "workspace.change",
"id": "<string>",
"shop_id": "<string>",
"target": {
"type": "<string>",
"id": "<string>"
},
"source": "<string>",
"actor": {
"type": "<string>",
"id": "<string>"
},
"write_id": "<string>",
"outcome": "<string>",
"fields": [
{
"field": "<string>",
"before": "<unknown>",
"after": "<unknown>",
"unrecorded": [
"before"
],
"omitted": [
"before"
]
}
],
"applied_fields": [
"<string>"
],
"failed_fields": [
{
"field": "<string>",
"code": "<string>"
}
],
"before_source": "<string>",
"before_as_of": "<string>",
"event": "<string>",
"revertable": true,
"not_revertable_reason": "<string>",
"reverts": "<string>",
"created_at": "<string>",
"as_of": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "https://docs.alura.io/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"code": "unauthorized",
"detail": "Unauthorized",
"suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "https://docs.alura.io/errors/method_not_allowed",
"title": "Method not allowed",
"status": 405,
"code": "method_not_allowed",
"detail": "Method not allowed",
"suggestion": "Use one of the methods in the Allow header.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}Listings
Delete listing
Delete one listing of your connected Etsy shops on Etsy, active listings included.
cURL
curl -X DELETE "https://api.alura.io/v1/workspace/listings/1834720561" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c"const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561",
method="DELETE",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
"Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "workspace.listing",
"id": "1834720561",
"shop_id": "22841907",
"title": null,
"description": null,
"url": null,
"state": "deleted",
"price": null,
"quantity": null,
"skus": null,
"tags": null,
"materials": null,
"category": null,
"section": null,
"shipping_profile_id": null,
"return_policy_id": null,
"processing_profile_id": null,
"production_partner_ids": null,
"who_made": null,
"when_made": null,
"is_supply": null,
"should_auto_renew": null,
"updated_at": null,
"as_of": "2026-10-17T12:00:00.000Z",
"change": {
"id": "chn_01JMOCK000000000000000DELETE",
"status": "succeeded",
"applied_fields": [
"state"
],
"failed_fields": []
},
"notices": [
{
"code": "listing_deleted",
"detail": "Etsy deleted the listing, so it has no fields left to show; the change records it."
}
]
}{
"object": "workspace.change",
"id": "<string>",
"shop_id": "<string>",
"target": {
"type": "<string>",
"id": "<string>"
},
"source": "<string>",
"actor": {
"type": "<string>",
"id": "<string>"
},
"write_id": "<string>",
"outcome": "<string>",
"fields": [
{
"field": "<string>",
"before": "<unknown>",
"after": "<unknown>",
"unrecorded": [
"before"
],
"omitted": [
"before"
]
}
],
"applied_fields": [
"<string>"
],
"failed_fields": [
{
"field": "<string>",
"code": "<string>"
}
],
"before_source": "<string>",
"before_as_of": "<string>",
"event": "<string>",
"revertable": true,
"not_revertable_reason": "<string>",
"reverts": "<string>",
"created_at": "<string>",
"as_of": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "https://docs.alura.io/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"code": "unauthorized",
"detail": "Unauthorized",
"suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "https://docs.alura.io/errors/method_not_allowed",
"title": "Method not allowed",
"status": 405,
"code": "method_not_allowed",
"detail": "Method not allowed",
"suggestion": "Use one of the methods in the Allow header.",
"retryable": false,
"request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "<string>",
"detail": "<string>",
"suggestion": "<string>",
"retryable": true,
"request_id": "<string>",
"upgrade_url": "<string>",
"credits_needed": 123,
"credits_remaining": 123,
"resets_at": "2023-11-07T05:31:56Z",
"change_id": "<string>",
"budget": "<string>",
"reason": "<string>",
"changed": [
"<string>"
],
"missing": [
"<string>"
],
"reconnect_url": "<string>",
"missing_scopes": [
"<string>"
]
}Cost: 1 API credit per write.
Needs the
To take a listing off sale without deleting it, send
curl -X DELETE "https://api.alura.io/v1/workspace/listings/1834720561" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"
listings:write scope and the Listing optimization workspace permission. Send dry_run=true to see what would be sent without sending it.
Etsy has no undo. A delete can never be reverted (
not_revertable_reason: "delete").| Answer | Meaning |
|---|---|
200 | Etsy deleted the listing. The body has its IDs, state: "deleted" and the change, with applied_fields: ["state"]. |
202 | Etsy is still answering. The body is the change: poll Get change at Location. |
404 | The listing is outside the workspace. |
410 listing_removed_on_etsy | The listing is already gone on Etsy. |
403 etsy_scope_required | The shop’s Etsy connection lacks the delete permission. Nothing was sent. |
Shops that need reconnecting first
Shops that need reconnecting first
Etsy needs the
listings_d permission on the shop’s connection, which shops connected through the older Alura app may lack. Such a shop answers 403 etsy_scope_required with reconnect_url and missing_scopes before anything is sent. Etsy refusing the delete for that reason answers the same, and the shop’s connection.capabilities.delete_listings then reads restricted (Get shop).state: "inactive" to Update listing. Credits and limits says when a write is charged.Authorizations
An API key: Authorization: Bearer alura_sk_....
Headers
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 - 255Path Parameters
The Etsy listing ID. A listing outside the workspace is 404.
Pattern:
^[0-9]{1,20}$Example:
"1834720561"
Query Parameters
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).
- Option 1
- Option 2
Allowed value:
"workspace.listing"Etsy ID, as a string.
Etsy ID, as a string.
The title as Etsy answered; null when Etsy did not say.
The description as Etsy answered; null when Etsy did not say.
The listing on Etsy.
Etsy's listing state, for example active, inactive or draft.
The listing's price as Etsy answered; usd is null unless the listing is priced in USD.
Show child attributes
Show child attributes
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).
The SKUs of the listing's offerings as Etsy answered; null when Etsy did not say.
The tags as Etsy answered; null when Etsy did not say.
The materials as Etsy answered; null when Etsy did not say.
Etsy's category (category_id in the request).
Show child attributes
Show child attributes
The shop section; null when the listing is in none.
Show child attributes
Show child attributes
The listing's shipping profile; null when it has none or Etsy did not say.
The listing's return policy; null when it has none or Etsy did not say.
The processing profile every offering has; null when they differ or Etsy did not say.
The production partners as Etsy answered; null when Etsy did not say.
Etsy ID, as a string.
Etsy's who_made: i_did, someone_else or collective; null when Etsy did not say.
Etsy's when_made, for example made_to_order; null when Etsy did not say.
true: a craft supply or tool; false: a finished product; null when Etsy did not say.
true: Etsy renews the listing automatically when it expires; null when Etsy did not say.
When Etsy last changed the listing.
When Etsy answered the write.
The write: its change ID and what landed.
Show child attributes
Show child attributes
Why a part of the answer is unknown; empty when nothing is.
Show child attributes
Show child attributes