Skip to content
On this page

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.

APIAuthenticated withFor
Billing APIA 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 APIA personal access tokenRead-only: your user profile and the teams you belong to.

Start in test mode

  1. First subscription: a plan, a checkout and a webhook in a few minutes.
  2. Test cards: a test card for every outcome, with no real money.
  3. 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/v1

Endpoint paths in the references are shown in full, for example /api/v1/customers.

Account API: first request

  1. Sign in to Cycle and open Settings → API tokens.
  2. Create a token with the Read permission (it is selected by default) and copy it. It is shown only once.
  3. Store it in an environment variable, for example CYCLE_API_TOKEN, and call GET /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. Send Accept: application/json on every request.
  • Wrapped in data. A successful response puts the resource, or the list of resources, in a top-level data key.
  • 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 their slug.
  • Null, not missing. A field without a value is returned as null, for example email_verified_at before the address is verified.
  • No pagination yet. List endpoints return every item in one data array, without links or meta.

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