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

promptless · 2025-07-03T15:10:27Z

Main changes: https://deploy-preview-4447--viam-docs.netlify.app/manage/manage/white-labelled-billing/#set-custom-pricing

CLAassistant · 2025-07-03T15:10:34Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ npentrel
❌ promptless[bot]
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

viambot · 2025-07-03T15:10:38Z

👋 Thanks for contributing! A reviewer will look at it on the next working day!

promptless · 2025-07-03T15:10:38Z

Just a reminder: If you'd like me to act on any feedback you have via Github comments, just type @Promptless in your suggestion and I'll get right on it! (I won't show up in the user dropdown, but I'll process any request that has @Promptless in the comment body.)

netlify · 2025-07-03T15:10:57Z

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	`61c3d1f`
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6870ef7c611dc700082ddaf1
😎 Deploy Preview	https://deploy-preview-4447--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 49 (🔴 down 3 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

edobranov

Thanks for jumping on this! To clarify a bit, there are only three valid use cases right now:

(1) Monthly, in arrears (the existing behavior):

{
  "billing": {
    "cost_per_month": {
      "per_machine": 10
      // ... and any other billable resources, like "binary_data_upload_bytes"
    },
    "tier_name": "monthly-arrears-tier",
    "in_arrears": true
  }
}

(2) Monthly, upfront (working on this right now in APP-8350):

{
  "billing": {
    "cost_per_month": {
      "per_machine": 10
    },
    "tier_name": "monthly-upfront-tier",
    "in_arrears": false   // or omitted
  }
}

(3) Yearly, upfront (the epic's primary goal):

{
  "billing": {
    "cost_per_year": {
      "per_machine": 10
    },
    "tier_name": "yearly-upfront-tier",
    "in_arrears": false   // or omitted
  }
}

Anything else is invalid. Specifically:

If in_arrears is false, then you can only specify the per_machine billable resource (it didn't make sense to allow charging for other kinds of usage upfront).
You cannot specify cost_per_year and in_arrears: true (this was more work for us to implement and didn't have a strong product case).

Lmk if I can help clarify anything else!

npentrel · 2025-07-04T13:55:35Z

Updated this, please have another look.

My only remaining question is:
Is there sufficient error-checking in the UI? I tested and currently I can set tabular_data_upload_bytes to a positive number and in_arrears: false. There's no error message. Maybe it's not fully deployed to prod, idk. Just want to check

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

npentrel · 2025-07-07T14:53:06Z

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.


Is this correct?

Thanks for asking – GetCurrentMonthUsage actually only applies to billing configs that have cost_per_month with in_arrears: true. In our backend, we don't consider upfront billing to be "current usage".

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

docs/manage/reference/billing.md

edobranov

Looks great! Just a handful of nits, will be good to LGTM right after

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

edobranov · 2025-07-08T21:17:19Z

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.


Thanks for asking – GetCurrentMonthUsage actually only applies to billing configs that have cost_per_month with in_arrears: true. In our backend, we don't consider upfront billing to be "current usage".

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

edobranov · 2025-07-08T21:21:16Z

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

+
+By setting `"in_arrears": false` you can change the configuration to charge customers upfront.
+
+If you want to charge customer


Probably can remove this?

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

Co-authored-by: Evgeni Dobranov <[email protected]>

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

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

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

…thUsage.md

npentrel · 2025-07-09T09:52:58Z

Thanks @edobranov - should be good to re-review

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

edobranov

Thank you! Looking again, I just have a couple final comments for the FAQ that I think can use a bit more detail 🙏

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

edobranov · 2025-07-09T15:57:20Z

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

+### Can customers switch from monthly to annual?
+
+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.


It should actually be okay to switch between the two. Here's my take on a rewrite for both q's (feel free to reword):

### 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/manage/white-labelled-billing.md

npentrel · 2025-07-10T11:33:24Z

@edobranov ready for re-review

edobranov

LGTM % a couple final nits, thank you!

Also could we wait a few days before merging this? I'm still working on the upfront monthly stuff (APP-8350) that's relevant to these docs, but it's taking a bit longer than I anticipated. I'll make sure to ping you when everything is ready to go.

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

Co-authored-by: Evgeni Dobranov <[email protected]>

npentrel · 2025-07-11T11:03:36Z

yes - ping me when ready and we'll merge!

Documentation updates from Promptless

5563efc

npentrel added 2 commits July 3, 2025 18:20

Simplify

ae4e377

update hash

45c8e06

edobranov reviewed Jul 3, 2025

View reviewed changes

Update based on feedback

3b4f57a

npentrel force-pushed the DOCS-3667 branch from f30dc96 to 3b4f57a Compare July 4, 2025 13:52

npentrel reviewed Jul 4, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

4860934

npentrel reviewed Jul 7, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

4d71402

npentrel reviewed Jul 7, 2025

View reviewed changes

static/include/app/apis/generated/billing.md Show resolved Hide resolved

npentrel reviewed Jul 7, 2025

View reviewed changes

docs/manage/reference/billing.md Outdated Show resolved Hide resolved

npentrel reviewed Jul 7, 2025

View reviewed changes

docs/manage/reference/billing.md Outdated Show resolved Hide resolved

Apply suggestions from code review

49875dd

edobranov requested changes Jul 8, 2025

View reviewed changes

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

574f609

Co-authored-by: Evgeni Dobranov <[email protected]>

npentrel reviewed Jul 9, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Show resolved Hide resolved

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

74950e8

npentrel reviewed Jul 9, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

c1342d3

npentrel reviewed Jul 9, 2025

View reviewed changes

static/include/app/apis/generated/billing.md Outdated Show resolved Hide resolved

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

f86b231

npentrel reviewed Jul 9, 2025

View reviewed changes

static/include/app/apis/overrides/protos/billing.GetCurrentMonthUsage.md Outdated Show resolved Hide resolved

Update static/include/app/apis/overrides/protos/billing.GetCurrentMon…

21acf95

…thUsage.md

npentrel requested a review from edobranov July 9, 2025 09:52

npentrel reviewed Jul 9, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

68b7fa3

edobranov requested changes Jul 9, 2025

View reviewed changes

npentrel reviewed Jul 10, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

b2e5792

npentrel reviewed Jul 10, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

d2a3ffb

npentrel requested a review from edobranov July 10, 2025 11:28

npentrel reviewed Jul 10, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

bf37135

npentrel reviewed Jul 10, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

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

867ebf1

edobranov approved these changes Jul 10, 2025

View reviewed changes

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

docs/manage/manage/white-labelled-billing.md Outdated Show resolved Hide resolved

npentrel and others added 3 commits July 11, 2025 13:02

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

02b4bd9

Co-authored-by: Evgeni Dobranov <[email protected]>

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

81e17b9

Co-authored-by: Evgeni Dobranov <[email protected]>

Merge branch 'main' into DOCS-3667

61c3d1f


		By setting `"in_arrears": false` you can change the configuration to charge customers upfront.

		If you want to charge customer

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

promptless bot commented Jul 3, 2025 • edited by npentrel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

viambot commented Jul 3, 2025

Uh oh!

promptless bot commented Jul 3, 2025

Uh oh!

netlify bot commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for viam-docs ready!

Uh oh!

edobranov left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

npentrel commented Jul 4, 2025

Uh oh!

Uh oh!

Uh oh!

npentrel Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

edobranov Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edobranov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

edobranov Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

edobranov Jul 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

npentrel commented Jul 9, 2025

Uh oh!

Uh oh!

edobranov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

edobranov Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

npentrel commented Jul 10, 2025

Uh oh!

edobranov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

npentrel commented Jul 11, 2025

Uh oh!

Uh oh!

promptless bot commented Jul 3, 2025 •

edited by npentrel

Loading

CLAassistant commented Jul 3, 2025 •

edited

Loading

netlify bot commented Jul 3, 2025 •

edited

Loading

edobranov left a comment •

edited

Loading