Summary of Changes
Making requests and authenticating#
To make a request to any Open API v3 endpoint, use URLs with a https://api.etsy.com/v3/application/ prefix. Every request to a v3 endpoint must include an x-api-key header, with your Etsy App API Key keystring (found in Your Apps) as the value. The Open API v3 supports authentication via OAuth 2.0 ONLY.
Read more about making requests here and setting up your OAuth 2.0 authentication flow here.
Standard request parameters#
We no longer support the fields query parameter to return partial resources.
We have limited support for the includes query parameter. Our reference documentation provides the most up-to-date information, but these are the endpoints that support includes and the resources you can request:
- getListing:
Images,Shop,User,Translations - getListingsByListingIds:
Images,Shop,User,Translations - getListingInventory:
Listing
Additionally, there are a few occasions where we return data from an associated resources by default in v3.
For example, in v2:
/v2/listings/:listing_id/inventory?includes=ListingOfferings&fields=products,sku_on_property
Becomes in v3:
/v3/application/listings/:listing_id/inventory
In the v3 response, a nested offerings field returns the ListingOfferings for this ListingInventory resource and returns all ListingInventory fields.
Pagination#
The Open API v3 only accepts limit and offset query parameters for pagination, and rejects the page parameter commonly specified in many v2 endpoints. Also, the Open API v3 a maximum limit of 100 for performance reasons, and passing a higher value resolves to the limit of 100 instead of throwing an error.
Resource scopes#
Instead of path-based scopes to filter lists of resources, we have converted these to query parameter-based filters.
For Example:
/v2/listings/active
Becomes:
/v3/application/listings?state=active
Responses#
Responses are no longer universally wrapped in the same v2 standard structure. In v3, endpoints that return lists of resources contain count and results fields, indicating the number of results in the response and the results themselves.
For Example:
Field visibility#
We no longer support field-level visibility in the API. In v2, the same endpoint could return resources with different sets of fields based on which were public or private. In v3, permission scopes are now at the endpoint-level instead. Endpoints either require OAuth 2.0 credentials with specific scope(s) along with an Etsy App API Key, or only an Etsy App API Key.
For Example (ListingInventory):
| Field | Visibility Level | Permission Scope |
|---|---|---|
| products | public | none |
| price_on_property | private | listings_r |
The getListingInventory endpoint, and therefore the ListingInventory resource and any of its fields, requires an oauth2 token with the listings_r scope.
Parameter/data types#
The parameter types supported in Open API v3 are largely the same as those listed in v2, but will often offer more specificity for their validation criteria in the endpoint documentation, if applicable.
Example:
| Parameter | Definition |
|---|---|
| lat | number [ -90 .. 90 ] Default: null |
| who_made required | string Enum: "i_did" "someone_else" "collective” |
Resources#
The following v2 resources and endpoints were replaced or removed in v3.
Payment#
ShopListingVariationImage#
v2 Resource: ListingVariationImage
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getVariationImages | getListingVariationImages | |
| updateVariationImages | updateVariationImages |
ShippingProfileUpgrade#
v2 Resource: ShippingUpgrade
User#
v2 Resource: UserProfile
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findUserProfile | getUser | We return UserProfile data along with getUser now |
| updateUserProfile | Retired |
ShopSection#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findAllShopSections | getShopSections | |
| createShopSection | createShopSection | |
| getShopSection | getShopSections | |
| updateShopSection | v3 Endpoint Schema TBD | |
| deleteShopSection | v3 Endpoint Schema TBD |
ShopListingFile#
v2 Resource: ListingFile
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findAllListingFiles | getAllListingFiles | |
| uploadListingFile | uploadListingFile | |
| findListingFile | getListingFile | |
| deleteListingFile | deleteListingFile |
PaymentAdjustment#
In v3, Payment responses return adjustments by default.
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findPaymentAdjustments | Retired | |
| findPaymentAdjustment | Retired | |
| findPaymentAdjustmentForLedgerEntry | Retired | |
| findPaymentAdjustmentForPaymentAccountLedgerEntry | Retired |
User#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findAllUsers | Retired | |
| getUser | getUser | |
| findAllUsersForTeam | Retired | |
| getCirclesContainingUser | Retired | |
| getConnectedUser | Retired | |
| unconnectUsers | Retired | |
| getConnectedUsers | Retired | |
| connectUsers | Retired |
ListingPropertyValue#
v2 Resource: PropertyValue
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getAttributes | getListingProperties | |
| getAttribute | getListingProperty | |
| updateAttribute | updateListingProperty | |
| deleteAttribute | deleteListingProperty |
ShopReceipt#
v2 Resource: Receipt
ShopReceiptShipment#
- v2 Resource: ShopReceiptShipment
ShopReceiptShipment information is now available inside the ShopReceipt resource.
ShopTransaction#
v2 Resource: Transaction
ListingTranslation#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getListingTranslation | getListingTranslation | |
| createListingTranslation | createListingTranslation | |
| updateListingTranslation | updateListingTranslation | |
| deleteListingTranslation | Retired |
ShopListingInventory#
v2 Resource: ListingInventory
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getInventory | getListingInventory | |
| updateInventory | updateListingInventory |
ShopListingProduct#
v2 Resource: ListingProduct
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getProduct | getListingProduct |
Shop#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findAllShops | findShops | |
| getShop | getShop | |
| updateShop | updateShop | |
| uploadShopBanner | Retired | |
| deleteShopBanner | Retired | |
| getListingShop | Retired | |
| findAllUserShops | getShopByOwnerUserId |
FavoriteUser#
Work is in progress to define a schema in v3 for this resource.
UserAddress#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findAllUserAddresses | getUserAddresses | |
| createUserAddress | v3 Endpoint Schema TBD | |
| getUserAddress | getUserAddress | |
| deleteUserAddress | v3 Endpoint Schema TBD |
PaymentAccountLedgerEntry#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findPaymentAccountEntries | getShopPaymentAccountLedgerEntries |
ShopListing#
v2 Resource: Listing
TaxonomyNodeProperty#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getTaxonomyNodeProperties | getPropertiesByTaxonomyId |
Taxonomy#
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getSellerTaxonomy | getSellerTaxonomyNodes |
ShopListingImage#
v2 Resource: ListingImage
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findAllListingImages | getListingImages | |
| uploadListingImage | uploadListingImage | |
| getImage_Listing | getListingImage | |
| deleteListingImage | deleteListingImage |
ShippingProfile#
v2 Resource: ShippingTemplate
ShopListingOffering#
v2 Resource: ListingOffering
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| getOffering | getListingOffering |
ShippingProfileDestination#
v2 Resource: ShippingTemplateEntry
Money#
There are no endpoints associated with this resource.
UserFeedback#
v2 Resource: Feedback
UserFeedback has been retired in favor of Reviews
| v2 Endpoint | v3 Endpoint | Notes |
|---|---|---|
| findAllUserFeedbackAsAuthor | Retired | |
| findAllUserFeedbackAsBuyer | Retired | |
| findAllUserFeedbackAsSeller | Retired | |
| findAllUserFeedbackAsSubject | Retired | |
| findAllFeedbackFromBuyers | Retired | |
| findAllFeedbackFromSellers | Retired |