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	GET	/settings/billing_periods	Returns a page of billing periods under data, with paging details under pagination.
Create a billing period	POST	/settings/billing_periods	Creates a billing period and returns it under billing_period.
Retrieve a billing period	GET	/settings/billing_periods/{billing_period_id}	Returns one billing period by its id, under billing_period.
Delete a billing period	DELETE	/settings/billing_periods/{billing_period_id}	Deletes a billing period. The response has no body.
Update a billing period	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. 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.