Choose a version:

Billing
object

Contains function used to bill merchants for your app with the Billing API.

This object is returned on authenticated Admin requests.

Note

Managed App Pricing is now available. Define your app’s pricing plans directly in the Shopify Partner Dashboard, without needing to use the Billing API.

Anchor to examplesExamples

Anchor to example-cancelcancel

Anchor to example-cancelling-a-subscriptionCancelling a subscription

Use the billing.cancel function to cancel an active subscription with the id returned from billing.require.

Was this section helpful?

Cancelling a subscription

import { LoaderFunctionArgs } from "react-router";

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

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

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

const billingCheck = await billing.require({

plans: [MONTHLY_PLAN],

onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),

});

const subscription = billingCheck.appSubscriptions[0];

const cancelledSubscription = await billing.cancel({

subscriptionId: subscription.id,

isTest: true,

prorate: true,

});

// App logic

};

Examples

Cancelling a subscription

Description

Use the `billing.cancel` function to cancel an active subscription with the id returned from `billing.require`.

/app/routes/cancel-subscription.ts

import { LoaderFunctionArgs } from "react-router";
import { authenticate, MONTHLY_PLAN } from "../shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { billing } = await authenticate.admin(request);
  const billingCheck = await billing.require({
    plans: [MONTHLY_PLAN],
    onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),
  });

  const subscription = billingCheck.appSubscriptions[0];
  const cancelledSubscription = await billing.cancel({
    subscriptionId: subscription.id,
    isTest: true,
    prorate: true,
   });

  // App logic
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const MONTHLY_PLAN = 'Monthly subscription';
export const ANNUAL_PLAN = 'Annual subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Every30Days,
        }
      ],
    },
    [ANNUAL_PLAN]: {
      lineItems: [
        {
          amount: 50,
          currencyCode: 'USD',
          interval: BillingInterval.Annual,
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Anchor to example-checkcheck

Anchor to example-check-what-billing-plans-a-merchant-is-subscribed-toCheck what billing plans a merchant is subscribed to

Use billing.check if you want to determine which plans are in use. Unlike require, check does notthrow an error if no active billing plans are present.

Anchor to example-check-for-payments-without-filteringCheck for payments without filtering

Use billing.check to see if any payments exist for the store, regardless of whether it's a test ormatches one or more plans.

Was this section helpful?

Check what billing plans a merchant is subscribed to

import { LoaderFunctionArgs } from "react-router";

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

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

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

const { hasActivePayment, appSubscriptions } = await billing.check({

plans: [MONTHLY_PLAN],

isTest: false,

});

console.log(hasActivePayment);

console.log(appSubscriptions);

};

Examples

Check what billing plans a merchant is subscribed to

Description

Use billing.check if you want to determine which plans are in use. Unlike `require`, `check` does notthrow an error if no active billing plans are present.

/app/routes/**\/*.ts

import { LoaderFunctionArgs } from "react-router";
import { authenticate, MONTHLY_PLAN } from "../shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { billing } = await authenticate.admin(request);
  const { hasActivePayment, appSubscriptions } = await billing.check({
    plans: [MONTHLY_PLAN],
    isTest: false,
  });
  console.log(hasActivePayment);
  console.log(appSubscriptions);
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const MONTHLY_PLAN = 'Monthly subscription';
export const ANNUAL_PLAN = 'Annual subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Every30Days,
        }
      ],
    },
    [ANNUAL_PLAN]: {
      lineItems: [
        {
          amount: 50,
          currencyCode: 'USD',
          interval: BillingInterval.Annual,
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Check for payments without filtering

Description

Use billing.check to see if any payments exist for the store, regardless of whether it's a test ormatches one or more plans.

/app/routes/**\/*.ts

import { LoaderFunctionArgs } from "react-router";
import { authenticate, MONTHLY_PLAN } from "../shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { billing } = await authenticate.admin(request);
  const { hasActivePayment, appSubscriptions } = await billing.check();
  // This will be true if any payment is found
  console.log(hasActivePayment);
  console.log(appSubscriptions);
};

Anchor to example-createusagerecordcreateUsageRecord

Anchor to example-creating-a-usage-recordCreating a usage record

Create a usage record for the active usage billing plan

Was this section helpful?

Creating a usage record

import { ActionFunctionArgs } from "react-router";

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

export const action = async ({ request }: ActionFunctionArgs) => {

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

const chargeBilling = await billing.createUsageRecord({

description: "Usage record for product creation",

price: {

amount: 1,

currencyCode: "USD",

isTest: true,

});

console.log(chargeBilling);

// App logic

};

Examples

Creating a usage record

Description

Create a usage record for the active usage billing plan

/app/routes/create-usage-record.ts

import { ActionFunctionArgs } from "react-router";
import { authenticate, MONTHLY_PLAN } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
   const { billing } = await authenticate.admin(request);

  const chargeBilling = await billing.createUsageRecord({
     description: "Usage record for product creation",
     price: {
       amount: 1,
       currencyCode: "USD",
      },
     isTest: true,
   });
 console.log(chargeBilling);

  // App logic
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const USAGE_PLAN = 'Usage subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [USAGE_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Usage,
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Anchor to example-requestrequest

Anchor to example-using-a-custom-return-urlUsing a custom return URL

Change where the merchant is returned to after approving the purchase using the returnUrl option.

Anchor to example-overriding-plan-settingsOverriding plan settings

Customize the plan for a merchant when requesting billing. Any fields from the plan can be overridden, as long as the billing interval for line items matches the config.

Was this section helpful?

Using a custom return URL

import { LoaderFunctionArgs } from "react-router";

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

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

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

await billing.require({

plans: [MONTHLY_PLAN],

onFailure: async () => billing.request({

plan: MONTHLY_PLAN,

isTest: true,

returnUrl: 'https://admin.shopify.com/store/my-store/apps/my-app/billing-page',

}),

});

// App logic

};

Examples

Using a custom return URL

Description

Change where the merchant is returned to after approving the purchase using the `returnUrl` option.

/app/routes/**\/*.ts

import { LoaderFunctionArgs } from "react-router";
import { authenticate, MONTHLY_PLAN } from "../shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { billing } = await authenticate.admin(request);
  await billing.require({
    plans: [MONTHLY_PLAN],
    onFailure: async () => billing.request({
      plan: MONTHLY_PLAN,
      isTest: true,
      returnUrl: 'https://admin.shopify.com/store/my-store/apps/my-app/billing-page',
    }),
  });

  // App logic
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const MONTHLY_PLAN = 'Monthly subscription';
export const ANNUAL_PLAN = 'Annual subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Every30Days,
        }
      ],
    },
    [ANNUAL_PLAN]: {
      lineItems: [
        {
          amount: 50,
          currencyCode: 'USD',
          interval: BillingInterval.Annual,
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Overriding plan settings

Description

Customize the plan for a merchant when requesting billing. Any fields from the plan can be overridden, as long as the billing interval for line items matches the config.

/app/routes/**\/*.ts

import { LoaderFunctionArgs } from "react-router";
import { authenticate, MONTHLY_PLAN } from "../shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { billing } = await authenticate.admin(request);
  await billing.require({
    plans: [MONTHLY_PLAN],
    onFailure: async () => billing.request({
      plan: MONTHLY_PLAN,
      isTest: true,
      trialDays: 14,
      lineItems: [
        {
          interval: BillingInterval.Every30Days,
          discount: { value: { percentage: 0.1 } },
        },
      ],
    }),
  });

  // App logic
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const MONTHLY_PLAN = 'Monthly subscription';
export const ANNUAL_PLAN = 'Annual subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Every30Days,
        }
      ],
    },
    [ANNUAL_PLAN]: {
      lineItems: [
        {
          amount: 50,
          currencyCode: 'USD',
          interval: BillingInterval.Annual,
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Anchor to example-requirerequire

Anchor to example-requesting-billing-right-awayRequesting billing right away

Call billing.request in the onFailure callback to immediately redirect to the Shopify page to request payment.

Anchor to example-redirect-to-a-plan-selection-pageRedirect to a plan selection page

When the app has multiple plans, create a page in your App that allows the merchant to select a plan. If a merchant does not have the required plan you can redirect them to page in your app to select one.

Was this section helpful?

Requesting billing right away

import { LoaderFunctionArgs } from "react-router";

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

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

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

await billing.require({

plans: [MONTHLY_PLAN],

isTest: true,

onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),

});

// App logic

};

Examples

Requesting billing right away

Description

Call `billing.request` in the `onFailure` callback to immediately redirect to the Shopify page to request payment.

/app/routes/**\/*.ts

import { LoaderFunctionArgs } from "react-router";
import { authenticate, MONTHLY_PLAN } from "../shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { billing } = await authenticate.admin(request);
  await billing.require({
    plans: [MONTHLY_PLAN],
    isTest: true,
    onFailure: async () => billing.request({ plan: MONTHLY_PLAN }),
  });

  // App logic
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const MONTHLY_PLAN = 'Monthly subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Every30Days,
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Redirect to a plan selection page

Description

/app/routes/**\/*.ts

import { LoaderFunctionArgs, redirect } from "react-router";
import { authenticate, MONTHLY_PLAN, ANNUAL_PLAN } from "../shopify.server";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { billing } = await authenticate.admin(request);
  const billingCheck = await billing.require({
    plans: [MONTHLY_PLAN, ANNUAL_PLAN],
    isTest: true,
    onFailure: () => redirect('/select-plan'),
  });

  const subscription = billingCheck.appSubscriptions[0];
  console.log(`Shop is on ${subscription.name} (id ${subscription.id})`);

  // App logic
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const MONTHLY_PLAN = 'Monthly subscription';
export const ANNUAL_PLAN = 'Annual subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [MONTHLY_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Every30Days,
        }
      ],
    },
    [ANNUAL_PLAN]: {
      lineItems: [
        {
          amount: 50,
          currencyCode: 'USD',
          interval: BillingInterval.Annual,
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Anchor to example-updateusagecappedamountupdateUsageCappedAmount

Anchor to example-updating-the-capped-amount-for-a-usage-billing-planUpdating the capped amount for a usage billing plan

Update the capped amount for the usage billing plan specified by subscriptionLineItemId.

Was this section helpful?

Updating the capped amount for a usage billing plan

import { ActionFunctionArgs } from "react-router";

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

export const action = async ({ request }: ActionFunctionArgs) => {

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

await billing.updateUsageCappedAmount({

subscriptionLineItemId: "gid://shopify/AppSubscriptionLineItem/12345?v=1&index=1",

cappedAmount: {

amount: 10,

currencyCode: "USD"

});

// App logic

};

Examples

Updating the capped amount for a usage billing plan

Description

Update the capped amount for the usage billing plan specified by `subscriptionLineItemId`.

/app/routes/**\/*.ts

import { ActionFunctionArgs } from "react-router";
import { authenticate } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
  const { billing } = await authenticate.admin(request);

  await billing.updateUsageCappedAmount({
    subscriptionLineItemId: "gid://shopify/AppSubscriptionLineItem/12345?v=1&index=1",
    cappedAmount: {
      amount: 10,
      currencyCode: "USD"
    },
  });

  // App logic
};

shopify.server.ts

import { shopifyApp, BillingInterval } from "@shopify/shopify-app-react-router/server";

export const USAGE_PLAN = 'Usage subscription';

const shopify = shopifyApp({
  // ...etc
  billing: {
    [USAGE_PLAN]: {
      lineItems: [
        {
          amount: 5,
          currencyCode: 'USD',
          interval: BillingInterval.Usage,
          terms: "Usage based"
        }
      ],
    },
  }
});
export default shopify;
export const authenticate = shopify.authenticate;

Anchor to relatedRelated

Authenticate requests from Shopify Admin.Admin context

Billingobject

Anchor to billingbilling

CancelBillingOptions

CheckBillingOptions

CreateUsageRecordOptions

RequestBillingOptions

RequireBillingOptions

UpdateUsageCappedAmountOptions

Anchor to examplesExamples

Anchor to example-cancelcancel

Examples

Cancelling a subscription

Description

/app/routes/cancel-subscription.ts

shopify.server.ts

Anchor to example-checkcheck

Examples

Check what billing plans a merchant is subscribed to

Description

/app/routes/**\/*.ts

shopify.server.ts

Check for payments without filtering

Description

/app/routes/**\/*.ts

Anchor to example-createusagerecordcreateUsageRecord

Examples

Creating a usage record

Description

/app/routes/create-usage-record.ts

shopify.server.ts

Anchor to example-requestrequest

Examples

Using a custom return URL

Description

/app/routes/**\/*.ts

shopify.server.ts

Overriding plan settings

Description

/app/routes/**\/*.ts

shopify.server.ts

Anchor to example-requirerequire

Examples

Requesting billing right away

Description

/app/routes/**\/*.ts

shopify.server.ts

Redirect to a plan selection page

Description

/app/routes/**\/*.ts

shopify.server.ts

Anchor to example-updateusagecappedamountupdateUsageCappedAmount

Examples

Updating the capped amount for a usage billing plan

Description

/app/routes/**\/*.ts

shopify.server.ts

Anchor to relatedRelated

Billing
object