Choose a version:

appSubscriptionCreate

mutation

Allows an app to charge a store for features or services on a recurring basis.

Arguments

Anchor to lineItemslineItems •[AppSubscriptionLineItemInput!]!required: Attaches one or more pricing plans to an app subscription. Only one pricing plan can be defined for each available type.
Anchor to namename •String!required: A descriptive name for the app subscription.
Anchor to replacementBehaviorreplacementBehavior •AppSubscriptionReplacementBehaviorDefault:STANDARD: The replacement behavior when creating an app subscription for a merchant with an already existing app subscription.
Anchor to returnUrlreturnUrl •URL!required: The URL pointing to the page where the merchant is redirected after approving the app subscription.
Anchor to testtest •BooleanDefault:false: Whether the app subscription is a test transaction.
Anchor to trialDaystrialDays •Int: The number of days of the free trial period, beginning on the day that the merchant approves the app charges.

Was this section helpful?

Anchor to AppSubscriptionCreatePayload returnsAppSubscriptionCreatePayload returns

Anchor to appSubscriptionappSubscription •AppSubscription: The newly-created app subscription.
Anchor to confirmationUrlconfirmationUrl •URL: The URL pointing to the page where the merchant approves or declines the charges for an app subscription.
Anchor to userErrorsuserErrors •[UserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Create a subscription for an app on a recurring pricing plan only.
Create a subscription for an app on a usage pricing plan only.
Create a subscription for an app on an annual recurring pricing plan.
Create a subscription for an app on both a recurring pricing plan and usage pricing plan.
Create a subscription with a fixed amount discount
Create a subscription with a free trial.
Create a subscription with a percentage value discount
Create a subscription with add-on modules
Creates a recurring application charge
appSubscriptionCreate reference

Examples

Open in GraphiQL

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

const response = await admin.graphql(

`#graphql

mutation AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!) {

appSubscriptionCreate(name: $name, returnUrl: $returnUrl, lineItems: $lineItems) {

userErrors {

field

message

}

appSubscription {

}

confirmationUrl

}

}`,

{

variables: {

"name": "Super Duper Recurring Plan",

"returnUrl": "http://super-duper.shopifyapps.com/",

"lineItems": [

{

"plan": {

"appRecurringPricingDetails": {

"price": {

"amount": 10.0,

"currencyCode": "USD"

"interval": "EVERY_30_DAYS"

}

]

);

const data = await response.json();

mutation AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!) {
  appSubscriptionCreate(name: $name, returnUrl: $returnUrl, lineItems: $lineItems) {
    userErrors {
      field
      message
    }
    appSubscription {
      id
    }
    confirmationUrl
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!) { appSubscriptionCreate(name: $name, returnUrl: $returnUrl, lineItems: $lineItems) { userErrors { field message } appSubscription { id } confirmationUrl } }",
 "variables": {
    "name": "Super Duper Recurring Plan",
    "returnUrl": "http://super-duper.shopifyapps.com/",
    "lineItems": [
      {
        "plan": {
          "appRecurringPricingDetails": {
            "price": {
              "amount": 10.0,
              "currencyCode": "USD"
            },
            "interval": "EVERY_30_DAYS"
          }
        }
      }
    ]
  }
}'

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

const response = await admin.graphql(
  `#graphql
  mutation AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!) {
    appSubscriptionCreate(name: $name, returnUrl: $returnUrl, lineItems: $lineItems) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
      }
      confirmationUrl
    }
  }`,
  {
    variables: {
      "name": "Super Duper Recurring Plan",
      "returnUrl": "http://super-duper.shopifyapps.com/",
      "lineItems": [
        {
          "plan": {
            "appRecurringPricingDetails": {
              "price": {
                "amount": 10.0,
                "currencyCode": "USD"
              },
              "interval": "EVERY_30_DAYS"
            }
          }
        }
      ]
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!) {
      appSubscriptionCreate(name: $name, returnUrl: $returnUrl, lineItems: $lineItems) {
        userErrors {
          field
          message
        }
        appSubscription {
          id
        }
        confirmationUrl
      }
    }`,
    "variables": {
      "name": "Super Duper Recurring Plan",
      "returnUrl": "http://super-duper.shopifyapps.com/",
      "lineItems": [
        {
          "plan": {
            "appRecurringPricingDetails": {
              "price": {
                "amount": 10.0,
                "currencyCode": "USD"
              },
              "interval": "EVERY_30_DAYS"
            }
          }
        }
      ]
    },
  },
});

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 AppSubscriptionCreate($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!) {
    appSubscriptionCreate(name: $name, returnUrl: $returnUrl, lineItems: $lineItems) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
      }
      confirmationUrl
    }
  }
QUERY

variables = {
  "name": "Super Duper Recurring Plan",
  "returnUrl": "http://super-duper.shopifyapps.com/",
  "lineItems": [{"plan"=>{"appRecurringPricingDetails"=>{"price"=>{"amount"=>10.0, "currencyCode"=>"USD"}, "interval"=>"EVERY_30_DAYS"}}}]
}

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

Input variables

JSON

{

"name": "Super Duper Recurring Plan",

"returnUrl": "http://super-duper.shopifyapps.com/",

"lineItems": [

{

"plan": {

"appRecurringPricingDetails": {

"price": {

"amount": 10,

"currencyCode": "USD"

"interval": "EVERY_30_DAYS"

}

]

}

Response

JSON

{

"appSubscriptionCreate": {

"userErrors": [],

"appSubscription": {

"id": "gid://shopify/AppSubscription/1029266964"

"confirmationUrl": "https://billingshop.myshopify.com/admin/charges/166357/1029266964/RecurringApplicationCharge/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBBReWT06EmF1dG9fYWN0aXZhdGVU--40f1bb287931224ca72323613fc6255d8a38a2c8"

}