> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ordergroove.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server.

# orders

The `orders` query returns [`OrderConnection`](/graphql/graphql-definitions/objects/order-connection).

## Arguments

| Argument               | Type      | Required | Description                                                                                                                                                                                                                                                    |
| ---------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `after`                | `String`  | No       | Cursor to paginate forward from.                                                                                                                                                                                                                               |
| `before`               | `String`  | No       | Cursor to paginate backward from.                                                                                                                                                                                                                              |
| `customer`             | `String`  | No       | Filter by customer ID.                                                                                                                                                                                                                                         |
| `first`                | `Int`     | No       | Return the first N results.                                                                                                                                                                                                                                    |
| `inStock`              | `Boolean` | No       | Filter by item stock: true returns orders where every item's resolved product is live; false returns orders with at least one out-of-stock item; omit for no filter. Resolution follows item.product → subscription\_component.product → subscription.product. |
| `includePrepaidOrders` | `Boolean` | No       | Include prepaid orders in results. Defaults to true.                                                                                                                                                                                                           |
| `last`                 | `Int`     | No       | Return the last N results.                                                                                                                                                                                                                                     |
| `place`                | `Date`    | No       | Filter by exact placement date (YYYY-MM-DD).                                                                                                                                                                                                                   |
| `placeEnd`             | `Date`    | No       | Filter orders placed on or before this date (YYYY-MM-DD).                                                                                                                                                                                                      |
| `placeStart`           | `Date`    | No       | Filter orders placed on or after this date (YYYY-MM-DD).                                                                                                                                                                                                       |
| `status`               | `[Int!]`  | No       | Filter by order status codes.                                                                                                                                                                                                                                  |
| `subscription`         | `String`  | No       | Filter by subscription public ID.                                                                                                                                                                                                                              |

## Return type: `OrderConnection`

| Field      | Type                                                               | Required |
| ---------- | ------------------------------------------------------------------ | -------- |
| `edges`    | [`[OrderEdge!]!`](/graphql/graphql-definitions/objects/order-edge) | Yes      |
| `pageInfo` | `PageInfo!`                                                        | Yes      |

## Examples

### List recent orders for a customer

Retrieve a customer's order history with basic info

```graphql title="GraphQL"
query {
  orders(customer: "cust123", first: 10) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        created
        items {
          nodes {
            quantity
            product {
              name
              externalProductId
            }
          }
        }
      }
    }
  }
}
```

```bash title="cURL"
curl -X POST https://restapi.ordergroove.com/graphql/2026-01/ \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { orders(customer: \"cust123\", first: 10) { edges { node { publicId status subTotal total place created items { nodes { quantity product { name externalProductId } } } } } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  orders(customer: "cust123", first: 10) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        created
        items {
          nodes {
            quantity
            product {
              name
              externalProductId
            }
          }
        }
      }
    }
  }
}
`;

const response = await fetch(
  "https://restapi.ordergroove.com/graphql/2026-01/",
  {
    method: "POST",
    headers: {
      "X-API-KEY": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query }),
  }
);

const data = await response.json();
```

```python title="Python"
import requests

query = """
query {
  orders(customer: "cust123", first: 10) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        created
        items {
          nodes {
            quantity
            product {
              name
              externalProductId
            }
          }
        }
      }
    }
  }
}
"""

response = requests.post(
    "https://restapi.ordergroove.com/graphql/2026-01/",
    headers={
        "X-API-KEY": "<your-api-key>",
        "Content-Type": "application/json",
    },
    json={"query": query},
)

data = response.json()
```

### List orders with pagination

Page through a customer's orders using cursor-based pagination

```graphql title="GraphQL"
query {
  orders(customer: "cust123", first: 10, after: "cursor123") {
    edges {
      cursor
      node {
        publicId
        status
        subTotal
        total
        place
        created
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}
```

```bash title="cURL"
curl -X POST https://restapi.ordergroove.com/graphql/2026-01/ \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { orders(customer: \"cust123\", first: 10, after: \"cursor123\") { edges { cursor node { publicId status subTotal total place created } } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  orders(customer: "cust123", first: 10, after: "cursor123") {
    edges {
      cursor
      node {
        publicId
        status
        subTotal
        total
        place
        created
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}
`;

const response = await fetch(
  "https://restapi.ordergroove.com/graphql/2026-01/",
  {
    method: "POST",
    headers: {
      "X-API-KEY": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query }),
  }
);

const data = await response.json();
```

```python title="Python"
import requests

query = """
query {
  orders(customer: "cust123", first: 10, after: "cursor123") {
    edges {
      cursor
      node {
        publicId
        status
        subTotal
        total
        place
        created
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}
"""

response = requests.post(
    "https://restapi.ordergroove.com/graphql/2026-01/",
    headers={
        "X-API-KEY": "<your-api-key>",
        "Content-Type": "application/json",
    },
    json={"query": query},
)

data = response.json()
```

### Get subscription details by customer

Detailed orders by customer

```graphql title="GraphQL"
query {
  orders(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        items {
          nodes {
            publicId
            quantity
            price
            totalPrice
            product {
              name
              externalProductId
              sku
            }
            subscription {
              publicId
              every
              everyPeriod
            }
          }
        }
      }
    }
  }
}
```

```bash title="cURL"
curl -X POST https://restapi.ordergroove.com/graphql/2026-01/ \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { orders(customer: \"cust123\", first: 25) { edges { node { publicId status subTotal total place items { nodes { publicId quantity price totalPrice product { name externalProductId sku } subscription { publicId every everyPeriod } } } } } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  orders(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        items {
          nodes {
            publicId
            quantity
            price
            totalPrice
            product {
              name
              externalProductId
              sku
            }
            subscription {
              publicId
              every
              everyPeriod
            }
          }
        }
      }
    }
  }
}
`;

const response = await fetch(
  "https://restapi.ordergroove.com/graphql/2026-01/",
  {
    method: "POST",
    headers: {
      "X-API-KEY": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query }),
  }
);

const data = await response.json();
```

```python title="Python"
import requests

query = """
query {
  orders(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        items {
          nodes {
            publicId
            quantity
            price
            totalPrice
            product {
              name
              externalProductId
              sku
            }
            subscription {
              publicId
              every
              everyPeriod
            }
          }
        }
      }
    }
  }
}
"""

response = requests.post(
    "https://restapi.ordergroove.com/graphql/2026-01/",
    headers={
        "X-API-KEY": "<your-api-key>",
        "Content-Type": "application/json",
    },
    json={"query": query},
)

data = response.json()
```

### Get subscription details by subscription

Retrieve orders for a specific subscription with line item details

```graphql title="GraphQL"
query {
  orders(subscription: "sub123", first: 25) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        created
        items {
          nodes {
            publicId
            quantity
            price
            totalPrice
            product {
              name
              externalProductId
              sku
            }
            subscription {
              publicId
              every
              everyPeriod
            }
          }
        }
      }
    }
  }
}
```

```bash title="cURL"
curl -X POST https://restapi.ordergroove.com/graphql/2026-01/ \
  -H "X-API-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { orders(subscription: \"sub123\", first: 25) { edges { node { publicId status subTotal total place created items { nodes { publicId quantity price totalPrice product { name externalProductId sku } subscription { publicId every everyPeriod } } } } } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  orders(subscription: "sub123", first: 25) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        created
        items {
          nodes {
            publicId
            quantity
            price
            totalPrice
            product {
              name
              externalProductId
              sku
            }
            subscription {
              publicId
              every
              everyPeriod
            }
          }
        }
      }
    }
  }
}
`;

const response = await fetch(
  "https://restapi.ordergroove.com/graphql/2026-01/",
  {
    method: "POST",
    headers: {
      "X-API-KEY": "<your-api-key>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query }),
  }
);

const data = await response.json();
```

```python title="Python"
import requests

query = """
query {
  orders(subscription: "sub123", first: 25) {
    edges {
      node {
        publicId
        status
        subTotal
        total
        place
        created
        items {
          nodes {
            publicId
            quantity
            price
            totalPrice
            product {
              name
              externalProductId
              sku
            }
            subscription {
              publicId
              every
              everyPeriod
            }
          }
        }
      }
    }
  }
}
"""

response = requests.post(
    "https://restapi.ordergroove.com/graphql/2026-01/",
    headers={
        "X-API-KEY": "<your-api-key>",
        "Content-Type": "application/json",
    },
    json={"query": query},
)

data = response.json()
```