Choose a version:

appSubscriptionCancel

mutation

Cancels an active app subscription, stopping future billing cycles. The cancellation behavior depends on the replacementBehavior setting - it can either disable auto-renewal (allowing the subscription to continue until the end of the current billing period) or immediately cancel with prorated refunds.

When a merchant decides to discontinue using subscription features, this mutation provides a clean cancellation workflow that respects billing periods and merchant expectations.

Use the AppSubscriptionCancel mutation to:

Process merchant-initiated subscription cancellations
Terminate subscriptions due to policy violations or account issues
Handle subscription cancellations during app uninstallation workflows

The cancellation timing and merchant access depends on the replacementBehavior setting and the app's specific implementation of subscription management.

For subscription lifecycle management and cancellation best practices, consult the subscription management guide.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the app subscription to be cancelled.
Anchor to prorateprorate •Boolean Default:false: Whether to issue prorated credits for the unused portion of the app subscription. There will be a corresponding deduction (based on revenue share) to your Partner account. For example, if a $10.00 app subscription (with 0% revenue share) is cancelled and prorated half way through the billing cycle, then the merchant will be credited $5.00 and that amount will be deducted from your Partner account.

Was this section helpful?

Anchor to AppSubscriptionCancelPayload returnsAppSubscriptionCancelPayload returns

Anchor to appSubscriptionappSubscription •AppSubscription: The cancelled app subscription.
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Cancel an app subscription on a shop and issue prorated credits

Query

mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
  appSubscriptionCancel(id: $id, prorate: $prorate) {
    userErrors {
      field
      message
    }
    appSubscription {
      id
      status
    }
  }
}

Variables

{
  "id": "gid://shopify/AppSubscription/1029266957",
  "prorate": true
}

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": "mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) { appSubscriptionCancel(id: $id, prorate: $prorate) { userErrors { field message } appSubscription { id status } } }",
 "variables": {
    "id": "gid://shopify/AppSubscription/1029266957",
    "prorate": true
  }
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
    appSubscriptionCancel(id: $id, prorate: $prorate) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
        status
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/AppSubscription/1029266957",
        "prorate": true
    },
  },
);

const data = await response.json();

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 AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
    appSubscriptionCancel(id: $id, prorate: $prorate) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
        status
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/AppSubscription/1029266957",
  "prorate": true
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
      appSubscriptionCancel(id: $id, prorate: $prorate) {
        userErrors {
          field
          message
        }
        appSubscription {
          id
          status
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/AppSubscription/1029266957",
        "prorate": true
    },
  },
});

Response

{
  "appSubscriptionCancel": {
    "userErrors": [],
    "appSubscription": {
      "id": "gid://shopify/AppSubscription/1029266957",
      "status": "CANCELLED"
    }
  }
}

Cancels a recurring application charge

Query

mutation AppSubscriptionCancel($id: ID!) {
  appSubscriptionCancel(id: $id) {
    userErrors {
      field
      message
    }
    appSubscription {
      id
      status
    }
  }
}

Variables

{
  "id": "gid://shopify/AppSubscription/1029266958"
}

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": "mutation AppSubscriptionCancel($id: ID!) { appSubscriptionCancel(id: $id) { userErrors { field message } appSubscription { id status } } }",
 "variables": {
    "id": "gid://shopify/AppSubscription/1029266958"
  }
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  mutation AppSubscriptionCancel($id: ID!) {
    appSubscriptionCancel(id: $id) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
        status
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/AppSubscription/1029266958"
    },
  },
);

const data = await response.json();

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 AppSubscriptionCancel($id: ID!) {
    appSubscriptionCancel(id: $id) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
        status
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/AppSubscription/1029266958"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation AppSubscriptionCancel($id: ID!) {
      appSubscriptionCancel(id: $id) {
        userErrors {
          field
          message
        }
        appSubscription {
          id
          status
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/AppSubscription/1029266958"
    },
  },
});

Response

{
  "appSubscriptionCancel": {
    "userErrors": [],
    "appSubscription": {
      "id": "gid://shopify/AppSubscription/1029266958",
      "status": "CANCELLED"
    }
  }
}

appSubscriptionCancel reference

Examples

Open in GraphiQL

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

const response = await admin.graphql(

`#graphql

mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {

appSubscriptionCancel(id: $id, prorate: $prorate) {

userErrors {

field

message

}

appSubscription {

status

}

}`,

{

variables: {

"id": "gid://shopify/AppSubscription/1029266957",

"prorate": true

);

const data = await response.json();

mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
  appSubscriptionCancel(id: $id, prorate: $prorate) {
    userErrors {
      field
      message
    }
    appSubscription {
      id
      status
    }
  }
}

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": "mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) { appSubscriptionCancel(id: $id, prorate: $prorate) { userErrors { field message } appSubscription { id status } } }",
 "variables": {
    "id": "gid://shopify/AppSubscription/1029266957",
    "prorate": true
  }
}'

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

const response = await admin.graphql(
  `#graphql
  mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
    appSubscriptionCancel(id: $id, prorate: $prorate) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
        status
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/AppSubscription/1029266957",
        "prorate": true
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
      appSubscriptionCancel(id: $id, prorate: $prorate) {
        userErrors {
          field
          message
        }
        appSubscription {
          id
          status
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/AppSubscription/1029266957",
        "prorate": true
    },
  },
});

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 AppSubscriptionCancel($id: ID!, $prorate: Boolean) {
    appSubscriptionCancel(id: $id, prorate: $prorate) {
      userErrors {
        field
        message
      }
      appSubscription {
        id
        status
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/AppSubscription/1029266957",
  "prorate": true
}

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

Input variables

JSON

{

"id": "gid://shopify/AppSubscription/1029266957",

"prorate": true

}

Response

JSON

{

"appSubscriptionCancel": {

"userErrors": [],

"appSubscription": {

"id": "gid://shopify/AppSubscription/1029266957",

"status": "CANCELLED"

}