cURL
curl -X PATCH "https://api.alura.io/v1/workspace/listings/1834720561/images/5001" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
-d '{"alt_text":"White personalized mug, front"}'const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561/images/5001', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
body: JSON.stringify({
"alt_text": "White personalized mug, front"
}),
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561/images/5001",
method="PATCH",
data=json.dumps({
"alt_text": "White personalized mug, front"
}).encode(),
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
"Content-Type": "application/json",
"Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "workspace.listing_images",
"listing_id": "<string>",
"shop_id": "<string>",
"added": [
{
"index": 123,
"image_id": "<string>"
}
],
"removed": [
"<string>"
],
"order": [
"<string>"
],
"replaced": [
{
"from": "<string>",
"to": "<string>"
}
],
"as_of": "<string>",
"change": {
"id": "<string>",
"status": "succeeded",
"applied_fields": [
"<string>"
],
"failed_fields": [
{
"field": "<string>",
"code": "<string>"
}
]
},
"notices": [
{
"code": "<string>",
"detail": "<string>"
}
]
}{
"object": "workspace.change",
"id": "chn_01JMOCK0000000000000000MEDIA",
"shop_id": "22841907",
"target": {
"type": "listing",
"id": "1834720561"
},
"source": "api",
"actor": {
"type": "key",
"id": "key_01JMOCK0000000000000000000"
},
"write_id": "wrt_01JMOCK0000000000000000MEDIA",
"outcome": "applying",
"fields": null,
"applied_fields": null,
"failed_fields": null,
"before_source": null,
"before_as_of": null,
"event": null,
"revertable": false,
"not_revertable_reason": "outcome_unknown",
"reverts": null,
"created_at": "2026-10-17T12:00:00.000Z",
"as_of": "2026-10-17T12:00:00.000Z"
}{
"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>"
]
}Images
Update alt text
Set the alt text of one image of one listing of your connected Etsy shops. The image keeps its position but gets a new ID.
cURL
curl -X PATCH "https://api.alura.io/v1/workspace/listings/1834720561/images/5001" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
-d '{"alt_text":"White personalized mug, front"}'const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561/images/5001', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
body: JSON.stringify({
"alt_text": "White personalized mug, front"
}),
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561/images/5001",
method="PATCH",
data=json.dumps({
"alt_text": "White personalized mug, front"
}).encode(),
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
"Content-Type": "application/json",
"Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "workspace.listing_images",
"listing_id": "<string>",
"shop_id": "<string>",
"added": [
{
"index": 123,
"image_id": "<string>"
}
],
"removed": [
"<string>"
],
"order": [
"<string>"
],
"replaced": [
{
"from": "<string>",
"to": "<string>"
}
],
"as_of": "<string>",
"change": {
"id": "<string>",
"status": "succeeded",
"applied_fields": [
"<string>"
],
"failed_fields": [
{
"field": "<string>",
"code": "<string>"
}
]
},
"notices": [
{
"code": "<string>",
"detail": "<string>"
}
]
}{
"object": "workspace.change",
"id": "chn_01JMOCK0000000000000000MEDIA",
"shop_id": "22841907",
"target": {
"type": "listing",
"id": "1834720561"
},
"source": "api",
"actor": {
"type": "key",
"id": "key_01JMOCK0000000000000000000"
},
"write_id": "wrt_01JMOCK0000000000000000MEDIA",
"outcome": "applying",
"fields": null,
"applied_fields": null,
"failed_fields": null,
"before_source": null,
"before_as_of": null,
"event": null,
"revertable": false,
"not_revertable_reason": "outcome_unknown",
"reverts": null,
"created_at": "2026-10-17T12:00:00.000Z",
"as_of": "2026-10-17T12:00:00.000Z"
}{
"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.
Changes the live listing on Etsy.
Variation images point at image IDs: after an alt-text change, read the listing again before Set variation images. Credits and limits says when a write is charged.
curl -X PATCH "https://api.alura.io/v1/workspace/listings/1834720561/images/5003" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"alt_text": "White personalized mug, front"}'
"alt_text": "" clears the alt text. Needs the 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 image update. Alura uploads the image again with the new alt text and deletes the old one, so the image’s ID changes. Its position, and any variation that showed it, are kept. The answer’s
replaced maps the old ID to the new one.Images can’t be reverted (
not_revertable_reason: "images").Always send an Idempotency-Key
A change withoutIdempotency-Key answers 400 invalid_request. replaced and the notices below are only in the answer a retry under the key gets, and a blind retry of an unfinished replacement would upload the photo again. See Idempotency.
The answer
The answer is202 with the write’s change, outcome: "applying". Poll Get change at Location. Once the write has finished, a retry under the same key answers 200 with replaced and any notice:
| Notice | Meaning |
|---|---|
replacement_unfinished | The new image was uploaded, but deleting the old one wasn’t confirmed, so Etsy may show both |
replacement_unconfirmed | At Etsy’s image limit, the image was uploaded again and Alura couldn’t confirm the result, so Etsy may hold both |
alt_text_not_changed | The image’s ID changed but the new alt text wasn’t applied. At Etsy’s image limit, the old image was deleted to make room and the photo uploaded again without it. |
Errors before anything is sent
Errors before anything is sent
An image of another listing answers
404. One Etsy no longer holds, removed since Alura’s last sync, answers 422 naming images.image_target_not_on_listing. Another write to the listing still running answers 409 listing_busy: retry after Retry-After.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"
The image to change. An image of another listing is 404.
Pattern:
^[1-9][0-9]{0,18}$Example:
"5001"
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.
Body
application/json
The new alt text, at most 500 characters; "" clears it.
Maximum string length:
500Response
OK: the write landed on Etsy (or, with dry_run=true, what it would do).
- Option 1
- Option 2
Allowed value:
"workspace.listing_images"Etsy ID, as a string.
Etsy ID, as a string.
The images added.
Show child attributes
Show child attributes
The images removed.
Etsy ID, as a string.
The listing's images in their new order, after a reorder; null otherwise.
Etsy ID, as a string.
Images whose alt text changed. Etsy has no image update, so the image is uploaded again with the new alt text and the old one deleted: its ID changes; its position and any variation that showed it are kept. An image whose ID changed while the new alt text was not applied (at Etsy's image limit, the old image deleted to make room and the photo uploaded again without it) is listed too, with an alt_text_not_changed notice.
Show child attributes
Show child attributes
When Etsy answered the write.
The write: its change ID and what landed.
Show child attributes
Show child attributes
What the answer leaves out and why; empty when nothing is.
Show child attributes
Show child attributes