> 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.

# subscriptions

The `subscriptions` query returns [`SubscriptionConnection`](/graphql/graphql-definitions/objects/subscription-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.                                                                    |
| `last`         | `Int`     | No       | Return the last N results.                                                                     |
| `live`         | `Boolean` | No       | Filter by subscription status. Requires a customer scope (customer auth or customer argument). |
| `productGroup` | `String`  | No       | Filter subscriptions whose product belongs to a ProductGroup with this name.                   |

## Return type: `SubscriptionConnection`

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

## Examples

### List customer subscriptions

Retrieve all subscriptions for a customer with product info

```graphql title="GraphQL"
query {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        startDate
        product {
          name
          externalProductId
          sku
          imageUrl
        }
      }
    }
  }
}
```

```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 { subscriptions(customer: \"cust123\", first: 25) { edges { node { publicId every everyPeriod quantity price live startDate product { name externalProductId sku imageUrl } } } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        startDate
        product {
          name
          externalProductId
          sku
          imageUrl
        }
      }
    }
  }
}
`;

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 {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        startDate
        product {
          name
          externalProductId
          sku
          imageUrl
        }
      }
    }
  }
}
"""

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 subscriptions with pagination

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

```graphql title="GraphQL"
query {
  subscriptions(customer: "cust123", first: 10, after: "cursor123") {
    edges {
      cursor
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        startDate
      }
    }
    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 { subscriptions(customer: \"cust123\", first: 10, after: \"cursor123\") { edges { cursor node { publicId every everyPeriod quantity price live startDate } } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  subscriptions(customer: "cust123", first: 10, after: "cursor123") {
    edges {
      cursor
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        startDate
      }
    }
    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 {
  subscriptions(customer: "cust123", first: 10, after: "cursor123") {
    edges {
      cursor
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        startDate
      }
    }
    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()
```

### List subscriptions with delivery details

Subscriptions with shipping address and payment info

```graphql title="GraphQL"
query {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        cancelled
        shippingAddress {
          firstName
          lastName
          address
          city
          stateProvinceCode
          zipPostalCode
        }
        payment {
          ccType
          ccNumberEnding
          paymentMethod
        }
        product {
          name
          externalProductId
          sku
        }
      }
    }
  }
}
```

```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 { subscriptions(customer: \"cust123\", first: 25) { edges { node { publicId every everyPeriod quantity price live cancelled shippingAddress { firstName lastName address city stateProvinceCode zipPostalCode } payment { ccType ccNumberEnding paymentMethod } product { name externalProductId sku } } } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        cancelled
        shippingAddress {
          firstName
          lastName
          address
          city
          stateProvinceCode
          zipPostalCode
        }
        payment {
          ccType
          ccNumberEnding
          paymentMethod
        }
        product {
          name
          externalProductId
          sku
        }
      }
    }
  }
}
`;

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 {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        cancelled
        shippingAddress {
          firstName
          lastName
          address
          city
          stateProvinceCode
          zipPostalCode
        }
        payment {
          ccType
          ccNumberEnding
          paymentMethod
        }
        product {
          name
          externalProductId
          sku
        }
      }
    }
  }
}
"""

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 subscriptions with prepaid status

Subscriptions with prepaid context for tracking remaining orders

```graphql title="GraphQL"
query {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        product {
          name
          externalProductId
          sku
        }
        prepaidSubscriptionContext {
          prepaidOrdersRemaining
          prepaidOrdersPerBilling
          renewalBehavior
          lastRenewalRevenue
          prepaidOriginMerchantOrderId
        }
      }
    }
  }
}
```

```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 { subscriptions(customer: \"cust123\", first: 25) { edges { node { publicId every everyPeriod quantity price live product { name externalProductId sku } prepaidSubscriptionContext { prepaidOrdersRemaining prepaidOrdersPerBilling renewalBehavior lastRenewalRevenue prepaidOriginMerchantOrderId } } } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        product {
          name
          externalProductId
          sku
        }
        prepaidSubscriptionContext {
          prepaidOrdersRemaining
          prepaidOrdersPerBilling
          renewalBehavior
          lastRenewalRevenue
          prepaidOriginMerchantOrderId
        }
      }
    }
  }
}
`;

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 {
  subscriptions(customer: "cust123", first: 25) {
    edges {
      node {
        publicId
        every
        everyPeriod
        quantity
        price
        live
        product {
          name
          externalProductId
          sku
        }
        prepaidSubscriptionContext {
          prepaidOrdersRemaining
          prepaidOrdersPerBilling
          renewalBehavior
          lastRenewalRevenue
          prepaidOriginMerchantOrderId
        }
      }
    }
  }
}
"""

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()
```