---
updatedAt: 2026-06-30T09:53:03.000Z
agentTools:
projectIndex: https://readme.centrobill.com/llms.txt
---
# Subscriptions
A subscription is a recurring billing agreement created when a customer completes an initial payment against a SKU that includes a recurring price schedule.
Subscriptions can be managed by Centrobill or by the merchant
**Managed by Centrobill**
Centrobill automatically processes future rebills according to the schedule configured in the SKU, so no manual subsequent charge requests are required. See [Failed rebills, grace period, and retry logic](https://readme.centrobill.com/docs/subscriptions#failed-rebills-grace-period-and-retry-logic) for details.
**Managed by the merchant**
You can handle rebilling entirely on your side. When a customer completes their first payment, Centrobill returns a `paymentAccountId`(an encrypted identifier for the card the customer used) in the IPN callback and in the [Feed API](https://readme.centrobill.com/reference/getpayments). Store it in your system and use it to initiate future charges manually by sending a `POST /payment` using the `paymentAccountId` on whatever schedule you define.
***
## How subscriptions are created
Subscriptions are created automatically when a payment request includes a SKU with a recurring price entry. See [Create billing structures for an SKU object](https://readme.centrobill.com/docs/create-different-skus) for details and examples.
Once the initial payment succeeds, a subscription `id` is created. The subscription `id` is returned as part of the subscription object in IPN/callback. Also described [here](https://readme.centrobill.com/docs/instant-payment-notification-ipn#subscription-object).
```json
{
"subscription": {
"id": "1234567",
"cycle": 0,
"status": "active",
"renewalDate": "2026-04-19 20:17:27",
"timezone": "+01:00",
"eventTime": "2026-03-20 20:17:30"
}
}
```
***
## Subscription object
All Subscription API responses return a subscription object with the following fields:
| Field | Type | Description |
| ------------- | -------------- | ----------------------------------------------------------------------------------------- |
| `id` | string | Unique subscription identifier |
| `status` | string | Current subscription status: `active` or `canceled` |
| `type` | string | Subscription type: `trial`, `free-trial`, or `regular` |
| `cycle` | number | Sequential count of recurring payments. `0` = initial payment; `n` = nth recurring charge |
| `skuName` | string | The SKU name associated with this subscription |
| `siteId` | string | The site ID the subscription is linked to |
| `renewalDate` | string | Expected date of the next renewal (`YYYY-MM-DD HH:MM:SS`) |
| `cancelDate` | string \| null | Scheduled cancellation date, if set. `null` if no cancellation is scheduled |
| `consumerId` | string | Centrobill gateway consumer ID |
***
## Subscription statuses
| Status | Meaning |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `active` | Subscription is active and will renew on `renewalDate` |
| `canceled` | Subscription has been cancelled. If `cancelDate` is in the future, the subscription remains active until that date |
***
## Subscription types
| Type | Meaning |
| ------------ | --------------------------------------------- |
| `trial` | The subscription is in a paid trial period |
| `free-trial` | The subscription is in a free trial period |
| `regular` | Standard recurring subscription with no trial |
***
## Subscription lifecycle
Initial payment has `cycle: 0`. First rebill has `cycle: 1` and so on. Use `subscription.id`Â with the Subscription API to manage the subscription lifecycle.
A subscription moves through the following stages:
1. **Created** — the initial payment succeeds and a subscription object is created with `status: active` and `cycle: 0`.
2. **Renewing** — Centrobill automatically charges the consumer on each `renewalDate`. Each successful renewal increments `cycle` by one.
3. **Cancelled** — cancellation is requested via the API. If `cancelDate` is set to a future date, the subscription remains `active` until then. If `cancelDate` is null or not passed, the subscription is cancelled immediately.
4. **Recovered** — a cancelled subscription can be reactivated via the API.
**Control the number of billing cycles at creation**
If you want to limit how many times a customer is billed from the start, rather than cancelling later, define this in the SKU price schedule using `sku.price.repeat`. See [Create billing structures for an SKU object](https://readme.centrobill.com/docs/create-different-skus) for details.
***
## Failed rebills, grace period, and retry logic
When a rebill attempt fails, Centrobill does not cancel the subscription silently. Instead, it enters a retry cycle and, if configured, a grace period during which the subscription remains accessible to the customer. The presence of a `subscription` object in the IPN payload is what distinguishes a rebill event (successful or failed) from a one-time payment charge.
Check the IPN for a failed rebill [here](https://readme.centrobill.com/docs/instant-payment-notification-ipn#failed-rebill-ipn).
### Subscription status during failed rebills
The subscription `status` field remains `active` throughout the retry cycle and grace period. There is no `past_due` or `grace_period` status value. To determine whether a subscription is in a failed rebill state, monitor IPN callbacks for charge events with `payment.status: fail` against a subscription ID.
### Retry logic
Centrobill automatically retries failed rebills. The retry schedule is either:
1. Centrobill applies built-in rules based on the subscription interval. For example, a monthly subscription receives up to 4 weekly retry attempts.
2. The retry frequency and number of attempts can be configured per merchant account. Retry logic can also be disabled entirely if you prefer to manage retries in your own system.
Contact your Account manager to review or adjust the retry configuration for your account.
## IPN callbacks for failed rebills
Centrobill sends an IPN callback for every charge attempt: successful or failed. The subscription IPN follows the general structure as described [here](https://readme.centrobill.com/docs/instant-payment-notification-ipn#ipn-structure). The IPN payload structure for a failed rebill is identical to a successful charge IPN, with `payment.status: fail` and a `payment.code` indicating the decline reason.
## Manage subscriptions
Once a subscription is created, you can retrieve its state, update the billing plan, change the payment method, cancel, or recover it using the Subscription API. See [Manage subscriptions](https://readme.centrobill.com/docs/manage-subscriptions) for a full list of operations and how-to guides.
***
## Error responses
All Subscription API endpoints return standard HTTP error codes:
| Code | Meaning |
| ----- | ---------------------------------------------------- |
| `400` | Bad Request — a required field is missing or invalid |
| `401` | Unauthorized — API key is missing or invalid |
| `403` | Forbidden — insufficient permissions |
| `404` | Not Found — the subscription ID does not exist |
| `500` | Internal Server Error |
See [Error handling](https://readme.centrobill.com/docs/error-handling) for retry guidance.