Start here
Cycle API
Add subscriptions, checkout and payments to your app over a JSON REST API, with signed webhooks. Test mode is free; real payments go to your own bank account.
Two APIs
Cycle has two APIs. Most apps only need the billing API.
| API | Authenticated with | For |
|---|---|---|
| Billing API | A business's secret key: sk_test_… or sk_live_… | Products and prices, checkout, customers, subscriptions, payments, refunds, invoices and events. Webhooks tell your server when something happens. |
| Account API | A personal access token | Read-only: your user profile and the teams you belong to. |
Start in test mode
- First subscription: a plan, a checkout and a webhook in a few minutes.
- Test cards: a test card for every outcome, with no real money.
- Build with AI: let an AI coding assistant add Cycle to your app.
Your first billing request, with a test key from Developers → Keys & webhooks in the dashboard:
curl -X GET https://cycle.am/api/v1/customers \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Base URL
Both APIs share this base URL. The API version is part of the path.
Base URL
https://cycle.am/api/v1Endpoint paths in the references are shown in full, for example /api/v1/customers.
Account API: first request
- Sign in to Cycle and open Settings → API tokens.
- Create a token with the Read permission (it is selected by default) and copy it. It is shown only once.
- Store it in an environment variable, for example
CYCLE_API_TOKEN, and callGET /api/v1/user.
curl https://cycle.am/api/v1/user \
-H "Authorization: Bearer $CYCLE_API_TOKEN" \
-H "Accept: application/json"The response is your user, wrapped in a data key. The Personal tokens page explains tokens, permissions and rate limits.
Account API conventions
- JSON everywhere. Responses, including errors, are
application/json. SendAccept: application/jsonon every request. - Wrapped in
data. A successful response puts the resource, or the list of resources, in a top-leveldatakey. - ISO 8601 timestamps. Dates are strings with a UTC offset, for example
2026-11-12T09:30:00+00:00. - Integer IDs. Every object has a numeric
id. Teams are addressed in URLs by theirslug. - Null, not missing. A field without a value is returned as
null, for exampleemail_verified_atbefore the address is verified. - No pagination yet. List endpoints return every item in one
dataarray, withoutlinksormeta.
The billing API has its own conventions (IDs like cus_…, amounts in minor units, paged lists with links and meta), described on the Billing endpoints page.
Where to go next
- Billing endpoints: every billing endpoint, with fields and example responses.
- Events & webhooks: event types, signatures and retries.
- Personal tokens: personal tokens for the account API, permissions and rate limits.
- Error responses: status codes and what each error body looks like.