Choose a version:

appPurchaseOneTimeCreate

mutation

Creates a one-time charge for app features or services that don't require recurring billing. This mutation is ideal for apps that sell individual features, premium content, or services on a per-use basis rather than subscription models.

For example, a design app might charge merchants once for premium templates, or a marketing app could bill for individual campaign setups without ongoing monthly fees.

Use the AppPurchaseOneTimeCreate mutation to:

Charge for premium features or content purchases
Bill for professional services or setup fees
Generate revenue from one-time digital product sales

The mutation returns a confirmation URL that merchants must visit to approve the charge. Test and development stores are not charged, allowing safe testing of billing flows.

Explore one-time billing options on the app purchases page.

Anchor to Arguments

Arguments

Anchor to namename •String! required: The name of the one-time purchase from the app.
Anchor to priceprice •MoneyInput! required: The amount to be charged to the store for the app one-time purchase.
Anchor to returnUrlreturnUrl •URL! required: The URL where the merchant is redirected after approving the app one-time purchase.
Anchor to testtest •Boolean Default:false: Whether the app one-time purchase is a test transaction.

Was this section helpful?

Anchor to AppPurchaseOneTimeCreatePayload returnsAppPurchaseOneTimeCreatePayload returns

Anchor to appPurchaseOneTimeappPurchaseOneTime •AppPurchaseOneTime: The newly created app one-time purchase.
Anchor to confirmationUrlconfirmationUrl •URL: The URL that the merchant can access to approve or decline the newly created app one-time purchase.

If the merchant declines, then the merchant is redirected to the app and receives a notification message stating that the charge was declined. If the merchant approves and they're successfully invoiced, then the state of the charge changes from pending to active.

You get paid after the charge is activated.
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Creates an application charge

Description

Summarizes the service rendered in the `name` field.

Query

mutation AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
  appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
    userErrors {
      field
      message
    }
    appPurchaseOneTime {
      createdAt
      id
    }
    confirmationUrl
  }
}

Variables

{
  "name": "1000 imported orders.",
  "returnUrl": "http://super-duper.shopifyapps.com/",
  "price": {
    "amount": 10,
    "currencyCode": "USD"
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) { appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) { userErrors { field message } appPurchaseOneTime { createdAt id } confirmationUrl } }",
 "variables": {
    "name": "1000 imported orders.",
    "returnUrl": "http://super-duper.shopifyapps.com/",
    "price": {
      "amount": 10,
      "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 AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
    appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
      userErrors {
        field
        message
      }
      appPurchaseOneTime {
        createdAt
        id
      }
      confirmationUrl
    }
  }`,
  {
    variables: {
        "name": "1000 imported orders.",
        "returnUrl": "http://super-duper.shopifyapps.com/",
        "price": {
            "amount": 10,
            "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 AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
    appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
      userErrors {
        field
        message
      }
      appPurchaseOneTime {
        createdAt
        id
      }
      confirmationUrl
    }
  }
QUERY

variables = {
  "name": "1000 imported orders.",
  "returnUrl": "http://super-duper.shopifyapps.com/",
  "price": {
    "amount": 10,
    "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 AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
      appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
        userErrors {
          field
          message
        }
        appPurchaseOneTime {
          createdAt
          id
        }
        confirmationUrl
      }
    }`,
    "variables": {
        "name": "1000 imported orders.",
        "returnUrl": "http://super-duper.shopifyapps.com/",
        "price": {
            "amount": 10,
            "currencyCode": "USD"
        }
    },
  },
});

Response

{
  "appPurchaseOneTimeCreate": {
    "userErrors": [],
    "appPurchaseOneTime": {
      "createdAt": "2024-11-21T22:47:04Z",
      "id": "gid://shopify/AppPurchaseOneTime/1017262352"
    },
    "confirmationUrl": "https://billingshop.myshopify.com/admin/charges/193172482/1017262352/ApplicationCharge/confirm_application_charge?signature=BAh7BzoHaWRpBBAxojw6EmF1dG9fYWN0aXZhdGVU--a03eedf9ef12d714906af085ebc2aa3d97aa9466"
  }
}

appPurchaseOneTimeCreate 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 AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {

appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {

userErrors {

field

message

}

appPurchaseOneTime {

createdAt

}

confirmationUrl

}

}`,

{

variables: {

"name": "1000 imported orders.",

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

"price": {

"amount": 10,

"currencyCode": "USD"

}

);

const json = await response.json();

return json.data;

}

mutation AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
  appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
    userErrors {
      field
      message
    }
    appPurchaseOneTime {
      createdAt
      id
    }
    confirmationUrl
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) { appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) { userErrors { field message } appPurchaseOneTime { createdAt id } confirmationUrl } }",
 "variables": {
    "name": "1000 imported orders.",
    "returnUrl": "http://super-duper.shopifyapps.com/",
    "price": {
      "amount": 10,
      "currencyCode": "USD"
    }
  }
}'

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
    appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
      userErrors {
        field
        message
      }
      appPurchaseOneTime {
        createdAt
        id
      }
      confirmationUrl
    }
  }`,
  {
    variables: {
        "name": "1000 imported orders.",
        "returnUrl": "http://super-duper.shopifyapps.com/",
        "price": {
            "amount": 10,
            "currencyCode": "USD"
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
      appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
        userErrors {
          field
          message
        }
        appPurchaseOneTime {
          createdAt
          id
        }
        confirmationUrl
      }
    }`,
    "variables": {
        "name": "1000 imported orders.",
        "returnUrl": "http://super-duper.shopifyapps.com/",
        "price": {
            "amount": 10,
            "currencyCode": "USD"
        }
    },
  },
});

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 AppPurchaseOneTimeCreate($name: String!, $price: MoneyInput!, $returnUrl: URL!) {
    appPurchaseOneTimeCreate(name: $name, returnUrl: $returnUrl, price: $price) {
      userErrors {
        field
        message
      }
      appPurchaseOneTime {
        createdAt
        id
      }
      confirmationUrl
    }
  }
QUERY

variables = {
  "name": "1000 imported orders.",
  "returnUrl": "http://super-duper.shopifyapps.com/",
  "price": {
    "amount": 10,
    "currencyCode": "USD"
  }
}

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

Input variables

JSON

{

"name": "1000 imported orders.",

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

"price": {

"amount": 10,

"currencyCode": "USD"

}

Response

JSON

{

"appPurchaseOneTimeCreate": {

"userErrors": [],

"appPurchaseOneTime": {

"createdAt": "2024-11-21T22:47:04Z",

"id": "gid://shopify/AppPurchaseOneTime/1017262352"

"confirmationUrl": "https://billingshop.myshopify.com/admin/charges/193172482/1017262352/ApplicationCharge/confirm_application_charge?signature=BAh7BzoHaWRpBBAxojw6EmF1dG9fYWN0aXZhdGVU--a03eedf9ef12d714906af085ebc2aa3d97aa9466"

}