Looking for clarification on multiple response fields in pagination API endpoints


I was hoping to get some clarification on how pagination works with multiple response fields. Specifically I’m looking at catalog/search (search catalog objects) and catalog/search-catalog-items. Both endpoints return multiple items in the response json.

  • search-catalog-items returns two lists, items and matched_variation_ids. Are both fields paginated? Can I expect (given enough search results) both fields to contain different items in subsequent queries? Or is only one of them paginated?
  • Similarly, search returns two lists, objects and related_objects. If (depending on your answer above) both fields are paginated, does related_objects only return objects relating to objects found in that specific response page? Or is it possible that the related_objects field will span across page boundaries (referencing objects on a previous or future response page?)


Hi @DaytonSwingSmackdown welcome to the forums!

I checked with our Catalog team to ensure I had the right info, and here’s what we got:

matched_variation_ids will be a subset of the variations on the items in the response. For example, if you are searching for “Large”, and the Soda item has variation small, medium, and large, you will get back the full item with all three variations, but only the token for the “Large” variation will be present in the matched_variation_ids . That would never contain ids of objects that are not present in the the items list. The pagination is just about the items in the items field.

For search, if you set include_related_objects to true, you will get related objects in the related_objects field. For example, if you were fetching an item, the category of that item and the taxes for that item will be in related_objects , basically any objects we consider necessary to properly display the item in Dashboard. The objects field is what is paginated. All objects related to those objects will be always present in related_objects and you will get duplicates across pages. If for example one item in the first page of objects is in the category Food, and an item in the second page of objects is in the category Food, then you will get the category Food in both responses.

Awesome I really appreciate you taking the time to look all of that up for me. Thanks for the information!