Add discount functionality to app billing functions

Author: lizkenyon

.changeset/long-brooms-poke.md

@@ -0,0 +1,5 @@
+---
+'@shopify/shopify-api': minor
+---
+
+Discount functionality for App Billing Fixes #731

docs/guides/billing.md

@@ -5,7 +5,7 @@ The Admin API provides endpoints that enable apps to trigger purchases in the Sh
 
 See the [billing reference](../reference/billing/README.md) for details on how to call those endpoints, using this configuration.
 
-To trigger the billing behaviour, you'll need to set the `billing` value when calling `shopifyApi()`. For example:
+To trigger the billing behaviour, you'll need to set the `billing` value when calling `shopifyApi()`. For example the following configuration will allow you to charge merchants $30 every 30 days. The first three charges will be discounted by $10, so merchants would be charged $20.
 
 ```ts
 import {
@@ -19,9 +19,15 @@ const shopify = shopifyApi({
   billing: {
     'My billing plan': {
       interval: BillingInterval.Every30Days,
-      amount: 1,
+      amount: 30,
       currencyCode: 'USD',
       replacementBehavior: BillingReplacementBehavior.ApplyImmediately,
+      discount: {
+        durationLimitInIntervals: 3,
+        value: {
+          amount: 10,
+        },
+      }
     },
   },
 });
@@ -35,7 +41,7 @@ This setting is a collection of billing plans. Each billing plan allows the foll
 | -------------- | ---------- | :-------: | :-----------: | ---------------------------------------------------------- |
 | `interval`     | `ONE_TIME` |    Yes    |       -       | `BillingInterval.OneTime` value                            |
 | `amount`       | `number`   |    Yes    |       -       | The amount to charge                                       |
-| `currencyCode` | `string`   |    Yes    |       -       | The currency to charge, currently only `"USD"` is accepted |
+| `currencyCode` | `string`   |    Yes    |       -       | The currency to charge, USD or merchant's shop currency |
 
 ### Recurring Billing Plans
 
@@ -46,6 +52,9 @@ This setting is a collection of billing plans. Each billing plan allows the foll
 | `currencyCode`        | `string`                     |    Yes    |       -       | The currency to charge, currently only `"USD"` is accepted                                                                                                   |
 | `trialDays`           | `number`                     |    No     |       -       | Give merchants this many days before charging                                                                                                                |
 | `replacementBehavior` | `BillingReplacementBehavior` |    No     |       -       | `BillingReplacementBehavior` value, see [the reference](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate) for more information. |
+| `discount.durationLimitInIntervals` | `number` | No | - | The number of billing intervals to apply the discount for. See the [reference](https://shopify.dev/docs/apps/billing/purchase-adjustments/subscription-discounts) for more information |
+| `discount.value.amount` | `number` | No | - | The amount of the discount in the currency that the merchant is being billed in. |
+| `discount.value.percentage` | `number` | No | - | The percentage value of the discount. |
 
 ### Usage Billing Plans
 

lib/billing/__tests__/request_payment.test.ts

@@ -230,6 +230,11 @@ describe('shopify.billing.request', () => {
           currencyCode: 'USD',
           interval: BillingInterval.Every30Days,
           replacementBehavior: BillingReplacementBehavior.ApplyImmediately,
+          discount: {
+            value: {
+              amount: 1,
+            },
+          },
           trialDays: 10,
         },
       },

lib/billing/request.ts

@@ -131,6 +131,14 @@ async function requestRecurringPayment({
                   amount: billingConfig.amount,
                   currencyCode: billingConfig.currencyCode,
                 },
+                discount: {
+                  durationLimitInIntervals:
+                    billingConfig.discount?.durationLimitInIntervals,
+                  value: {
+                    amount: billingConfig.discount?.value?.amount,
+                    percentage: billingConfig.discount?.value?.percentage,
+                  },
+                },
               },
             },
           },

lib/billing/types.ts

@@ -18,6 +18,13 @@ export interface BillingConfigSubscriptionPlan extends BillingConfigPlan {
   interval: RecurringBillingIntervals;
   trialDays?: number;
   replacementBehavior?: BillingReplacementBehavior;
+  discount?: {
+    durationLimitInIntervals?: number;
+    value: {
+      amount?: number;
+      percentage?: number;
+    };
+  };
 }
 
 export interface BillingConfigUsagePlan extends BillingConfigPlan {