# Switch a service to usage billing

> Move a deployment, Cloud Compute instance, game server or database that keeps a flat price to usage billing, after a preview built from its last 30 days.

Source: https://www.coritan.com/docs/billing/switch-to-usage-billing/

In the dashboard:

- /dashboard/deployments/…/billing: https://www.coritan.com/dashboard/deployments

A service ordered before [usage billing](/docs/billing/usage-billing/) keeps the price it had: a deployment on pay as you go or monthly per location, and an instance, a game server or a database on a plan with a monthly or hourly price. You can move any of them to usage billing, and Coritan does not move them for you. A static site is the one exception: it has no instance to price, so Coritan moved every static site already.

After the move, the service has no price of its own. It is billed by the second for what it uses, and the month's included amounts apply ([Usage rates](/docs/billing/usage-rates/#included)). The move is one way, so a service cannot go back to a flat price. You switch a deployment in the dashboard or with the API. An instance, a game server or a database switches with the API.

## Before you begin

- On a team, the Billing and Admin roles can switch a service, and the Technical role cannot. To switch with the API, get an access token first: [Make your first API request](/docs/get-started/first-steps-with-the-api/) shows how.
- The service must be active, and not set to end. A suspended service moves after you pay its open invoice.
- A prepaid account needs the first deposit for anything that runs an instance. A static site needs none ([What you need before you order](/docs/billing/usage-billing/#deposit)).
- A Cloud Compute instance, a game server or a database needs the [Paid plan](/docs/billing/usage-billing/#paid-plan).
- The service must be yours. A free server, a service of one of your organization's customers, and a service that keeps a Coritan brand's price cannot move. A deployment Coritan runs at no charge cannot either.

## Switch a deployment in the dashboard {#dashboard}

1. In the dashboard, go to **App Deployment** and open the deployment.
2. Open the **Billing** tab.
3. On the **Billed by use instead** card, select **Switch to usage billing…**. The card shows only for a deployment that is active, not set to end, and billed pay as you go or monthly per location.
4. Read the preview. It prices the last 30 days, or the days since the deployment began, both ways: **On usage billing**, the **Difference**, and **The move happens**, then each meter's use and cost. When nothing was measured yet, a note says the estimate assumes the deployment ran all month.
5. For a deployment billed monthly per location, choose **When its paid period ends** (the default) or **Now**. **Now** credits the unused days, less the days Coritan keeps back, to your credit balance.
6. Select **Switch to usage billing**.

The button stays off while the preview loads, and when the move is refused. The dialog says why, in the words of [Troubleshooting](#troubleshooting). A member of an organization with the Billing role or above switches the organization's own deployments the same way, and the owner's account pays.

## Preview the move {#preview}

A preview prices the last 30 days, or the days since the service began when that is shorter, as usage billing would have, and sets it beside what the service paid. It changes nothing. Use [`POST /billing/deployments/{app_uuid}/switch`](/docs/api/reference/client/billing/#op-post-api-v1-billing-deployments-app-uuid-switch) for a deployment, and [`POST /billing/services/{service_id}/switch`](/docs/api/reference/client/billing/#op-post-api-v1-billing-services-service-id-switch) for an instance, a game server or a database. Add `?preview=1`, or send `{"preview": true}`.

```bash
curl -s -X POST "https://api.coritan.com/api/v1/billing/deployments/$DEPLOYMENT_UUID/switch?preview=1" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

The answer is shortened here:

```json
{
  "preview": true,
  "current": {"billing": "payg", "cycle": "hourly", "price": "0.0055", "paid": "3.96", "renews_at": null},
  "usage": {
    "total": "1.14",
    "currency": "USD",
    "lines": [
      {"meter": "memory_gib_hours", "unit": "GiB-hour", "quantity": "365.000000", "included": "100.000000", "billable": "265.000000", "unit_price": "0.003", "amount": "0.7950"},
      {"meter": "cpu_vcpu_hours", "unit": "vCPU-hour", "quantity": "73.000000", "included": "50.000000", "billable": "23.000000", "unit_price": "0.015", "amount": "0.3450"}
    ]
  },
  "basis": "measured",
  "window": {"start": "2026-09-11T00:00:00", "end": "2026-10-11T00:00:00", "hours": 720, "days": 30},
  "difference": "-2.82",
  "effective": "now",
  "switches_at": null,
  "credit": "0.00",
  "credit_now": "0.00",
  "scheduled": null,
  "refusal": null,
  "notes": ["The included monthly amounts are applied to this service alone."]
}
```

`current`
: How the service is billed now (`payg`, `commit` or `flat`), its billing cycle and price, what it `paid` in the window and, for a service on a longer cycle, when it `renews_at`.

`usage`
: What the window would have cost on usage billing: a line for each meter, with its `quantity`, what the month's amounts cover (`included`), what is `billable`, the `unit_price` and the `amount`, and the `total`. A preview applies the month's included amounts to this service alone. For a server it applies the Paid plan's amounts.

`basis`
: `measured` when the figures come from the service's own meters and run history. `assumed` when nothing was measured yet, and the preview takes the service as always running with its CPU at 10%.

`difference`
: `usage.total` less what the service paid. A negative figure means usage billing would have cost less.

`effective`, `switches_at`, `credit`
: When the move would happen and what it would credit, as [When the move happens](#when) describes.

`refusal`
: What stops the move now, with its `code` and `message`: the Paid plan or the first deposit missing, or a renewal invoice part paid. The estimate stays in the answer.

## Move the service {#move}

Send the same request without `?preview=1`. The body is optional. It takes `when` for a service that is billed by the month or longer:

```bash
curl -s -X POST https://api.coritan.com/api/v1/billing/deployments/$DEPLOYMENT_UUID/switch \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"when": "now"}'
```

The answer is the deployment's billing, as [`GET /billing/deployments/{app_uuid}`](/docs/api/reference/client/billing/#op-get-api-v1-billing-deployments-app-uuid) returns it, with a `switch` object: `effective`, `switched` (`true` when the service moved now), `switches_at`, `credited` and `from`. For an instance, a game server or a database, the answer holds its `service` in place of the deployment's billing, with the same `switch` object.

## When the move happens {#when}

A service billed by the hour moves at once. A deployment on pay as you go is one.

A service billed by the month or longer, such as a deployment on monthly per location or an instance on a monthly plan, moves in one of two ways:

`"when": "renewal"` (the default)
: It keeps its price until its paid period ends, then moves. We void its open renewal invoices, so it is not invoiced again. The `switch` object's `effective` reads `at renewal` and `switches_at` gives the date.

`"when": "now"`
: It moves at once. We credit the unused days of the period you paid for, less the days Coritan keeps back, to your credit balance, and `credited` says how much. By default Coritan keeps back one day, as for a downgrade ([Change a service's plan](/docs/billing/change-plan/#what-the-preview-shows)). We void its open renewal invoices too.

Once a service has a move scheduled for its renewal, a second request without `"when": "now"` answers `409` with the code `switch_scheduled`.

After the move, the service has an amount of 0 and an hourly cycle, and no monthly cap. Rating starts at the first whole hour after the move, so no hour is billed twice. Spend limits and add-ons stay as they are.

## Result

The service's billing shows usage billing. A deployment's `billing_mode` is `usage`, and its **Billing** tab reads **Billed by use** with its rates and the free amounts. From the first whole hour, each hour's use appears in [`GET /billing/usage`](/docs/api/reference/client/billing/#op-get-api-v1-billing-usage), and a prepaid account sees the charge in its credit history as `Compute usage for service #311`.

## Troubleshooting

`402` with the code `paid_plan_required`
: An instance, a game server or a database needs the Paid plan. The answer names the add-on in `upgrade.addon` and the plan that includes it in `upgrade.plan`. Add it, or move to Pro, then try again ([The Paid plan](/docs/billing/usage-billing/#paid-plan)).

`403` with the code `deposit_required`
: A prepaid account has not added the first deposit. The answer gives its `minimum`. [Add credit](/docs/billing/add-credit/), then try again.

`404`
: The deployment or service is not one this account pays for.

`409` with the code `already_usage`
: The service is already billed by use.

`409` with the code `free_server`, `sponsored`, `brand_service`, `organization_customer` or `organization_service`
: The service has no price to move or keeps terms that someone else sets: the free server, a deployment Coritan runs at no charge, a service that keeps a Coritan brand's price, a service of an organization's customer, or a service of an organization. An organization moves its own deployments with [its own billing page](/docs/organizations/deployment-usage-billing/).

`409` with the code `not_billed`
: The deployment has no billing yet, so there is nothing to move.

`409` with the code `not_usage_billable`
: The service is not a server or a deployment. Only those can be billed by use.

`409` with the code `service_not_active` or `service_ending`
: The service is suspended, still being set up, or set to end. Pay its open invoice, or keep it, then try again.

`409` with the code `renewal_part_paid`
: A renewal invoice the move would void is part paid. The answer gives its `invoice_number`. [Pay the invoice](/docs/billing/invoices/), then try again.

`429`
: You have made more than 20 changes or 240 previews in an hour. Wait, then try again.

## Related

- [How usage billing works](/docs/billing/usage-billing/)
- [Usage rates and included amounts](/docs/billing/usage-rates/)
- [How App Deployment is billed](/docs/managed-containers/how-billing-works/)
- [Change a service's plan](/docs/billing/change-plan/)

## API

- `POST /api/v1/billing/deployments/{app_uuid}/switch`: Move a deployment from pay as you go or a commit to usage billing (https://www.coritan.com/docs/api/reference/client/billing/#op-post-api-v1-billing-deployments-app-uuid-switch)
- `POST /api/v1/billing/services/{service_id}/switch`: Switch service to usage (https://www.coritan.com/docs/api/reference/client/billing/#op-post-api-v1-billing-services-service-id-switch)