Subscriptions
A subscription combines a Token Management Service (TMS) customer token with a plan, plus a start date, name, and optional description. Subscriptions can be updated, activated, suspended, or canceled.
Subscription Elements
- Subscription code: optional. See Assigning a subscription code.
- Subscription name: required. A descriptive name for the subscription.
- Start date: required. Must be in UTC format:
YYYY-MM-DDThh:mm:ssZ. For subscriptions created on the start date, the time value must be the current time and day in the merchant's time zone. - TMS customer token (
paymentInformation.customer.id): required. Identifies the customer's stored payment credentials. - Plan: required. Either a standard plan (referenced by plan ID) or a one-time plan (embedded in the subscription).
- Merchant reference number (
clientReferenceInformation.code): optional.
Prerequisites
Before creating a subscription, you must create a customer token. For more information about creating a customer token, see the Token Management Service Developer Guide.
When creating a subscription, these values from the TMS response map to fields in the subscription request:
Field mapping from TMS response to subscription request
| Payments API Response Field | Recurring Billing Create Subscription Request Field | Required Value Information |
|---|---|---|
tokenInformation.customer.id | paymentInformation.customer.id | Customer token ID. |
processorInformation.networkTransactionId | subscriptionInformation.originalTransactionId | Network token for the transaction initializing the subscription. For EFTPOS cards, a network token is not generated — provide the transaction request ID or use 0. |
orderInformation.amountDetails.authorizedAmount | subscriptionInformation.originalTransactionAuthorizedAmount | Authorized amount for the transaction initializing the subscription. Required only for Diners or Discover cards. |
Subscription ID
When a subscription is created, the system assigns a unique subscription ID. This ID is used in subsequent requests to retrieve, amend, cancel, reactivate, or suspend the subscription.
The interval between subscription payments cannot exceed 12 months.
Assigning a Subscription Code
When you create a subscription, you can choose to supply a subscription code that relates to your business and is used for reference. This code can be numeric or alphanumeric with dash (-) and dot (.) characters, and up to 10 characters long.
If no subscription code is assigned, the system automatically assigns a system-generated value.
Subscription Statuses
| Status | Description |
|---|---|
| Pending | The first payment is scheduled, or the subscription is in transition to another state. |
| Active | The subscription is currently in use. It is set with a payment instrument, and a payment is scheduled at a pre-determined frequency that you agreed upon with your customer. |
| Delinquent | When a scheduled recurring payment fails, the account is placed in a Delinquent status while the system retries the payment a number of times. If the retries all fail, the account is placed into a Suspended status. |
| Suspended | The automated retry logic failed to obtain successful payment, or the subscription was explicitly suspended. A suspended subscription can be resumed for the next billing cycle: a different payment method can be collected from the customer and the subscription reactivated, or the subscription can be canceled and a new subscription created for the customer. |
| Cancelled | You have explicitly cancelled the subscription, and it cannot be reactivated. You might cancel an active or pending subscription when you and the customer agree to end the subscription. You might choose to cancel a delinquent subscription rather than wait for the automatic retry logic to proceed. You might cancel a suspended subscription if the customer does not have an acceptable alternate payment method. Important: You cannot cancel a subscription within 10 minutes before or after a payment begins processing. |
| Completed | All scheduled payments were made. This is the state of a subscription that ends with all scheduled payments successfully completed. This state applies to subscriptions set up with a scheduled end date. Important: You cannot reactivate a completed subscription. |
Zero-Amount Authorization
When a subscription is created before the start date, a zero-amount authorization is automatically performed to validate the payment instrument:
- Address Verification Service (AVS)
- Card verification number (CVN)
- Expiration date
When a subscription is created on the start date, no zero-amount authorization is performed — the first payment is processed immediately.
Plan Overrides
When assigning or amending a subscription with a standard plan, you can override specific plan details for the individual subscription. Plan overrides apply only to the individual subscription and do not amend the standard plan details used for other subscriptions.
Subscription Management
For API operations to manage subscriptions, see Manage Subscriptions.
Thanks for your feedback!
Last published: September 29, 2026