> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: "cartsByQuery"
description: "Returns a paginated list of `Cart` objects matching the provided filter criteria."
---

Returned carts are sorted by `createdAt` in descending order (newest first).\
The maximum page size is **10**.\
This query requires API key authentication

***

### Arguments

<ParamField path="filter" type={<a href="/api-reference/cartsFilterInput">CartsFilterInput</a>}>
  Filter parameters to narrow down the search results based on cart creation datetime.
</ParamField>

<ParamField path="pagination" type={<a href="/api-reference/cursorPaginationInput">CursorPaginationInput</a>}>
  Pagination parameters to control the fetching of data, such as specifying the number of items before or after a cursor.
</ParamField>

### Returns

<ParamField path="CartsConnection" type={<a href="/api-reference/cartsConnection">CartsConnection</a>}>
  Returns a `CartsConnection` object containing the carts that satisfy the criteria together with pagination details.
</ParamField>

***

### Example - request

```json
{
  "filter": {
    "createdBefore" : "2025-06-20T21:24:00.000Z",
    "createdAfter" : "2025-05-10T21:24:00.000Z"
  },
  "pagination": {
    "first": 2
  }
}
```

### Example - query

```GraphQL GraphQL
query CartsByQuery($pagination: CursorPaginationInput!, $filter: CartsFilterInput!) {
  cartsByQuery(pagination: $pagination, filter: $filter) {
    edges {
        cursor
        node {
            cart {
                id
                createdAt
                buyerIdentity {
                    firstName
                }
                stores {
                    ... on AmazonStore {
                        isSubmitted
                    }
                }
            }
        }
    },
    pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
    }
  }
}
```

### Example - response

```json
{
    "data": {
        "cartsByQuery": {
            "edges": [
                {
                    "cursor": "1hbiiW6YWUioHklegdRq",
                    "node": {
                        "cart": {
                            "id": "1hbiiW6YWUioHklegdRq",
                            "createdAt": "2025-06-26T20:18:52.671Z",
                            "buyerIdentity": {
                                "firstName": "Eric"
                            },
                            "stores": [
                                {
                                    "isSubmitted": false
                                }
                            ]
                        }
                    }
                }
            ],
            "pageInfo": {
                "hasNextPage": false,
                "hasPreviousPage": true,
                "startCursor": "1hbiiW6YWUioHklegdRq",
                "endCursor": "1hbiiW6YWUioHklegdRq"
            }
        }
    },
    "extensions": {
        "cost": {
            "queryCost": 16,
            "queryCostLimit": 750
        }
    }
}
```

***

### Related queries

* [`getCart(id: ID!)`](/api-reference/getcart)


---

*Powered by [holocron.so](https://holocron.so)*