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
  • getListing
  • getListingByListingIds
    • New “includes” input parameter accepts comma delimited list of the following associations:
      • Shop
      • Images
      • User
• getListingsByShop
  • Added updated as a valid sort_on parameter
• 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 of shipping_template_id
• updateListing now accepts is_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
• deleteListingShippingProfile
  • New Name: deleteShopShippingProfile
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id
• getListingShippingProfile
  • New Name: getShopShippingProfile
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id
• getListingShippingProfiles
  • New Name: getShopShippingProfiles
  • New Route: /shops/:shop_id/shipping-profiles
• updateListingShippingProfile
  • New Name: updateShopShippingProfile
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id

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
• deleteListingShippingProfileDestination
  • New Name: deleteShopShippingProfileDestination
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id/destinations/:shipping_profile_destination_id
• getListingShippingProfileDestinationsByShippingProfile
  • New Name: getShopShippingProfileDestinationsByShippingProfile
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id/destinations
• updateListingShippingProfileDestination
  • New Name: updateShopShippingProfileDestination
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id/destinations/:shipping_profile_destination_id

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
• deleteListingShippingProfileUpgrade
  • New Name: deleteShopShippingProfileUpgrade
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id/upgrades/:upgrade_id
• getListingShippingProfileUpgrades
  • New Name: getShopShippingProfileUpgrades
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id/upgrades
• updateListingShippingProfileUpgrade
  • New Name: updateShopShippingProfileUpgrade
  • New Route: /shops/:shop_id/shipping-profiles/:shipping_profile_id/upgrades/:upgrade_id

Shipping Carriers have been moved from the Listings perspective to the Shop perspective.

• getShippingCarriers
  • New Route: /shipping-carriers

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 named createDraftListing
  • Removed state, channels, and type as inputs
  • Requires shipping_profile_id as input
• getReviewsByShop no longer includes receipt_id or transaction_id.
• Transaction endpoints no longer include the title or description in the JSON output
• updateListing now accepts only active and inactive values for the state 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 now
• updateListingShippingProfileDestination and deleteListingShippingProfileDestination endpoints now have shipping_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}

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 state
• updateListingAttributes 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 vacation
• findShops now returns an non-indexed array per the documentation
• getListing now returns 404 when a deleted listing is requested
• getListingProduct 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 params
• getShippingCarriers 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

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 called should_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) and is_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

Alpha release: 3.0.0-alpha-2021-03-05

We’re so excited to share our first incremental release for Etsy’s Open API v3 schema! Below you’ll find a changelog calling out the updates we’ve made to our endpoints and reference documentation since our initial release. Going forward you can expect to see regular releases like this one approximately every two weeks during the alpha period.

We hope these release notes help you understand what we’re working on and plan your migration to v3. If you have any feedback or suggestions on this release or anything else, we’d love to hear about it!

Added

• getListingProperty feedback-only endpoint (getAttribute in V2)
• getUserAddress feedback-only endpoint (getUserAddress in V2)
• getSellerTaxonomy feedback-only endpoint
• findAllShopListingsActive feedback-only endpoint (search functionality associated with findAllShopListingsActive in V2)
• getPropertiesByTaxonomyId alpha endpoint (getTaxonomyNodeProperties in V2)
• OAS description fields for each of our schema objects

Changed

• getShopReceiptTransactionsByShop is now an alpha endpoint (findAllShopTransactions in V2)
• createListingShippingProfile is now an alpha endpoint (createShippingTemplate in V2)
• getPayments is now an alpha endpoint (findPayment in V2)
• getUser now requires the email_r OAuth scope
• destination_region_id field is now destination_region across all endpoints and resources. The field is now a string enum of regions to which the listing ships. Currently supported regions enum values are "eu" (European Union countries) and "non_eu" (European countries not in the European Union)
• *_country_id fields are now *_country_iso fields across all endpoints and resources. The fields are now ISO 3166-1 alpha-2 country code strings.
• Renamed image_listing_id to listing_image_id on the ShopTransaction resource.

Removed

• Country schema object and related endpoints. Removing these endpoints in favor of using ISO 3166-1 alpha-2 country code strings across all of V3.