Document iOS monthly billing plans support

content/docs/dashboard/charts/index.mdx

@@ -152,6 +152,12 @@ When you're done, **click** on the **Apply** button, and the chart will refresh
 
 <Frame>![](/images/chartsv2_filterResult.jpeg)</Frame>
 
+<Note>
+  On iOS revenue charts, use **Billing Plan Type** to filter revenue by App Store billing plan.
+  The available values are `MONTHLY` and `UP_FRONT`. This filter is only available for supported
+  iOS revenue charts and is ignored for non-iOS apps or charts that do not use revenue events.
+</Note>
+
 To remove an individual filter, **click** on the **trash can** icon on the trailing side of it:
 
 <Frame>![](/images/chartsv2_remove.jpeg)</Frame>
@@ -173,6 +179,8 @@ The breakdowns available are tailored to the type of chart you have selected. Af
 
 <Frame>![](/images/chartsv2_breakdownResult.jpeg)</Frame>
 
+For annual iOS subscriptions that use [monthly billing plans](/dashboard/products#monthly-billing-plans-for-annual-ios-subscriptions), supported revenue charts can also be broken down by **Billing Plan Type** to compare monthly-installment revenue against up-front annual revenue.
+
 <Tip>Breaking down a **Proceeds** chart by **Placements** is a powerful way to directly correlate features you make, or similar things you've paywalled, to your app's revenue growth.</Tip>
 
 ### Selecting time ranges

content/docs/dashboard/dashboard-creating-paywalls/paywall-editor-products.mdx

@@ -105,6 +105,21 @@ You can display as many products as you see fit on your paywall. Superwall will
 It's important to remember that _you_ retain full control over which of your products show in a paywall, and how. For example, use them along with [dynamic values](/dashboard/dashboard-creating-paywalls/paywall-editor-dynamic-values) to hide or show them to create any U.X. your design calls for.
 </Tip>
 
+### Choosing a billing plan for annual iOS subscriptions
+
+If an annual iOS App Store product has a [monthly billing plan](/dashboard/products#monthly-billing-plans-for-annual-ios-subscriptions), the product entry shows a **Billing plan** control after you add it to a paywall.
+
+Choose:
+
+| Option | What it does |
+| ------ | ------------ |
+| Monthly installments | Presents Apple's monthly billing plan where available. This is the default for products that offer a monthly billing plan. |
+| Up-front | Presents the up-front annual billing plan for this paywall slot. |
+
+This choice is stored per paywall product slot. That means the same annual App Store product can appear as monthly installments on one paywall and up-front annual billing on another paywall.
+
+The iOS SDK applies the selected plan during StoreKit 2 purchase on iOS SDK `4.16.0` or later. If the user's device or storefront cannot use the selected billing plan, StoreKit falls back to Apple's default plan. Use `products.selected.isBillingPlanAvailable` or the matching product variable to hide billing-plan-specific copy when the plan is not available.
+
 ### Understanding the selected product and selected product index variables
 
 The `products.selected` variable will always represent any product the user has selected on your paywall. By default, it will be the _first_ product you've added. In addition, the `products.selectedIndex` variable will also be updated as products are selected. This opens up many patterns to use, such as customizing copy, images, videos, or anything else based on which product the user has tapped on. 

content/docs/dashboard/dashboard-creating-paywalls/paywall-editor-variables.mdx

@@ -193,6 +193,8 @@ Reference any of the variables above by using the `device` variable. For example
 | Currency Symbol | Text | $ |
 | Daily Price | Text | $0.26 |
 | Identifier | Text | efc.1m799.3dt |
+| Billing Plan Type | Text | MONTHLY |
+| Is Billing Plan Available | Bool | True/False |
 | Lanauge Code | Text | en |
 | Locale | Text | en_US@currency=USD |
 | Localized Period | Text | 1m |
@@ -225,6 +227,15 @@ The values above apply to any referenced product. There is the notion of a **pri
 
 For example, to reference the price of the selected product (i.e. one the user has clicked or tapped on within the paywall) — you could write `The selected product cost {{ products.selected.price }}`.
 
+For annual iOS App Store products with a [monthly billing plan](/dashboard/products#monthly-billing-plans-for-annual-ios-subscriptions), each product also exposes billing plan variables:
+
+| Variable | Values | Use it for |
+| -------- | ------ | ---------- |
+| `billingPlanType` | `MONTHLY`, `UP_FRONT`, or empty | Showing which plan the product will use when Apple can honor it. |
+| `isBillingPlanAvailable` | `true` or `false` | Hiding monthly-installment copy when the selected billing plan is unavailable on the user's device or storefront. |
+
+For example, use `products.selected.isBillingPlanAvailable` with [dynamic values](/dashboard/dashboard-creating-paywalls/paywall-editor-dynamic-values) before showing copy such as "Billed monthly for 12 months."
+
 There are also stock variables that deal with products, but aren't part of a single product variable itself. They are referenced via the `products` variable:
 
 | Property               | Type   | Example    |

content/docs/dashboard/products.mdx

@@ -121,6 +121,31 @@ When you're done, click **Save**.
 
 Note that the pricing information you enter here is **only** used in the Paywall Editor for App Store and Google Play products. On device, that information is pulled directly from the App Store or Google Play Store and will be localized. For iOS Custom Store Products, the SDK uses the product metadata from Superwall and routes purchase attempts to your `PurchaseController`.
 
+## Monthly billing plans for annual iOS subscriptions
+
+Annual App Store subscriptions can offer Apple's monthly billing plan, where the customer is billed monthly with a 12-month commitment. Use this when the same annual subscription should be merchandised as either a monthly-installment plan or an up-front annual plan.
+
+Before adding the plan in Superwall:
+
+- Configure the monthly billing plan for the annual subscription in App Store Connect.
+- Use an iOS App Store product with **Period** set to **1 year** in Superwall.
+- Use iOS SDK `4.16.0` or later in your app.
+
+To add the plan to a product:
+
+1. Open the iOS App Store product in **Products**.
+2. Make sure **Period** is set to **1 year**.
+3. Click **Add monthly billing plan**.
+4. Enter the **Monthly price**.
+5. If the monthly plan has its own introductory offer, configure **Monthly trial**.
+6. Click **Save**.
+
+<Frame>![Annual App Store subscription monthly billing plan setup](/images/12monthsetup.jpg)</Frame>
+
+The monthly price and monthly trial values are used for Paywall Editor previews. On device, the iOS SDK reads the matching StoreKit pricing term and uses App Store localized pricing. If the device or storefront cannot use the monthly billing plan, the purchase falls back to Apple's default billing plan for the product.
+
+After the product has a monthly billing plan, each paywall product slot can choose whether to present **Monthly installments** or **Up-front**. See [Products in the Paywall Editor](/dashboard/dashboard-creating-paywalls/paywall-editor-products#choosing-a-billing-plan-for-annual-ios-subscriptions).
+
 <Warning>
   Take care to make sure your product identifier is correct and matches its storefront. This is the
   most common cause for products not working correctly when testing.