Releases: etsy/open-api
3.0.0-general-release-2021-07-28
Etsy's Open API v3 is now in General Release! 🎉
7/28/21
Changed
-
getAllListingFiles
does not throw a 404 for a non-existent or invalid listing ID -
Update
deleteListingFile
returns a value description -
getListingsByListingIds
now Implement Shop, User and Images associations -
lists of shipping profiles Include calculated shipping profiles
-
a product can be assigned a calculated shipping profile
-
updateListingProperty
bug fixed (returned a 500 when only value id or values is passed) -
rate limits have been included in v3 endpoints
-
listing property update - allows to submit
values
orvalue_ids
only in the request -
updateListing
has now 'is_supply' request parameter in -
listings are now returning
taxonomy_id
-
getListingInventory
now returns an array of ids for the properties -
should_auto_renew
value bug fixed in the lIsting update method -
Endpoints moved into beta
updateListingProperty
3.0.0-beta-2021-07-12
Added
- Shop Management tutorial
- All listing responses now return
is_supply
- Bug fixes
Changed
- Associations are now supported in these endpoints
getListingInventory
- New “includes” parameter accepts the following association:
- Listing
- New “includes” parameter accepts the following association:
getListing
getListingByListingIds
- New “includes” input parameter accepts comma delimited list of the following associations:
- Shop
- Images
- User
- New “includes” input parameter accepts comma delimited list of the following associations:
getListingsByShop
- Added
updated
as a validsort_on
parameter
- Added
- Transaction endpoints now includes the Title or Description in the JSON output again
- createReceiptShipment
- Requires either only a carrier name or tracking number with carrier name
- All listing responses now return
shipping_profile_id
instead ofshipping_template_id
updateListing
now acceptsis_supply
as a request parameter
Shipping Profiles have been moved from the Listings perspective to the Shop perspective.
createListingShippingProfile
- New Name:
createShopShippingProfile
- New Route:
/shops/:shop_id/shipping-profiles
- New Name:
deleteListingShippingProfile
- New Name:
deleteShopShippingProfile
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id
- New Name:
getListingShippingProfile
- New Name:
getShopShippingProfile
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id
- New Name:
getListingShippingProfiles
- New Name:
getShopShippingProfiles
- New Route:
/shops/:shop_id/shipping-profiles
- New Name:
updateListingShippingProfile
- New Name:
updateShopShippingProfile
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id
- New Name:
Shipping Profile Destinations have been moved from the Listings perspective to the Shop perspective.
createListingShippingProfileDestination
- New Name:
createShopShippingProfileDestination
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/destinations
- New Name:
deleteListingShippingProfileDestination
- New Name:
deleteShopShippingProfileDestination
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/destinations/:shipping_profile_destination_id
- New Name:
getListingShippingProfileDestinationsByShippingProfile
- New Name:
getShopShippingProfileDestinationsByShippingProfile
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/destinations
- New Name:
updateListingShippingProfileDestination
- New Name:
updateShopShippingProfileDestination
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/destinations/:shipping_profile_destination_id
- New Name:
Shipping Profile Upgrades have been moved from the Listings perspective to the Shop perspective.
createListingShippingProfileUpgrade
- New Name:
createShopShippingProfileUpgrade
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/upgrades
- New Name:
deleteListingShippingProfileUpgrade
- New Name:
deleteShopShippingProfileUpgrade
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/upgrades/:upgrade_id
- New Name:
getListingShippingProfileUpgrades
- New Name:
getShopShippingProfileUpgrades
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/upgrades
- New Name:
updateListingShippingProfileUpgrade
- New Name:
updateShopShippingProfileUpgrade
- New Route:
/shops/:shop_id/shipping-profiles/:shipping_profile_id/upgrades/:upgrade_id
- New Name:
Shipping Carriers have been moved from the Listings perspective to the Shop perspective.
getShippingCarriers
- New Route:
/shipping-carriers
- New Route:
The following endpoints are now in beta
getListingProperties
getPropertiesByTaxonomyId
getListingsByListingIds
getListingsByShopSectionId
getShopReceiptTransactionsByListing
getReviewsByShop
getPaymentAccountLedgerEntryPayments
getShopPaymentAccountLedgerEntries
getAllListingFiles
deleteListingFile
getListingFile
getListingImages
getListingImage
deleteListingImage
uploadListingImage
getListingProduct
getShopReceiptTransaction
getSellerTaxonomyNodes
getShopSection
updateVariationImages
getListingVariationImages
createShopShippingProfile
createShopShippingProfileDestination
createShopShippingProfileUpgrade
deleteShopShippingProfile
deleteShopShippingProfileDestination
deleteShopShippingProfileUpgrade
getListingsByShopReceipt
getShopShippingProfile
getShopShippingProfileDestinationsByShippingProfile
getShopShippingProfiles
getShopShippingProfileUpgrades
updateShopShippingProfile
updateShopShippingProfileUpgrade
updateShopShippingProfileDestination
updateListing
getListingsByShop
getListing
createDraftListing
createReceiptShipment
With this, all our endpoints for the general release are now in Beta!
3.0.0-alpha-2021-06-29
Changed
- Removed views field from Listings
createListing
is now namedcreateDraftListing
- Removed
state
,channels
, andtype
as inputs - Requires
shipping_profile_id
as input
- Removed
getReviewsByShop
no longer includesreceipt_id
ortransaction_id
.- Transaction endpoints no longer include the
title
ordescription
in the JSON output updateListing
now accepts onlyactive
andinactive
values for thestate
param. This value now will affect the state of the listing, either activating and publishing if expired or draft or deactivating if active.getShippingCarriers
is a public endpoint nowupdateListingShippingProfileDestination
anddeleteListingShippingProfileDestination
endpoints now haveshipping_profile_id
in them
Route updates
getListingImage
- O : GET /v3/application//shop/{shop_id}/listings/{listing_id}/images/{listing_image_id}
- N : GET /v3/application/shops/{shop_id}/listings/{listing_id}/images/{listing_image_id}
getShopReceiptTransactionsByShop
- O : GET /v3/application/transactions
- N : GET /v3/application/shops/{shop_id}/transactions
getShopReceiptTransaction
- O : GET /v3/application/transactions/{transaction_id}
- N : GET /v3/application/shops/{shop_id}/transactions/{transaction_id}
deleteListingFile
- O : DELETE /v3/application/listings/{listing_id}/files/{listing_file_id}
- N : DELETE /v3/application/shops/{shop_id}/listings/{listing_id}/files/{listing_file_id}
deleteListingShippingProfileDestination
- O : DELETE /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations/{shipping_profile_destination_id}
- N : DELETE /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/destinations/{shipping_profile_destination_id}
updateListingShippingProfileDestination
- O : PUT /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations/{shipping_profile_destination_id}
N: PUT /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/destinations/{shipping_profile_destination_id}
- O : PUT /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations/{shipping_profile_destination_id}
The following endpoints are now Beta endpoints
updateListingTranslation
createListingTranslation
getListingTranslation
findShops
updateShop
uploadListingFile
createShopSection
getUserAddresses
getShopByOwnerUserId
getShop
deleteListing
getShopSections
getUser
ping
Alpha release: 3.0.0-alpha-2021-06-14
We no longer require active Etsy developers to request access to Open API v3 endpoints. Your existing API keys will work with all of the new endpoints.
Added
uploadListingFile
is now an Alpha endpoint- The following endpoints had 404 added as possible response values:
getListingShippingProfileDestinationsByShippingProfile
getListingProperties
updateListingShippingProfileUpgrade
getListingShippingProfileUpgrades
- bio, gender, birth_month, birth_day, transaction_buy_count, transaction_sold_count, is_seller, first_name and last_name fields to
getUser
endpoint getListingsByListingIDs
endpoint in Alpha stateupdateListingAttributes
is now an Alpha endpoint
Changed
- Reference documentation has moved to https://developers.etsy.com/documentation/reference. Later this week, the old URL will redirect to the new one.
updateListing
no longer allows listing renewal when shop is on vacationfindShops
now returns an non-indexed array per the documentationgetListing
now returns 404 when a deleted listing is requestedgetListingProduct
now require oauth scope of listings_r instead of listings_w- “State” field in
getListings
endpoint is not required anymore. It defaults to “active”. getListingsByShopSectionId
now used request params for shop_section_ids instead of URL paramsgetShippingCarriers
no longer requires an oauth scope
Route updates
deleteListingFile
- O : DELETE /v3/application/listings/{listing_id}/files/{listing_file_id}
- N : DELETE /v3/application/shops/{shop_id}/listings/{listing_id}/files/{listing_file_id}
getListingFile
- O : GET /v3/application/listings/{listing_id}/files/{listing_file_id}
- N : GET /v3/application/shops/{shop_id}/listings/{listing_id}/files/{listing_file_id}
uploadListingFile
- O : POST /v3/application/listings/{listing_id}/files
- N : POST /v3/application/shops/{shop_id}/listings/{listing_id}/files
getShopReceiptTransactionsByShop
- O : POST /v3/application/transactions
- N : POST /v3/application/shops/{shop_id}/transactions
getShopReceiptTransaction
- O : GET /v3/application/transactions/{transaction_id}
- N : GET /v3/application/shops/{shop_id}/transactions/{transaction_id}
getListingImage
- O : GET /v3/application/shop/{shop_id}/listings/{listing_id}/images/{listing_image_id}
- N : GET /v3/application/shops/{shop_id}/listings/{listing_id}/images/{listing_image_id}
getAllListingFiles
- O : /v3/application/listings/{listing_id}/files
- N : /v3/application/shops/{shop_id}/listings/{listing_id}/files
getListingsByShopSectionId
- O : /v3/application/shops/{shop_id}/sections/:shop_section_ids/listings
- N : /v3/application/shops/{shop_id}/shop-sections/listings
Alpha release: 3.0.0-alpha-2021-06-01
Added
- We launched our new site for Open API v3 developer documentation. It can be found at https://developers.etsy.com/documentation.
Changed
- All users can now edit their OAuth2 callback URLs. They are available at https://www.etsy.com/developers/your-apps.
- getShop - added four new fields: review_count, review_average, shipping_from_country_iso, and shop_location_country_iso
- createListingTranslation is now an Alpha endpoint
- getListingTranslation is now an Alpha endpoint
- updateListingTranslation is now an Alpha endpoint
- getListingsByShopSectionId is now an Alpha endpoint
- getShopReceiptTransactionsByListing is now an Alpha endpoint
- all delete methods return empty response body and 204 HTTP status code
Removed
- Removed order_id from the ShopReceipt response (the value is no longer updated or used)
Alpha release: 3.0.0-alpha-2021-05-18
Changed
New fields in endpoints
- createListingShippingProfile - added new fields to schema:
origin_postal_code
,shipping_carrier_id
,mail_class
,min_delivery_time
,max_delivery_time
- updateListingShippingProfile - added new fields to schema:
origin_postal_code
,shipping_carrier_id
,mail_class
,min_delivery_time
,max_delivery_time
- createListingShippingProfileDestination - added new fields to schema:
shipping_carrier_id
,mail_class
,min_delivery_time
,max_delivery_time
- updateListingShippingProfileDestination - added new fields to schema:
destination_region
,shipping_carrier_id
,mail_class
,min_delivery_time
,max_delivery_time
- createListingShippingProfileUpgrade - the field “label” has been renamed to
upgrade_name
- getShop - added new field to schema:
transaction_sold_count
Route Updates
- createListingShippingProfileDestination
O: POST /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations
N: POST /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/destinations - getListingShippingProfileUpgrades
O: GET /v3/application/listings/shipping-profiles/upgrades
N: GET /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/upgrades - createListingShippingProfileUpgrade
O: POST /v3/application/listings/shipping-profiles/{shipping_profile_id}/upgrades
N: POST /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/upgrades - updateListingShippingProfileUpgrade
O: PUT /v3/application/listings/shipping-profiles/{shipping_profile_id}/upgrades/{label_id}
N: PUT /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/upgrades/{upgrade_id} - createListingTranslation
O: POST /v3/application/listings/{listing_id}/translations/{language}
N: POST /v3/application/shops/{shop_id}/listings/{listing_id}/translations/{language} - getListingTranslation
O: GET /v3/application/listings/{listing_id}/translations/{language}
N: GET /v3/application/shops/{shop_id}/listings/{listing_id}/translations/{language} - updateListingTranslation
O: PUT /v3/application/listings/{listing_id}/translations/{language}
N: PUT /v3/application/shops/{shop_id}/listings/{listing_id}/translations/{language}
Endpoints now in Alpha
- deleteListingProperty is now an Alpha endpoint
- updateListingShippingProfileUpgrade is now an alpha endpoint
- getListingShippingProfileUpgrades is now an alpha endpoint
- deleteShippingProfileUpgrade is now an alpha endpoint
- getReviewsbyShop is now an Alpha endpoint
- getListingProperties is now an Alpha endpoint
Alpha release: 3.0.0-alpha-2021-05-04
Added
- getShippingCarriers as an alpha endpoint
- getShop, updateShop, getShopByOwnerUserId and findShops now return the "transaction_sold_count" field
- Shipping Profiles endpoints return “is_deleted” to indicate whether the profile is active or not
Changed
- createShopSection is now an Alpha endpoint
- createListingShippingProfileUpgrade is now an Alpha endpoint
- getListingsByShopReceipt is now an Alpha endpoint
- Route Updates:
- createListing
- O: POST /v3/application/listings
- N: POST /v3/application/shops/{shop_id}/listings
- updateListing
- O: PUT /v3/application/listings/{listing_id}
- N: PUT /v3/application/shops/{shop_id}/listings/{listing_id}
- getListingProduct
- O: GET /v3/application/listings/{listing_id}/products/{product_id}
- N: GET /v3/application/listings/{listing_id}/inventory/products/{product_id}
- getListingImages
- O: GET /v3/application/listings/{listing_id}/images
- N: GET /v3/application/shops/{shop_id}/listings/{listing_id}/images
- deleteListingImage
- O: DELETE /v3/application/listings/{listing_id}/images/{listing_image_id}
- N: DELETE /v3/application/shops/{shop_id}/listings/{listing_id}/images/{listing_image_id}
- uploadListingImage
- O: POST /v3/application/listings/{listing_id}/images
- N: POST /v3/application/shops/{shop_id}/listings/{listing_id}/images
- updateVariationImages
- O: POST /v3/application/listings/{listing_id}/variation-images
- N: POST /v3/application/shops/{shop_id}/listings/{listing_id}/variation-images
- getListingVariationImages
- O: GET /v3/application/listings/{listing_id}/variation-images
- N: GET /v3/application/shops/{shop_id}/listings/{listing_id}/variation-images
- createListingShippingProfile
- O: POST /v3/application/listings/shipping-profiles
- N: POST /v3/application/shops/{shop_id}/listings/shipping-profiles
- getListingShippingProfiles
- O: GET /v3/application/shipping-profiles
- N: GET /v3/application/shops/{shop_id}/listings/shipping-profiles
- getListingShippingProfile
- O: GET /v3/application/listings/shipping-profiles/{shipping_profile_id}
- N: GET /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}
- createListingShippingProfileDestination
- O: POST /v3/application/listings/shipping-profiles/destinations
- N: POST /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations
- getListingShippingProfileDestinationsByShippingProfile
- O: GET /v3/application/listings/shipping-profiles/{shipping_profile_id}/destinations
- N: GET /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/destinations
- createListingShippingProfile
- O: POST /v3/application/listings/shipping-profiles
- N: POST /v3/application/shops/{shop_id}/listings/shipping-profiles
- getListingShippingProfiles
- O: GET /v3/application/shipping-profiles
- N: GET /v3/application/shops/{shop_id}/listings/shipping-profiles
- deleteListingShippingProfiles
- O: DELETE /v3/application/listings/shipping-profiles/{shipping_profile_id}
- N: DELETE /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}
- getListingShippingProfile
- O: GET /v3/application/listings/shipping-profiles/{shipping_profile_id}
- N: GET /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}
- updateListingShippingProfile
- O: PUT /v3/application/listings/shipping-profiles/{shipping_profile_id}
- N: PUT /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}
- createListingShippingProfileDestination
- O: POST /v3/application/listings/shipping-profiles/destinations
- N: POST /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations
- deleteListingShippingProfileDestination
- O: DELETE /v3/application/listings/shipping-profiles/destinations/{shipping_profile_destination_id}
- N: DELETE /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations/{shipping_profile_destination_id}
- updateListingShippingProfileDestination
- O: PUT /v3/application/listings/shipping-profiles/destinations/{shipping_profile_destination_id}
- N: PUT /v3/application/shops/{shop_id}/listings/shipping-profiles/destinations/{shipping_profile_destination_id}
- getListingShippingProfileDestinationsByShippingProfile
- O: GET /v3/application/listings/shipping-profiles/{shipping_profile_id}/destinations
- N: GET /v3/application/shops/{shop_id}/listings/shipping-profiles/{shipping_profile_id}/destinations
- getPaymentAccountLedgerEntryPayments
- O: GET /v3/application/payment-account/ledger-entries/payments
- N: GET /v3/application/shop/{shop_id}/payment-account/ledger-entries/payments
- getShopPaymentAccountLedgerEntries
- O: GET /v3/application/payment-account/ledger-entries
- N: GET /v3/application/shop/{shop_id}/payment-account/ledger-entries
- getShopPaymentByReceiptId
- O: GET /v3/application/receipts/{receipt_id}/payments
- N: GET /v3/application/shops/{shop_id}/receipts/{receipt_id}/payments
- getPayments
- O: GET /v3/application/payments
- N: GET /v3/application/shop/{shop_id}/payments
- getShopReceipt
- O: GET /v3/application/receipts/{receipt_id}
- N: GET /v3/application/shops/{shop_id}/receipts/{receipt_id}
- getShopReceipts
- O: GET /v3/application/receipts
- N: GET /v3/application/shops/{shop_id}/receipts
- createReceiptShipment
- O: POST /v3/application/receipts/{receipt_id}/tracking
- N: POST /v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking
- getShopReceiptTransactionsByReceipt
- O: GET /v3/application/receipts/{receipt_id}/transactions
- N: GET /v3/application/shops/{shop_id}/receipts/{receipt_id}/transactions
- createListing
Removed
- Removed getPublicUserFeedback
- Removed getShopUserFeedback
- Removed getMemberUserFeedback
- Removed any feedback related fields from all endpoints
Alpha release: 3.0.0-alpha-2021-04-22
Added
- updateListingShippingProfileUpgrade feedback-only endpoint
- getListingsByShopReceipt feedback-only endpoint
- getShippingCarriers alpha endpoint
Changed
- deleteListing is now an alpha endpoint
- getSellerTaxonomyNodes is now an alpha endpoint (replaces getSellerTaxonomy in V2)
- getUserAddresses is now an alpha endpoint (replaces findAllUserAddresses in V2)
- deleteListingShippingProfile is now an alpha endpoint (replaces deleteShippingTemplate in V2)
- updateShop is now an alpha endpoint
- createListingShippingProfileUpgrade is now an alpha endpoint
- createListingShippingProfileDestinations now returns all created records when a region is passed
- shipping_profile_entry_id -> shipping_profile_destination_id in a few remaining places
- updated documentation for getShopReceipts
Alpha release: 3.0.0-alpha-2021-04-05
Changed
createListingShippingProfileDestination
is now an alpha endpoint (replaces createShippingTemplateEntry in V2).updateListing
is now an alpha endpoint (replaces updateListing in V2). Here’s a list of fields that were added, removed or changed:is_renew
is now calledshould_auto_renew
- We added a
publish
field - We deleted the following fields:
processing_min
(update via updateShippingProfile),processing_max
(update via updateShippingProfile),image_ids
(update via uploadListingImage),sku
(update via updateInventory) andis_customizable
(field no longer supported)
getListingShippingProfileDestinationsByShippingProfile
is now an alpha endpoint.findAllListingActive
is now an alpha endpoint (replaces findAllListingActive in V2)getShops
is now an alpha endpoint (replaces findAllShops in V2)updateListingShippingProfile
is now an alpha endpoint (replaces updateShippingTemplate in V2)
Alpha release: 3.0.0-alpha-2021-03-22
Added
- Ping endpoint to be able to check connectivity of your app
Changed
- findAllActiveListingsByShop is now an alpha endpoint (replaces the keyword search functionality of findAllShopListingsActive in V2)
- getFeaturedListingsByShop is now an alpha endpoint (findAllShopListingsFeatured in V2)
- updateInventory is now an alpha endpoints (updateInventory in V2)
- getPublicUserFeedback no longer requires oauth