Skip to main content

Examples for the Endpoint Migration period

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.

  1. 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

  2. Execute a getListingPersonalization GET request with your x-api-key.

  3. 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 still retrieve the personalization data for a listing by using the following endpoints and including the parameter ?includes=personalization in your requests:

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

Example response:

During this phase we will continue to return the legacy keys related to personalization, since the new data shape is fully backwards compatible with the legacy one.

{
"listing_id": 429494249,
"title": "Example of personalizable listing",
"is_personalizable": true,
... // Legacy keys
"personalization_is_required": true, 
"personalization_char_count_max": 50,
"personalization_instructions": "Personalization\nWhat name would you like engraved? Please enter their full name",
... // New personalization 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
      }
    ]
  }
}

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.

The following procedure creates and attaches personalization profile to a specific listing:

  1. Form a valid URL for updateListingPersonalization, 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 createListingPersonalization URL would be:

    https://api.etsy.com/v3/application/shops/12345678/listings/987654/personalization

  2. Build the updateListingPersonalization request body, which must include:

    1. personalization_questions - Array of personalization_questions with a single text_input question and the question_text value must be “Personalization”, similar to:
{
  "personalization_questions": [
    {
      "question_text": "Personalization",
      "instructions": "What name would you like engraved? Please enter their full name",
      "question_type": "text_input",
      "required": true,
      "max_allowed_characters": 50
    }
  ]
}
  1. Execute a updateListingPersonalization POST request with your listings_w scoped OAuth token and x-api-key. For example, a request with the previous personalization_question might look like this:
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: "Personalization",
      instructions: "What name would you like engraved? Please enter their full name",
      question_type: "text_input",
      required: true,
      max_allowed_characters: 50
    }
  ]
});

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

fetch("https://api.etsy.com/v3/application/shops/12345678/listings/987654/personalization", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
  1. The response would look something like this:
{
  "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
    }
  ]
}
  1. The content of this request will replace any existing personalization data in this listing.

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.

  1. 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

  2. Execute a deleteListingPersonalization DELETE request with your listings_w scoped OAuth token and x-api-key.

  3. Check the response. On success, the endpoint returns 204 No Content.