> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Dedicated billing

> Pay for a Dedicated database monthly, yearly or by the hour, from your wallet or card.

> [!NOTE]
>
> **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

## Goal

Choose how to pay for a Dedicated database and understand what happens when a payment fails.

## Prerequisites

* A wallet balance or a saved card

## Workflow

**Step 1**

Choose `billing` when you create the database: `monthly` (default), `yearly` or `hourly`.

**Step 2**

Monthly and yearly are paid up front from your wallet, or through a checkout link when the wallet is short.

**Step 3**

Hourly needs a wallet balance or a saved card; the first hour is charged when you create the database.

**Step 4**

See what you are paying and when with `stackshift database billing DATABASE` (`GET /api/v1/databases/{id}/billing`). It shows the status, the price lines, the current period and anything overdue.

## Changes during a period

* Upgrades (a bigger size, a standby, a replica, more storage) are charged for the rest of the period. The API first answers `409 price_confirmation_required` with the exact charge; send the same request again with `confirm_charge_minor` to confirm.
* Downgrades and removals credit your wallet.
* A size change that fails is credited back, so you aren’t charged for a size you didn’t get.
* On hourly billing the new price simply applies from the next hour.
* Automatic storage growth never asks for confirmation; the new storage price applies from the next renewal or hour.

## Pay by card and check a payment

* When a charge needs a card payment, the answer is `402 payment_required` with a `checkout_url`. Open it and pay.
* After you are redirected back, the database page confirms the payment.
* Pay whatever is due (a first payment, an overdue renewal or unpaid hourly usage) from the database page. Payments need a signed-in browser: the CLI and agent tokens get `403 browser_session_required`.
* The billing status is `pending_payment`, `active`, `past_due`, `suspended`, `paused`, `terminated` or `cancelled`.

## Change how you pay

* Switch between monthly, yearly and hourly from the database page.
* Monthly or yearly to another prepaid period, or to hourly: the switch is recorded and takes effect at your next renewal. Hourly billing then starts from the end of the period with nothing up front.
* Hourly to monthly or yearly: it takes effect right away and is paid up front from your wallet. You first get `409 price_confirmation_required` with the amount (the new period plus any unbilled hourly usage); resend with `confirm_charge_minor`.
* Sending the mode you already have cancels a switch that hasn’t happened yet.

## If a payment fails

* Monthly and yearly: after the period ends you get a grace period, then the database is suspended (connections are refused, data and backups are kept), and later retired with a final backup. The database page shows each date.
* Hourly: failed card charges are retried; if they keep failing the database is paused (connections refused, data kept) and resumes as soon as you pay.
* Pay what is due from the database page.
* Nothing is deleted without a final backup.

## Prices

See [https://stackshift.cloud/pricing](https://stackshift.cloud/pricing).

## Expected result

> [!TIP]
>
> The database billing shows `active`, with the current period and the next renewal date.

## Common failures

> [!WARNING]
>
> * `402 payment_required` on a change: top up your wallet, then retry.
> * A stopped or suspended database won’t start while a payment is overdue: pay first.

## Related guides

> **[Dedicated databases](https://docs.stackshift.cloud/databases/dedicated-databases.md)**
>
> Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.

> **[Move a Starter database to Dedicated](https://docs.stackshift.cloud/databases/move-starter-to-dedicated.md)**
>
> Copy a Starter PostgreSQL database to a new Dedicated database, switch your apps over and keep the original read-only for 7 days.

> **[Starter or Dedicated](https://docs.stackshift.cloud/databases/starter-and-dedicated.md)**
>
> Starter databases share a server with other databases. A Dedicated database is its own virtual machine with a standby, read replicas and restore to any second.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.