Inventory and Shipping Data Migration Tutorial

The Inventory and Shipping values for the includes parameter have been removed from the following endpoints:

  • GET /v3/application/listings/{listing_id} (getListing)
  • GET /v3/application/listings/batch (getListingsByListingIds)

If your integration passes includes=Inventory or includes=Shipping on either of these endpoints, follow the steps below to migrate.

What changed#

Two includes values have been removed and replaced with dedicated endpoints, each with its own required OAuth scope:

Was usingMigrate toRequired scope
?includes=InventorygetListingsInventoryByListingIdslistings_r
?includes=ShippinggetListingsShippingByListingIdsshops_r

Read on for step-by-step migration instructions for each.

Migrating from ?includes=Inventory#

Use the dedicated batch inventory endpoint instead:

GET /v3/application/listings/batch/inventory?listing_ids={listing_ids}

Changes required:

  • Replace calls to getListing or getListingsByListingIds with getListingsInventoryByListingIds.
  • Ensure your app requests the listings_r OAuth scope.
  • Re-authorize any users who have not already granted listings_r.

Limits: Up to 100 listing IDs per request.

Before:

GET /v3/application/listings/batch?listing_ids=123,456&includes=Inventory

After:

GET /v3/application/listings/batch/inventory?listing_ids=123,456

The response includes a populated inventory field on each listing result, containing products, price_on_property, quantity_on_property, and sku_on_property.

Note: inventory is null for listings that were not created or edited using Etsy’s inventory tools.

Migrating from ?includes=Shipping#

Use the dedicated batch shipping endpoint instead:

GET /v3/application/listings/batch/shipping?listing_ids={listing_ids}

Changes required:

  • Replace calls to getListing or getListingsByListingIds with getListingsShippingByListingIds.
  • Ensure your app requests the shops_r OAuth scope.
  • Re-authorize any users who have not already granted shops_r.

Limits: Up to 100 listing IDs per request.

Before:

GET /v3/application/listings/batch?listing_ids=123,456&includes=Shipping

After:

GET /v3/application/listings/batch/shipping?listing_ids=123,456

The response includes a populated shipping_profile field on each listing result, containing origin_country_iso, origin_postal_code, shipping_profile_destinations, shipping_profile_upgrades, and profile_type.

Note: shipping_profile is null for digital listings, which do not have shipping information.

Quick Reference#

Previous usageNew endpointRequired scope
?includes=InventorygetListingsInventoryByListingIdslistings_r
?includes=ShippinggetListingsShippingByListingIdsshops_r

Not affected#

  • Creating or updating listings is unchanged.
  • All other includes values (Images, Shop, User, Translations, Videos, Personalization, BuyerPrice) continue to work as before on getListing and getListingsByListingIds.
  • Apps that do not use ?includes=Inventory or ?includes=Shipping require no changes.