docs(billing): document overage, and fix the overdue grace period

README.md

@@ -57,6 +57,7 @@ Start with the [Quick Start](getting-started/quickstart.md) to install the CLI a
 
 * [Test Run Billing](billing/test-run-billing.md) - what a single test run costs
 * [Subscriptions](billing/subscriptions.md) - the Pro, Max and Enterprise plans
+* [Overage](billing/overage.md) - usage beyond your plan's included credits, and the Overage Limit
 * [Concurrency & Parallel Runs](getting-started/concurrency-and-parallel-runs.md) - how many of your tests run at once
 
 ## FAQ
@@ -67,7 +68,7 @@ For most projects, yes. The CLI mimics the Maestro Cloud API, so you change `mae
 
 ### How much does it cost?
 
-DeviceCloud bills per test run i.e. a single top-level flow on a single device and are charged at $0.11 for standard iOS and $0.09 for standard Android. iPad, iPhone Duo, Pixel 10 Pro Fold, Google Play, tablet and `m4`, `m1` and `gpu1` (deprecated) runner flows are charged at the advanced rate of $0.15. New accounts get $20 of free credits. See [Test Run Billing](billing/test-run-billing.md).
+DeviceCloud bills per test run i.e. a single top-level flow on a single device and are charged at $0.11 for standard iOS and $0.09 for standard Android. iPad, iPhone Duo, Pixel 10 Pro Fold, Google Play, tablet and `m4`, `m1` and `gpu1` (deprecated) runner flows are charged at the advanced rate of $0.15. New accounts get $20 of free credits. The Pro and Max plans include a set amount of usage each month, and usage beyond that is billed as [overage](billing/overage.md), up to a limit you control. See [Test Run Billing](billing/test-run-billing.md).
 
 ### How many tests can I run in parallel?
 

SUMMARY.md

@@ -93,6 +93,7 @@
 ## Billing
 
 * [Subscriptions](billing/subscriptions.md)
+* [Overage](billing/overage.md)
 * [Test Run Billing](billing/test-run-billing.md)
 
 ## Legal

advanced/exit-codes.md

@@ -17,6 +17,8 @@ Device Cloud uses standard exit codes to indicate the status of command executio
 2    # Test run explicitly failed
 ```
 
+A run the API refuses to start also exits `1`. That includes HTTP `402` refusals, when a run would take you over your [Overage Limit](../billing/overage.md#when-a-run-would-go-over-the-limit) or a subscription payment is [overdue](../billing/test-run-billing.md#overdue-payments).
+
 A run fails if any of its tests fails or is cancelled, so a run you cancel from the console also exits `2`. With `--async`, `dcd cloud` exits `0` as soon as the run is submitted, whatever the outcome.
 
 ## JSON Output

api/results.md

@@ -57,7 +57,9 @@ was cancelled for a recorded reason:
 * `superseded_by:<upload id>` — a newer run from the same CI context replaced
   this one. See [Cancelling superseded runs](../advanced/cancel-previous.md).
 * `Cancelled: payment for this run failed.` — the run's payment failed after
-  its tests were created.
+  its tests were created, for example because it was submitted at the same
+  moment as another run and together they went over your
+  [Overage Limit](../billing/overage.md#when-a-run-would-go-over-the-limit).
 
 A test you cancel yourself has a `null` reason, and so does a retry of a cancelled test. Match on the `superseded_by:`
 prefix rather than comparing whole values, as more reasons may be added.

billing/overage.md

@@ -0,0 +1,94 @@
+---
+description: "How usage beyond your plan's included credits is charged on the Pro and Max plans: the order usage is paid in, when overage is invoiced, the Overage Limit, and what happens when a run would go over it."
+---
+
+# Overage
+
+The Pro and Max [subscriptions](subscriptions.md) include a set amount of usage each billing period: $25 on Pro and $200 on Max. The console calls this your **included credits**. Usage beyond it is **overage**. Overage is charged at the same per-run prices as everything else (see [Test Run Billing](test-run-billing.md)), added to your next invoice, and capped by your [Overage Limit](#overage-limit).
+
+::: info
+All amounts exclude Sales Tax. Our Merchant of Record, Paddle, adds tax for your country to your invoice.
+:::
+
+## How usage is paid for
+
+Each run is charged when you submit it. The charge is taken from three places, in this order:
+
+1. **Prepaid credit balance.** This covers free credits and any credits bought before subscriptions replaced them.
+2. **Included credits.** Your plan's included usage for the current billing period.
+3. **Overage.** Whatever is left.
+
+One upload can be split across all three. For example, with $1 of included credits left, a $3 upload uses that $1 and adds $2 of overage.
+
+The [billing page](https://console.devicecloud.dev/billing) shows your included credits used and remaining, and your overage so far this billing period. Every charge is listed under **Usage**, with a type of `CREDITS`, `SUBSCRIPTION` or `OVERAGE`.
+
+## When overage is billed
+
+Overage is billed in arrears. It isn't charged to your card as you go. About once a day, any new overage is added to your next subscription invoice. Each renewal invoice therefore holds two things:
+
+* the plan fee for the billing period that's starting
+* the overage from the billing period that's ending
+
+Overage from the last day of a billing period may only be added after you renew. If so, it appears on the invoice after that.
+
+For example, a Pro team uses $60 of test runs in one billing period. $25 of that is covered by its included credits and $35 is overage. At renewal it's invoiced $25 for the next period's plan fee plus $35 of overage, so $60 before tax.
+
+You can see past invoices under **Invoice history** on the billing page.
+
+## Overage Limit
+
+The Overage Limit caps how much overage you can run up in one billing period, so a runaway pipeline can't produce an unexpected bill. The limit is added on top of your included credits. It doesn't cap your total spend.
+
+By default the limit is 8× your plan's included credits:
+
+| Plan | Included credits | Default Overage Limit | Most usage per billing period |
+| ---- | ---------------- | --------------------- | ----------------------------- |
+| Pro  | $25              | $200                  | $225                          |
+| Max  | $200             | $1,600                | $1,800                        |
+
+### Changing the limit
+
+Only owners and admins can see the billing page and change the limit:
+
+1. Open the [billing page](https://console.devicecloud.dev/billing).
+2. Select **Edit** next to **Overage Limit**.
+3. Enter a whole number of dollars and select **Save**.
+
+The new limit applies from your next run.
+
+* Set it to `0` to allow no overage at all. Runs then stop as soon as your included credits are used up.
+* There's no maximum.
+* If you change plan and haven't changed the limit yourself, it moves to the new plan's default. A limit you've set yourself is kept.
+
+## When a run would go over the limit
+
+When you submit a run, DeviceCloud checks whether its cost would take your usage for the billing period past your included credits plus your Overage Limit. If it would, the whole upload is refused and none of its tests run.
+
+That means a run can be refused before you've used the whole limit. With $5 of your Overage Limit left, a $6 upload is refused, but a $4 upload still runs. Tests that were already queued or running aren't affected.
+
+`dcd cloud` reports the refusal as an error and exits with code `1`, even with `--json-file`. In CI, the step fails like any other CLI error. The output looks like this:
+
+```text
+✗ Error: Failed to submit test flows: Usage limit exceeded … (HTTP 402)
+```
+
+The full message also gives your usage so far, the cost of the upload, your limit and the dates of your billing period. Behind the CLI, the API responds with HTTP `402` and `"error": "USAGE_LIMIT_EXCEEDED"`.
+
+To start testing again, raise your Overage Limit or wait for your next billing period to start.
+
+
+## Warnings
+
+The billing page shows a warning once you've used 80% of your Overage Limit, and another when you reach it. With a limit of `0`, both are based on your included credits instead.
+
+
+## Refunds
+
+Tests you cancel before they start are refunded at 75% of their cost. A refund for a test paid from overage reduces overage that hasn't been added to an invoice yet. Overage is added about once a day, so the refund usually lands before the overage it cancels is invoiced. If that overage is already on your next invoice, the refund comes off any further overage in the same billing period instead. See [Cancelled tests](test-run-billing.md#cancelled-tests).
+
+## Other plans
+
+* **Enterprise.** Your agreement sets your overage terms. Contact support for details.
+* **No subscription.** If you only have a prepaid credit balance, there's no overage. Runs are refused once the balance runs out.
+
+If a renewal payment fails, including one with overage on it, see [Overdue payments](test-run-billing.md#overdue-payments).

billing/subscriptions.md

@@ -12,7 +12,7 @@ Subscriptions have replaced one-off credit purchases. Reach out to support if yo
 
 This subscription costs $25 per month and comes with $25 of usage included which can be used as per [Test Run Billing](test-run-billing.md).
 
-Additional usage beyond $25 will be billed as overage and charged in your next monthly payment.
+Additional usage beyond $25 is billed as [overage](overage.md) on your next monthly invoice.
 
 This plan lets you run up to 5 iOS and 5 Android tests in parallel. Read about [Concurrency & Parallel Runs](../getting-started/concurrency-and-parallel-runs.md) to understand how this may be reduced at peak times.
 
@@ -24,7 +24,7 @@ This plan supports unlimited users and unlimited apps. Results are retained for
 
 This subscription costs $200 per month and comes with $200 of usage included which can be used as per [Test Run Billing](test-run-billing.md).
 
-Additional usage beyond $200 will be billed as overage and charged in your next monthly payment.
+Additional usage beyond $200 is billed as [overage](overage.md) on your next monthly invoice.
 
 This plan lets you run up to 20 iOS and 20 Android tests in parallel.
 
@@ -36,9 +36,9 @@ This plan supports unlimited users and unlimited apps. Results are retained for
 
 ### Overage Limit
 
-On the Pro and Max plans, overage is capped each billing period so a runaway pipeline can't produce an unexpected bill. By default the **Overage Limit** is 8× your plan's included usage — $200 on Pro and $1,600 on Max — and it applies on top of the usage included in your plan. You can view and change it on the [billing page](https://console.devicecloud.dev/billing), which shows a warning once you've used 80% of it. If you change plan and haven't customised the limit, it moves to the new plan's default.
+On the Pro and Max plans, overage is capped each billing period so a runaway pipeline can't produce an unexpected bill. By default the **Overage Limit** is 8× your plan's included usage: $200 on Pro and $1,600 on Max, on top of the usage included in your plan. Owners and admins can change it on the [billing page](https://console.devicecloud.dev/billing).
 
-Once the limit is reached, new test runs are refused with HTTP `402` (`USAGE_LIMIT_EXCEEDED`) until your next billing period starts or you raise the limit.
+A run that would take you over the limit is refused. See [Overage](overage.md#overage-limit) for how the limit works and what happens when you reach it.
 
 ### Enterprise Plan
 

billing/test-run-billing.md

@@ -10,7 +10,7 @@ In billing terms, a test run is a single top-level flow executing on a single de
 
 For example, an upload with 10 flows running on iOS (at $0.11 per test run) will incur $1.10 of charges to your Team's account.
 
-Details of charges made to your account can be found on the [billing page](https://console.devicecloud.dev/billing).
+Details of charges made to your account can be found on the [billing page](https://console.devicecloud.dev/billing). On the Pro and Max plans, usage beyond your plan's included credits is billed as [overage](overage.md).
 
 | Test Run Type    | Includes                                                                                          | Cost (USD) |
 | ---------------- | ------------------------------------------------------------------------------------------------- | ---------- |
@@ -43,7 +43,7 @@ Each refund appears as a negative line in your usage history, alongside the orig
 
 * **Credit balance** - the refund is added back to your balance immediately.
 * **Your plan's included credits** - the refund restores that amount of your included allowance for the current billing period.
-* **Overage** - the refund reduces overage that hasn't been billed yet. Overage that has already been billed isn't credited back; the refund is deducted from any further overage in the same billing period instead.
+* **Overage** - the refund reduces overage that hasn't been added to an invoice yet. Overage is added to your next invoice about once a day (see [When overage is billed](overage.md#when-overage-is-billed)). Overage that's already been added isn't credited back; the refund is deducted from any further overage in the same billing period instead.
 
 A run paid for from more than one of these is refunded in the same proportions. Refunds for cancelled tests are never paid back to your card.
 
@@ -57,4 +57,8 @@ Upgrading your plan takes effect immediately, and you're charged the prorated di
 
 ### Overdue payments
 
-If a subscription payment fails, you can keep testing for 72 hours while the payment is retried. After that, new test runs are refused with HTTP `402` until the payment succeeds.
+If a subscription payment fails, you can keep testing for 14 days while the payment is retried. We email your billing email address, or your team's owners and admins if you haven't set one. A notice also appears in the CLI, the console and your CI output, with the date new runs will stop.
+
+After 14 days, new test runs and live sessions are refused with HTTP `402` until the payment succeeds. Tests already queued or running aren't affected, and nothing is deleted.
+
+If you still have a prepaid credit balance, you can keep running tests while it lasts. Those runs are paid from your balance.