cURL
curl -X PUT "https://api.alura.io/v1/workspace/listings/1834720561/personalization" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
-d '{"questions":[{"type":"text_input","text":"Name to paint","required":true,"instructions":"Up to 12 letters","max_characters":12}]}'const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561/personalization', {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
body: JSON.stringify({
"questions": [
{
"type": "text_input",
"text": "Name to paint",
"required": true,
"instructions": "Up to 12 letters",
"max_characters": 12
}
]
}),
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561/personalization",
method="PUT",
data=json.dumps({
"questions": [
{
"type": "text_input",
"text": "Name to paint",
"required": true,
"instructions": "Up to 12 letters",
"max_characters": 12
}
]
}).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_personalization",
"listing_id": "1834720561",
"shop_id": "22841907",
"questions": [
{
"id": "7100",
"type": "text_input",
"text": "Name to paint",
"instructions": "Up to 12 letters",
"required": true,
"max_characters": 12,
"max_files": null,
"options": []
}
],
"as_of": "2026-10-17T12:00:00.000Z",
"change": {
"id": "chn_01JMOCK0000000000000000000",
"status": "succeeded",
"applied_fields": [
"personalization"
],
"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
Replace personalization
Replace every personalization question of one listing on Etsy, such as a name to engrave or a photo to upload, or remove personalization.
cURL
curl -X PUT "https://api.alura.io/v1/workspace/listings/1834720561/personalization" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
-d '{"questions":[{"type":"text_input","text":"Name to paint","required":true,"instructions":"Up to 12 letters","max_characters":12}]}'const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561/personalization', {
method: 'PUT',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
body: JSON.stringify({
"questions": [
{
"type": "text_input",
"text": "Name to paint",
"required": true,
"instructions": "Up to 12 letters",
"max_characters": 12
}
]
}),
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/workspace/listings/1834720561/personalization",
method="PUT",
data=json.dumps({
"questions": [
{
"type": "text_input",
"text": "Name to paint",
"required": true,
"instructions": "Up to 12 letters",
"max_characters": 12
}
]
}).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_personalization",
"listing_id": "1834720561",
"shop_id": "22841907",
"questions": [
{
"id": "7100",
"type": "text_input",
"text": "Name to paint",
"instructions": "Up to 12 letters",
"required": true,
"max_characters": 12,
"max_files": null,
"options": []
}
],
"as_of": "2026-10-17T12:00:00.000Z",
"change": {
"id": "chn_01JMOCK0000000000000000000",
"status": "succeeded",
"applied_fields": [
"personalization"
],
"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. Send every question, in order, at most 5.
Revert change restores the questions from before the change, with new IDs again. Send an
curl -X PUT "https://api.alura.io/v1/workspace/listings/1834720561/personalization" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"questions": [{"type": "text_input", "text": "Name to paint", "required": true, "instructions": "Up to 12 letters", "max_characters": 12}]}'
"questions": [] removes personalization. Needs the listings:write scope and the Listing optimization workspace permission. Send dry_run=true to see the planned write without sending it.
Question types
type | The buyer | Needs |
|---|---|---|
text_input | Types an answer | max_characters, 1 to 1024 |
dropdown | Picks an option | options, labels of 1 to 20 characters. No instructions (400 personalization_dropdown_instructions_forbidden). |
unlabeled_upload | Uploads files | max_files, 1 to 10 |
labeled_upload | Uploads files, one per label | max_files, 1 to 10, and options as its labels |
Etsy issues new question and option IDs on every write. The answer carries the new ones, so never keep an earlier ID.
The answer
| Answer | Meaning | What to do |
|---|---|---|
200 | The write landed. The body is the questions as Etsy answered, with their new IDs, 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
Every question, in order, at most 5; it replaces the listing's questions. [] removes personalization.
Maximum array length:
5Show child attributes
Show child attributes
Response
OK: the write landed on Etsy (or, with dry_run=true, what it would do).
- Option 1
- Option 2
Allowed value:
"workspace.listing_personalization"Etsy ID, as a string.
Etsy ID, as a string.
The questions as Etsy holds them after the write, with Etsy's NEW question and option IDs (Etsy issues new ones on every write); null when Etsy's answer was not readable.
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