Summary of Changes

Making requests and authenticating#

To make a request to any Open API v3 endpoint, use URLs with a https://openapi.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. Though you can currently make requests to most v3 endpoints with existing OAuth 1.0 tokens, we strongly encourage migrating to OAuth 2.0 as support for OAuth 1.0 tokens ends when we sunset the v2 API.

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:

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:

{
"count": integer,
"results": [
{ result object }
],
}

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):

FieldVisibility LevelPermission Scope
productspublicnone
price_on_propertyprivatelistings_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:

ParameterDefinition
latnumber [ -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#

v2 Endpointv3 EndpointNotes
findPaymentgetPayments
findPaymentForLedgerEntryRetired
findShopPaymentByReceiptgetShopPaymentByReceiptId
findPaymentForPaymentAccountLedgerEntrygetPaymentAccountLedgerEntryPayments

ShopListingVariationImage#

v2 Resource: ListingVariationImage

v2 Endpointv3 EndpointNotes
getVariationImagesgetListingVariationImages
updateVariationImagesupdateVariationImages

ShippingProfileUpgrade#

v2 Resource: ShippingUpgrade

v2 Endpointv3 EndpointNotes
getListingShippingUpgradesRetired
createListingShippingUpgradeRetired
updateListingShippingUpgradeRetired
deleteListingShippingUpgradeRetired
findAllShippingTemplateUpgradesgetShopShippingProfileUpgrades
createShippingTemplateUpgradecreateShopShippingProfileUpgrade
updateShippingTemplateUpgradeupdateShopShippingProfileUpgrade
deleteShippingTemplateUpgradedeleteShopShippingProfileUpgrade

User#

v2 Resource: UserProfile

v2 Endpointv3 EndpointNotes
findUserProfilegetUserWe return UserProfile data along with getUser now
updateUserProfileRetired

ShopSection#

v2 Endpointv3 EndpointNotes
findAllShopSectionsgetShopSections
createShopSectioncreateShopSection
getShopSectiongetShopSections
updateShopSectionv3 Endpoint Schema TBD
deleteShopSectionv3 Endpoint Schema TBD

ShopListingFile#

v2 Resource: ListingFile

v2 Endpointv3 EndpointNotes
findAllListingFilesgetAllListingFiles
uploadListingFileuploadListingFile
findListingFilegetListingFile
deleteListingFiledeleteListingFile

PaymentAdjustment#

In v3, Payment responses return adjustments by default.

v2 Endpointv3 EndpointNotes
findPaymentAdjustmentsRetired
findPaymentAdjustmentRetired
findPaymentAdjustmentForLedgerEntryRetired
findPaymentAdjustmentForPaymentAccountLedgerEntryRetired

User#

v2 Endpointv3 EndpointNotes
findAllUsersRetired
getUsergetUser
findAllUsersForTeamRetired
getCirclesContainingUserRetired
getConnectedUserRetired
unconnectUsersRetired
getConnectedUsersRetired
connectUsersRetired

ListingPropertyValue#

v2 Resource: PropertyValue

v2 Endpointv3 EndpointNotes
getAttributesgetListingProperties
getAttributegetListingProperty
updateAttributeupdateListingProperty
deleteAttributedeleteListingProperty

ShopReceipt#

v2 Resource: Receipt

v2 Endpointv3 EndpointNotes
getShop_Receipt2getShopReceipt
updateReceiptcreateReceiptShipment
findAllShopReceiptsgetShopReceipts
submitTrackingcreateReceiptShipment
findAllShopReceiptsByStatusgetShopReceipts
searchAllShopReceiptsRetired
findAllUserBuyerReceiptsRetired

ShopReceiptShipment#

ShopReceiptShipment information is now available inside the ShopReceipt resource.

ShopTransaction#

v2 Resource: Transaction

v2 Endpointv3 EndpointNotes
getShop_TransactiongetShopReceiptTransaction
findAllListingTransactionsgetShopReceiptTransactionsByListing
findAllShop_Receipt2TransactionsgetShopReceiptTransactionsByReceipt
findAllShopTransactionsgetShopReceiptTransactionsByShop
findAllUserBuyerTransactionsRetired

ListingTranslation#

v2 Endpointv3 EndpointNotes
getListingTranslationgetListingTranslation
createListingTranslationcreateListingTranslation
updateListingTranslationupdateListingTranslation
deleteListingTranslationRetired

ShopListingInventory#

v2 Resource: ListingInventory

v2 Endpointv3 EndpointNotes
getInventorygetListingInventory
updateInventoryupdateListingInventory

ShopListingProduct#

v2 Resource: ListingProduct

v2 Endpointv3 EndpointNotes
getProductgetListingProduct

Shop#

v2 Endpointv3 EndpointNotes
findAllShopsgetShops
getShopgetShop
updateShopupdateShop
uploadShopBannerRetired
deleteShopBannerRetired
getListingShopRetired
findAllUserShopsgetShopByOwnerUserId

FavoriteUser#

Work is in progress to define a schema in v3 for this resource.

UserAddress#

v2 Endpointv3 EndpointNotes
findAllUserAddressesgetUserAddresses
createUserAddressv3 Endpoint Schema TBD
getUserAddressgetUserAddress
deleteUserAddressv3 Endpoint Schema TBD

PaymentAccountLedgerEntry#

v2 Endpointv3 EndpointNotes
findPaymentAccountEntriesgetShopPaymentAccountLedgerEntries

ShopListing#

v2 Resource: Listing

v2 Endpointv3 EndpointNotes
createListingcreateDraftListing
findAllFeaturedListingsRetired
getListinggetListing
updateListingupdateListing
deleteListingdeleteListing
findAllListingActivefindAllListingsActive
getInterestingListingsRetired
getTrendingListingsRetired
findAllListingsForFeaturedTreasuryIdRetired
findAllActiveListingsForFeaturedTreasuryIdRetired
findAllCurrentFeaturedListingsRetired
findAllReceiptListingsgetListingsByShopReceipt
findAllShopListingsActivefindAllActiveListingsByShop
findAllShopListingsDraftgetListingsByShop
findAllShopListingsExpiredgetListingsByShop
getShopListingExpiredRetired
findAllShopListingsFeaturedRetired
findAllShopListingsInactivegetListingsByShop
getShopListingInactiveRetired
findAllShopSectionListingsRetired
findAllShopSectionListingsActivegetListingsByShopSectionId
findAllCartListingsRetired

TaxonomyNodeProperty#

v2 Endpointv3 EndpointNotes
getTaxonomyNodePropertiesgetPropertiesByTaxonomyId

Taxonomy#

v2 Endpointv3 EndpointNotes
getSellerTaxonomygetSellerTaxonomyNodes

ShopListingImage#

v2 Resource: ListingImage

v2 Endpointv3 EndpointNotes
findAllListingImagesgetListingImages
uploadListingImageuploadListingImage
getImage_ListinggetListingImage
deleteListingImagedeleteListingImage

ShippingProfile#

v2 Resource: ShippingTemplate

v2 Endpointv3 EndpointNotes
createShippingTemplatecreateShopShippingProfile
getShippingTemplategetShopShippingProfile
updateShippingTemplateupdateShopShippingProfile
deleteShippingTemplatedeleteShopShippingProfile
findAllShippingTemplateEntriesgetShopShippingProfileDestinationsByShippingProfile
findAllUserShippingProfilesgetShopShippingProfiles

ShopListingOffering#

v2 Resource: ListingOffering

v2 Endpointv3 EndpointNotes
getOfferinggetListingOffering

ShippingProfileDestination#

v2 Resource: ShippingTemplateEntry

v2 Endpointv3 EndpointNotes
createShippingTemplateEntrycreateShopShippingProfileDestination
getShippingTemplateEntryRetired
updateShippingTemplateEntryupdateShopShippingProfileDestination
deleteShippingTemplateEntrydeleteShopShippingProfileDestination

Money#

There are no endpoints associated with this resource.

UserFeedback#

v2 Resource: Feedback

UserFeedback has been retired in favor of Reviews

v2 Endpointv3 EndpointNotes
findAllUserFeedbackAsAuthorRetired
findAllUserFeedbackAsBuyerRetired
findAllUserFeedbackAsSellerRetired
findAllUserFeedbackAsSubjectRetired
findAllFeedbackFromBuyersRetired
findAllFeedbackFromSellersRetired