# Usage Billing

Usage billing enables you to bill your customers based on the volume of use in the billing period. For example, if you want to implement a credits-based pricing system, you can do so with usage billing.

Usage is tracked in the usage table and is reported to Stripe daily (customisable).

{% hint style="info" %}
Usage tracking is supported on [free accounts](/gravity-server/free-accounts.md) but won't be reported to Stripe or billed.
{% endhint %}

## Enabling Usage Billing in Stripe

Usage billing uses the volume pricing in Stripe. 

You must create a new price and set the pricing model to volume pricing. Then, set the price per unit to whatever you want to charge per unit.

{% hint style="danger" %}
Stripe doesn't support switching from a non-volume pricing model to a volume pricing model on the same subscription. Ensure all of your prices are volume pricing to support changing plans.
{% endhint %}

<figure><img src="/files/fOveFX2AAcYfgBR7j58r" alt=""><figcaption></figcaption></figure>

## Incrementing Usage

To track usage, use the `usage.increment` method. You can increment by a specific amount  passing `quantity` or omit it to increment by one.

```javascript
const usage = require('./model/usage');

// increment by 10 
usage.increment({ account: 'account_id', quantity: 10 });

// increment by 1
usage.increment({ account: 'account_id' });
```

You should call this function in any relevant API endpoint where you want to log use.

## Reporting Usage to Stripe

Usage is [reported to Stripe](https://stripe.com/docs/products-prices/pricing-models#reporting-usage) once per day using the `usage` [background job](/gravity-server/background-jobs.md). You can customise how often this job runs in `config.worker_schedule.usage`

Shorter billing times are recommended to ensure Stripe always has the latest usage data for the current billing period and can charge your customers the correct amount.&#x20;

When usage is reported, the `report` column of the usage table for the corresponding report will be marked as `true`. The `end_period` will also be populated, and the report is closed.&#x20;

The worker will then open a new report, and any incrementation will be applied to the new open report.

## Getting Usage

You can use the usage.get method to fetch usage. The client application will fetch and display usage for the current billing period.

```javascript
const usageData = await usage.get({ 

  account: 'account_id', 
  period_start: '2023-10-10', 
  period_end: '2023-11-11'

});
```

## Prorations

On usage (and seat) tiered plans, `invoice_now` and `prorate` are enabled. Users will be charged at the end of the billing cycle for uncharged tiered usage.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usegravity.app/gravity-server/payments/usage-billing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.