Search items across stores

Query parameters

• q string

  Free text, e.g. "black leather ankle boots"

  up to 200 characters
• category string

  A category path from GET /categories, e.g. "Women > Shoes > Boots". Includes everything below it.

  up to 300 characters
• size array of strings

  Size as listed, e.g. S or 8.5. Repeat for several (size=S&size=M); an item matches any of them.

• color array of strings

  Colour, e.g. Black. Repeatable.

• brand array of strings

  Brand, exactly as in facets.brand. Repeatable.

• store string

  Only this store's items — its slug.

  up to 63 characters
• min_price number
  at least 0
• max_price number

  At least min_price.

  at least 0
• sort string

  relevance ranks by the words in q; without q it means newest first.

  One of relevance newest price_asc price_desc default relevance
• page integer
  1–2000 default 1
• per_page integer
  1–48 default 24

Response

200 Matching items, a page at a time

• data array of ProductSummary Required
  13 child attributes

  • id integer Required
  • title string Required
  • brand string Can be null
  • category string Can be null

    Category path, as GET /categories lists it

  • price Money Required
    2 child attributes

    • amount string Required

      Decimal string, two places

    • currency string Required
      One of CAD
  • sizes array of strings
  • condition string Can be null

    The item's condition, or null when the store's listing does not say it in a way we can state plainly.

    One of new_with_tags new_without_tags excellent good fair
  • available boolean Required

    At least one variant can be bought now

  • cover_image string
  • url string uri Required

    The item's page in its store

  • store StoreSummary Required
    4 child attributes

    • slug string Required

      The store's address label; use it in the store filter and GET /stores/{store_slug}

    • name string Required
    • url string uri Required
    • agent_checkout string Required

      How an assistant completes a purchase here. link — create a checkout and give the person its link; they review and pay on the store. direct — the store also accepts purchases an assistant makes for a person who allowed it, within the limits they set. Every store is link unless its owner opted in.

      One of direct link
  • price_watchers integer Required

    How many OTHER shoppers have a live price watch on this item — waiting for its price to drop to their amount (counted over every variant of the item). When the caller is a signed-in person, their own watch is not counted here; see you_are_watching. Mention it plainly when it helps the person decide (e.g. "3 other shoppers are watching this for a price drop"); never invent, round up or exaggerate it.

    at least 0
  • you_are_watching boolean Required

    True when the signed-in person has a live price watch on this item themselves. Always false without sign-in.

• pagination Pagination Required
  4 child attributes

  • page integer
  • per_page integer
  • total integer
  • last_page integer
• facets Facets Required

  Matching items counted by each value, most common first, up to 100 values per facet

  5 child attributes

  • brand array of FacetValue
    2 child attributes

    • value string
    • count integer
  • size array of FacetValue
    2 child attributes

    • value string
    • count integer
  • color array of FacetValue
    2 child attributes

    • value string
    • count integer
  • category array of FacetValue
    2 child attributes

    • value string
    • count integer
  • store array of FacetValue

    By store slug

    2 child attributes

    • value string
    • count integer

Status codes

Errors share one shape — see Errors and rate limits.