Billing API
Billing API
Create plans, open checkouts, manage customers and subscriptions, read payments, invoices and events, refund payments and register webhooks with your business's secret key.
Introduction
The billing API works on one business in one mode. A secret key decides both: a sk_test_… key sees and changes only test data, a sk_live_… key only live data. It can never reach another business.
Create keys in the dashboard under Developers → Keys & webhooks. Base URL: https://cycle.am/api/v1.
curl -X GET https://cycle.am/api/v1/customers \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Authentication and scopes
Send the key as Authorization: Bearer sk_test_…. A key has scopes and can be limited to IP addresses:
| Scope | Allows |
|---|---|
read | List and retrieve customers, products, subscriptions, payments, invoices and events. |
write | Create and change customers and subscriptions, cancel subscriptions and refund payments. Includes Read. |
Rotate a key from the dashboard to replace it; the old one can keep working for up to 7 days while you switch. Revoked and expired keys get 401.
Idempotent requests
Send an Idempotency-Key header (any unique string, up to 255 characters, like a UUID) with every POST. If the network fails and you send the same request again with the same key within 24 hours, Cycle returns the first response, with Idempotent-Replayed: true, instead of creating or charging twice.
- The same key with different parameters gets
422. - A retry while the first request is still running gets
409; try again a moment later. - Server errors (
5xx) aren't stored, so retrying with the same key runs the request again.
Lists and pagination
List endpoints return a page of objects in data, newest first, with links and meta for the other pages. Use ?limit= (1 to 100, default 20) and ?page=.
Amounts are integers in minor units: 1200000 with currency AMD is ֏ 12 000. Times are ISO 8601. Every object has livemode.
Errors
Errors have a JSON message; validation errors add errors by field. Branch on the status code.
Response
404{
"message": "No such customer: cus_unknown"
}Response
422{
"message": "This customer has no card to charge.",
"errors": {
"subscription": [
"This customer has no card to charge."
]
}
}Endpoints
| Method | Path | Endpoint |
|---|---|---|
GET | /api/v1/customers | List customers |
POST | /api/v1/customers | Create a customer |
GET | /api/v1/customers/{customer} | Retrieve a customer |
PATCH | /api/v1/customers/{customer} | Update a customer |
GET | /api/v1/products | List products |
GET | /api/v1/products/{product} | Retrieve a product |
GET | /api/v1/prices | List prices |
GET | /api/v1/prices/{price} | Retrieve a price |
GET | /api/v1/subscriptions | List subscriptions |
POST | /api/v1/subscriptions | Create a subscription |
GET | /api/v1/subscriptions/{subscription} | Retrieve a subscription |
POST | /api/v1/subscriptions/{subscription}/cancel | Cancel a subscription |
GET | /api/v1/payments | List payments |
GET | /api/v1/payments/{payment} | Retrieve a payment |
POST | /api/v1/payments/{payment}/refunds | Refund a payment |
GET | /api/v1/invoices | List invoices |
GET | /api/v1/invoices/{invoice} | Retrieve an invoice |
GET | /api/v1/events | List events |
GET | /api/v1/events/{event} | Retrieve an event |
POST | /api/v1/products | Create a product |
POST | /api/v1/prices | Create a price |
POST | /api/v1/checkout/sessions | Create a checkout session |
GET | /api/v1/checkout/sessions/{checkoutSession} | Retrieve a checkout session |
POST | /api/v1/customers/{customer}/portal-links | Create a customer portal link |
GET | /api/v1/webhook-endpoints | List webhook endpoints |
POST | /api/v1/webhook-endpoints | Create a webhook endpoint |
DELETE | /api/v1/webhook-endpoints/{webhookEndpoint} | Delete a webhook endpoint |
POST | /api/v1/test/subscriptions/{subscription}/renew | Renew a subscription now (test mode) |
List customers
/api/v1/customersCustomers, newest first. Filter with ?email=.
Query parameters
limitinteger- Objects per page, 1 to 100. Default 20.
pageinteger- The page to return, from 1.
emailstring- Only the customer with this email.
Request
curl -X GET https://cycle.am/api/v1/customers \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "cus_8f2a1c",
"object": "customer",
"email": "ani@example.com",
"name": "Ani Petrosyan",
"phone": null,
"locale": "hy",
"default_card": {
"id": "pm_0c9e44",
"object": "card",
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2029,
"status": "active"
},
"metadata": {
"crm_id": "1042"
},
"livemode": false,
"created_at": "2026-11-12T09:30:00+00:00"
}
],
"links": {
"first": "…?page=1",
"last": "…?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Create a customer
/api/v1/customersCreates a customer in the key's mode.
Body parameters
emailstringrequired- The customer's email. Receipts and portal links go here.
namestring- Full name.
phonestring- Phone number, up to 32 characters.
localestring- Language of emails and customer pages:
hyoren. metadataobject- Up to 20 string values for your own use.
Request
curl -X POST https://cycle.am/api/v1/customers \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"email":"ani@example.com","name":"Ani Petrosyan"}'Response
Example response
201{
"data": {
"id": "cus_8f2a1c",
"object": "customer",
"email": "ani@example.com",
"name": "Ani Petrosyan",
"phone": null,
"locale": "hy",
"default_card": {
"id": "pm_0c9e44",
"object": "card",
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2029,
"status": "active"
},
"metadata": {
"crm_id": "1042"
},
"livemode": false,
"created_at": "2026-11-12T09:30:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
Retrieve a customer
/api/v1/customers/{customer}Returns one customer.
Request
curl -X GET https://cycle.am/api/v1/customers/cus_8f2a1c \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "cus_8f2a1c",
"object": "customer",
"email": "ani@example.com",
"name": "Ani Petrosyan",
"phone": null,
"locale": "hy",
"default_card": {
"id": "pm_0c9e44",
"object": "card",
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2029,
"status": "active"
},
"metadata": {
"crm_id": "1042"
},
"livemode": false,
"created_at": "2026-11-12T09:30:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
Update a customer
/api/v1/customers/{customer}Changes the fields you send; the others stay as they are.
Request
curl -X PATCH https://cycle.am/api/v1/customers/cus_8f2a1c \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Ani P."}'Response
Example response
200{
"data": {
"id": "cus_8f2a1c",
"object": "customer",
"email": "ani@example.com",
"name": "Ani Petrosyan",
"phone": null,
"locale": "hy",
"default_card": {
"id": "pm_0c9e44",
"object": "card",
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2029,
"status": "active"
},
"metadata": {
"crm_id": "1042"
},
"livemode": false,
"created_at": "2026-11-12T09:30:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
List products
/api/v1/productsProducts with their prices, newest first. Filter with ?active=true.
Query parameters
limitinteger- Objects per page, 1 to 100. Default 20.
pageinteger- The page to return, from 1.
Request
curl -X GET https://cycle.am/api/v1/products \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "prod_3b9d0e",
"object": "product",
"name": "Yoga membership",
"description": null,
"active": true,
"prices": [
{
"id": "price_7c41aa",
"object": "price",
"product": "prod_3b9d0e",
"nickname": "Monthly",
"amount": 1200000,
"currency": "AMD",
"type": "recurring",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"active": true,
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
],
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
],
"links": {
"first": "…?page=1",
"last": "…?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Retrieve a product
/api/v1/products/{product}Returns one product with its prices.
Request
curl -X GET https://cycle.am/api/v1/products/prod_3b9d0e \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "prod_3b9d0e",
"object": "product",
"name": "Yoga membership",
"description": null,
"active": true,
"prices": [
{
"id": "price_7c41aa",
"object": "price",
"product": "prod_3b9d0e",
"nickname": "Monthly",
"amount": 1200000,
"currency": "AMD",
"type": "recurring",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"active": true,
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
],
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
List prices
/api/v1/pricesPrices, newest first. Filter with ?product= and ?active=.
Query parameters
limitinteger- Objects per page, 1 to 100. Default 20.
pageinteger- The page to return, from 1.
Request
curl -X GET https://cycle.am/api/v1/prices \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "price_7c41aa",
"object": "price",
"product": "prod_3b9d0e",
"nickname": "Monthly",
"amount": 1200000,
"currency": "AMD",
"type": "recurring",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"active": true,
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
],
"links": {
"first": "…?page=1",
"last": "…?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Retrieve a price
/api/v1/prices/{price}Returns one price.
Request
curl -X GET https://cycle.am/api/v1/prices/price_7c41aa \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "price_7c41aa",
"object": "price",
"product": "prod_3b9d0e",
"nickname": "Monthly",
"amount": 1200000,
"currency": "AMD",
"type": "recurring",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"active": true,
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
List subscriptions
/api/v1/subscriptionsSubscriptions, newest first. Filter with ?customer= and ?status= (scheduled, trialing, active, past_due, paused, canceled, incomplete).
Query parameters
limitinteger- Objects per page, 1 to 100. Default 20.
pageinteger- The page to return, from 1.
Request
curl -X GET https://cycle.am/api/v1/subscriptions \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "sub_51e0d2",
"object": "subscription",
"customer": "cus_8f2a1c",
"price": "price_7c41aa",
"pending_price": null,
"status": "active",
"quantity": 1,
"currency": "AMD",
"collection_method": "charge_automatically",
"days_until_due": null,
"description": null,
"current_period_start": "2026-11-12T09:31:00+00:00",
"current_period_end": "2026-12-12T09:31:00+00:00",
"trial_end": null,
"next_charge_at": "2026-12-12T09:31:00+00:00",
"next_charge_amount": 1200000,
"cancel_at_period_end": false,
"canceled_at": null,
"cancel_reason": null,
"pause": null,
"billing_cycles": null,
"periods_paid": 1,
"discount": null,
"livemode": false,
"created_at": "2026-11-12T09:31:00+00:00"
}
],
"links": {
"first": "…?page=1",
"last": "…?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Create a subscription
/api/v1/subscriptionsStarts a subscription. Unless it has a trial, a later start date or is paid by invoice, the first period is charged to the customer's saved card right away; if the card is declined the subscription stays incomplete. Send an Idempotency-Key so a retry never charges twice.
Body parameters
customerstringrequired- The customer's ID. They need a saved card unless
collection_methodissend_invoice. pricestringrequired- An active price's ID.
quantityinteger- Default 1.
trial_daysinteger- Free days before the first charge. Defaults to the price's trial.
start_datestring- A later day to start billing (
YYYY-MM-DD, in the business's timezone). Can't be combined with a trial. billing_cyclesinteger- End by itself after this many paid periods (1 to 120).
couponstring- A coupon code.
descriptionstring- Shown on its payments and invoices.
collection_methodstringcharge_automatically(default) orsend_invoice(email an invoice each period).days_until_dueinteger- For
send_invoice: days to pay each invoice (0 = on receipt).
Request
curl -X POST https://cycle.am/api/v1/subscriptions \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"customer":"cus_8f2a1c","price":"price_7c41aa"}'Response
Example response
201{
"data": {
"id": "sub_51e0d2",
"object": "subscription",
"customer": "cus_8f2a1c",
"price": "price_7c41aa",
"pending_price": null,
"status": "active",
"quantity": 1,
"currency": "AMD",
"collection_method": "charge_automatically",
"days_until_due": null,
"description": null,
"current_period_start": "2026-11-12T09:31:00+00:00",
"current_period_end": "2026-12-12T09:31:00+00:00",
"trial_end": null,
"next_charge_at": "2026-12-12T09:31:00+00:00",
"next_charge_amount": 1200000,
"cancel_at_period_end": false,
"canceled_at": null,
"cancel_reason": null,
"pause": null,
"billing_cycles": null,
"periods_paid": 1,
"discount": null,
"livemode": false,
"created_at": "2026-11-12T09:31:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
Retrieve a subscription
/api/v1/subscriptions/{subscription}Returns one subscription.
Request
curl -X GET https://cycle.am/api/v1/subscriptions/sub_51e0d2 \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "sub_51e0d2",
"object": "subscription",
"customer": "cus_8f2a1c",
"price": "price_7c41aa",
"pending_price": null,
"status": "active",
"quantity": 1,
"currency": "AMD",
"collection_method": "charge_automatically",
"days_until_due": null,
"description": null,
"current_period_start": "2026-11-12T09:31:00+00:00",
"current_period_end": "2026-12-12T09:31:00+00:00",
"trial_end": null,
"next_charge_at": "2026-12-12T09:31:00+00:00",
"next_charge_amount": 1200000,
"cancel_at_period_end": false,
"canceled_at": null,
"cancel_reason": null,
"pause": null,
"billing_cycles": null,
"periods_paid": 1,
"discount": null,
"livemode": false,
"created_at": "2026-11-12T09:31:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
Cancel a subscription
/api/v1/subscriptions/{subscription}/cancelCancels at the end of the paid period (default) or now. A canceled subscription is never charged again.
Body parameters
at_period_endbooleantrue(default) to end when the paid period ends,falseto end now.reasonstring- too_expensive, not_using, missing_feature, switching, temporary or other.
commentstring- Up to 500 characters.
Request
curl -X POST https://cycle.am/api/v1/subscriptions/sub_51e0d2/cancel \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"at_period_end":true}'Response
Example response
200{
"data": {
"id": "sub_51e0d2",
"object": "subscription",
"customer": "cus_8f2a1c",
"price": "price_7c41aa",
"pending_price": null,
"status": "active",
"quantity": 1,
"currency": "AMD",
"collection_method": "charge_automatically",
"days_until_due": null,
"description": null,
"current_period_start": "2026-11-12T09:31:00+00:00",
"current_period_end": "2026-12-12T09:31:00+00:00",
"trial_end": null,
"next_charge_at": "2026-12-12T09:31:00+00:00",
"next_charge_amount": 1200000,
"cancel_at_period_end": false,
"canceled_at": null,
"cancel_reason": null,
"pause": null,
"billing_cycles": null,
"periods_paid": 1,
"discount": null,
"livemode": false,
"created_at": "2026-11-12T09:31:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
List payments
/api/v1/paymentsPayments, newest first. Filter with ?customer=, ?subscription= and ?status= (pending, succeeded, failed, requires_action, canceled).
Query parameters
limitinteger- Objects per page, 1 to 100. Default 20.
pageinteger- The page to return, from 1.
Request
curl -X GET https://cycle.am/api/v1/payments \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "pay_b53be1",
"object": "payment",
"amount": 1200000,
"amount_refunded": 0,
"currency": "AMD",
"status": "succeeded",
"type": "subscription",
"description": "Yoga membership",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"invoice": "in_9a7f3c",
"card": {
"brand": "visa",
"last4": "4242"
},
"failure_code": null,
"failure_message": null,
"livemode": false,
"succeeded_at": "2026-11-12T09:31:02+00:00",
"created_at": "2026-11-12T09:31:00+00:00"
}
],
"links": {
"first": "…?page=1",
"last": "…?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Retrieve a payment
/api/v1/payments/{payment}Returns one payment.
Request
curl -X GET https://cycle.am/api/v1/payments/pay_b53be1 \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "pay_b53be1",
"object": "payment",
"amount": 1200000,
"amount_refunded": 0,
"currency": "AMD",
"status": "succeeded",
"type": "subscription",
"description": "Yoga membership",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"invoice": "in_9a7f3c",
"card": {
"brand": "visa",
"last4": "4242"
},
"failure_code": null,
"failure_message": null,
"livemode": false,
"succeeded_at": "2026-11-12T09:31:02+00:00",
"created_at": "2026-11-12T09:31:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
Refund a payment
/api/v1/payments/{payment}/refundsRefunds a succeeded payment in full (no amount) or in part. Send an Idempotency-Key so a retry never refunds twice.
Body parameters
amountinteger- In minor units, up to what is left to refund. Default: all of it.
reasonstring- requested_by_customer, duplicate, fraudulent or other.
Request
curl -X POST https://cycle.am/api/v1/payments/pay_b53be1/refunds \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"amount":200000}'Response
Example response
201{
"data": {
"id": "re_1f8c22",
"object": "refund",
"payment": "pay_b53be1",
"amount": 200000,
"currency": "AMD",
"reason": "requested_by_customer",
"status": "succeeded",
"failure_message": null,
"livemode": false,
"created_at": "2026-11-13T10:02:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
List invoices
/api/v1/invoicesInvoices, newest first. Filter with ?customer=, ?subscription= and ?status= (draft, open, paid, void, uncollectible).
Query parameters
limitinteger- Objects per page, 1 to 100. Default 20.
pageinteger- The page to return, from 1.
Request
curl -X GET https://cycle.am/api/v1/invoices \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "in_9a7f3c",
"object": "invoice",
"number": "TEST-2026-0001",
"status": "paid",
"collection_method": "charge_automatically",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"currency": "AMD",
"subtotal": 1200000,
"discount": 0,
"credit_applied": 0,
"total": 1200000,
"amount_paid": 1200000,
"amount_due": 0,
"period_start": "2026-11-12T09:31:00+00:00",
"period_end": "2026-12-12T09:31:00+00:00",
"due_at": null,
"paid_at": "2026-11-12T09:31:02+00:00",
"hosted_invoice_url": "…/hy/i/Xk3f…",
"lines": [
{
"description": "Yoga membership",
"quantity": 1,
"unit_amount": 1200000,
"amount": 1200000
}
],
"livemode": false,
"created_at": "2026-11-12T09:31:00+00:00"
}
],
"links": {
"first": "…?page=1",
"last": "…?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Retrieve an invoice
/api/v1/invoices/{invoice}Returns one invoice with its lines and the page the customer pays it on.
Request
curl -X GET https://cycle.am/api/v1/invoices/in_9a7f3c \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "in_9a7f3c",
"object": "invoice",
"number": "TEST-2026-0001",
"status": "paid",
"collection_method": "charge_automatically",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"currency": "AMD",
"subtotal": 1200000,
"discount": 0,
"credit_applied": 0,
"total": 1200000,
"amount_paid": 1200000,
"amount_due": 0,
"period_start": "2026-11-12T09:31:00+00:00",
"period_end": "2026-12-12T09:31:00+00:00",
"due_at": null,
"paid_at": "2026-11-12T09:31:02+00:00",
"hosted_invoice_url": "…/hy/i/Xk3f…",
"lines": [
{
"description": "Yoga membership",
"quantity": 1,
"unit_amount": 1200000,
"amount": 1200000
}
],
"livemode": false,
"created_at": "2026-11-12T09:31:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
List events
/api/v1/eventsEvents, newest first: the same objects webhooks receive. Filter with ?type=. Use it to catch up on anything your endpoint missed.
Query parameters
limitinteger- Objects per page, 1 to 100. Default 20.
pageinteger- The page to return, from 1.
Request
curl -X GET https://cycle.am/api/v1/events \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "evt_2d61f0",
"object": "event",
"type": "payment.succeeded",
"livemode": false,
"created_at": "2026-11-12T09:31:02+00:00",
"data": {
"object": {
"id": "pay_b53be1",
"object": "payment",
"amount": 1200000,
"amount_refunded": 0,
"currency": "AMD",
"status": "succeeded",
"type": "subscription",
"description": "Yoga membership",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"invoice": "in_9a7f3c",
"card": {
"brand": "visa",
"last4": "4242"
},
"failure_code": null,
"failure_message": null,
"livemode": false,
"succeeded_at": "2026-11-12T09:31:02+00:00",
"created_at": "2026-11-12T09:31:00+00:00"
}
}
}
],
"links": {
"first": "…?page=1",
"last": "…?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Retrieve an event
/api/v1/events/{event}Returns one event.
Request
curl -X GET https://cycle.am/api/v1/events/evt_2d61f0 \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "evt_2d61f0",
"object": "event",
"type": "payment.succeeded",
"livemode": false,
"created_at": "2026-11-12T09:31:02+00:00",
"data": {
"object": {
"id": "pay_b53be1",
"object": "payment",
"amount": 1200000,
"amount_refunded": 0,
"currency": "AMD",
"status": "succeeded",
"type": "subscription",
"description": "Yoga membership",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"invoice": "in_9a7f3c",
"card": {
"brand": "visa",
"last4": "4242"
},
"failure_code": null,
"failure_message": null,
"livemode": false,
"succeeded_at": "2026-11-12T09:31:02+00:00",
"created_at": "2026-11-12T09:31:00+00:00"
}
}
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
Create a product
/api/v1/productsCreates a product. Send the price fields of Create a price too (without product) to add its first price in the same call.
Body parameters
namestringrequired- What customers see on checkout, receipts and invoices.
descriptionstring- Up to 2000 characters.
amountinteger- Optional first price, in minor units; then also
currencyand, for a recurring price,interval.
Request
curl -X POST https://cycle.am/api/v1/products \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Yoga membership","amount":1200000,"currency":"AMD","interval":"month"}'Response
Example response
201{
"data": {
"id": "prod_3b9d0e",
"object": "product",
"name": "Yoga membership",
"description": null,
"active": true,
"prices": [
{
"id": "price_7c41aa",
"object": "price",
"product": "prod_3b9d0e",
"nickname": "Monthly",
"amount": 1200000,
"currency": "AMD",
"type": "recurring",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"active": true,
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
],
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
Create a price
/api/v1/pricesAdds a price to a product. Prices can't be changed later; add a new one and archive the old one in the dashboard.
Body parameters
productstringrequired- The product's ID.
amountintegerrequired- In minor units. AMD prices are whole dram (multiples of 100).
currencystringrequiredAMD,USDorEUR.typestringrecurring(default) orone_time.intervalstring- For recurring prices:
day,week,monthoryear. interval_countinteger- Bill every this many intervals. Default 1.
trial_daysinteger- Free days before the first charge (0 to 365). Default 0.
nicknamestring- Your own name for the price, like "Monthly".
Request
curl -X POST https://cycle.am/api/v1/prices \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"product":"prod_3b9d0e","amount":12000000,"currency":"AMD","interval":"year"}'Response
Example response
201{
"data": {
"id": "price_7c41aa",
"object": "price",
"product": "prod_3b9d0e",
"nickname": "Monthly",
"amount": 1200000,
"currency": "AMD",
"type": "recurring",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"active": true,
"livemode": false,
"created_at": "2026-11-10T08:00:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
Create a checkout session
/api/v1/checkout/sessionsOpens a checkout for a price: redirect your customer to url, the bank's page, where they type their card. A recurring price starts a subscription (with a trial, the card is saved and nothing is charged yet); a one-time price is one payment. When it completes you get the checkout.session.completed event with your client_reference_id.
Body parameters
pricestringrequired- An active price's ID.
customer_emailstringrequired- Your customer's email. An existing customer with this email is reused.
success_urlstringrequired- Where the customer lands after paying.
{CHECKOUT_SESSION_ID}in it is replaced with the session's ID. Must be https in live mode. client_reference_idstring- Your own ID for the customer, usually your user's ID. Up to 255 characters.
localestringhyoren. Defaults to the business's customer language.
Request
curl -X POST https://cycle.am/api/v1/checkout/sessions \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"price":"price_7c41aa","customer_email":"ani@example.com","client_reference_id":"user_42","success_url":"https://example.com/billing/success?session={CHECKOUT_SESSION_ID}"}'Response
Example response
201{
"data": {
"id": "cs_4f81c2",
"object": "checkout_session",
"status": "open",
"type": "subscription",
"url": "https://cycle.am/bank/pay/…",
"price": "price_7c41aa",
"amount": 1200000,
"currency": "AMD",
"customer_email": "ani@example.com",
"client_reference_id": "user_42",
"customer": null,
"subscription": null,
"payment": null,
"success_url": "https://example.com/billing/success?session=cs_4f81c2",
"livemode": false,
"expires_at": "2026-11-12T10:00:00+00:00",
"completed_at": null,
"created_at": "2026-11-12T09:30:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
Retrieve a checkout session
/api/v1/checkout/sessions/{checkoutSession}Returns one session. An open session is first checked with the bank, so a success page can rely on status: completed, failed, expired or still open.
Request
curl -X GET https://cycle.am/api/v1/checkout/sessions/cs_4f81c2 \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": {
"id": "cs_4f81c2",
"object": "checkout_session",
"status": "completed",
"type": "subscription",
"url": null,
"price": "price_7c41aa",
"amount": 1200000,
"currency": "AMD",
"customer_email": "ani@example.com",
"client_reference_id": "user_42",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"payment": "pay_b53be1",
"success_url": "https://example.com/billing/success?session=cs_4f81c2",
"livemode": false,
"expires_at": "2026-11-12T10:00:00+00:00",
"completed_at": "2026-11-12T09:31:02+00:00",
"created_at": "2026-11-12T09:30:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
Create a customer portal link
/api/v1/customers/{customer}/portal-linksA sign-in link to the customer portal, valid for an hour, where the customer changes their card, switches plan or cancels (as your portal settings allow). Make a new one each time the customer clicks; don't email or store it.
Body parameters
localestringhyoren. Defaults to the customer's language.
Request
curl -X POST https://cycle.am/api/v1/customers/cus_8f2a1c/portal-links \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)"Response
Example response
201{
"data": {
"object": "portal_link",
"customer": "cus_8f2a1c",
"url": "https://cycle.am/hy/portal/your-business/enter/cus_8f2a1c?expires=1794831656&signature=…",
"expires_at": "2026-11-12T10:31:00+00:00"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
List webhook endpoints
/api/v1/webhook-endpointsThe webhook endpoints of the key's mode.
Request
curl -X GET https://cycle.am/api/v1/webhook-endpoints \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json"Response
Example response
200{
"data": [
{
"id": "we_2a7d90",
"object": "webhook_endpoint",
"url": "https://example.com/webhooks/cycle",
"description": null,
"enabled_events": [
"checkout.session.completed",
"subscription.past_due",
"subscription.canceled"
],
"enabled": true,
"created_at": "2026-11-12T09:30:00+00:00"
}
]
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key isn't allowed from this IP address, or it is a publishable key.
- 429More than 100 requests in a minute with this key.
Create a webhook endpoint
/api/v1/webhook-endpointsRegisters a URL to receive events (see Events & webhooks). The response has the signing secret, shown only now.
Body parameters
urlstringrequired- A public
https://URL. eventsarrayrequired- Event types to send, or
["*"]for all. descriptionstring- Your own note.
Request
curl -X POST https://cycle.am/api/v1/webhook-endpoints \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"url":"https://example.com/webhooks/cycle","events":["checkout.session.completed","subscription.past_due","subscription.canceled"]}'Response
Example response
201{
"data": {
"id": "we_2a7d90",
"object": "webhook_endpoint",
"url": "https://example.com/webhooks/cycle",
"description": null,
"enabled_events": [
"checkout.session.completed",
"subscription.past_due",
"subscription.canceled"
],
"enabled": true,
"created_at": "2026-11-12T09:30:00+00:00",
"secret": "whsec_…"
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
Delete a webhook endpoint
/api/v1/webhook-endpoints/{webhookEndpoint}Deletes an endpoint; nothing more is sent to it. Answers 204 with no body.
Request
curl -X DELETE https://cycle.am/api/v1/webhook-endpoints/we_2a7d90 \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)"Response
Example response
204[]Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.
Renew a subscription now (test mode)
/api/v1/test/subscriptions/{subscription}/renewTest keys only (403 with a live key). Runs the subscription's next renewal now, exactly as it would run on the day: a trial ends, an active period renews, a past-due subscription gets its next retry. The outcome follows the saved test card, so you can prove every case without waiting.
Request
curl -X POST https://cycle.am/api/v1/test/subscriptions/sub_51e0d2/renew \
-H "Authorization: Bearer $CYCLE_SECRET_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)"Response
Example response
200{
"data": {
"subscription": {
"id": "sub_51e0d2",
"object": "subscription",
"customer": "cus_8f2a1c",
"price": "price_7c41aa",
"pending_price": null,
"status": "active",
"quantity": 1,
"currency": "AMD",
"collection_method": "charge_automatically",
"days_until_due": null,
"description": null,
"current_period_start": "2026-11-12T09:31:00+00:00",
"current_period_end": "2026-12-12T09:31:00+00:00",
"trial_end": null,
"next_charge_at": "2026-12-12T09:31:00+00:00",
"next_charge_amount": 1200000,
"cancel_at_period_end": false,
"canceled_at": null,
"cancel_reason": null,
"pause": null,
"billing_cycles": null,
"periods_paid": 1,
"discount": null,
"livemode": false,
"created_at": "2026-11-12T09:31:00+00:00"
},
"payment": {
"id": "pay_b53be1",
"object": "payment",
"amount": 1200000,
"amount_refunded": 0,
"currency": "AMD",
"status": "succeeded",
"type": "subscription",
"description": "Yoga membership",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"invoice": "in_9a7f3c",
"card": {
"brand": "visa",
"last4": "4242"
},
"failure_code": null,
"failure_message": null,
"livemode": false,
"succeeded_at": "2026-11-12T09:31:02+00:00",
"created_at": "2026-11-12T09:31:00+00:00"
}
}
}Errors
- 401The key is missing, invalid, revoked or expired.
- 403The key doesn't have the
writescope. - 422A field is invalid, or the change isn't allowed (the message says why).
- 429More than 100 requests in a minute with this key.
- 404No object with this ID in the key's business and mode.