cURL
curl -X PATCH "https://api.alura.io/v1/workspace/listings/1834720561/attributes" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
-d '{"set":[{"property_id":"200","value_ids":["2"]}]}'const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561/attributes', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
body: JSON.stringify({
"set": [
{
"property_id": "200",
"value_ids": [
"2"
]
}
]
}),
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561/attributes",
method="PATCH",
data=json.dumps({
"set": [
{
"property_id": "200",
"value_ids": [
"2"
]
}
]
}).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_attributes",
"listing_id": "1834720561",
"shop_id": "22841907",
"values": [
{
"property_id": "200",
"property_name": "Primary color",
"scale_id": null,
"scale_name": null,
"value_ids": [
"2"
],
"values": [
"Black"
]
}
],
"as_of": "2026-10-17T12:00:00.000Z",
"change": {
"id": "chn_01JMOCK0000000000000000000",
"status": "succeeded",
"applied_fields": [
"attributes"
],
"failed_fields": []
},
"notices": []
}{
"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>"
]
}Content
Update attributes
Set or remove attribute values of one listing of your connected Etsy shops on Etsy, such as its color or material, checked against its category’s properties.
cURL
curl -X PATCH "https://api.alura.io/v1/workspace/listings/1834720561/attributes" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
-d '{"set":[{"property_id":"200","value_ids":["2"]}]}'const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561/attributes', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
body: JSON.stringify({
"set": [
{
"property_id": "200",
"value_ids": [
"2"
]
}
]
}),
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561/attributes",
method="PATCH",
data=json.dumps({
"set": [
{
"property_id": "200",
"value_ids": [
"2"
]
}
]
}).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_attributes",
"listing_id": "1834720561",
"shop_id": "22841907",
"values": [
{
"property_id": "200",
"property_name": "Primary color",
"scale_id": null,
"scale_name": null,
"value_ids": [
"2"
],
"values": [
"Black"
]
}
],
"as_of": "2026-10-17T12:00:00.000Z",
"change": {
"id": "chn_01JMOCK0000000000000000000",
"status": "succeeded",
"applied_fields": [
"attributes"
],
"failed_fields": []
},
"notices": []
}{
"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.
Changes the live listing on Etsy. Needs the
Properties you don’t name are untouched. A property the listing varies by can’t be removed here: change variations with Replace inventory.
Revert change restores the values from before the change. Send an
curl -X PATCH "https://api.alura.io/v1/workspace/listings/1834720561/attributes" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"set": [{"property_id": "200", "value_ids": ["2"]}]}'
listings:write scope and the Listing optimization workspace permission. Send dry_run=true to see the planned write without sending it.
Set and remove
| You want | Send |
|---|---|
| Replace one property’s values | A set entry: property_id and value_ids from the property’s possible_values, or values by name |
| A value Etsy lists no choices for | values as free text, only for such a property |
| Values in a size system or unit | scale_id, required when the property has scales |
| Remove one property’s values | Its ID in remove |
Checked before anything is sent
Every entry is checked against Etsy’s properties for the listing’s category, from Get category properties. These answer400:
- a property the category doesn’t have;
- a value outside its set;
- a missing or foreign scale;
- more values than the property takes.
503. The write is never sent unchecked.
The answer
| Answer | Meaning | What to do |
|---|---|---|
200 | The write landed. The body has every attribute value of the listing as Etsy holds it now, and the change. | Nothing. |
202 | Etsy is still answering, or Alura is checking whether it landed. The body is the change. | Poll Get change at Location. Don’t send the write again. |
Idempotency-Key with every write: see Idempotency.
Another write to the listing in flight answers 409 listing_busy. 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.
Body
application/json
Response
OK: the write landed on Etsy (or, with dry_run=true, what it would do).
- Option 1
- Option 2
Allowed value:
"workspace.listing_attributes"Etsy ID, as a string.
Etsy ID, as a string.
Every attribute value of the listing as Etsy holds it after the write; null when Etsy's answer was not readable (notice content_not_returned).
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
Why a part of the answer is unknown; empty when nothing is.
Show child attributes
Show child attributes