---
title: Billing
description: |-
  Contains function used to bill merchants for your app.

  This object is returned on authenticated Admin requests.
api_version: v2
api_name: shopify-app-remix
source_url:
  html: 'https://shopify.dev/docs/api/shopify-app-remix/v2/apis/billing'
  md: 'https://shopify.dev/docs/api/shopify-app-remix/v2/apis/billing.md'
---

# Billingobject

Contains function used to bill merchants for your app.

This object is returned on authenticated Admin requests.

## billing

Provides utilities that apps can use to request billing for the app using the Admin API.

* require

  (options: RequireBillingOptions\<Config>) => Promise\<BillingCheckResponseObject>

  required

  Checks if the shop has an active payment for any plan defined in the `billing` config option.

* check

  (options: CheckBillingOptions\<Config>) => Promise\<BillingCheckResponseObject>

  required

  Checks if the shop has an active payment for any plan defined in the `billing` config option.

* request

  (options: RequestBillingOptions\<Config>) => Promise\<never>

  required

  Requests payment for the plan.

* cancel

  (options: CancelBillingOptions) => Promise\<AppSubscription>

  required

  Cancels an ongoing subscription, given its ID.

### RequireBillingOptions

* plans

  The plans to check for. Must be one of the values defined in the \`billing\` config option.

  ```ts
  (keyof Config["billing"])[]
  ```

* onFailure

  How to handle the request if the shop doesn't have an active payment for any plan.

  ```ts
  (error: any) => Promise<Response>
  ```

* isTest

  Whether to consider test purchases.

  ```ts
  boolean
  ```

```ts
export interface RequireBillingOptions<Config extends AppConfigArg>
  extends Omit<BillingCheckParams, 'session' | 'plans' | 'returnObject'> {
  /**
   * The plans to check for. Must be one of the values defined in the `billing` config option.
   */
  plans: (keyof Config['billing'])[];
  /**
   * How to handle the request if the shop doesn't have an active payment for any plan.
   */
  onFailure: (error: any) => Promise<Response>;
}
```

### BillingCheckResponseObject

* hasActivePayment

  Whether the user has an active payment method.

  ```ts
  boolean
  ```

* oneTimePurchases

  The one-time purchases the shop has.

  ```ts
  OneTimePurchase[]
  ```

* appSubscriptions

  The active subscriptions the shop has.

  ```ts
  AppSubscription[]
  ```

```ts
export interface BillingCheckResponseObject {
  /**
   * Whether the user has an active payment method.
   */
  hasActivePayment: boolean;
  /**
   * The one-time purchases the shop has.
   */
  oneTimePurchases: OneTimePurchase[];
  /**
   * The active subscriptions the shop has.
   */
  appSubscriptions: AppSubscription[];
}
```

### OneTimePurchase

* id

  The ID of the one-time purchase.

  ```ts
  string
  ```

* name

  The name of the purchased plan.

  ```ts
  string
  ```

* test

  Whether this is a test purchase.

  ```ts
  boolean
  ```

* status

  The status of the one-time purchase.

  ```ts
  string
  ```

```ts
export interface OneTimePurchase {
  /**
   * The ID of the one-time purchase.
   */
  id: string;
  /**
   * The name of the purchased plan.
   */
  name: string;
  /**
   * Whether this is a test purchase.
   */
  test: boolean;
  /**
   * The status of the one-time purchase.
   */
  status: string;
}
```

### AppSubscription

* id

  The ID of the app subscription.

  ```ts
  string
  ```

* name

  The name of the purchased plan.

  ```ts
  string
  ```

* test

  Whether this is a test subscription.

  ```ts
  boolean
  ```

* lineItems

  ```ts
  ActiveSubscriptionLineItem[]
  ```

```ts
export interface AppSubscription {
  /**
   * The ID of the app subscription.
   */
  id: string;
  /**
   * The name of the purchased plan.
   */
  name: string;
  /**
   * Whether this is a test subscription.
   */
  test: boolean;

  /*
   * The line items for this plan. This will become mandatory in v10.
   */
  lineItems?: ActiveSubscriptionLineItem[];
}
```

### ActiveSubscriptionLineItem

* id

  ```ts
  string
  ```

* plan

  ```ts
  AppPlan
  ```

```ts
export interface ActiveSubscriptionLineItem {
  /*
   * The ID of the line item.
   */
  id: string;
  /*
   * The details of the plan.
   */
  plan: AppPlan;
}
```

### AppPlan

* pricingDetails

  ```ts
  RecurringAppPlan | UsageAppPlan
  ```

```ts
export interface AppPlan {
  /*
   * The pricing details of the plan.
   */
  pricingDetails: RecurringAppPlan | UsageAppPlan;
}
```

### RecurringAppPlan

* interval

  ```ts
  BillingInterval.Every30Days | BillingInterval.Annual
  ```

* price

  ```ts
  Money
  ```

* discount

  ```ts
  AppPlanDiscount
  ```

```ts
export interface RecurringAppPlan {
  /*
   * The interval for this plan is charged on.
   */
  interval: BillingInterval.Every30Days | BillingInterval.Annual;
  /*
   * The price of the plan.
   */
  price: Money;
  /*
   * The discount applied to the plan.
   */
  discount: AppPlanDiscount;
}
```

### BillingInterval

* OneTime

  ```ts
  ONE_TIME
  ```

* Every30Days

  ```ts
  EVERY_30_DAYS
  ```

* Annual

  ```ts
  ANNUAL
  ```

* Usage

  ```ts
  USAGE
  ```

```ts
export enum BillingInterval {
  OneTime = 'ONE_TIME',
  Every30Days = 'EVERY_30_DAYS',
  Annual = 'ANNUAL',
  Usage = 'USAGE',
}
```

### Money

* amount

  ```ts
  number
  ```

* currencyCode

  ```ts
  string
  ```

```ts
interface Money {
  amount: number;
  currencyCode: string;
}
```

### AppPlanDiscount

* durationLimitInIntervals

  ```ts
  number
  ```

* remainingDurationInIntervals

  ```ts
  number
  ```

* priceAfterDiscount

  ```ts
  Money
  ```

* value

  ```ts
  AppPlanDiscountAmount
  ```

```ts
export interface AppPlanDiscount {
  /*
   * The total number of intervals the discount applies to.
   */
  durationLimitInIntervals: number;
  /*
   * The remaining number of intervals the discount applies to.
   */
  remainingDurationInIntervals: number;
  /*
   * The price after the discount is applied.
   */
  priceAfterDiscount: Money;
  /*
   * The value of the discount applied every billing interval.
   */
  value: AppPlanDiscountAmount;
}
```

### AppPlanDiscountAmount

```ts
BillingConfigSubscriptionPlanDiscountAmount | BillingConfigSubscriptionPlanDiscountPercentage
```

### BillingConfigSubscriptionPlanDiscountAmount

* amount

  The amount to discount. Cannot be set if \`percentage\` is set.

  ```ts
  number
  ```

* percentage

  The percentage to discount. Cannot be set if \`amount\` is set.

  ```ts
  never
  ```

```ts
export interface BillingConfigSubscriptionPlanDiscountAmount {
  /**
   * The amount to discount.
   *
   * Cannot be set if `percentage` is set.
   */
  amount: number;
  /**
   * The percentage to discount.
   *
   * Cannot be set if `amount` is set.
   */
  percentage?: never;
}
```

### BillingConfigSubscriptionPlanDiscountPercentage

* amount

  The amount to discount. Cannot be set if \`percentage\` is set.

  ```ts
  never
  ```

* percentage

  The percentage to discount. Cannot be set if \`amount\` is set.

  ```ts
  number
  ```

```ts
export interface BillingConfigSubscriptionPlanDiscountPercentage {
  /**
   * The amount to discount.
   *
   * Cannot be set if `percentage` is set.
   */
  amount?: never;
  /**
   * The percentage to discount.
   *
   * Cannot be set if `amount` is set.
   */
  percentage: number;
}
```

### UsageAppPlan

* balanceUsed

  ```ts
  Money
  ```

* cappedAmount

  ```ts
  Money
  ```

* terms

  ```ts
  string
  ```

```ts
export interface UsageAppPlan {
  /*
   * The total usage records for interval.
   */
  balanceUsed: Money;
  /*
   * The capped amount prevents the merchant from being charged for any usage over that amount during a billing period.
   */
  cappedAmount: Money;
  /*
   * The terms and conditions for app usage pricing.
   */
  terms: string;
}
```

### CheckBillingOptions

* plans

  The plans to check for. Must be one of the values defined in the \`billing\` config option.

  ```ts
  (keyof Config["billing"])[]
  ```

* isTest

  Whether to consider test purchases.

  ```ts
  boolean
  ```

```ts
export interface CheckBillingOptions<Config extends AppConfigArg>
  extends Omit<BillingCheckParams, 'session' | 'plans' | 'returnObject'> {
  /**
   * The plans to check for. Must be one of the values defined in the `billing` config option.
   */
  plans: (keyof Config['billing'])[];
}
```

### RequestBillingOptions

* plan

  The plan to request. Must be one of the values defined in the \`billing\` config option.

  ```ts
  keyof Config["billing"]
  ```

* isTest

  Whether to use the test mode. This prevents the credit card from being charged. Test shops and demo shops cannot be charged.

  ```ts
  boolean
  ```

* returnUrl

  The URL to return to after the merchant approves the payment.

  ```ts
  string
  ```

```ts
export interface RequestBillingOptions<Config extends AppConfigArg>
  extends Omit<BillingRequestParams, 'session' | 'plan' | 'returnObject'> {
  /**
   * The plan to request. Must be one of the values defined in the `billing` config option.
   */
  plan: keyof Config['billing'];
  /**
   * Whether to use the test mode. This prevents the credit card from being charged. Test shops and demo shops cannot be charged.
   */
  isTest?: boolean;
  /**
   * The URL to return to after the merchant approves the payment.
   */
  returnUrl?: string;
}
```

### CancelBillingOptions

* subscriptionId

  The ID of the subscription to cancel.

  ```ts
  string
  ```

* prorate

  Whether to prorate the cancellation.

  ```ts
  boolean
  ```

* isTest

  ```ts
  boolean
  ```

```ts
export interface CancelBillingOptions {
  /**
   * The ID of the subscription to cancel.
   */
  subscriptionId: string;
  /**
   * Whether to prorate the cancellation.
   *
   * {@link https://shopify.dev/docs/apps/billing/subscriptions/cancel-recurring-charges}
   */
  prorate?: boolean;
  /*
   * Whether to use the test mode. This prevents the credit card from being charged. Test shops and demo shops cannot be charged.
   */
  isTest?: boolean;
}
```

## Examples

### require

### check

### request

### cancel

## Related

[Authenticate requests from Shopify Admin. - Admin context](https://shopify.dev/docs/api/shopify-app-remix/authenticate/admin)