Breaking Change for April 15, 2025

[openapi-support[bot]]

Hello,

We’re getting in touch to let you know about the deprecation of some listing property values that will affect Etsy’s Open API. Starting April 15, 2025, Etsy will no longer accept references to the property_ids of deprecated properties in requests to get, create or update a property or listing. We’re doing this to ensure that the Open API is in line with the Etsy web experience.

What are Variations and Properties?

Variations are a means to offer different options for an item within the same listing. For example, if a seller sells a dress with different sizes and colors, they can specify these options in that dress listing’s variations.

Properties describe the ways in which a listing may vary (and therefore may use a variation). Examples of valid properties include "Sleeve length" and "Primary Color".

What's changing?

Starting April 15, 2025, in order to provide a better experience to buyers viewing listings with variations, we will deprecate certain properties, and reduce support for using those deprecated properties in variations. Any existing listings with variations that are linked to the deprecated properties will be converted to a custom variation so that those listings may remain available for sale on Etsy. That migration will be complete by Apr 15, 2025. If you have cached any property_ids , we recommend that you call getListingProperties to get the new property_ids for any listings formerly connected to variations with deprecated properties after the migration.

Affected endpoints:

• getPropertiesByBuyerTaxonomyId: will no longer return deprecated properties for a given buyer taxonomy_id.
• getPropertiesByTaxonomyId: will no longer return deprecated properties for a given seller taxonomy_id.
• updateListingInventory: will respond with a 400 error code if you include a property_id linked to a deprecated property in your request, as that property will no longer exist.
• updateListingProperty: will respond with a 400 error code if you include a property_id linked to a deprecated property, as that property will no longer exist.
• getListingInventory: will begin to return different property_ids and value_ids on a rolling basis when we begin to backfill. Property ids and value ids will change, but the labels and names will remain the same.

Before migration	After migration
{ "products": [ { "product_id": 1, "sku": "string", "is_deleted": false, "offerings": [...], "property_values": [ { "property_id": 509, "property_name": "Scent", "scale_id": null, "scale_name": null, "value_ids": [ 306634771979 ], "values": [ "Cheese" ] }] }, ... ], ... }	{ "products": [ { "product_id": 1, "sku": "string", "is_deleted": false, "offerings": [...], "property_values": [ { "property_id": 513, // id updated "property_name": "Scent", // same name "scale_id": null, "scale_name": null, "value_ids": [ 1355677451254 // id updated ], "values": [ "Cheese" // same name ] }] }, ... ], ... }

Deprecated Properties

property_id	property_name
175269961	ListingMetadata_Property_ShoeSizeUSMen
6	ListingMetadata_Property_Style
100	ListingMetadata_Variation_TeeShirtSize
500	ListingMetadata_Variation_Finish
501	ListingMetadata_Variation_Dimensions
502	ListingMetadata_Variation_Fabric
503	ListingMetadata_Variation_Flavor
504	ListingMetadata_Variation_Diameter
505	ListingMetadata_Variation_Height
506	ListingMetadata_Variation_Length
507	ListingMetadata_Variation_Material
508	ListingMetadata_Variation_Pattern
509	ListingMetadata_Variation_Scent
510	ListingMetadata_Variation_Style
511	ListingMetadata_Variation_Weight
512	ListingMetadata_Variation_Width
515	ListingMetadata_Variation_Device
175264397	ListingMetadata_Property_WhenMade
174746014	ListingMetadata_Property_IsSupply
175271657	ListingMetadata_Property_WhoMade
175271659	ListingMetadata_Property_WhatContent
345442291	ListingMetadata_Property_ShortUrl
445512291	ListingMetadata_Property_IsNipsa
1	ListingMetadata_Property_File
786712878	ListingMetadata_Property_OriginalQuantity
786712880	ListingMetadata_Property_OriginalState
2	ListingMetadata_Property_ListingType
46	ListingMetadata_Property_IsNotCustomizable
598273500	ListingMetadata_Property_Source
700	ListingMetadata_Property_ShippingUpgrade
2000	ListingMetadata_Property_Channels
598273501	ListingMetadata_Property_Taxonomy
69488881	ListingMetadata_Property_DigitalFulfillment
900	ListingMetadata_Property_ItemWeight
901	ListingMetadata_Property_ItemWeightUnit
902	ListingMetadata_Property_ItemLength
903	ListingMetadata_Property_ItemWidth
904	ListingMetadata_Property_ItemHeight
905	ListingMetadata_Property_ItemDimensionsUnit
50	ListingMetadata_Property_ShouldAutoRenew
52	ListingMetadata_Property_DisplayUnitPrice
420	ListingMetadata_Property_SquareCatalogItemId
53	ListingMetadata_Property_IsWaitlistEnabled
54	ListingMetadata_Property_IsPersonalizable
175271658	ListingMetadata_Property_WhatTools
175271660	ListingMetadata_Property_HowMade
266817057	ListingMetadata_Property_Recipient
300	ListingMetadata_Property_SizingScale
301	ListingMetadata_Property_WeightScale
302	ListingMetadata_Property_DiameterScale
303	ListingMetadata_Property_DimensionsScale
304	ListingMetadata_Property_HeightScale
305	ListingMetadata_Property_LengthScale
306	ListingMetadata_Property_WidthScale

Update your app

If you have stored any references to the property_ids of deprecated properties, those should be removed, and you should be sure to retrieve the most up-to-date property_ids available at the time of your request using the getListingProperties endpoint until the full migration is complete.

[yasinsarigul]

Has this update been postponed? I am still receiving successful responses from the API.

[baahar]

Hi,

You state that /getPropertiesByTaxonomyId will no longer return deprecated properties for a given seller taxonomy_id. But for taxonomy_id = 1764, for instance, I am still getting many properties from the list above.

Could you please clarify?

Best wishes,
Baa