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

# subscription

The `subscription` query returns [`SubscriptionType`](/graphql/graphql-definitions/objects/subscription-type).

## Arguments

| Argument   | Type      | Required | Description                                 |
| ---------- | --------- | -------- | ------------------------------------------- |
| `publicId` | `String!` | Yes      | The globally unique ID of the subscription. |

## Return type: `SubscriptionType`

| Field                          | Type                                                                                               | Required |
| ------------------------------ | -------------------------------------------------------------------------------------------------- | -------- |
| `cancelReason`                 | `String`                                                                                           | No       |
| `cancelReasonCode`             | [`CancelReasonType`](/graphql/graphql-definitions/objects/cancel-reason-type)                      | No       |
| `cancelled`                    | `DateTime`                                                                                         | No       |
| `components`                   | [`[ComponentType!]`](/graphql/graphql-definitions/objects/component-type)                          | No       |
| `created`                      | `DateTime`                                                                                         | No       |
| `currencyCode`                 | `String`                                                                                           | No       |
| `customer`                     | [`CustomerType`](/graphql/graphql-definitions/objects/customer-type)                               | No       |
| `every`                        | `Int`                                                                                              | No       |
| `everyPeriod`                  | `Int`                                                                                              | No       |
| `externalId`                   | `String`                                                                                           | No       |
| `extraData`                    | `String`                                                                                           | No       |
| `freeTrialSubscriptionContext` | [`FreeTrialSubscriptionContextType`](/graphql/graphql-definitions/objects/free-trial-context-type) | No       |
| `frequencyDays`                | `Int`                                                                                              | No       |
| `grantees`                     | [`[GranteeType!]!`](/graphql/graphql-definitions/objects/grantee-type)                             | Yes      |
| `id`                           | `ID!`                                                                                              | Yes      |
| `live`                         | `Boolean!`                                                                                         | Yes      |
| `merchantOrderId`              | `String`                                                                                           | No       |
| `merchantPublicId`             | `String!`                                                                                          | Yes      |
| `offerPublicId`                | `String`                                                                                           | No       |
| `payment`                      | [`PaymentType`](/graphql/graphql-definitions/objects/payment-type)                                 | No       |
| `prepaidSubscriptionContext`   | [`PrepaidSubscriptionContextType`](/graphql/graphql-definitions/objects/prepaid-context-type)      | No       |
| `price`                        | `Decimal`                                                                                          | No       |
| `product`                      | [`ProductType`](/graphql/graphql-definitions/objects/product-type)                                 | No       |
| `publicId`                     | `String`                                                                                           | No       |
| `quantity`                     | `Int!`                                                                                             | Yes      |
| `queuedActions`                | [`[QueuedActionType!]`](/graphql/graphql-definitions/objects/queued-action-type)                   | No       |
| `reminderDays`                 | `Int`                                                                                              | No       |
| `sessionId`                    | `String!`                                                                                          | Yes      |
| `shippingAddress`              | [`AddressType`](/graphql/graphql-definitions/objects/address-type)                                 | No       |
| `startDate`                    | `Date!`                                                                                            | Yes      |
| `subscriptionType`             | `String`                                                                                           | No       |
| `updated`                      | `DateTime`                                                                                         | No       |

## Examples

### Get subscription overview

Basic subscription info with product details

```graphql title="GraphQL"
query {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    startDate
    created
    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 { subscription(publicId: \"sub123\") { publicId every everyPeriod quantity price live startDate created product { name externalProductId sku imageUrl } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    startDate
    created
    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 {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    startDate
    created
    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()
```

### Get subscription for account management

Full subscription details for editing customer, shipping, and payment

```graphql title="GraphQL"
query {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    cancelled
    cancelReason
    startDate
    currencyCode
    customer {
      merchantUserId
      firstName
      lastName
      email
      phoneNumber
    }
    shippingAddress {
      publicId
      firstName
      lastName
      address
      address2
      city
      stateProvinceCode
      zipPostalCode
      countryCode
      phone
    }
    payment {
      publicId
      ccType
      ccNumberEnding
      ccExpDate
      ccHolder
      paymentMethod
    }
    product {
      name
      externalProductId
      sku
      price
      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 { subscription(publicId: \"sub123\") { publicId every everyPeriod quantity price live cancelled cancelReason startDate currencyCode customer { merchantUserId firstName lastName email phoneNumber } shippingAddress { publicId firstName lastName address address2 city stateProvinceCode zipPostalCode countryCode phone } payment { publicId ccType ccNumberEnding ccExpDate ccHolder paymentMethod } product { name externalProductId sku price imageUrl } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    cancelled
    cancelReason
    startDate
    currencyCode
    customer {
      merchantUserId
      firstName
      lastName
      email
      phoneNumber
    }
    shippingAddress {
      publicId
      firstName
      lastName
      address
      address2
      city
      stateProvinceCode
      zipPostalCode
      countryCode
      phone
    }
    payment {
      publicId
      ccType
      ccNumberEnding
      ccExpDate
      ccHolder
      paymentMethod
    }
    product {
      name
      externalProductId
      sku
      price
      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 {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    cancelled
    cancelReason
    startDate
    currencyCode
    customer {
      merchantUserId
      firstName
      lastName
      email
      phoneNumber
    }
    shippingAddress {
      publicId
      firstName
      lastName
      address
      address2
      city
      stateProvinceCode
      zipPostalCode
      countryCode
      phone
    }
    payment {
      publicId
      ccType
      ccNumberEnding
      ccExpDate
      ccHolder
      paymentMethod
    }
    product {
      name
      externalProductId
      sku
      price
      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()
```

### Get bundle subscription components

Retrieve a subscription's bundle components with product details

```graphql title="GraphQL"
query {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    product {
      name
      externalProductId
    }
    components {
      publicId
      quantity
      product {
        name
        externalProductId
        sku
        price
      }
    }
  }
}
```

```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 { subscription(publicId: \"sub123\") { publicId every everyPeriod quantity price live product { name externalProductId } components { publicId quantity product { name externalProductId sku price } } } }"}'
```

```javascript title="Node.js"
const query = `
query {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    product {
      name
      externalProductId
    }
    components {
      publicId
      quantity
      product {
        name
        externalProductId
        sku
        price
      }
    }
  }
}
`;

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 {
  subscription(publicId: "sub123") {
    publicId
    every
    everyPeriod
    quantity
    price
    live
    product {
      name
      externalProductId
    }
    components {
      publicId
      quantity
      product {
        name
        externalProductId
        sku
        price
      }
    }
  }
}
"""

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