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.

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 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. 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 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.

{
  "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:

Subscription statuses

Subscription types

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.

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.

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. 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 for a full list of operations and how-to guides.

Error responses

All Subscription API endpoints return standard HTTP error codes:

See Error handling for retry guidance.