Skip to content
On this page

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"
Secret keys, not personal tokens
Personal access tokens (the account API) don't work here, and secret keys don't work on the account API. Keep secret keys on your server only.

Authentication and scopes

Send the key as Authorization: Bearer sk_test_…. A key has scopes and can be limited to IP addresses:

ScopeAllows
readList and retrieve customers, products, subscriptions, payments, invoices and events.
writeCreate 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

MethodPathEndpoint
GET/api/v1/customersList customers
POST/api/v1/customersCreate a customer
GET/api/v1/customers/{customer}Retrieve a customer
PATCH/api/v1/customers/{customer}Update a customer
GET/api/v1/productsList products
GET/api/v1/products/{product}Retrieve a product
GET/api/v1/pricesList prices
GET/api/v1/prices/{price}Retrieve a price
GET/api/v1/subscriptionsList subscriptions
POST/api/v1/subscriptionsCreate a subscription
GET/api/v1/subscriptions/{subscription}Retrieve a subscription
POST/api/v1/subscriptions/{subscription}/cancelCancel a subscription
GET/api/v1/paymentsList payments
GET/api/v1/payments/{payment}Retrieve a payment
POST/api/v1/payments/{payment}/refundsRefund a payment
GET/api/v1/invoicesList invoices
GET/api/v1/invoices/{invoice}Retrieve an invoice
GET/api/v1/eventsList events
GET/api/v1/events/{event}Retrieve an event
POST/api/v1/productsCreate a product
POST/api/v1/pricesCreate a price
POST/api/v1/checkout/sessionsCreate a checkout session
GET/api/v1/checkout/sessions/{checkoutSession}Retrieve a checkout session
POST/api/v1/customers/{customer}/portal-linksCreate a customer portal link
GET/api/v1/webhook-endpointsList webhook endpoints
POST/api/v1/webhook-endpointsCreate a webhook endpoint
DELETE/api/v1/webhook-endpoints/{webhookEndpoint}Delete a webhook endpoint
POST/api/v1/test/subscriptions/{subscription}/renewRenew a subscription now (test mode)

List customers

GET/api/v1/customers
scope: read

Customers, 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

POST/api/v1/customers
scope: write

Creates 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: hy or en.
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 write scope.
  • 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

GET/api/v1/customers/{customer}
scope: read

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

PATCH/api/v1/customers/{customer}
scope: write

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 write scope.
  • 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

GET/api/v1/products
scope: read

Products 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

GET/api/v1/products/{product}
scope: read

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

GET/api/v1/prices
scope: read

Prices, 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

GET/api/v1/prices/{price}
scope: read

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

GET/api/v1/subscriptions
scope: read

Subscriptions, 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

POST/api/v1/subscriptions
scope: write

Starts 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_method is send_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_methodstring
charge_automatically (default) or send_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 write scope.
  • 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

GET/api/v1/subscriptions/{subscription}
scope: read

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

POST/api/v1/subscriptions/{subscription}/cancel
scope: write

Cancels at the end of the paid period (default) or now. A canceled subscription is never charged again.

Body parameters

at_period_endboolean
true (default) to end when the paid period ends, false to 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 write scope.
  • 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

GET/api/v1/payments
scope: read

Payments, 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

GET/api/v1/payments/{payment}
scope: read

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

POST/api/v1/payments/{payment}/refunds
scope: write

Refunds 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 write scope.
  • 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

GET/api/v1/invoices
scope: read

Invoices, 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

GET/api/v1/invoices/{invoice}
scope: read

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

GET/api/v1/events
scope: read

Events, 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

GET/api/v1/events/{event}
scope: read

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

POST/api/v1/products
scope: write

Creates 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 currency and, 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 write scope.
  • 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

POST/api/v1/prices
scope: write

Adds 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).
currencystringrequired
AMD, USD or EUR.
typestring
recurring (default) or one_time.
intervalstring
For recurring prices: day, week, month or year.
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 write scope.
  • 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

POST/api/v1/checkout/sessions
scope: write

Opens 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.
localestring
hy or en. 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 write scope.
  • 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

GET/api/v1/checkout/sessions/{checkoutSession}
scope: read

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.

List webhook endpoints

GET/api/v1/webhook-endpoints
scope: read

The 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

POST/api/v1/webhook-endpoints
scope: write

Registers 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 write scope.
  • 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

DELETE/api/v1/webhook-endpoints/{webhookEndpoint}
scope: write

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 write scope.
  • 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)

POST/api/v1/test/subscriptions/{subscription}/renew
scope: write

Test 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 write scope.
  • 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.