Personalization Examples#

This page provides detailed examples for reading, writing, and deleting listing personalization data. For a full description of the endpoints, data structure, and constraints, see the Personalization Migration Guide.

Getting personalization data through the dedicated personalization GET endpoint#

This endpoint retrieves a listing’s personalization questions by listing ID. It returns a personalization_questions array. If the listing has no personalization configured, the array is empty.

The following procedure retrieves the personalization questions attached to a listing.

Form a valid URL for getListingPersonalization, which must include a listing_id. For example, if your listing_id is "987654", the URL is:
https://api.etsy.com/v3/application/listings/987654/personalization
Execute a getListingPersonalization GET request with your x-api-key.
The response contains a personalization_questions object:

{
  "personalization_questions": [
    {
      "question_text": "Personalization",
      "instructions": "What name would you like engraved? Please enter their full name",
      "question_id": 18205840821,
      "question_type": "text_input",
      "required": true,
      "max_allowed_characters": 50,
      "max_allowed_files": null
    }
  ]
}

Getting personalization data via endpoints that return listings with associations#

You can also retrieve the personalization data for a listing by using the following endpoints and including the parameter ?includes=personalization in your requests:

getListingsByShop - GET /v3/application/shops/{shop_id}/listings
getListing - GET /v3/application/listings/{listing_id}
getListingsByListingIds - GET /v3/application/listings/batch

Example url for the getListing endpoint: https://api.etsy.com/v3/application/shops/12345678/listings?includes=personalization\&language=en

Example response:

{
"listing_id": 429494249,
"title": "Example of personalizable listing",
"is_personalizable": true,
... // other listing data
"personalization": {
  "personalization_questions": [
      {
      "question_text": "Personalization",
      "instructions": "What name would you like engraved? Please enter their full name",
      "question_id": 18205840821,
      "question_type": "text_input",
      "required": true,
      "max_allowed_characters": 50,
      "max_allowed_files": null
      }
    ]
  }
}

Examples of question types#

Dropdown questions#

{
      "question_text": "Font",
      "question_type": "dropdown",
      "options": [
            {
                "label": "Arial"
            },
            {
                "label": "Century Gothic"
            },
            {
                "label": "Times New Roman"
            }
        ],
      "required": true
    }

Unlabeled file uploads#

{
      "question_text": "Family pictures",
      "instructions": "Add images of the members of the family members that you want in your family portrait",
      "question_type": "unlabeled_upload",
      "required": true,
      "max_allowed_files": 10
}

Labeled file uploads#

{
      "question_text": "Family pictures",
      "instructions": "Add images of the members of the family members that you want in your family portrait",
      "question_type": "labeled_upload",
      "options": [
        {
            "label": "Dad"
        },
        {
            "label": "Mom"
        },
        {
            "label": "Children"
        }
      ],
      "required": true,
      "max_allowed_files": 3
}

note

For labeled file upload questions, the max_allowed_files value must be 2 or more, and must match the number of labels provided in the options array.

Adding or updating personalization data through the dedicated personalization POST endpoint#

To create or update personalization questions for a listing you must first have an existing listing. If you do not have one, you can create a new listing using the createDraftListing endpoint before utilizing this endpoint.

warning

If your app has been updated to support multiple questions and all three question types, then you should send the query parameter ?supports_multiple_personalization_questions=true in your request to update the listing. If this parameter is omitted, an attempt to overwrite previously configured personalization questions will result in a 409 Conflict response. Adding the param without updating the application can lead to deleting data provided by the seller on Etsyweb.

The following procedure creates and attaches a personalization profile to a specific listing with the maximum number of personalization questions allowed and an unlabeled file upload question:

Form a valid URL for updateListingPersonalization, which must include a shop_id and a listing_id and include the ?supports_multiple_personalization_questions=true param. For example, if your shop_id is "12345678", and your listing_id is “987654” then the updateListingPersonalization URL would be:
https://api.etsy.com/v3/application/shops/12345678/listings/987654/personalization?supports_multiple_personalization_questions=true
Build the updateListingPersonalization request body, which must include:
1. personalization_questions - Array of question objects, with the following shape:

{
  "personalization_questions": [
    {
      "question_text": "What name would you like engraved?",
      "instructions": "Please enter your family lastname",
      "question_type": "text_input",
      "required": true,
      "max_allowed_characters": 50
    },
    {
      "question_text": "What message would you like in the card?",
      "instructions": "Please enter the message you would like added in the giftcard.",
      "question_type": "text_input",
      "required": true,
      "max_allowed_characters": 680
    },
    {
      "question_text": "Family pictures",
      "instructions": "Add images of the members of your family that you want in your family portrait",
      "question_type": "unlabeled_upload",
      "required": true,
      "max_allowed_files": 10
    },
    {
      "question_text": "Font",
      "question_type": "dropdown",
      "options": [
            {
                "label": "Arial"
            },
            {
                "label": "Century Gothic"
            },
            {
                "label": "Times New Roman"
            }
        ],
      "required": true
    },
    {
      "question_text": "Frame color",
      "question_type": "dropdown",
      "options": [
            {
                "label": "Dark brown"
            },
            {
                "label": "Light brown"
            },
            {
                "label": "White"
            },
            {
                "label": "Black"
            }
        ],
      "required": true
    }
  ]
}

Execute an updateListingPersonalization POST request with your listings_w scoped OAuth token and x-api-key. For example, a request with the previous personalization_questions might look like this:

JavaScript fetch

    var headers = new Headers();
    headers.append("Content-Type", "application/json");
    headers.append("x-api-key", "1aa2bb33c44d55eeeeee6fff:a1b2c3d4e5");
    headers.append("Authorization", "Bearer 12345678.jKBPLnOiYt7vpWlsny_lDKqINn4Ny_jwH89hA4IZgggyzqmV_bmQHGJ3HOHH2DmZxOJn5V1qQFnVP9bCn9jnrggCRz");

    var raw = JSON.stringify({
        "personalization_questions": [
            {
                "question_text": "What name would you like engraved?",
                "instructions": "Please enter your family lastname",
                "question_type": "text_input",
                "required": true,
                "max_allowed_characters": 50
            },
            {
                "question_text": "What message would you like in the card?",
                "instructions": "Please enter the message you would like added in the giftcard.",
                "question_type": "text_input",
                "required": true,
                "max_allowed_characters": 680
            },
            {
                "question_text": "Family pictures",
                "instructions": "Add images of the members of your family that you want in your family portrait",
                "question_type": "unlabeled_upload",
                "required": true,
                "max_allowed_files": 10
            },
            {
                "question_text": "Font",
                "question_type": "dropdown",
                "options": [
                    {
                        "label": "Arial"
                    },
                    {
                        "label": "Century Gothic"
                    },
                    {
                        "label": "Times New Roman"
                    }
                ],
                "required": true
            },
            {
                "question_text": "Frame color",
                "question_type": "dropdown",
                "options": [
                    {
                        "label": "Dark brown"
                    },
                    {
                        "label": "Light brown"
                    },
                    {
                        "label": "White"
                    },
                    {
                        "label": "Black"
                    }
                ],
                "required": true
            }
        ]
    });

    var requestOptions = {
        method: 'POST',
        headers: headers,
        body: raw,
        redirect: 'follow'
    };

    fetch("https://api.etsy.com/v3/application/shops/12345678/listings/987654/personalization?supports_multiple_personalization_questions=true", requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

You should get a 201 Created response that would look similar to this:

{
    "personalization_questions": [
        {
            "question_text": "What name would you like engraved?",
            "instructions": "Please enter your family lastname",
            "question_id": 18205669682,
            "question_type": "text_input",
            "required": true,
            "max_allowed_characters": 50,
            "max_allowed_files": null
        },
        {
            "question_text": "What message would you like in the card?",
            "instructions": "Please enter the message you would like added in the giftcard.",
            "question_id": 18205669686,
            "question_type": "text_input",
            "required": true,
            "max_allowed_characters": 680,
            "max_allowed_files": null
        },
        {
            "question_text": "Family pictures",
            "instructions": "Add images of the members of your family that you want in your family portrait",
            "question_id": 18205849779,
            "question_type": "unlabeled_upload",
            "required": true,
            "max_allowed_characters": null,
            "max_allowed_files": 10
        },
        {
            "question_text": "Font",
            "instructions": null,
            "question_id": 18205849781,
            "question_type": "dropdown",
            "required": true,
            "max_allowed_characters": null,
            "max_allowed_files": null,
            "options": [
                {
                    "option_id": 18205669694,
                    "label": "Arial"
                },
                {
                    "option_id": 18205849785,
                    "label": "Century Gothic"
                },
                {
                    "option_id": 18205669696,
                    "label": "Times New Roman"
                }
            ]
        },
        {
            "question_text": "Frame color",
            "instructions": null,
            "question_id": 18205849787,
            "question_type": "dropdown",
            "required": true,
            "max_allowed_characters": null,
            "max_allowed_files": null,
            "options": [
                {
                    "option_id": 18205849789,
                    "label": "Dark brown"
                },
                {
                    "option_id": 18205849791,
                    "label": "Light brown"
                },
                {
                    "option_id": 18205849793,
                    "label": "White"
                },
                {
                    "option_id": 18205849795,
                    "label": "Black"
                }
            ]
        }
    ]
}

The content of this request replaces any existing personalization data on the listing.

Updating a listing with existing personalization#

When updating personalization on a listing, the payload must contain all the personalization information that you want on the listing, as the POST request replaces the existing listing personalization data.

If the update includes existing questions — for instance, if you are adding an additional question to existing ones — include the question_id for each of the existing questions in your POST request to the updateListingPersonalization endpoint.

The following procedure updates listing personalization with an existing question:

Obtain the question_id through the getListingPersonalization GET endpoint. A valid URL must include a listing_id. For example, if your listing_id is "987654", the URL is:
https://api.etsy.com/v3/application/listings/987654/personalization
Read the question_id value from the response.

{
    "personalization_questions": [
        {
            "question_text": "What name would you like engraved?",
            "instructions": "Please enter your family lastname",
            "question_id": 1458181502381,
            "question_type": "text_input",
            "required": true,
            "max_allowed_characters": 50,
            "max_allowed_files": null
        }
    ]
}

Form a valid URL for updateListingPersonalization, which must include a shop_id and a listing_id and include the ?supports_multiple_personalization_questions=true param. For example, if your shop_id is "12345678", and your listing_id is “987654” then the updateListingPersonalization URL would be:
https://api.etsy.com/v3/application/shops/12345678/listings/987654/personalization?supports_multiple_personalization_questions=true
Build the updateListingPersonalization request body, which must include:
1. personalization_questions - Array of question objects, each question should include its question_id if you’re editing an existing question:

{
    "personalization_questions": [
        {
            "question_text": "What name would you like engraved?", // existing question
            "instructions": "Please enter your family lastname",
            "question_id": 1458181502381,
            "question_type": "text_input",
            "required": true,
            "max_allowed_characters": 50
        },
        {
            "question_text": "Font", // new question
            "question_type": "dropdown",
            "required": true,
            "options": [
                {
                    "label": "Arial"
                },
                {
                    "label": "Century Gothic"
                },
                {
                    "label": "Times New Roman"
                }
            ]
        }
    ]
}

Execute an updateListingPersonalization POST request with your listings_w scoped OAuth token and x-api-key, similar to the example above.
You should get a 201 Created response that would look similar to this:

{
    "personalization_questions": [
        {
            "question_text": "What names would you like engraved?",
            "instructions": "Please enter the names of your family members.",
            "question_id": 1458184327757,
            "question_type": "text_input",
            "required": true,
            "max_allowed_characters": 100,
            "max_allowed_files": null
        },
        {
            "question_text": "Font",
            "question_type": "dropdown",
            "question_id": 1458184327768,
            "required": true,
            "options": [
                {
                    "option_id": 18205849800,
                    "label": "Arial"
                },
                {
                    "option_id": 18205849801,
                    "label": "Century Gothic"
                },
                {
                    "option_id": 18205849802,
                    "label": "Times New Roman"
                }
            ]
        }
    ]
}

Keep in mind that the question_id is not stable and it might change in a successful response if Etsy detects any changes to the current question.

Deleting personalization from a listing through the dedicated DELETE endpoint#

This endpoint deletes personalization for a listing. It clears personalization by setting is_personalizable to false and removing the listing’s personalization data.

The following procedure deletes the personalization questions attached to a listing.

Form a valid URL for deleteListingPersonalization, which must include a shop_id and a listing_id. For example, if your shop_id is "12345678", and your listing_id is “987654” then the deleteListingPersonalization URL would be:
https://api.etsy.com/v3/application/shops/12345678/listings/987654/personalization
Execute a deleteListingPersonalization DELETE request with your listings_w scoped OAuth token and x-api-key.
Check the response. On success, the endpoint returns 204 No Content.