Skip to main content

List Etsy Listings

GET 
/api/etsy/instances/:integrationInstance/listings

Lists Etsy listings for this instance — one row per variation (a listing without variations has one row). Each row includes its parent listing (state, push status, images) and the SKU.io product, subscription offering, or revenue line it is mapped to. Archived rows are excluded.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Pagination: page, per_page (default 10).

Search: filter[search] matches ID, SKU, title, variation, Etsy listing ID, and external ID.

Text filters — filter[<field>] or filter[<field>.<operator>] with operators: contains, does_not_contain, is, is_not, is_one_of, is_not_one_of, starts_with, does_not_start_with, ends_with, does_not_end_with, is_empty, is_not_empty. Fields: sku, title, listing_id.

Numeric filters — filter[<field>] or filter[<field>.<operator>] with operators: is, is_not, is_one_of, is_not_one_of, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between, is_empty, is_not_empty. Fields: price, quantity.

Listing filters (each also accepts a .is suffix):

  • filter[state] — Listing state, comma-separated: active, inactive, sold_out, draft, removed, expired.
  • filter[mapped] — true/false: mapped to SKU.io.
  • filter[push_error] — true/false: the last inventory push failed or the listing uses shared quantity (which SKU.io cannot push).
  • filter[sync_enabled] — true/false: inventory push enabled for the listing.
  • filter[quantity_shared] — true/false: variations share one quantity on Etsy.
  • filter[personalizable] — true/false.
  • filter[has_variations] — true/false.

Sort: sort — prefix with - for descending. Allowed: id, sku, title, listing_id, price, quantity, created_at, updated_at. Default: -id.

Push status values (listing.push_status): ok, error, unsupported_shared_quantity, excluded.

Grouped filters: instead of filter[...] params you can send filter_groups — a base64-encoded JSON tree such as {"conjunction":"and","children":[{"type":"condition","condition":{"column":"status","operator":"is","value":"paid"}}]}. Each condition's column + operator must be one of the filters listed above.

Authentication: Bearer token (Personal Access Token).

Request​

Responses​

OK

Response Headers
    Content-Type