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

# Billing periods

> List, create, read, update and delete billing periods, each built on a time period.

A billing period is a settings record built on a time period, with a name, a period and a duration. You can list, create, read, update and delete billing periods. This area has 5 endpoints, and all seven SDKs call every one.

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List billing periods](https://exsited.mintlify.site/api-reference/billing-periods/list-billing-periods.md) | GET | `/settings/billing_periods` | Returns a page of billing periods under `data`, with paging details under `pagination`. |
| [Create a billing period](https://exsited.mintlify.site/api-reference/billing-periods/create-a-billing-period.md) | POST | `/settings/billing_periods` | Creates a billing period and returns it under `billing_period`. |
| [Retrieve a billing period](https://exsited.mintlify.site/api-reference/billing-periods/retrieve-a-billing-period.md) | GET | `/settings/billing_periods/{billing_period_id}` | Returns one billing period by its `id`, under `billing_period`. |
| [Delete a billing period](https://exsited.mintlify.site/api-reference/billing-periods/delete-a-billing-period.md) | DELETE | `/settings/billing_periods/{billing_period_id}` | Deletes a billing period. The response has no body. |
| [Update a billing period](https://exsited.mintlify.site/api-reference/billing-periods/update-a-billing-period.md) | PATCH | `/settings/billing_periods/{billing_period_id}` | Changes the fields you send on a billing period and returns it under `billing_period`. |

## 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 create takes the time period's hyphenated uuid, not its `tp_` id.** For a time period `tp_2b1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d`, send `2b1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d` as `time_period`. Charging and pricing periods take the `tp_` id instead.
* **`name` and `time_period` are required on a create.** Both go under the `billing_period` key.
* **An update returns `time_period` in place of `period` and `duration`.** Read the billing period again to see those two fields.
* **A billing period `id` starts with `bp_`.**
* **Listings page by cursor.** Records sit under `data`; pass `pagination.next_cursor` as `cursor` to read the next page, and stop when `pagination.has_more` is `false`.
* **A delete returns `204` with no body.** Reading the billing period afterwards returns `404`.


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