# Set up usage billing in the dashboard (/docs/usage-billing/dashboard)

You can set up usage billing in the dashboard, with no code. Your app still has to send the usage, but everything else is a few forms. This guide walks through each screen.

All of it is under **Usage Billing** in the side menu. The page has five tabs: **Overview**, **Customers**, **Prices**, **Metrics** and **Usage keys**.

## Before you start [#before-you-start]

- **Usage billing is turned on for your account.** Comecero turns it on: ask support. Until then, every Usage Billing page says "Usage billing isn't turned on for your account."
- **The customer has a subscription.** Usage goes on the subscription's renewal invoice, next to the plan's price, and is charged with the card the customer already uses. Only active subscriptions and subscriptions in a trial can be billed for usage.
- **Start in test mode.** Turn on **Test** at the top of the dashboard. Test mode has its own metrics, prices, customers and keys, so you can try everything without charging anyone. Set it up again in live mode when you are ready.

<Steps>

<Step>

## Open the setup checklist [#open-the-setup-checklist]

Open **Usage Billing**. On a new account, the **Overview** tab shows a checklist called **Set up usage billing**, with a button for each step. It hides itself once every step is done.

![The Usage Billing overview with the setup checklist](/images/guides/usage/usage-overview-new.png)

</Step>

<Step>

## Add a metric [#add-a-metric]

A metric is something you charge for, such as API calls, AI tokens or seats. Click **Add metric**.

![The Add metric form](/images/guides/usage/usage-metric-add.png)

| Field | What to enter |
| --- | --- |
| **Name** | What you and your customers see on invoices, such as "API calls". |
| **Metric key** | The name your app sends with each event, such as `api_calls`. Lowercase letters, digits, `_`, `.` or `-`. It can't be changed later. |
| **Unit** | What one unit is called on invoices, such as `call`, `GB` or `token`. |
| **Counted as** | **Total (sum)** adds up every event: API calls, messages sent. **Highest (gauge)** takes the highest level each hour, and the bill uses the highest hour of the period: storage used, seats. This can't change once the metric is in use. |
| **Allowed properties** | Optional. Extra fields your app may send with an event, such as `model` or `region`, separated by commas. Up to 20. |

Click **Save metric**. A new metric takes a few minutes to reach the usage meter. Until then it shows **Updating**.

</Step>

<Step>

## Set a price [#set-a-price]

Open **Prices** and click **Add price**.

![The Add price form](/images/guides/usage/usage-price-add.png)

1. Pick the **Metric**.
2. Enter the **Currency**. It must be the currency of the subscriptions you bill with this price.
3. Choose **How it is charged**:
   - **Per unit:** every unit above what is included costs the same.
   - **Per package:** units above what is included are sold in packages, such as 1,000 at a time. A part package costs a whole one.
4. Enter the price. Up to 6 decimals, such as `0.002` for a fifth of a cent.
5. Enter what is **Included each billing period**: free units before anything is charged. Use `0` for none.

The box at the bottom shows what customers are billed, for example "100,000 included, then USD 0.00002 per token". Click **Save price**.

A price can't be changed once it is saved, so bills already made stay right. To charge a different amount, add a new price and move customers to it. Tiered prices, where the price per unit drops as usage grows, are made with the API: see [Set up usage billing](/docs/usage-billing/set-up#2-set-a-price).

</Step>

<Step>

## Bill a customer [#bill-a-customer]

Open **Customers** and click **Bill a customer**.

First, choose the subscription. The list shows live subscriptions, newest first. Search by customer name, or by the exact email or subscription id. Then fill in what they are billed for:

![The Bill a customer for usage form, with a subscription chosen](/images/guides/usage/usage-bill-customer.png)

| Field | What to enter |
| --- | --- |
| **Your customer id** | The id your app sends with this customer's usage, as `external_customer_id`. Usually your own user or account id, such as `user_8342`. Never an email. It can't be changed later. |
| **Metric** | What they pay for. |
| **Price** | Only prices in the subscription's currency are listed. **Add another price** opens the price form. |
| **Start billing usage** | **From the start of this period** also bills usage since the current period began. **From now** bills only usage from now on. |

**What happens** sums it up in one sentence. Click **Start billing usage**. To bill the same customer for a second metric, open them and click **Bill another metric**.

<Callout type="warn">
The usage meter counts events for any customer id, but only bills ids that match a customer here. If your app sends a different id, the usage is counted and never billed. Copy the id exactly.
</Callout>

</Step>

<Step>

## Create a usage key [#create-a-usage-key]

Your app sends usage with a usage key. Open **Usage keys**, enter a **Name** such as "Production app", and click **Create key**.

![The new usage key, shown once](/images/guides/usage/usage-key-created.png)

The key starts with `apk_test_` in test mode and `apk_live_` in live mode. **It is shown only once.** Copy it into the place your app keeps its secrets, then click **I have copied it**. If it is ever lost, create a new key and revoke the old one.

A new key shows **Activating** for a few minutes, then **Active**. **Revoke** stops a key. A revoked key can still send usage for a few minutes while the change reaches the usage meter.

</Step>

<Step>

## Send usage from your app [#send-usage-from-your-app]

This step is for whoever builds your app. The **Send usage events** card on the **Overview** and **Usage keys** tabs has the address and a request to copy:

![The Send usage events card with the address and an example request](/images/guides/usage/usage-send-events.png)

Paste the example in a terminal with your test key in place of `<your usage key>`, and the event is counted. Each event needs four values:

- `operation_id`: a new id for each piece of usage. Sending the same one again never counts twice.
- `external_customer_id`: the **Your customer id** you entered for the customer.
- `metric_key`: the metric's **Metric key**.
- `quantity`: how much was used, as text, such as `"125"`.

For the code, see [Send usage](/docs/usage-billing/send-usage) or the [Bill for API calls](/docs/tutorials/bill-for-api-calls) tutorial.

</Step>

</Steps>

## Check that usage arrives [#check-that-usage-arrives]

Open **Customers** and click the customer. Their page shows:

- **This period so far:** usage not billed yet, against what is included, and the **Estimated usage charge**. It can be a few minutes behind.
- **What is billed:** each metric and its price. **Change price** moves them to another price. Usage not billed yet is billed at the new price.
- **Prepaid credit:** the balance and **Add credit**, when the customer has a credit balance. See [Credits and burndown](/docs/usage-billing/credits).
- **Billing runs:** each period that was billed, with its invoice.
- **Usage:** a chart for the last 24 hours, 7, 30 or 90 days.

![A customer's usage page: details, this period so far and what is billed](/images/guides/usage/usage-customer-detail.png)

Click **View events** to see every event your app sent for the customer, one UTC day at a time. Events show here a few minutes after they are counted. Use it to check that your app sends the right ids, or to answer a question about a bill.

![The events for one customer and day](/images/guides/usage/usage-events.png)

## What happens at renewal [#what-happens-at-renewal]

When the subscription renews, Comecero adds up the period's usage, takes off what is included, prices the rest and puts it on the renewal invoice. You don't need to do anything. Customer, subscription and invoice pages in the dashboard also have a **Usage billing** card with **Open usage**.

Sometimes a bill is held instead. The **Overview** tab then shows it under **Needs your attention**, and the customer is not charged for it until it is sorted out:

| Shown as | What to do |
| --- | --- |
| **Being checked by Comecero** | The bill is above the review limit. Comecero checks it with you, then releases it. |
| **Waiting for credit** | The customer used more than their prepaid credit, and their plan stops at the credit. Add credit, then click **Bill it again** under **Billing runs**. |
| **Price in another currency** | A price is not in the subscription's currency. Use **Change price** to pick one that is, then **Bill it again**. |
| **Price or metric missing** | Bill them with an existing metric and price, then **Bill it again**. |

Usage too small to invoice on its own waits under **Waiting for the next invoice**. See [How usage is billed](/docs/usage-billing/how-usage-is-billed) for every case.

## Go live [#go-live]

Turn **Test** off and do the same steps in live mode: add the metric, the price, bill each customer and create a live key. Test and live never mix. A test key can't send live usage, and test usage is never billed to a live customer.