export interface BillingContext { /** * Checks if the shop has an active payment for any plan defined in the `billing` config option. * * @returns A promise that resolves to an object containing the active purchases for the shop. * * @example * Requesting billing right away. * Call `billing.request` in the `onFailure` callback to immediately redirect to the Shopify page to request payment. * ```ts * // /app/routes/**\/*.ts * import { LoaderFunctionArgs } from "@remix-run/node"; * 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 * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` * * @example * Redirect 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. * ```ts * // /app/routes/**\/*.ts * import { LoaderFunctionArgs, redirect } from "@remix-run/node"; * 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 * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` */ require: ( options: RequireBillingOptions, ) => Promise; /** * Checks if the shop has an active payment for any plan defined in the `billing` config option. * * @returns A promise that resolves to an object containing the active purchases for the shop. * * @example * Check 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 not * throw an error if no active billing plans are present. * ```ts * // /app/routes/**\/*.ts * import { LoaderFunctionArgs } from "@remix-run/node"; * 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); * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` * * @example * Check for payments without filtering. * Use billing.check to see if any payments exist for the store, regardless of whether it's a test or * matches one or more plans. * ```ts * // /app/routes/**\/*.ts * import { LoaderFunctionArgs } from "@remix-run/node"; * 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); * }; * ``` */ check: >( options?: Options, ) => Promise; /** * Requests payment for the plan. * * @returns Redirects to the confirmation URL for the payment. * * @example * Using a custom return URL. * Change where the merchant is returned to after approving the purchase using the `returnUrl` option. * ```ts * // /app/routes/**\/*.ts * import { LoaderFunctionArgs } from "@remix-run/node"; * 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 * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` * * @example * Overriding 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. * ```ts * // /app/routes/**\/*.ts * import { LoaderFunctionArgs } from "@remix-run/node"; * 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 * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` */ request: (options: RequestBillingOptions) => Promise; /** * Cancels an ongoing subscription, given its ID. * * @returns The cancelled subscription. * * @example * Cancelling a subscription. * Use the `billing.cancel` function to cancel an active subscription with the id returned from `billing.require`. * ```ts * // /app/routes/cancel-subscription.ts * import { LoaderFunctionArgs } from "@remix-run/node"; * 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 * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` */ cancel: (options: CancelBillingOptions) => Promise; /** * Creates a usage record for an app subscription. * * @returns Returns a usage record when one was created successfully. * * @example * Creating a usage record * Create a usage record for the active usage billing plan * ```ts * // /app/routes/create-usage-record.ts * import { ActionFunctionArgs } from "@remix-run/node"; * 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 * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` */ createUsageRecord: ( options: CreateUsageRecordOptions, ) => Promise; /** * Updates the capped amount for a usage billing plan. * * @returns Redirects to a confirmation page to update the usage billing plan. * * @example * Updating the capped amount for a usage billing plan. * Update the capped amount for the usage billing plan specified by `subscriptionLineItemId`. * ```ts * // /app/routes/**\/*.ts * import { ActionFunctionArgs } from "@remix-run/node"; * 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 * }; * ``` * ```ts * // shopify.server.ts * import { shopifyApp, BillingInterval } from "@shopify/shopify-app-remix/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; * ``` */ updateUsageCappedAmount: ( options: UpdateUsageCappedAmountOptions, ) => Promise; }