Switch a service to usage billing

A service ordered before 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). 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.

• 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 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).
• A Cloud Compute instance, a game server or a database needs the 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.

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. 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.

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 for a deployment, and POST /billing/services/{service_id}/switch for an instance, a game server or a database. Add ?preview=1, or send {"preview": true}.

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:

{
  "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 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.

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:

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} 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.

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). 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.

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, and a prepaid account sees the charge in its credit history as Compute usage for service #311.

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).

403 with the code deposit_required

A prepaid account has not added the first deposit. The answer gives its minimum. 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.

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, then try again.

429

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

• How usage billing works
• Usage rates and included amounts
• How App Deployment is billed
• Change a service's plan