Breaking change: instructions field reduced from 256 to 120 characters in personalization migration

[franciscodelgadodev]

Hello,

As part of the personalization migration efforts https://developer.etsy.com/documentation/tutorials/personalization-migration, the maximum length of the instructions attribute appears to have changed from 256 characters to 120 characters.

Because this change reduces the previously supported limit, it effectively introduces a breaking change for existing integrations and listings.

In our case, the impact is significant:

• 22% of the listings supported by our integration are personalizable
• 49% of those listings currently have instructions longer than 120 characters

We attempted to roll out the first phase of the migration but had to roll it back after receiving complaints from customers whose listings exceeded the new limit.

Since many existing listings were created under the 256-character limit, enforcing the new 120-character limit causes previously valid content to fail validation and disrupts the experience for sellers.

Would it be possible to maintain the 256-character limit for the instructions field?

This would help prevent disruptions for sellers and integrations that relied on the previously supported limit.

Thank you.

[openapi-support[bot]]

Thank you for raising this and for sharing the impact details. We appreciate you flagging the potential disruption.

To clarify:

• During the current endpoint migration phase, the instructions field will continue to support up to 256 characters.

• The updated 120-character limit will only be enforced after the general audience (GA) launch, and only once your integration opts in by sending the supports_multiple_personalization_questions queryparam, indicating that your UI has been updated to support the new features.

• Additionally, the new updateListingPersonalization endpoint should only be called when personalization content is actually being modified. On the front end, we recommend only enforcing personalization-specific validations when personalization is edited, so sellers do not need to modify existing instructions in order to make unrelated listing updates.

This phased approach is intended to prevent unexpected breaking changes and to give third-party integrations time to update their UIs before the new limit is enforced.

If you previously saw documentation referencing a 120-character limit during the endpoint migration phase, we apologize for the confusion. That reference was incorrect and has been corrected here: https://developer.etsy.com/documentation/tutorials/personalization/endpoint-migration.

If you are currently seeing validation errors at 120 characters without sending the opt-in query parameter, that would be unexpected. Please let us know at developers@etsy.com with any additional information about reproducing the issue, and we’ll investigate.

Thanks again for raising this and for working through the migration with us — we appreciate the partnership.

[franciscodelgadodev]

Hello Etsy team, and thanks for the clarification — that helps a lot.

We confirmed that the phase-1 migration endpoints continue to accept 256 characters, so from that standpoint we’re unblocked. Also, in our system we only call the personalization endpoints when users actually modify personalization settings, so unrelated listing updates won’t trigger validations.

However, we are still concerned about the impact once we move to phase 2 and begin sending the supports_multiple_personalization_questions query param.

A very common workflow among our users is to create new listings by copying an existing one and then adjusting some properties (including personalization instructions). Because of that workflow, the new 120-character limit may introduce confusing situations for sellers. For example:

• A seller copies an existing listing that has >120 characters in the instructions field (which is valid under the previous rules).
• The copied listing becomes invalid, even though it was created from a valid configuration.
• Similarly, an existing listing with >120 characters could appear valid in the UI, but as soon as the seller edits or adds a small change to the instructions it would suddenly fail validation.

From a seller’s perspective this can feel inconsistent: two listings with essentially the same configuration behaving differently depending on whether the instructions were edited after the migration.

While the migration path you described works well for the first step, the dual behavior between existing content and edited/new content still creates a potentially confusing experience for sellers and adds additional complexity for integrations that need to handle both cases.

For that reason, we wanted to ask whether it would be possible to maintain the 256-character limit for the instructions field, or otherwise reconsider the reduction. Many sellers currently rely on the existing limit for their personalization instructions.

We appreciate the clarification and the effort to make the migration smooth for third-party integrations, and we’re happy to provide additional examples from real workflows if that would be helpful.

Thanks again for the support.

[openapi-support[bot]]

Thanks for the detailed feedback and for outlining these workflows so clearly. This is really helpful context.

We understand your concern around the shift from 256 to 120 characters and the potential for inconsistent experiences during the transition, especially for sellers who duplicate listings or edit existing ones. You’re right that this can create cases where similar listings behave differently depending on when or how they’re updated.

To share more context on the change: we’re introducing additional personalization fields to improve clarity and usability on both the buyer and seller sides. Today, personalization requirements are often embedded in long, unstructured text, which can be easy for buyers to miss or misunderstand. This frequently leads to incomplete inputs and requires sellers to follow up, adding friction and delaying orders.

With multiple personalization fields, sellers can collect structured inputs for each requirement, for example name, date, or color, in a more explicit and guided way. This reduces the need to combine multiple requests into a single instructions field and helps ensure buyers provide complete and accurate information upfront. Over time, we expect this will reduce reliance on longer instruction text.

In the Etsy seller website, we’ve also introduced specific error handling for this scenario. When a seller exceeds the new 120-character limit after structured fields are enabled, we provide a clear validation message explaining the change and guiding them to adjust their instructions accordingly.

Given this shift, one recommendation is to help guide sellers in your experience toward adopting more structured inputs, both by providing some of this context and by encouraging patterns that break out multiple requests into separate fields with clear options for buyers.

We also hear your concerns about the migration experience and are continuing to evaluate ways to minimize confusion during the transition.

Thanks again for the thoughtful partnership here.

[franciscodelgadodev]

Thanks for the additional context.

We still believe the transition will introduce some friction for sellers, particularly around the workflows mentioned earlier. That said, we understand the broader goals behind the change.

We’ll proceed on our end by mirroring Etsy’s UI validation rules and guiding users toward the new structured inputs.

We’ll keep an eye on this thread, as well as the public docs and announcements, in case there are any updates around this.

Thanks again for the collaboration.