Choose a version:

subscriptionContract

query

Retrieves a SubscriptionContract by ID.

The contract tracks the subscription's lifecycle through various statuses, and links to related billing attempts, generated Order objects, and the customer's CustomerPaymentMethod.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the Subscription Contract to return.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to SubscriptionContractSubscriptionContract

•SubscriptionContract

A subscription contract that defines recurring purchases for a customer. Each contract specifies what products to deliver, when to bill and ship them, and at what price.

The contract includes SubscriptionBillingPolicy and SubscriptionDeliveryPolicy that control the frequency of charges and fulfillments. SubscriptionLine items define the products, quantities, and pricing for each recurring Order. The contract tracks SubscriptionBillingAttempt records, payment status, and generated orders throughout its lifecycle. App instances manage contracts through various status transitions including active, paused, failed, cancelled, or expired states.

Learn more about building subscription contracts and updating subscription contracts.

Anchor to appapp

•App

The subscription app that the subscription contract is registered to.

Anchor to appAdminUrlappAdminUrl

•URL

The URL of the subscription contract page on the subscription app.

Anchor to billingAttemptsbillingAttempts

•SubscriptionBillingAttemptConnection!

non-null

The list of billing attempts associated with the subscription contract.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to billingPolicybillingPolicy

•SubscriptionBillingPolicy!

non-null

The billing policy associated with the subscription contract.

Anchor to createdAtcreatedAt

•DateTime!

non-null

The date and time when the subscription contract was created.

Anchor to currencyCodecurrencyCode

•CurrencyCode!

non-null

The currency that's used for the subscription contract.

Anchor to customAttributescustomAttributes

•[Attribute!]!

non-null

A list of the custom attributes to be added to the generated orders.

Anchor to customercustomer

•Customer

The customer to whom the subscription contract belongs.

Anchor to customerPaymentMethodcustomerPaymentMethod

•CustomerPaymentMethod

The customer payment method that's used for the subscription contract.

Anchor to showRevokedshowRevoked •Boolean Default:false: Whether to show the customer's revoked payment method.

Anchor to deliveryMethoddeliveryMethod

•SubscriptionDeliveryMethod

The delivery method for each billing of the subscription contract.

Anchor to deliveryPolicydeliveryPolicy

•SubscriptionDeliveryPolicy!

non-null

The delivery policy associated with the subscription contract.

Anchor to deliveryPricedeliveryPrice

•MoneyV2!

non-null

The delivery price for each billing of the subscription contract.

Anchor to discountsdiscounts

•SubscriptionManualDiscountConnection!

non-null

The list of subscription discounts associated with the subscription contract.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to lastBillingAttemptErrorTypelastBillingAttemptErrorType

•SubscriptionContractLastBillingErrorType

The last billing error type of the contract.

Anchor to lastPaymentStatuslastPaymentStatus

•SubscriptionContractLastPaymentStatus

The current status of the last payment.

Anchor to lineslines

•SubscriptionLineConnection!

non-null

The list of subscription lines associated with the subscription contract.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to linesCountlinesCount

•Count

The number of lines associated with the subscription contract.

Anchor to nextBillingDatenextBillingDate

•DateTime

The next billing date for the subscription contract. This field is managed by the apps. Alternatively you can utilize our Billing Cycles APIs, which provide auto-computed billing dates and additional functionalities.

Anchor to notenote

•String

The note field that will be applied to the generated orders.

Anchor to ordersorders

•OrderConnection!

non-null

A list of the subscription contract's orders.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to originOrderoriginOrder

•Order

The order from which this contract originated.

Anchor to revisionIdrevisionId

•UnsignedInt64!

non-null

The revision id of the contract.

Anchor to statusstatus

•SubscriptionContractSubscriptionStatus!

non-null

The current status of the subscription contract.

Anchor to updatedAtupdatedAt

•DateTime!

non-null

The date and time when the subscription contract was updated.

Anchor to lineCountlineCount

•Int!

non-nullDeprecated

Was this section helpful?

Examples

Query for a subscription contract

Description

Finds a subscription contract by id.

Query

query findContract($subscriptionContractId: ID!) {
  subscriptionContract(id: $subscriptionContractId) {
    id
    status
    nextBillingDate
  }
}

Variables

{
  "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query findContract($subscriptionContractId: ID!) { subscriptionContract(id: $subscriptionContractId) { id status nextBillingDate } }",
 "variables": {
    "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query findContract($subscriptionContractId: ID!) {
    subscriptionContract(id: $subscriptionContractId) {
      id
      status
      nextBillingDate
    }
  }`,
  {
    variables: {
        "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query findContract($subscriptionContractId: ID!) {
    subscriptionContract(id: $subscriptionContractId) {
      id
      status
      nextBillingDate
    }
  }
QUERY

variables = {
  "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query findContract($subscriptionContractId: ID!) {
      subscriptionContract(id: $subscriptionContractId) {
        id
        status
        nextBillingDate
      }
    }`,
    "variables": {
        "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
    },
  },
});

Response

{
  "subscriptionContract": {
    "id": "gid://shopify/SubscriptionContract/593791907",
    "status": "ACTIVE",
    "nextBillingDate": "2120-02-05T15:00:00Z"
  }
}

Query for a subscription contract

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query findContract($subscriptionContractId: ID!) {

subscriptionContract(id: $subscriptionContractId) {

status

nextBillingDate

}

}`,

{

variables: {

"subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"

);

const json = await response.json();

return json.data;

}

GQL

query findContract($subscriptionContractId: ID!) {
  subscriptionContract(id: $subscriptionContractId) {
    id
    status
    nextBillingDate
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query findContract($subscriptionContractId: ID!) { subscriptionContract(id: $subscriptionContractId) { id status nextBillingDate } }",
 "variables": {
    "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query findContract($subscriptionContractId: ID!) {
    subscriptionContract(id: $subscriptionContractId) {
      id
      status
      nextBillingDate
    }
  }`,
  {
    variables: {
        "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query findContract($subscriptionContractId: ID!) {
      subscriptionContract(id: $subscriptionContractId) {
        id
        status
        nextBillingDate
      }
    }`,
    "variables": {
        "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
    },
  },
});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query findContract($subscriptionContractId: ID!) {
    subscriptionContract(id: $subscriptionContractId) {
      id
      status
      nextBillingDate
    }
  }
QUERY

variables = {
  "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"

}

Response

JSON

{

"subscriptionContract": {

"id": "gid://shopify/SubscriptionContract/593791907",

"status": "ACTIVE",

"nextBillingDate": "2120-02-05T15:00:00Z"

}