Choose a version:

appSubscriptionLineItemUpdate

mutation

Updates the capped amount on usage-based billing for an AppSubscriptionLineItem. Enables you to modify the maximum charge limit that prevents merchants from exceeding a specified threshold during their billing period.

The mutation returns a confirmation URL where the merchant must approve the new pricing limit before it takes effect. Use this when adjusting usage limits based on merchant needs or changing pricing models.

Learn more about updating the maximum charge for a subscription.

Anchor to Arguments

Arguments

Anchor to cappedAmountcappedAmount

•MoneyInput!

required

The new maximum amount of usage charges that can be incurred within a subscription billing interval.

Anchor to idid

•ID!

required

The ID of the app subscription line item to be updated.

Was this section helpful?

Anchor to AppSubscriptionLineItemUpdatePayload returnsAppSubscriptionLineItemUpdatePayload returns

Anchor to appSubscriptionappSubscription •AppSubscription: The updated app subscription.
Anchor to confirmationUrlconfirmationUrl •URL: The URL where the merchant approves or declines the updated app subscription line item.
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Updates the capped amount of a recurring application charge

Description

You can modify the capped amount on a usage pricing plan.

Query

mutation appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
  appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
    userErrors {
      field
      message
    }
    confirmationUrl
    appSubscription {
      id
    }
  }
}

Variables

{
  "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
  "cappedAmount": {
    "amount": 100,
    "currencyCode": "USD"
  }
}

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": "mutation appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) { appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) { userErrors { field message } confirmationUrl appSubscription { id } } }",
 "variables": {
    "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "cappedAmount": {
      "amount": 100,
      "currencyCode": "USD"
    }
  }
}'

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 appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
    appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
      userErrors {
        field
        message
      }
      confirmationUrl
      appSubscription {
        id
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
        "cappedAmount": {
            "amount": 100,
            "currencyCode": "USD"
        }
    },
  },
  );
  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 appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
    appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
      userErrors {
        field
        message
      }
      confirmationUrl
      appSubscription {
        id
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
  "cappedAmount": {
    "amount": 100,
    "currencyCode": "USD"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
      appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
        userErrors {
          field
          message
        }
        confirmationUrl
        appSubscription {
          id
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
        "cappedAmount": {
            "amount": 100,
            "currencyCode": "USD"
        }
    },
  },
});

Response

{
  "appSubscriptionLineItemUpdate": {
    "userErrors": [],
    "confirmationUrl": "https://billingshop.myshopify.com/admin/charges/193172482/1029266946/RecurringApplicationCharge/confirm_update_capped_amount?signature=BAh7BzoHaWRpBAJeWT06EmF1dG9fYWN0aXZhdGVG--5d28879b4ac4355216b7e6d2f861f9c245272daa",
    "appSubscription": {
      "id": "gid://shopify/AppSubscription/1029266946"
    }
  }
}

appSubscriptionLineItemUpdate reference

Examples

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

mutation appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {

appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {

userErrors {

field

message

}

confirmationUrl

appSubscription {

}

}`,

{

variables: {

"id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",

"cappedAmount": {

"amount": 100,

"currencyCode": "USD"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
  appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
    userErrors {
      field
      message
    }
    confirmationUrl
    appSubscription {
      id
    }
  }
}

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": "mutation appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) { appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) { userErrors { field message } confirmationUrl appSubscription { id } } }",
 "variables": {
    "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "cappedAmount": {
      "amount": 100,
      "currencyCode": "USD"
    }
  }
}'

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 appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
    appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
      userErrors {
        field
        message
      }
      confirmationUrl
      appSubscription {
        id
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
        "cappedAmount": {
            "amount": 100,
            "currencyCode": "USD"
        }
    },
  },
  );
  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 appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
      appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
        userErrors {
          field
          message
        }
        confirmationUrl
        appSubscription {
          id
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
        "cappedAmount": {
            "amount": 100,
            "currencyCode": "USD"
        }
    },
  },
});

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 appSubscriptionLineItemUpdate($cappedAmount: MoneyInput!, $id: ID!) {
    appSubscriptionLineItemUpdate(cappedAmount: $cappedAmount, id: $id) {
      userErrors {
        field
        message
      }
      confirmationUrl
      appSubscription {
        id
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
  "cappedAmount": {
    "amount": 100,
    "currencyCode": "USD"
  }
}

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

Input variables

JSON

{

"id": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",

"cappedAmount": {

"amount": 100,

"currencyCode": "USD"

}

Response

JSON

{

"appSubscriptionLineItemUpdate": {

"userErrors": [],

"confirmationUrl": "https://billingshop.myshopify.com/admin/charges/193172482/1029266946/RecurringApplicationCharge/confirm_update_capped_amount?signature=BAh7BzoHaWRpBAJeWT06EmF1dG9fYWN0aXZhdGVG--5d28879b4ac4355216b7e6d2f861f9c245272daa",

"appSubscription": {

"id": "gid://shopify/AppSubscription/1029266946"

}