Open API v2 will be deprecated on April 3, 2023. Please begin transitioning to Open API v3 as soon as possible. As of September 29, 2022 all new apps will only be permitted to use Open API v3.
Estimated Delivery Dates
Some data requirements in Open API v2 are changing on April 1
Hello,
We're getting in touch to let you know about data requirement changes in Etsy's Open API v2. Starting April 1, Etsy will require requests to create or save changes to a listing or a shipping profile to provide certain fulfillment data needed to calculate an Estimated Delivery Date. We're doing this to ensure that Open API v2 is in line with the Etsy web experience.
What is an Estimated Delivery Date?
We use fulfillment data to calculate an estimated delivery date for shoppers on Etsy. This lets customers know when their order is expected to arrive—a key piece of information they look for when shopping on Etsy.
Generally, the estimated delivery date is based on a combination of the processing time, transit time*, and origin location data. These factors inform what data we require.
What's changing?
Starting April 1, in order to save changes to a listing or a shipping profile via Open API v2, certain fulfillment data on shipping profiles will be required.
The following routes are affected:
Method Name | HTTP Method and URI | Newly Required Data |
---|---|---|
createListing | POST /listings | shipping_template_id If the shipping template you're attaching to this listing or any of its entries and upgrades is missing required data, the listing create request will fail. Update the relevant shipping data before attempting to create a listing. |
updateListing | PUT /listings/:listing_id | If the shipping template attached to this listing or any of its entries and upgrades are missing any required data, the listing update request will fail. Update the relevant shipping data before attempting to update a listing. |
createShippingInfo | POST /listings/:listing_id/shipping/info |
min_processing_days max_processing_days origin_postal_code transit time data* |
updateShippingInfo | PUT /shipping/info/:shipping_info_id |
If any of the data required to create a ShippingInfo record is not already stored on the record you're updating, the request will fail. Provide the missing data in the update request if it doesn't already exist. |
createShippingTemplate | POST /shipping/templates |
min_processing_days max_processing_days origin_postal_code transit time data* |
updateShippingTemplate | PUT /shipping/templates/:shipping_template_id | transit time data* |
createShippingTemplateEntry | POST /shipping/templates/entries | transit time data* |
updateShippingTemplateEntry | PUT /shipping/templates/entries/:shipping_template_entry_id | transit time data* |
createListingShippingUpgrade | POST /listings/:listing_id/shipping/upgrades | transit time data* |
updateListingShippingUpgrade | PUT /listings/:listing_id/shipping/upgrades | transit time data* |
createShippingTemplateUpgrade | POST /shipping/templates/:shipping_template_id/upgrades | transit time data* |
updateShippingTemplateUpgrade | PUT /shipping/templates/:shipping_template_id/upgrades | transit time data* |
* We can derive transit times with two different sets of data, so "transit time data" is defined as a combination of shipping_carrier_id
and mail_class
OR a combination of min_delivery_time
and max_delivery_time
If you don't provide the data listed above in listing and shipping endpoints by April 1, your requests to update listings and shipping data will fail. We wanted to let you know so that you can account for these requirements in your product as needed.
Update your app
These required fields are already available to you, so you can start sending this data in your API requests right away.
We plan to officially sunset Open API v2 in the second half of 2022. You can learn more about that timeline and migrating to Etsy's Open API v3 here. We plan to include these same requirements in Open API v3 and will share the details in the coming months.
Got questions?
We have answers. We'll continue to share updates on the Open API v2 site.