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

# Usages

> Record, list, read, change and delete the usage that Exsited bills on metered order lines.

A usage records how much of a metered item a customer used in a billing period, against one order line. This area records usages one at a time or several at once, and lists, reads, changes and deletes them. It has 6 endpoints, and every SDK supports all of them.

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List usages](https://exsited.mintlify.site/api-reference/usages/list-usages.md) | GET | `/usages` | Lists recorded usages, one page at a time. |
| [Create usages](https://exsited.mintlify.site/api-reference/usages/create-usages.md) | POST | `/usages` | Records one usage, or several in one call, against a metered order line. |
| [Retrieve a usage](https://exsited.mintlify.site/api-reference/usages/retrieve-a-usage.md) | GET | `/usages/{usage_id}` | Returns one usage, under `usage`. |
| [Delete a usage](https://exsited.mintlify.site/api-reference/usages/delete-a-usage.md) | DELETE | `/usages/{usage_id}` | Deletes a usage and returns no content. |
| [Update a usage](https://exsited.mintlify.site/api-reference/usages/update-a-usage.md) | PATCH | `/usages/{usage_id}` | Changes some of a usage's fields and returns a reference to it. |
| [Replace a usage](https://exsited.mintlify.site/api-reference/usages/replace-a-usage.md) | PUT | `/usages/{usage_id}` | Replaces a usage's quantity, times and custom attributes and returns a reference to it. |

## Before you call

Register your API credentials once when your app starts, as shown in
[Authentication](https://exsited.mintlify.site/authentication.md). Every SDK sample on these pages then gets its client in one line.
With cURL, send the access token in an `Authorization` header: `Authorization: Bearer $ACCESS_TOKEN`.

## Things to know

* **A usage belongs to a metered order line.** `charge_item_id` is the `id` of an order line whose item is charged as `METERED`.
* **`charging_period` is two dates joined by a hyphen.** It runs from the order's `order_start_date` to the day before its `next_billing_from_date`, such as `2026-10-01-2026-10-31`.
* **One usage goes under `usage`, several under `usages`.** A list sent under `usage` returns `400`. For several, the response lists each one under `usages.success` or `usages.failed`.
* **Updates return a reference, not the usage.** [Update a usage](https://exsited.mintlify.site/api-reference/usages/update-a-usage.md) and [Replace a usage](https://exsited.mintlify.site/api-reference/usages/replace-a-usage.md) return only the usage's `id` and `href` under `usage`; retrieve the usage again to see the new values.
* **The listing pages by cursor.** Send `limit`, then pass `pagination.next_cursor` as `cursor` while `pagination.has_more` is `true`.


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