Introducing the Subscription CRUD API

Version: 1.0.7

Calmony Pay v1.0.7 ships full lifecycle management for recurring subscriptions. You can now create, update, cancel, and list subscriptions directly through the API, with support for monthly and annual billing intervals.

Overview

Subscriptions in Calmony Pay tie a customer to a recurring charge at a fixed price and billing interval. Each subscription is linked to a saved payment method and automatically tracks the current billing period.

Field	Description
`id`	Unique subscription ID, prefixed `sub_`
`customerId`	The customer this subscription belongs to
`priceAmount`	Recurring charge amount in pence
`currency`	ISO 4217 currency code (e.g. `gbp`)
`interval`	`monthly` or `annual`
`defaultPaymentMethodId`	The saved payment method used to charge the customer
`currentPeriodStart`	Unix timestamp — start of the active billing period
`currentPeriodEnd`	Unix timestamp — end of the active billing period
`status`	`active`, `past_due`, `canceled`, or `unpaid`
`cancelAtPeriodEnd`	If `true`, the subscription cancels at `currentPeriodEnd` rather than immediately

Endpoints

Create a Subscription

POST /v1/subscriptions

Request body:

{
  "customerId": "cus_abc123",
  "priceAmount": 1999,
  "currency": "gbp",
  "interval": "monthly",
  "defaultPaymentMethodId": "pm_xyz789"
}

Response (201 Created):

{
  "id": "sub_01HXYZ",
  "customerId": "cus_abc123",
  "priceAmount": 1999,
  "currency": "gbp",
  "interval": "monthly",
  "defaultPaymentMethodId": "pm_xyz789",
  "currentPeriodStart": 1718000000,
  "currentPeriodEnd": 1720592000,
  "status": "active",
  "cancelAtPeriodEnd": false
}

Update a Subscription

PATCH /v1/subscriptions/:id

Update the priceAmount or schedule a cancellation at the end of the current period.

Request body (all fields optional):

{
  "priceAmount": 2499,
  "cancelAtPeriodEnd": true
}

Response: Returns the updated subscription object.

Cancel a Subscription

DELETE /v1/subscriptions/:id

Cancels the subscription immediately. The subscription status is set to canceled.

Response: Returns the canceled subscription object.

Tip: To cancel at the end of the billing period rather than immediately, use PATCH with cancelAtPeriodEnd: true instead.

List Subscriptions

GET /v1/subscriptions

Returns an array of all subscriptions.

Response (200 OK):

[
  {
    "id": "sub_01HXYZ",
    "customerId": "cus_abc123",
    "status": "active",
    ...
  }
]

Subscription Statuses

Status	Meaning
`active`	The subscription is in good standing and the last payment succeeded
`past_due`	The last payment attempt failed; the subscription is still active but requires attention
`unpaid`	Payment has failed and the subscription is no longer being charged
`canceled`	The subscription has been canceled and will not renew

Billing Intervals

monthly — The customer is charged once per calendar month.
annual — The customer is charged once per year.

currentPeriodStart and currentPeriodEnd are updated automatically at the start of each new billing cycle.

Notes

All amounts (priceAmount) are expressed in the smallest currency unit (pence for GBP).
defaultPaymentMethodId must reference a previously saved payment method attached to the customer.
Subscription IDs are always prefixed sub_ for easy identification in logs and webhooks.