Etsy, the popular online marketplace, has introduced its latest API version, Etsy API v3, replacing the older v2 version. This transition brings significant changes and improvements that sellers and developers need to be aware of to ensure a smooth integration process. In this article, we will explore the key changes in Etsy API v3 in simple terms, helping you understand and adapt to these updates.
Key Changes in Etsy API v3 and How They Impact Sellers and Developers:
Enhanced Security with OAuth 2.0:
One of the important changes in Etsy API v3 is the adoption of OAuth 2.0 for authentication and authorization. OAuth 2.0 is a more secure and widely used industry standard. It ensures that only authorized applications can access seller data and perform actions on their behalf.
Clearer Endpoint Requests:
Etsy API v3 introduces changes to how developers make requests to the API. With the new version, each request must include an “x-API-key” header containing the Etsy App API Key. This change enhances security and helps Etsy track API requests more effectively. Sellers and developers need to update their code to include this header when communicating with Etsy’s API.
Standard request parameters:
The handling of standard request parameters has been modified. The “fields” query parameter, previously used to retrieve partial resources in v2, is no longer supported in v3.
While the “includes” query parameter is still available in some endpoints, its support is limited. Notably, some endpoints now return associated resource data by default, simplifying the API call.
Pagination:
The users can now experience updated pagination. The “limit” and “offset” query parameters should be used for pagination instead of the “page” parameter used in v2. The default records returned per API call is 25, and the maximum number of records that can be returned is 100. To facilitate navigation through larger data sets, Etsy provides limit and offset parameters. The limit parameter allows you to specify the number of records to retrieve per page. While the offset parameter helps you navigate to a specific page of results.
Additionally, the response includes a count field, indicating the total number of records available for pagination. Please note that for performance reasons, the offset parameter has a maximum value of 50000, ensuring efficient handling of large data sets.
Resource scopes:
In the updated Etsy API v3, resource scopes for filtering lists of resources have transitioned from path-based to query parameter-based filters.
Example: Filtering listings by shop ID and state
Suppose you wanted to filter listings by a specific shop ID and state. In v2, you would use:
/v2/shops/:shop_id/listings/active
With the shift to v3, the URL and query parameter approach would be:
/v3/application/listings?shop_id=:shop_id&state=active
Here, you include the desired values for the shop ID and state as query parameters.
Improved Response Structure:
In the previous version of the Etsy API (v2), API responses followed a standardized structure. Encapsulating various fields and nested objects. However, in Etsy API v3, responses have changed. Specifically, endpoints that return lists of resources now include two important fields: “count” and “results.”
The “count” field denotes the number of results in the response, providing a quick overview of the total count of resources returned. On the other hand, the “results” field contains the actual resource objects themselves. This revised structure allows developers to easily access the count and retrieve the specific results from the response.
Retirement of Outdated Resources:
Over 40+ resources and endpoints have been replaced or removed in v3 across various categories such as Payment. ShopListingVariationImage, ShippingProfileUpgrade, User, ShopSection, and more. The complete list of retired resources can be found in the documentation.>>https://developers.etsy.com/documentation/migration/retired-resources/
API Rate Limits:
In Etsy API v3, there have been no changes to the API rate limits compared to v2. If you were using the same Etsy App API Key in v2, your negotiated rate limits will remain the same in v3 as well.
By default, Etsy apps authenticated with their API key can make up to 10,000 public requests within a 24-hour period, providing developers ample opportunities to interact with the Etsy platform and retrieve the necessary data for their applications. The rate limit (10 queries per second) ensures fair usage and maintains system stability.
Do You Know?
Are you already having a Prestashop, Opencart, WooComemrce, or Magento 2-based eCommerce shop? Do you know that with Knowband Etsy marketplace connector, you can list and manage your products on the Etsy marketplace?
The Knowband Etsy Marketplace connector comes with the latest Etsy V3 API changes and ensures seamless integration between your website and the Etsy marketplace.
For example, you can manage all your Etsy orders and listings right from the admin panel of your eCommerce store. Furthermore, you can also reach out to us at support@knowband.com for more information about Etsy Marketplace Connector.
Conclusion:
The transition to Etsy API v3 brings important changes aimed at enhancing security, simplifying integration, and improving the overall experience for sellers and developers. By understanding and adapting to these changes, you can ensure seamless integration with Etsy’s updated API version and leverage its new capabilities effectively.
