Skip to main content
Service

List recurring-billing cycles

Returns a paginated list of recurring-billing cycles for the authenticated company. Results are ordered by created_at (newest first).

GET
/cycles

A cycle owns the cadence, amount and next billing date behind a service plan's recurring charge — the service plan's own fields do not. Follow billing_cycle_ids from a service plan or a serviced job to get here.

Cancelled and rollup cycles are included. Filter them out with status and pricing_mode if you do not want them; they are returned by default so that a sync does not read an omitted row as a deletion.

next_amount is in dollars, and is null for rollup cycles, which charge whatever work is outstanding when the period closes.

Requires the service_plans:read scope.

Authorizations

x-api-keystringheaderrequired

Company API key in the format: rotor_{keyId}_{keySecret}

To obtain an API key:

  1. Log into your Rotor dashboard
  2. Go to Settings → Integrations → API Keys
  3. Create a new key and select the scopes you need
  4. Copy the key — it's only shown once!

Query Parameters

pageintegerquerydefault:1

Page number (1-based)

Required range: 1 <= x
Example: 1
limitintegerquerydefault:50

Number of results per page (max 1000)

Required range: 1 <= x <= 1000
Example: 50
statusstringquery

Comma-separated list of statuses to include

Example: active,past_due
pricing_modeenum<string>query
Available options: fixed, rollup, variable
Example: fixed
customer_idstringquery

Only cycles billing this customer

service_plan_idstringquery

Only cycles that bill this service plan

next_billing_date_range_startstringquery

Cycles whose next charge falls on or after this calendar date

Example: 2026-09-01
next_billing_date_range_endstringquery

Cycles whose next charge falls on or before this calendar date

Example: 2026-09-30
created_at_range_startstringquery
created_at_range_endstringquery

Headers

rotor-api-versionenum<string>headerdefault:1.1.0required

Required OpenAPI version header.

Available options: 1.1.0
Example: 1.1.0

Response

application/json

Cycles listed successfully

dataobject[]
paginationobject
statusstring
Example: success

Still need help? Ask the team