DOCS-3667: Document annual billing feature for subscription billing model (#4447)

Author: promptless[bot]

docs/dev/reference/changelog.md

@@ -42,6 +42,14 @@ date: "2024-09-18"
 # updated: ""  # When the content was last entirely checked
 ---
 
+{{% changelog color="added" title="Annual billing support for subscription billing model" date="2025-07-23" %}}
+
+You can now configure annual billing alongside monthly billing options for your organizations.
+See [white-labelled billing documentation](/manage/manage/white-labelled-billing/) for configuration details.
+applications/).
+
+{{% /changelog %}}
+
 {{% changelog color="added" title="Build custom Viam applications" date="2025-07-17" %}}
 
 You can now create and use Viam applications to build custom applications that interact with your Viam-powered machines through the Viam SDKs.

docs/manage/manage/white-labelled-billing.md

@@ -100,33 +100,19 @@ https://app.viam.com/billing/<public-namespace>?id=<org-id>
 
 ## Set custom pricing
 
-To use custom billing, add a billing configuration the fragment you use for your machine configurations.
+To use custom billing, add a billing configuration to a fragment.
 
 1. Navigate to the **FLEET** page.
 1. Go to the [**FRAGMENTS** tab](https://app.viam.com/fragments).
 1. Select the fragment you use for your machines.
 1. Click **+** and add **Billing**
 1. Adjust attributes as needed.
+1. Mark the fragment as public or unlisted.
 1. Save the fragment.
+1. Add the fragment to the machines that you want to bill for.
 
 {{< tabs >}}
-{{% tab name="Example" %}}
-
-```json { class="line-numbers linkable-line-numbers" }
-{
-  "components": { ... },
-  "services" : { ... },
-  "billing": {
-    "cost_per_month": {
-      "per_machine": 10
-    },
-    "tier_name": "not-free"
-  }
-}
-```
-
-{{% /tab %}}
-{{% tab name="Full Template" %}}
+{{% tab name="Full Template (monthly)" %}}
 
 ```json
 {
@@ -146,7 +132,62 @@ To use custom billing, add a billing configuration the fragment you use for your
     },
     "tier_name": "example-tier",
     "description": "",
-    "tier_credit": 0.0
+    "tier_credit": 0.0,
+    "in_arrears": true
+  }
+}
+```
+
+{{% /tab %}}
+{{% tab name="Full Template (yearly)" %}}
+
+```json
+{
+  "billing": {
+    "cost_per_year": {
+      "per_machine": 0
+    },
+    "tier_name": "example-tier",
+    "description": "",
+    "tier_credit": 0.0,
+    "in_arrears": false
+  }
+}
+```
+
+{{% /tab %}}
+{{% tab name="Example (monthly)" %}}
+
+This configuration charges customers every month in arrears, which means after usage:
+
+```json { class="line-numbers linkable-line-numbers" }
+{
+  "billing": {
+    "cost_per_month": {
+      "per_machine": 10,
+      "binary_data_upload_bytes": 0.01
+    },
+    "tier_name": "monthly-tier",
+    "in_arrears": true
+  }
+}
+```
+
+By setting `"in_arrears": false` you can change the configuration to charge customers upfront.
+
+{{% /tab %}}
+{{% tab name="Example (yearly)" %}}
+
+This configuration charges customers every 12 months, with upfront payment:
+
+```json { class="line-numbers linkable-line-numbers" }
+{
+  "billing": {
+    "cost_per_year": {
+      "per_machine": 100
+    },
+    "tier_name": "annual-tier",
+    "in_arrears": false
   }
 }
 ```
@@ -159,11 +200,12 @@ To use custom billing, add a billing configuration the fragment you use for your
 <!-- prettier-ignore -->
 | Name | Type | Required? | Description |
 | ---- | ---- | --------- | ----------- |
-| `cost_per_month` | object | Optional | See [cost per month attributes](/manage/manage/white-labelled-billing/#click-to-view-cost-per-month-attributes). Default: `{}` (all machines cost `0`). |
-| `cost_per_year` | object | Optional | See [cost per year attributes](/manage/manage/white-labelled-billing/#click-to-view-cost-per-year-attributes). Default: `{}` (all machines cost `0`). |
+| `cost_per_month` | object | Optional | See [cost per month attributes](/manage/manage/white-labelled-billing/#click-to-view-cost-per-month-attributes). If specified, you cannot also specify `cost_per_year`. Default: `{}` (all machines cost `0`). |
+| `cost_per_year` | object | Optional | See [cost per year attributes](/manage/manage/white-labelled-billing/#click-to-view-cost-per-year-attributes). If specified, you cannot also specify `cost_per_month`. Default: `{}` (all machines cost `0`). |
 | `tier_name` | string | **Required** | The name of the billing tier. |
-| `description` |  | Optional | Description for the billing tier. Default: `""`. |
+| `description` | string | Optional | Description for the billing tier. Default: `""`. |
 | `tier_credit` | number | Optional | Credit that should be applied to final total for the org. Default: `0`. |
+| `in_arrears` | boolean | Optional | Whether billing is charged in arrears (after usage) or upfront. For monthly billing, set to `true` for billing after usage and `false` for upfront billing. If set to `false` you can only set the `per_machine` attribute in `cost_per_month`. For annual billing, `in_arrears` must be set to `false`. Default: `false`. |
 
 {{% /expand%}}
 
@@ -204,3 +246,26 @@ Payments for white-labeled billing go directly to Viam. To arrange reimbursement
 ### Can I customize the billing page further?
 
 If you need further customization, please [contact us](mailto:[email protected]).
+
+### How does renewal work?
+
+Renewal is automatic for upfront annual billing and for upfront monthly billing.
+For monthly billing after usage, if there is no usage, there is no charge.
+If the `per_machine` field is set, then a machine existing, is considered usage.
+
+### When are invoices generated?
+
+- **Monthly billing (`in_arrears: true`)**: Invoices are generated on the first day of the month and customers are charged at the end of each month for the per machine cost and usage during that month.
+  For example, if you set up a machine on June 20, you'll get an invoice on July 1 for 10 days of usage. Then you'll get the next invoice on August 1 for the usage in July.
+- **Monthly billing (`in_arrears: false`)**: Invoices are generated shortly after the billing fragment is added to the machine and customers are charged at the beginning of each new month of usage for the per machine cost.
+  For example, if you set up a monthly upfront machine on June 20, you'll get an invoice shortly after on the same day.
+  Then you'll get the next invoice on July 20, then August 20, and so on.
+- **Annual billing (`in_arrears: false`)**: Invoices are generated shortly after the billing fragment is added to the machine and customers are charged at the beginning of each new year of usage for the per machine cost.
+  For example, if you set up an annual upfront machine on June 20, you'll get an invoice shortly after on the same day.
+  Then you'll get the next invoice on June 20 the following year.
+
+### Can customers switch between monthly and annual billing?
+
+Yes. However, switching billing fragments will result in the new charge immediately taking effect.
+We recommend that you wait until the end of the current billing cycle to remove the old billing
+fragment and assign the new billing fragment.

docs/manage/reference/billing.md

@@ -20,11 +20,11 @@ You must be an [organization owner](/manage/manage/rbac/) to see this page.
 
 The **Payment and billing** page shows you:
 
-- your usage for the current month
+- your usage for the current billing period
 - the date for your next invoice
 - the payment method on the account
 - a cost breakdown for cloud storage, cloud data upload, cloud data egress, remote control, and standard compute costs
-- all your monthly invoices
+- all your invoices (monthly or annual depending on your billing configuration)
 
 {{< alert title="Note" color="note" >}}
 
@@ -60,12 +60,16 @@ Organizations without valid payment methods may experience limitations on their
 
 ## Download an invoice
 
-You can view all your monthly invoices for your organization:
+You can view all your invoices for your organization:
 
 1. Click on the organization name in the top right of the navigation bar and then click on **Payment and billing**.
    You must be an [organization owner](https://docs.viam.com/manage/manage/rbac/) to see this page.
 1. Find the **Invoices** section of the **Payment & Billing** page.
-1. Click on **Download (PDF)** next to the relevant month.
+1. Click on **Download (PDF)** next to the relevant billing period.
+
+{{< alert title="Note" color="note" >}}
+Invoices may be generated monthly or annually depending on your billing configuration. Organizations using annual billing will receive invoices every 12 months instead of monthly.
+{{< /alert >}}
 
 ## Set billing alerts
 
@@ -74,7 +78,7 @@ You can set alerts to receive an email notification when your monthly spend exce
 1. Click on the organization name in the top right of the navigation bar and then click on **Payment and billing**.
    You must be an [organization owner](https://docs.viam.com/manage/manage/rbac/) to see this page.
 1. Scroll to the bottom of the **Payment & Billing** page.
-1. Click **Set amount** and enter a monthly threshold.
+1. Click **Set amount** and enter a monthly threshold amount.
 
 ## Receive billing emails at a different email or and email alias
 

static/include/app/apis/generated/billing.md

@@ -1,6 +1,7 @@
 ### GetCurrentMonthUsage
 
-Access data usage information for the current month for a given organization.
+Access data usage information for the current billing period for a given organization.
+This method only returns usage for organizations with monthly billing at the end of the month (`"in_arrears": true`).
 You can also find your usage data on the [**Payment and billing** page](/manage/reference/billing/).
 
 {{< tabs >}}
@@ -96,7 +97,8 @@ For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/
 
 ### GetInvoicesSummary
 
-Access total outstanding balance plus invoice summaries for a given org.
+Access total outstanding balance plus invoice summaries for a given organization.
+This includes both monthly and annual invoices depending on the organization's billing configuration.
 
 {{< tabs >}}
 {{% tab name="Python" %}}

static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md

@@ -1,2 +1,3 @@
-Access data usage information for the current month for a given organization.
+Access data usage information for the current billing period for a given organization.
+This method only returns usage for organizations with monthly billing at the end of the month (`"in_arrears": true`).
 You can also find your usage data on the [**Payment and billing** page](/manage/reference/billing/).

static/include/app/apis/overrides/protos/billing.GetInvoicesSummary.md

@@ -1 +1,2 @@
-Access total outstanding balance plus invoice summaries for a given org.
+Access total outstanding balance plus invoice summaries for a given organization.
+This includes both monthly and annual invoices depending on the organization's billing configuration.