Choose a version:

Anchor to subscriptionContractAtomicCreate

subscriptionContractAtomicCreate

mutation

Requires write_own_subscription_contracts access scope. Also: The user must have manage_orders_information permission.

Creates a Subscription Contract.

Anchor to Arguments

Arguments

Anchor to inputinput

•SubscriptionContractAtomicCreateInput!

required

The properties of the new Subscription Contract.

Show input fields

Was this section helpful?

Anchor to SubscriptionContractAtomicCreatePayload returnsSubscriptionContractAtomicCreatePayload returns

Anchor to contractcontract •SubscriptionContract: The new Subscription Contract object.

Show fields
Anchor to userErrorsuserErrors •[SubscriptionDraftUserError!]! non-null: The list of errors that occurred from executing the mutation.

Show fields

Was this section helpful?

Examples

Create a subscription contract with a single line item

Description

Creates a subscription contract with a line item with a single GraphQL call.

Query

mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
  subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
    contract {
      id
      lines(first: 10) {
        nodes {
          id
          quantity
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "customerId": "gid://shopify/Customer/544365967",
  "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
  "variantId": "gid://shopify/ProductVariant/30322695"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) { subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: \"2025-06-01\", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: \"John\", lastName: \"King\", address1: \"1483 rue Mossoro\", city: \"Montreal\", province: \"Quebec\", country: \"Canada\", zip: \"H2S1Z5\"}}}}}) { contract { id lines(first: 10) { nodes { id quantity } } } userErrors { field message } } }",
 "variables": {
    "customerId": "gid://shopify/Customer/544365967",
    "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
    "variantId": "gid://shopify/ProductVariant/30322695"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
    subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
      contract {
        id
        lines(first: 10) {
          nodes {
            id
            quantity
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerId": "gid://shopify/Customer/544365967",
        "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
        "variantId": "gid://shopify/ProductVariant/30322695"
    },
  },
  );
  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
  mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
    subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
      contract {
        id
        lines(first: 10) {
          nodes {
            id
            quantity
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerId": "gid://shopify/Customer/544365967",
  "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
  "variantId": "gid://shopify/ProductVariant/30322695"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
      subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
        contract {
          id
          lines(first: 10) {
            nodes {
              id
              quantity
            }
          }
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "customerId": "gid://shopify/Customer/544365967",
        "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
        "variantId": "gid://shopify/ProductVariant/30322695"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
  subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
    contract {
      id
      lines(first: 10) {
        nodes {
          id
          quantity
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "customerId": "gid://shopify/Customer/544365967",
  "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
  "variantId": "gid://shopify/ProductVariant/30322695"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-07/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
        subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
          contract {
            id
            lines(first: 10) {
              nodes {
                id
                quantity
              }
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerId": "gid://shopify/Customer/544365967",
        "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
        "variantId": "gid://shopify/ProductVariant/30322695"
    },
  }),
});

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

Response

{
  "subscriptionContractAtomicCreate": {
    "contract": {
      "id": "gid://shopify/SubscriptionContract/975257121",
      "lines": {
        "nodes": [
          {
            "id": "gid://shopify/SubscriptionLine/93b63eb2-70d1-43db-98a8-031a9b1c8042",
            "quantity": 20
          }
        ]
      }
    },
    "userErrors": []
  }
}

subscriptionContractAtomicCreate reference

Examples

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

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

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

const response = await admin.graphql(

`#graphql

mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {

subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {

contract {

lines(first: 10) {

nodes {

quantity

}

userErrors {

field

message

}

}`,

{

variables: {

"customerId": "gid://shopify/Customer/544365967",

"paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",

"variantId": "gid://shopify/ProductVariant/30322695"

);

const json = await response.json();

return json.data;

}

GQL

mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
  subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
    contract {
      id
      lines(first: 10) {
        nodes {
          id
          quantity
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) { subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: \"2025-06-01\", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: \"John\", lastName: \"King\", address1: \"1483 rue Mossoro\", city: \"Montreal\", province: \"Quebec\", country: \"Canada\", zip: \"H2S1Z5\"}}}}}) { contract { id lines(first: 10) { nodes { id quantity } } } userErrors { field message } } }",
 "variables": {
    "customerId": "gid://shopify/Customer/544365967",
    "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
    "variantId": "gid://shopify/ProductVariant/30322695"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
    subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
      contract {
        id
        lines(first: 10) {
          nodes {
            id
            quantity
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerId": "gid://shopify/Customer/544365967",
        "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
        "variantId": "gid://shopify/ProductVariant/30322695"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
      subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
        contract {
          id
          lines(first: 10) {
            nodes {
              id
              quantity
            }
          }
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "customerId": "gid://shopify/Customer/544365967",
        "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
        "variantId": "gid://shopify/ProductVariant/30322695"
    },
  },
});

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
  mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
    subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
      contract {
        id
        lines(first: 10) {
          nodes {
            id
            quantity
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerId": "gid://shopify/Customer/544365967",
  "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
  "variantId": "gid://shopify/ProductVariant/30322695"
}

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

Shopify CLI

shopify app execute \
--query \
'mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
  subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
    contract {
      id
      lines(first: 10) {
        nodes {
          id
          quantity
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "customerId": "gid://shopify/Customer/544365967",
  "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
  "variantId": "gid://shopify/ProductVariant/30322695"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-07/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation($customerId: ID!, $paymentMethodId: ID!, $variantId: ID!) {
        subscriptionContractAtomicCreate(input: {customerId: $customerId, nextBillingDate: "2025-06-01", currencyCode: USD, lines: [{line: {productVariantId: $variantId, quantity: 20, currentPrice: 25.0}}], contract: {status: ACTIVE, paymentMethodId: $paymentMethodId, billingPolicy: {interval: MONTH, intervalCount: 1, minCycles: 3}, deliveryPolicy: {interval: MONTH, intervalCount: 1}, deliveryPrice: 14.99, deliveryMethod: {shipping: {address: {firstName: "John", lastName: "King", address1: "1483 rue Mossoro", city: "Montreal", province: "Quebec", country: "Canada", zip: "H2S1Z5"}}}}}) {
          contract {
            id
            lines(first: 10) {
              nodes {
                id
                quantity
              }
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerId": "gid://shopify/Customer/544365967",
        "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
        "variantId": "gid://shopify/ProductVariant/30322695"
    },
  }),
});

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

Input variables

JSON

{

"customerId": "gid://shopify/Customer/544365967",

"paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",

"variantId": "gid://shopify/ProductVariant/30322695"

}

Response

JSON

{

"subscriptionContractAtomicCreate": {

"contract": {

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

"lines": {

"nodes": [

{

"id": "gid://shopify/SubscriptionLine/93b63eb2-70d1-43db-98a8-031a9b1c8042",

"quantity": 20

}

]

}

"userErrors": []

}