From 5563efccf436d958846716e432c073c6193ffb53 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Thu, 3 Jul 2025 15:10:24 +0000 Subject: [PATCH 01/19] Documentation updates from Promptless --- docs/dev/reference/changelog.md | 13 ++ docs/manage/manage/annual-billing.md | 205 ++++++++++++++++++ docs/manage/manage/white-labelled-billing.md | 65 +++++- docs/manage/reference/billing.md | 20 +- static/include/app/apis/generated/billing.md | 6 +- .../protos/billing.GetCurrentMonthUsage.md | 3 +- .../protos/billing.GetInvoicesSummary.md | 3 +- 7 files changed, 301 insertions(+), 14 deletions(-) create mode 100644 docs/manage/manage/annual-billing.md diff --git a/docs/dev/reference/changelog.md b/docs/dev/reference/changelog.md index b9c3162323..9b18270532 100644 --- a/docs/dev/reference/changelog.md +++ b/docs/dev/reference/changelog.md @@ -42,6 +42,19 @@ 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-03" %}} + +Organizations can now configure annual billing alongside monthly billing options. This includes: + +- **Annual pricing**: Configure `cost_per_year` in billing fragments for 12-month billing cycles +- **Upfront billing**: Set `in_arrears: false` to charge customers upfront instead of in arrears +- **Flexible billing models**: Offer monthly, annual, or combined billing options to customers +- **Enhanced billing workflows**: Support for annual invoices and billing cycle management + +This feature improves allows you to configure annual subscription options. See [white-labelled billing documentation](/manage/manage/white-labelled-billing/) for configuration details. + +{{% /changelog %}} + {{% changelog color="added" title="Data regions for organizations" date="2025-06-30" %}} Organizations can now specify continent-level [data regions](/manage/manage/data-regions/) (North America or Europe) to control where data is geographically stored. You can only change this region in organizations that have not yet synced any data. diff --git a/docs/manage/manage/annual-billing.md b/docs/manage/manage/annual-billing.md new file mode 100644 index 0000000000..9bb2c22fd9 --- /dev/null +++ b/docs/manage/manage/annual-billing.md @@ -0,0 +1,205 @@ +--- +title: "Annual Billing" +linkTitle: "Annual Billing" +weight: 75 +layout: "docs" +type: "docs" +description: "Configure annual billing for improved revenue retention and customer flexibility." +date: "2025-07-03" +--- + +Viam's annual billing feature allows organizations to offer 12-month subscription billing cycles alongside traditional monthly billing. This feature helps improve revenue retention by providing customers with annual pricing options and reduces churn from seasonal cancellations. + +## Key Features + +Annual billing provides several advantages over monthly-only billing: + +- **Revenue retention**: Customers commit to longer billing cycles, reducing seasonal cancellations +- **Upfront payment options**: Charge customers immediately rather than in arrears +- **Flexible pricing models**: Offer monthly, annual, or combined billing options +- **Automated billing cycles**: Handle 12-month billing periods automatically +- **Enhanced invoicing**: Generate annual invoices with proper billing period tracking + +## Billing Configuration Options + +You can configure billing in three ways: + +### Monthly Billing Only +Traditional monthly billing charged in arrears (after usage): + +```json +{ + "billing": { + "cost_per_month": { + "per_machine": 10 + }, + "tier_name": "monthly-tier", + "in_arrears": true + } +} +``` + +### Annual Billing Only +Annual billing with upfront payment: + +```json +{ + "billing": { + "cost_per_year": { + "per_machine": 100 + }, + "tier_name": "annual-tier", + "in_arrears": false + } +} +``` + +### Combined Billing +Offer both monthly and annual options: + +```json +{ + "billing": { + "cost_per_month": { + "per_machine": 10 + }, + "cost_per_year": { + "per_machine": 100 + }, + "tier_name": "flexible-tier", + "in_arrears": true + } +} +``` + +## Configuration Attributes + +### Core Billing Attributes + + +| Name | Type | Required? | Description | +| ---- | ---- | --------- | ----------- | +| `cost_per_month` | object | Optional | Monthly pricing configuration. See [monthly pricing attributes](#monthly-pricing-attributes). | +| `cost_per_year` | object | Optional | Annual pricing configuration. See [annual pricing attributes](#annual-pricing-attributes). | +| `tier_name` | string | **Required** | The name of the billing tier. | +| `description` | string | Optional | Description for the billing tier. Default: `""`. | +| `tier_credit` | number | Optional | Credit applied to final total for the organization. Default: `0`. | +| `in_arrears` | boolean | Optional | Whether billing is charged in arrears (after usage) or upfront. Set to `true` for monthly billing in arrears, `false` for upfront annual billing. Default: `true`. | + +### Annual Pricing Attributes + + +| Name | Type | Required? | Description | +| ---- | ---- | --------- | ----------- | +| `per_machine` | number | Optional | Charge a flat annual fee per machine. Default: `0`. | + +### Monthly Pricing Attributes + + +| Name | Type | Required? | Description | +| ---- | ---- | --------- | ----------- | +| `per_machine` | number | Optional | Charge a flat monthly fee per machine. Default: `0`. | +| `binary_data_upload_bytes` | float | Optional | Cost per byte for binary data upload. Default: `0`. | +| `binary_data_egress_bytes` | float | Optional | Cost per byte for binary data download. Default: `0`. | +| `binary_data_cloud_storage_bytes` | float | Optional | Cost per byte per month for binary data stored. Default: `0`. | +| `tabular_data_upload_bytes` | float | Optional | Cost per byte per month for tabular data upload. Default: `0`. | +| `tabular_data_egress_bytes` | float | Optional | Cost per byte per month for tabular data egress. Default: `0`. | +| `tabular_data_cloud_storage_bytes` | float | Optional | Cost per byte per month for tabular data cloud storage. Default: `0`. | +| `history_cloud_storage_bytes` | float | Optional | Cost per byte per month for config history stored. Default: `0`. | +| `logs_cloud_storage_bytes` | float | Optional | Cost per byte per month for logs cloud storage. Default: `0`. | +| `logs_data_upload_bytes` | float | Optional | Cost per byte per month for logs data upload. Default: `0`. | +| `logs_data_egress_bytes` | float | Optional | Cost per byte per month for logs data egress. Default: `0`. | + +## Billing Behavior + +### Payment Timing + +- **Monthly billing (`in_arrears: true`)**: Customers are charged at the end of each month for usage during that month +- **Annual billing (`in_arrears: false`)**: Customers are charged upfront at the beginning of each 12-month period + +### Invoice Generation + +- **Monthly billing**: Invoices are generated monthly with usage from the previous month +- **Annual billing**: Invoices are generated every 12 months for the upcoming annual period +- **Combined billing**: Customers can choose between monthly and annual billing cycles + +### Billing Cycle Management + +Annual billing automatically handles: + +- 12-month billing periods starting from the initial subscription date +- Automatic renewal after each 12-month cycle +- Proper invoice timing and generation +- Usage tracking across annual periods + +## Implementation Considerations + +### Migration from Monthly to Annual + +When migrating existing customers from monthly to annual billing: + +1. **Timing**: Consider waiting until the next billing cycle to avoid mid-cycle complications +2. **Communication**: Notify customers about billing cycle changes in advance +3. **Pricing**: Ensure annual pricing provides appropriate value compared to monthly rates + +### Pricing Strategy + +When setting annual pricing: + +- **Discount incentive**: Annual pricing typically offers savings compared to 12 months of monthly billing +- **Cash flow**: Consider the impact of upfront payments on your cash flow +- **Customer value**: Balance customer savings with revenue optimization + +### Technical Requirements + +Annual billing requires: + +- Updated billing fragments with `cost_per_year` configuration +- Proper `in_arrears` setting based on payment timing preferences +- Billing system configuration to handle 12-month cycles +- Invoice templates updated for annual billing periods + +## Use Cases + +### Seasonal Business Models + +Annual billing is particularly valuable for businesses with seasonal usage patterns: + +- **Boating industry**: Customers might cancel during off-season without annual commitments +- **Agricultural applications**: Seasonal farming operations benefit from annual pricing +- **Tourism and recreation**: Businesses with seasonal peaks can maintain year-round revenue + +### Enterprise Customers + +Large organizations often prefer annual billing for: + +- **Budget planning**: Annual costs are easier to budget and approve +- **Procurement processes**: Many enterprises prefer annual contracts +- **Cost savings**: Annual discounts provide value to enterprise customers + +## Troubleshooting + +### Common Issues + +**Billing cycle confusion**: Ensure customers understand when they'll be charged and for what period. + +**Invoice timing**: Annual invoices are generated at the beginning of each 12-month period, not at calendar year boundaries. + +**Mixed billing models**: When offering both monthly and annual options, ensure clear communication about which option customers have selected. + +### Configuration Validation + +Verify your billing configuration: + +1. **Required fields**: Ensure `tier_name` is set +2. **Pricing consistency**: Check that annual pricing provides appropriate value +3. **Payment timing**: Confirm `in_arrears` setting matches your business model +4. **Fragment deployment**: Ensure billing fragments are properly deployed to target machines + +## Support + +For questions about annual billing configuration or implementation: + +- **Technical support**: [Contact Viam support](mailto:support@viam.com) +- **Billing questions**: [Contact billing team](mailto:billing@viam.com) +- **White-labelled billing**: See [white-labelled billing documentation](/manage/manage/white-labelled-billing/) \ No newline at end of file diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 54bf6b7049..8e87a72152 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -102,6 +102,12 @@ https://app.viam.com/billing/?id= To use custom billing, add a billing configuration the fragment you use for your machine configurations. +You can configure monthly billing, annual billing, or both depending on your pricing model: + +- **Monthly billing**: Charges customers every month in arrears (after usage) +- **Annual billing**: Charges customers every 12 months, with optional upfront payment +- **Combined billing**: Offer both monthly and annual options to give customers flexibility + 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. @@ -110,7 +116,41 @@ To use custom billing, add a billing configuration the fragment you use for your 1. Save the fragment. {{< tabs >}} -{{% tab name="Example" %}} +{{% tab name="Monthly Billing Example" %}} + +```json { class="line-numbers linkable-line-numbers" } +{ + "components": { ... }, + "services" : { ... }, + "billing": { + "cost_per_month": { + "per_machine": 10 + }, + "tier_name": "monthly-tier", + "in_arrears": true + } +} +``` + +{{% /tab %}} +{{% tab name="Annual Billing Example" %}} + +```json { class="line-numbers linkable-line-numbers" } +{ + "components": { ... }, + "services" : { ... }, + "billing": { + "cost_per_year": { + "per_machine": 100 + }, + "tier_name": "annual-tier", + "in_arrears": false + } +} +``` + +{{% /tab %}} +{{% tab name="Combined Billing Example" %}} ```json { class="line-numbers linkable-line-numbers" } { @@ -120,7 +160,11 @@ To use custom billing, add a billing configuration the fragment you use for your "cost_per_month": { "per_machine": 10 }, - "tier_name": "not-free" + "cost_per_year": { + "per_machine": 100 + }, + "tier_name": "flexible-tier", + "in_arrears": true } } ``` @@ -144,9 +188,13 @@ To use custom billing, add a billing configuration the fragment you use for your "logs_data_upload_bytes": 0.0, "logs_data_egress_bytes": 0.0 }, + "cost_per_year": { + "per_machine": 0 + }, "tier_name": "example-tier", "description": "", - "tier_credit": 0.0 + "tier_credit": 0.0, + "in_arrears": true } } ``` @@ -162,8 +210,9 @@ To use custom billing, add a billing configuration the fragment you use for your | `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`). | | `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. Set to `true` for monthly billing in arrears, `false` for upfront annual billing. Default: `true`. | {{% /expand%}} @@ -204,3 +253,11 @@ 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:support@viam.com). + +### How do I implement annual billing? + +For detailed information about annual billing configuration, billing cycles, and implementation considerations, see the [Annual Billing guide](/manage/manage/annual-billing/). + +### Can I offer both monthly and annual billing options? + +Yes, you can configure billing fragments with both `cost_per_month` and `cost_per_year` to give customers flexibility in choosing their preferred billing cycle. See the [Combined Billing Example](#set-custom-pricing) above. diff --git a/docs/manage/reference/billing.md b/docs/manage/reference/billing.md index b495f8044f..70f97e4bd9 100644 --- a/docs/manage/reference/billing.md +++ b/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,21 +60,29 @@ 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 -You can set alerts to receive an email notification when your monthly spend exceeds a certain threshold: +You can set alerts to receive an email notification when your spend exceeds a certain threshold: 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 threshold amount. + +{{< alert title="Note" color="note" >}} +For organizations with annual billing, alerts are based on cumulative spending within the annual billing cycle rather than monthly spending. +{{< /alert >}} ## Help diff --git a/static/include/app/apis/generated/billing.md b/static/include/app/apis/generated/billing.md index 0bcecc8925..cae023b492 100644 --- a/static/include/app/apis/generated/billing.md +++ b/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. +For organizations with monthly billing, this returns current month usage. For organizations with annual billing, this returns usage within the current annual billing cycle. 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" %}} diff --git a/static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md b/static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md index 6cd59b10a0..f1b6d69439 100644 --- a/static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md +++ b/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. +For organizations with monthly billing, this returns current month usage. For organizations with annual billing, this returns usage within the current annual billing cycle. You can also find your usage data on the [**Payment and billing** page](/manage/reference/billing/). diff --git a/static/include/app/apis/overrides/protos/billing.GetInvoicesSummary.md b/static/include/app/apis/overrides/protos/billing.GetInvoicesSummary.md index a2649dcf30..e8bc65399c 100644 --- a/static/include/app/apis/overrides/protos/billing.GetInvoicesSummary.md +++ b/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. From ae4e377e83ec3432b87e3c4b1601b0d1ca0eac4f Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 3 Jul 2025 18:20:13 +0200 Subject: [PATCH 02/19] Simplify --- docs/dev/reference/changelog.md | 10 +- docs/manage/manage/annual-billing.md | 205 ------------------- docs/manage/manage/white-labelled-billing.md | 100 ++++----- 3 files changed, 55 insertions(+), 260 deletions(-) delete mode 100644 docs/manage/manage/annual-billing.md diff --git a/docs/dev/reference/changelog.md b/docs/dev/reference/changelog.md index 9b18270532..d32f095446 100644 --- a/docs/dev/reference/changelog.md +++ b/docs/dev/reference/changelog.md @@ -44,14 +44,8 @@ date: "2024-09-18" {{% changelog color="added" title="Annual billing support for subscription billing model" date="2025-07-03" %}} -Organizations can now configure annual billing alongside monthly billing options. This includes: - -- **Annual pricing**: Configure `cost_per_year` in billing fragments for 12-month billing cycles -- **Upfront billing**: Set `in_arrears: false` to charge customers upfront instead of in arrears -- **Flexible billing models**: Offer monthly, annual, or combined billing options to customers -- **Enhanced billing workflows**: Support for annual invoices and billing cycle management - -This feature improves allows you to configure annual subscription options. See [white-labelled billing documentation](/manage/manage/white-labelled-billing/) for configuration details. +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. {{% /changelog %}} diff --git a/docs/manage/manage/annual-billing.md b/docs/manage/manage/annual-billing.md deleted file mode 100644 index 9bb2c22fd9..0000000000 --- a/docs/manage/manage/annual-billing.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: "Annual Billing" -linkTitle: "Annual Billing" -weight: 75 -layout: "docs" -type: "docs" -description: "Configure annual billing for improved revenue retention and customer flexibility." -date: "2025-07-03" ---- - -Viam's annual billing feature allows organizations to offer 12-month subscription billing cycles alongside traditional monthly billing. This feature helps improve revenue retention by providing customers with annual pricing options and reduces churn from seasonal cancellations. - -## Key Features - -Annual billing provides several advantages over monthly-only billing: - -- **Revenue retention**: Customers commit to longer billing cycles, reducing seasonal cancellations -- **Upfront payment options**: Charge customers immediately rather than in arrears -- **Flexible pricing models**: Offer monthly, annual, or combined billing options -- **Automated billing cycles**: Handle 12-month billing periods automatically -- **Enhanced invoicing**: Generate annual invoices with proper billing period tracking - -## Billing Configuration Options - -You can configure billing in three ways: - -### Monthly Billing Only -Traditional monthly billing charged in arrears (after usage): - -```json -{ - "billing": { - "cost_per_month": { - "per_machine": 10 - }, - "tier_name": "monthly-tier", - "in_arrears": true - } -} -``` - -### Annual Billing Only -Annual billing with upfront payment: - -```json -{ - "billing": { - "cost_per_year": { - "per_machine": 100 - }, - "tier_name": "annual-tier", - "in_arrears": false - } -} -``` - -### Combined Billing -Offer both monthly and annual options: - -```json -{ - "billing": { - "cost_per_month": { - "per_machine": 10 - }, - "cost_per_year": { - "per_machine": 100 - }, - "tier_name": "flexible-tier", - "in_arrears": true - } -} -``` - -## Configuration Attributes - -### Core Billing Attributes - - -| Name | Type | Required? | Description | -| ---- | ---- | --------- | ----------- | -| `cost_per_month` | object | Optional | Monthly pricing configuration. See [monthly pricing attributes](#monthly-pricing-attributes). | -| `cost_per_year` | object | Optional | Annual pricing configuration. See [annual pricing attributes](#annual-pricing-attributes). | -| `tier_name` | string | **Required** | The name of the billing tier. | -| `description` | string | Optional | Description for the billing tier. Default: `""`. | -| `tier_credit` | number | Optional | Credit applied to final total for the organization. Default: `0`. | -| `in_arrears` | boolean | Optional | Whether billing is charged in arrears (after usage) or upfront. Set to `true` for monthly billing in arrears, `false` for upfront annual billing. Default: `true`. | - -### Annual Pricing Attributes - - -| Name | Type | Required? | Description | -| ---- | ---- | --------- | ----------- | -| `per_machine` | number | Optional | Charge a flat annual fee per machine. Default: `0`. | - -### Monthly Pricing Attributes - - -| Name | Type | Required? | Description | -| ---- | ---- | --------- | ----------- | -| `per_machine` | number | Optional | Charge a flat monthly fee per machine. Default: `0`. | -| `binary_data_upload_bytes` | float | Optional | Cost per byte for binary data upload. Default: `0`. | -| `binary_data_egress_bytes` | float | Optional | Cost per byte for binary data download. Default: `0`. | -| `binary_data_cloud_storage_bytes` | float | Optional | Cost per byte per month for binary data stored. Default: `0`. | -| `tabular_data_upload_bytes` | float | Optional | Cost per byte per month for tabular data upload. Default: `0`. | -| `tabular_data_egress_bytes` | float | Optional | Cost per byte per month for tabular data egress. Default: `0`. | -| `tabular_data_cloud_storage_bytes` | float | Optional | Cost per byte per month for tabular data cloud storage. Default: `0`. | -| `history_cloud_storage_bytes` | float | Optional | Cost per byte per month for config history stored. Default: `0`. | -| `logs_cloud_storage_bytes` | float | Optional | Cost per byte per month for logs cloud storage. Default: `0`. | -| `logs_data_upload_bytes` | float | Optional | Cost per byte per month for logs data upload. Default: `0`. | -| `logs_data_egress_bytes` | float | Optional | Cost per byte per month for logs data egress. Default: `0`. | - -## Billing Behavior - -### Payment Timing - -- **Monthly billing (`in_arrears: true`)**: Customers are charged at the end of each month for usage during that month -- **Annual billing (`in_arrears: false`)**: Customers are charged upfront at the beginning of each 12-month period - -### Invoice Generation - -- **Monthly billing**: Invoices are generated monthly with usage from the previous month -- **Annual billing**: Invoices are generated every 12 months for the upcoming annual period -- **Combined billing**: Customers can choose between monthly and annual billing cycles - -### Billing Cycle Management - -Annual billing automatically handles: - -- 12-month billing periods starting from the initial subscription date -- Automatic renewal after each 12-month cycle -- Proper invoice timing and generation -- Usage tracking across annual periods - -## Implementation Considerations - -### Migration from Monthly to Annual - -When migrating existing customers from monthly to annual billing: - -1. **Timing**: Consider waiting until the next billing cycle to avoid mid-cycle complications -2. **Communication**: Notify customers about billing cycle changes in advance -3. **Pricing**: Ensure annual pricing provides appropriate value compared to monthly rates - -### Pricing Strategy - -When setting annual pricing: - -- **Discount incentive**: Annual pricing typically offers savings compared to 12 months of monthly billing -- **Cash flow**: Consider the impact of upfront payments on your cash flow -- **Customer value**: Balance customer savings with revenue optimization - -### Technical Requirements - -Annual billing requires: - -- Updated billing fragments with `cost_per_year` configuration -- Proper `in_arrears` setting based on payment timing preferences -- Billing system configuration to handle 12-month cycles -- Invoice templates updated for annual billing periods - -## Use Cases - -### Seasonal Business Models - -Annual billing is particularly valuable for businesses with seasonal usage patterns: - -- **Boating industry**: Customers might cancel during off-season without annual commitments -- **Agricultural applications**: Seasonal farming operations benefit from annual pricing -- **Tourism and recreation**: Businesses with seasonal peaks can maintain year-round revenue - -### Enterprise Customers - -Large organizations often prefer annual billing for: - -- **Budget planning**: Annual costs are easier to budget and approve -- **Procurement processes**: Many enterprises prefer annual contracts -- **Cost savings**: Annual discounts provide value to enterprise customers - -## Troubleshooting - -### Common Issues - -**Billing cycle confusion**: Ensure customers understand when they'll be charged and for what period. - -**Invoice timing**: Annual invoices are generated at the beginning of each 12-month period, not at calendar year boundaries. - -**Mixed billing models**: When offering both monthly and annual options, ensure clear communication about which option customers have selected. - -### Configuration Validation - -Verify your billing configuration: - -1. **Required fields**: Ensure `tier_name` is set -2. **Pricing consistency**: Check that annual pricing provides appropriate value -3. **Payment timing**: Confirm `in_arrears` setting matches your business model -4. **Fragment deployment**: Ensure billing fragments are properly deployed to target machines - -## Support - -For questions about annual billing configuration or implementation: - -- **Technical support**: [Contact Viam support](mailto:support@viam.com) -- **Billing questions**: [Contact billing team](mailto:billing@viam.com) -- **White-labelled billing**: See [white-labelled billing documentation](/manage/manage/white-labelled-billing/) \ No newline at end of file diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 8e87a72152..a0f8b2b595 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -100,13 +100,7 @@ https://app.viam.com/billing/?id= ## Set custom pricing -To use custom billing, add a billing configuration the fragment you use for your machine configurations. - -You can configure monthly billing, annual billing, or both depending on your pricing model: - -- **Monthly billing**: Charges customers every month in arrears (after usage) -- **Annual billing**: Charges customers every 12 months, with optional upfront payment -- **Combined billing**: Offer both monthly and annual options to give customers flexibility +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). @@ -114,14 +108,45 @@ You can configure monthly billing, annual billing, or both depending on your pri 1. Click **+** and add **Billing** 1. Adjust attributes as needed. 1. Save the fragment. +1. Add the fragment to the machines that you want to bill for. {{< tabs >}} +{{% tab name="Full Template" %}} + +```json +{ + "billing": { + "cost_per_month": { + "per_machine": 0, + "binary_data_upload_bytes": 0.0, + "binary_data_egress_bytes": 0.0, + "binary_data_cloud_storage_bytes": 0.0, + "tabular_data_upload_bytes": 0.0, + "tabular_data_egress_bytes": 0.0, + "tabular_data_cloud_storage_bytes": 0.0, + "history_cloud_storage_bytes": 0.0, + "logs_cloud_storage_bytes": 0.0, + "logs_data_upload_bytes": 0.0, + "logs_data_egress_bytes": 0.0 + }, + "cost_per_year": { + "per_machine": 0 + }, + "tier_name": "example-tier", + "description": "", + "tier_credit": 0.0, + "in_arrears": true + } +} +``` + +{{% /tab %}} {{% tab name="Monthly Billing Example" %}} +This configuration charges customers every month in arrears, which means after usage: + ```json { class="line-numbers linkable-line-numbers" } { - "components": { ... }, - "services" : { ... }, "billing": { "cost_per_month": { "per_machine": 10 @@ -135,10 +160,10 @@ You can configure monthly billing, annual billing, or both depending on your pri {{% /tab %}} {{% tab name="Annual Billing Example" %}} +This configuration charges customers every 12 months, with upfront payment: + ```json { class="line-numbers linkable-line-numbers" } { - "components": { ... }, - "services" : { ... }, "billing": { "cost_per_year": { "per_machine": 100 @@ -152,10 +177,10 @@ You can configure monthly billing, annual billing, or both depending on your pri {{% /tab %}} {{% tab name="Combined Billing Example" %}} +This configuration charges customers both a monthly and an annual fee in arrears, which means after usage: + ```json { class="line-numbers linkable-line-numbers" } { - "components": { ... }, - "services" : { ... }, "billing": { "cost_per_month": { "per_machine": 10 @@ -169,36 +194,6 @@ You can configure monthly billing, annual billing, or both depending on your pri } ``` -{{% /tab %}} -{{% tab name="Full Template" %}} - -```json -{ - "billing": { - "cost_per_month": { - "per_machine": 0, - "binary_data_upload_bytes": 0.0, - "binary_data_egress_bytes": 0.0, - "binary_data_cloud_storage_bytes": 0.0, - "tabular_data_upload_bytes": 0.0, - "tabular_data_egress_bytes": 0.0, - "tabular_data_cloud_storage_bytes": 0.0, - "history_cloud_storage_bytes": 0.0, - "logs_cloud_storage_bytes": 0.0, - "logs_data_upload_bytes": 0.0, - "logs_data_egress_bytes": 0.0 - }, - "cost_per_year": { - "per_machine": 0 - }, - "tier_name": "example-tier", - "description": "", - "tier_credit": 0.0, - "in_arrears": true - } -} -``` - {{% /tab %}} {{< /tabs >}} @@ -254,10 +249,21 @@ Payments for white-labeled billing go directly to Viam. To arrange reimbursement If you need further customization, please [contact us](mailto:support@viam.com). -### How do I implement annual billing? +### How does renewal work? + +Renewal is automatic for both monthly and annual billing. + +### When are invoices generated? + +- **Monthly billing (`in_arrears: true`)**: Invoiced are generated and customers are charged at the end of each month for usage during that month. + The 1-month period starts from the initial subscription date. +- **Annual billing (`in_arrears: false`)**: Invoiced are generated and customers are charged upfront at the beginning of each 12-month period. + The 12-month period starts from the initial subscription date. + +### Can customers switch from monthly to annual? -For detailed information about annual billing configuration, billing cycles, and implementation considerations, see the [Annual Billing guide](/manage/manage/annual-billing/). +Yes. 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. -### Can I offer both monthly and annual billing options? +### Can customers switch from annual to monthly? -Yes, you can configure billing fragments with both `cost_per_month` and `cost_per_year` to give customers flexibility in choosing their preferred billing cycle. See the [Combined Billing Example](#set-custom-pricing) above. +This is not currently possible. From 45c8e067780bdead03a7cb63c35bfb9197b2b4ec Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 3 Jul 2025 18:21:55 +0200 Subject: [PATCH 03/19] update hash --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index f847955ebd..fc7a424d9b 100644 --- a/netlify.toml +++ b/netlify.toml @@ -57,7 +57,7 @@ [plugins.inputs] # change this key to a new one any time you need to restart from scratch - cacheKey = ["June302025"] + cacheKey = ["July32025"] # either "warn" or "error" failBuildOnError = true From 3b4f57aca271a429ba4b3f783e73737b2d75dad4 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 4 Jul 2025 15:47:06 +0200 Subject: [PATCH 04/19] Update based on feedback --- docs/manage/manage/white-labelled-billing.md | 64 +++++++++++--------- 1 file changed, 34 insertions(+), 30 deletions(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index a0f8b2b595..9d698e86a6 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -111,7 +111,7 @@ To use custom billing, add a billing configuration to a fragment. 1. Add the fragment to the machines that you want to bill for. {{< tabs >}} -{{% tab name="Full Template" %}} +{{% tab name="Full Template (monthly)" %}} ```json { @@ -129,9 +129,6 @@ To use custom billing, add a billing configuration to a fragment. "logs_data_upload_bytes": 0.0, "logs_data_egress_bytes": 0.0 }, - "cost_per_year": { - "per_machine": 0 - }, "tier_name": "example-tier", "description": "", "tier_credit": 0.0, @@ -141,55 +138,57 @@ To use custom billing, add a billing configuration to a fragment. ``` {{% /tab %}} -{{% tab name="Monthly Billing Example" %}} - -This configuration charges customers every month in arrears, which means after usage: +{{% tab name="Full Template (yearly)" %}} -```json { class="line-numbers linkable-line-numbers" } +```json { "billing": { - "cost_per_month": { - "per_machine": 10 + "cost_per_year": { + "per_machine": 0 }, - "tier_name": "monthly-tier", + "tier_name": "example-tier", + "description": "", + "tier_credit": 0.0, "in_arrears": true } } ``` {{% /tab %}} -{{% tab name="Annual Billing Example" %}} +{{% tab name="Example (monthly)" %}} -This configuration charges customers every 12 months, with upfront payment: +This configuration charges customers every month in arrears, which means after usage: ```json { class="line-numbers linkable-line-numbers" } { "billing": { - "cost_per_year": { - "per_machine": 100 + "cost_per_month": { + "per_machine": 10, + "binary_data_upload_bytes": 0.01 }, - "tier_name": "annual-tier", - "in_arrears": false + "tier_name": "monthly-tier", + "in_arrears": true } } ``` +By setting `"in_arrears": false` you can change the configuration to charge customers upfront. + +If you want to charge customer + {{% /tab %}} -{{% tab name="Combined Billing Example" %}} +{{% tab name="Example (yearly)" %}} -This configuration charges customers both a monthly and an annual fee in arrears, which means after usage: +This configuration charges customers every 12 months, with upfront payment: ```json { class="line-numbers linkable-line-numbers" } { "billing": { - "cost_per_month": { - "per_machine": 10 - }, "cost_per_year": { "per_machine": 100 }, - "tier_name": "flexible-tier", - "in_arrears": true + "tier_name": "annual-tier", + "in_arrears": false } } ``` @@ -202,12 +201,12 @@ This configuration charges customers both a monthly and an annual fee in arrears | 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` | 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. Set to `true` for monthly billing in arrears, `false` for upfront annual billing. Default: `true`. | +| `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%}} @@ -255,10 +254,15 @@ Renewal is automatic for both monthly and annual billing. ### When are invoices generated? -- **Monthly billing (`in_arrears: true`)**: Invoiced are generated and customers are charged at the end of each month for usage during that month. - The 1-month period starts from the initial subscription date. -- **Annual billing (`in_arrears: false`)**: Invoiced are generated and customers are charged upfront at the beginning of each 12-month period. +- **Monthly billing (`in_arrears: true`)**: Invoiced are generated and customers are charged at the end of each month for the per machine cost and usage during that month. + The first 1-month period starts from the subscription date. + Afterwards each new month starts on the next day after the previous usage month's end. +- **Monthly billing (`in_arrears: false`)**: Invoiced are generated and customers are charged at the beginning of each new month of usage for the per machine cost. + The first 1-month period starts from the subscription date. + Afterwards each new month starts on the next day after the previous usage month's end. +- **Annual billing (`in_arrears: false`)**: Invoiced are generated and customers are charged upfront at the beginning of each 12-month period for the per machine cost. The 12-month period starts from the initial subscription date. + Each new 12-month period starts on the next day after the pervious 12-month period's end. ### Can customers switch from monthly to annual? From 4860934b440f61d404d88723648d9c4fb3b4fccb Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 4 Jul 2025 15:56:29 +0200 Subject: [PATCH 05/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 9d698e86a6..7d2d23eca9 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -262,7 +262,7 @@ Renewal is automatic for both monthly and annual billing. Afterwards each new month starts on the next day after the previous usage month's end. - **Annual billing (`in_arrears: false`)**: Invoiced are generated and customers are charged upfront at the beginning of each 12-month period for the per machine cost. The 12-month period starts from the initial subscription date. - Each new 12-month period starts on the next day after the pervious 12-month period's end. + Each new 12-month period starts on the next day after the previous 12-month period's end. ### Can customers switch from monthly to annual? From 4d71402fcca671766ee0ea53f2f28db03639bc7f Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Mon, 7 Jul 2025 16:51:13 +0200 Subject: [PATCH 06/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 7d2d23eca9..4df9902e45 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -250,7 +250,9 @@ If you need further customization, please [contact us](mailto:support@viam.com). ### How does renewal work? -Renewal is automatic for both monthly and annual billing. +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? From 49875dd5e017b60846eb3cc112bac9ad19657ee6 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Mon, 7 Jul 2025 16:55:36 +0200 Subject: [PATCH 07/19] Apply suggestions from code review --- docs/manage/reference/billing.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/manage/reference/billing.md b/docs/manage/reference/billing.md index 70f97e4bd9..25b924847e 100644 --- a/docs/manage/reference/billing.md +++ b/docs/manage/reference/billing.md @@ -73,16 +73,12 @@ Invoices may be generated monthly or annually depending on your billing configur ## Set billing alerts -You can set alerts to receive an email notification when your spend exceeds a certain threshold: +You can set alerts to receive an email notification when your monthly spend exceeds a certain threshold: 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 threshold amount. - -{{< alert title="Note" color="note" >}} -For organizations with annual billing, alerts are based on cumulative spending within the annual billing cycle rather than monthly spending. -{{< /alert >}} +1. Click **Set amount** and enter a monthly threshold amount. ## Help From 574f609357d92872e8a6893c62b702fbcead335b Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:48:36 +0200 Subject: [PATCH 08/19] Update docs/manage/manage/white-labelled-billing.md Co-authored-by: Evgeni Dobranov --- docs/manage/manage/white-labelled-billing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 4df9902e45..d7b3abfcdd 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -256,13 +256,13 @@ If the `per_machine` field is set, then a machine existing, is considered usage. ### When are invoices generated? -- **Monthly billing (`in_arrears: true`)**: Invoiced are generated and customers are charged at the end of each month for the per machine cost and usage during that month. +- **Monthly billing (`in_arrears: true`)**: Invoices are generated and customers are charged at the end of each month for the per machine cost and usage during that month. The first 1-month period starts from the subscription date. Afterwards each new month starts on the next day after the previous usage month's end. -- **Monthly billing (`in_arrears: false`)**: Invoiced are generated and customers are charged at the beginning of each new month of usage for the per machine cost. +- **Monthly billing (`in_arrears: false`)**: Invoices are generated and customers are charged at the beginning of each new month of usage for the per machine cost. The first 1-month period starts from the subscription date. Afterwards each new month starts on the next day after the previous usage month's end. -- **Annual billing (`in_arrears: false`)**: Invoiced are generated and customers are charged upfront at the beginning of each 12-month period for the per machine cost. +- **Annual billing (`in_arrears: false`)**: Invoices are generated and customers are charged upfront at the beginning of each 12-month period for the per machine cost. The 12-month period starts from the initial subscription date. Each new 12-month period starts on the next day after the previous 12-month period's end. From 74950e879bb6e456f2c2c34598940a1f149e0733 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:50:03 +0200 Subject: [PATCH 09/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index d7b3abfcdd..c61a433f76 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -107,6 +107,7 @@ To use custom billing, add a billing configuration to a fragment. 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. From c1342d34ed7794d7a5955b830912a15d578df8ad Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:50:42 +0200 Subject: [PATCH 10/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index c61a433f76..225aef18dc 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -175,7 +175,6 @@ This configuration charges customers every month in arrears, which means after u By setting `"in_arrears": false` you can change the configuration to charge customers upfront. -If you want to charge customer {{% /tab %}} {{% tab name="Example (yearly)" %}} From f86b23136954801797a628f88a38fac73dba2224 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:52:11 +0200 Subject: [PATCH 11/19] Update static/include/app/apis/generated/billing.md --- static/include/app/apis/generated/billing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/include/app/apis/generated/billing.md b/static/include/app/apis/generated/billing.md index cae023b492..65c676ebdd 100644 --- a/static/include/app/apis/generated/billing.md +++ b/static/include/app/apis/generated/billing.md @@ -1,7 +1,7 @@ ### GetCurrentMonthUsage Access data usage information for the current billing period for a given organization. -For organizations with monthly billing, this returns current month usage. For organizations with annual billing, this returns usage within the current annual billing cycle. +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 >}} From 21acf9555ec5e9b41d6ddfb5a2b0d34f876370c9 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:52:31 +0200 Subject: [PATCH 12/19] Update static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md --- .../app/apis/overrides/protos/billing.GetCurrentMonthUsage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md b/static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md index f1b6d69439..b48c94f790 100644 --- a/static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md +++ b/static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md @@ -1,3 +1,3 @@ Access data usage information for the current billing period for a given organization. -For organizations with monthly billing, this returns current month usage. For organizations with annual billing, this returns usage within the current annual billing cycle. +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/). From 68b7fa3df1b1ceecee08737da6f95b30cb04fc42 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 9 Jul 2025 11:54:30 +0200 Subject: [PATCH 13/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 225aef18dc..80fe500f10 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -175,7 +175,6 @@ This configuration charges customers every month in arrears, which means after u By setting `"in_arrears": false` you can change the configuration to charge customers upfront. - {{% /tab %}} {{% tab name="Example (yearly)" %}} From b2e5792e8e3aa89c6eeef3b67f3d5387260cf07c Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 10 Jul 2025 12:11:43 +0200 Subject: [PATCH 14/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 80fe500f10..150d71bd7d 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -265,10 +265,8 @@ If the `per_machine` field is set, then a machine existing, is considered usage. The 12-month period starts from the initial subscription date. Each new 12-month period starts on the next day after the previous 12-month period's end. -### Can customers switch from monthly to annual? +### Can customers switch between monthly and annual billing? -Yes. 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. - -### Can customers switch from annual to monthly? - -This is not currently possible. +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. From d2a3ffbefdbec37c2c4725fca87f71c2d50f70c6 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 10 Jul 2025 13:27:30 +0200 Subject: [PATCH 15/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 150d71bd7d..e2296b372d 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -255,15 +255,14 @@ 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 and customers are charged at the end of each month for the per machine cost and usage during that month. - The first 1-month period starts from the subscription date. - Afterwards each new month starts on the next day after the previous usage month's end. -- **Monthly billing (`in_arrears: false`)**: Invoices are generated and customers are charged at the beginning of each new month of usage for the per machine cost. - The first 1-month period starts from the subscription date. - Afterwards each new month starts on the next day after the previous usage month's end. -- **Annual billing (`in_arrears: false`)**: Invoices are generated and customers are charged upfront at the beginning of each 12-month period for the per machine cost. - The 12-month period starts from the initial subscription date. - Each new 12-month period starts on the next day after the previous 12-month period's end. +- **Monthly billing (`in_arrears: true`)**: Invoices are generated on the 1st 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 s machine on June 20th, you'll get an invoice on July 1st 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 within 30 to 90 minutes 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 within an hour or two. + Then you'll get the next invoice on July 20, then August 20, and so on. +- **Annual billing (`in_arrears: false`)**: Invoices are generated within 30 to 90 minutes 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 20th, you'll get an invoice within an hour or two. + Then you'll get the next invoice on June 20th the following year. ### Can customers switch between monthly and annual billing? From bf3713506c43c5fd326fef6a2d5640dce68f91ff Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 10 Jul 2025 13:30:07 +0200 Subject: [PATCH 16/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index e2296b372d..e22c2342e7 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -255,14 +255,14 @@ 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 1st 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 s machine on June 20th, you'll get an invoice on July 1st for 10 days of usage. Then you'll get the next invoice on August 1 for the usage in July. +- **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 within 30 to 90 minutes 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 within an hour or two. Then you'll get the next invoice on July 20, then August 20, and so on. - **Annual billing (`in_arrears: false`)**: Invoices are generated within 30 to 90 minutes 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 20th, you'll get an invoice within an hour or two. - Then you'll get the next invoice on June 20th the following year. + For example, if you set up an annual upfront machine on June 20, you'll get an invoice within an hour or two. + Then you'll get the next invoice on June 20 the following year. ### Can customers switch between monthly and annual billing? From 867ebf1be617be0bbd93fe6bd0ccc094e7a54b00 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 10 Jul 2025 13:30:39 +0200 Subject: [PATCH 17/19] Update docs/manage/manage/white-labelled-billing.md --- docs/manage/manage/white-labelled-billing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index e22c2342e7..dd8e4bc57f 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -261,7 +261,7 @@ If the `per_machine` field is set, then a machine existing, is considered usage. For example, if you set up a monthly upfront machine on June 20, you'll get an invoice within an hour or two. Then you'll get the next invoice on July 20, then August 20, and so on. - **Annual billing (`in_arrears: false`)**: Invoices are generated within 30 to 90 minutes 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 within an hour or two. + For example, if you set up an annual upfront machine on June 20, you'll get an invoice within an hour or two. Then you'll get the next invoice on June 20 the following year. ### Can customers switch between monthly and annual billing? From 02b4bd999cdb726fbea1941ca3764dfa634993c5 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 11 Jul 2025 13:02:07 +0200 Subject: [PATCH 18/19] Update docs/manage/manage/white-labelled-billing.md Co-authored-by: Evgeni Dobranov --- docs/manage/manage/white-labelled-billing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index dd8e4bc57f..1c03f8fd7c 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -150,7 +150,7 @@ To use custom billing, add a billing configuration to a fragment. "tier_name": "example-tier", "description": "", "tier_credit": 0.0, - "in_arrears": true + "in_arrears": false } } ``` From 81e17b935b19bfbfeae90d3bdc2d0739279aa7f4 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 11 Jul 2025 13:02:22 +0200 Subject: [PATCH 19/19] Update docs/manage/manage/white-labelled-billing.md Co-authored-by: Evgeni Dobranov --- docs/manage/manage/white-labelled-billing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/manage/manage/white-labelled-billing.md b/docs/manage/manage/white-labelled-billing.md index 1c03f8fd7c..0b192558c7 100644 --- a/docs/manage/manage/white-labelled-billing.md +++ b/docs/manage/manage/white-labelled-billing.md @@ -257,11 +257,11 @@ If the `per_machine` field is set, then a machine existing, is considered usage. - **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 within 30 to 90 minutes 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 within an hour or two. +- **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 within 30 to 90 minutes 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 within an hour or two. +- **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?