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.

Show fields

Anchor to appapp

•App

The subscription app that the subscription contract is registered to.

Show fields

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.

Show fields

Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to lastlast •Int: The last n elements from the paginated list.
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.

Show fields

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.

Show enum values

Anchor to customAttributescustomAttributes

•[Attribute!]!

non-null

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

Show fields

Anchor to customercustomer

•Customer

The customer to whom the subscription contract belongs.

Show fields

Anchor to customerPaymentMethodcustomerPaymentMethod

•CustomerPaymentMethod

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

Show fields

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.

Show union types

Anchor to deliveryPolicydeliveryPolicy

•SubscriptionDeliveryPolicy!

non-null

The delivery policy associated with the subscription contract.

Show fields

Anchor to deliveryPricedeliveryPrice

•MoneyV2!

non-null

The delivery price for each billing of the subscription contract.

Show fields

Anchor to discountsdiscounts

•SubscriptionManualDiscountConnection!

non-null

The list of subscription discounts associated with the subscription contract.

Show fields

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

Anchor to groupedLinesgroupedLines

•SubscriptionGroupedLineConnection

The list of subscription lines grouped by bundle parent, with bundle components nested under their parent line.

Show fields

Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to lastlast •Int: The last n elements from the paginated list.
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.

Show enum values

Anchor to lastPaymentStatuslastPaymentStatus

•SubscriptionContractLastPaymentStatus

The current status of the last payment.

Show enum values

Anchor to latestCommittedProjectedOrderTotalslatestCommittedProjectedOrderTotals

•SubscriptionContractCalculationProjectedOrderTotals

The projected order totals from the last successful commit of the subscription contract. Returns null when no projected order totals have been persisted for the contract, or the latest version was committed through a subscription draft.

Show fields

Anchor to lineslines

•SubscriptionLineConnection!

non-null

The list of subscription lines associated with the subscription contract.

Show fields

Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to lastlast •Int: The last n elements from the paginated list.
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.

Show fields

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.

Show fields

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

Anchor to originOrderoriginOrder

•Order

The order from which this contract originated.

Show fields

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.

Show enum values

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/unstable/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"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query findContract($subscriptionContractId: ID!) {
  subscriptionContract(id: $subscriptionContractId) {
    id
    status
    nextBillingDate
  }
}' \
--variables \
'{
  "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
}'

Direct API Access

const response = await fetch('shopify:admin/api/unstable/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query findContract($subscriptionContractId: ID!) {
        subscriptionContract(id: $subscriptionContractId) {
          id
          status
          nextBillingDate
        }
      }
    `,
    variables: {
        "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

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

Query for a subscription contract

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/unstable/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)

Shopify CLI

shopify app execute \
--query \
'query findContract($subscriptionContractId: ID!) {
  subscriptionContract(id: $subscriptionContractId) {
    id
    status
    nextBillingDate
  }
}' \
--variables \
'{
  "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
}'

Direct API Access

const response = await fetch('shopify:admin/api/unstable/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query findContract($subscriptionContractId: ID!) {
        subscriptionContract(id: $subscriptionContractId) {
          id
          status
          nextBillingDate
        }
      }
    `,
    variables: {
        "subscriptionContractId": "gid://shopify/SubscriptionContract/593791907"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

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

}

Response

JSON

{

"subscriptionContract": {

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

"status": "ACTIVE",

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

}