Subscriptions

Subscriptions store customer details using a Token Management Service (TMS) token and have an assigned payment plan. Subscriptions consist of this information:
  • Subscription code
  • Subscription name
  • Start date
  • Token Management Service (TMS) token
  • Plan: standard or one-time
Subscriptions can be updated, activated, suspended, or cancelled.

Subscription Prerequisites

Before creating a subscription, you must create a customer token.

Subscription Statuses

This diagram illustrates the statuses of a subscription from creation to completion.

Figure:

Subscription Flow
Diagram of the statuses of a subscription.
A subscription has one of these statuses:
Created
The subscription has been created but the first payment has not been processed.
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 agreed upon with your customer.
Delinquent
A scheduled payment was declined.
The system automatically retries the payment for a number of times. If the payment succeeds, the system automatically moves the subscription back to
active
 state. Otherwise, if the automated retry logic fails to obtain a successful payment, the system automatically moves the subscription to the
suspended
 state.
Suspended
The automated retry logic failed to obtain successful payment, or you have explicitly suspended the subscription. In order to resume a suspended subscription for the next billing cycle, choose one of these options:
  • Collect a different payment method from your customer and then reactivate the subscription
  • Cancel the subscription and create a new subscription for your 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 Authorizations

When you create a subscription before the subscription start date,
Cybersource
 verifies the account with a zero amount authorization to ensure that the stored card details are valid.
When you create a subscription on the subscription start date,
Cybersource
 does not perform a zero amount authorization because the first recurring payment is processed immediately.

Assigning a Subscription Code

When you create a subscription, you can supply a subscription code that relates to your business and that is used for reference to the subscription. This code can be numeric or alphanumeric with dash (-) and dot (.) characters and can be up to 10 characters long.
If you do not supply a subscription code, the recurring billing system automatically assigns a code.

Subscription ID

When you create a subscription, the system assigns an ID to the subscription that you can use for these actions:
  • Retrieving a subscription
  • Amending a subscription
  • Canceling a subscription
  • Re-activating a subscription
  • Suspending a subscription
IMPORTANT
A subscription's plan duration (number of billing cycles) cannot exceed 12 months. The interval between subscription payments cannot exceed 12 months.

Overriding a Plan

When assigning a plan to a subscription or amending a subscription, you can amend standard plan details for individual subscriptions. For example, such changes might include an amendment to the billing amount, plan duration (billing cycles) amendment, or removal of the set-up fee.
IMPORTANT
Plan overrides apply only to the individual subscription and do not amend the standard plan details used for other subscriptions.

Creating a Subscription

You can create a subscription with a standard plan, with plan overrides, or with a fully customized, one-time plan.
The start date must be in coordinated universal time (UTC) in this format: YYYY-MM-DDThh:mm:ssZ. The T separates the date and the time. The Z indicates UTC. For example,
2023-08-11T22:47:57Z
 indicates August 11, 2023, at 22:47:57 (10:47:57PM). For subscriptions with a future start date, the payment processing time defaults to start at 2:00a.m. in your time zone. For subscriptions created on the start date, set the time to the current time and day in your time zone.
Follow these steps to create a subscription:
  1. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    POST https://<
    url_prefix
    >/rbs/v1/subscriptions

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  2. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.

Retrieving a List of Subscriptions

You can retrieve a list of subscriptions with these details for each subscription:
  • Subscription ID
  • Subscription code
  • Subscription status
  • Subscription name
  • Customer ID
  • Plan ID
  • Plan code
  • Plan name
  • Plan description
  • Plan status
  • Billing period unit
  • Billing period length
  • Billing cycles total
  • Billing cycles current
  • Currency
  • Billing amount
  • Set-up fee
Use the subscription ID to retrieve, amend, activate, suspend, or cancel an individual subscription.
Follow these steps to retrieve a list of subscriptions:
  1. Filter the list of subscriptions by these query string parameters:

    ADDITIONAL INFORMATION

    • filters
      : Use Lucene query syntax. Only keyword-matching and
      AND
       are supported. Example:
      status:"ACTIVE" AND code:"01" AND id:"21345"
    • offset
      : Page offset number.
    • limit
      : Number of items to be returned. Default is
      20
       and maximum is
      100
      .
  2. Format the endpoint as follows:

    ADDITIONAL INFORMATION

    GET https://
    <url_prefix>
    /rbs/v1/subscriptions

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  3. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.

Retrieving a Subscription

You can retrieve the details of a specific subscription. The subscription details returned in the response include:
  • Subscription ID
  • Subscription code
  • Subscription status
  • Subscription name
  • Customer ID
  • Plan ID
  • Plan code
  • Plan name
  • Plan description
  • Plan status
  • Billing period unit
  • Billing period length
  • Billing cycles total
  • Billing cycles current
  • Currency
  • Billing amount
  • Set-up fee
Follow these steps to retrieve a subscription:
  1. In the endpoint path, include the subscription ID that you received from your list of subscriptions.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    GET https://<
    url_prefix
    >/rbs/v1/subscriptions{id}

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  3. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.

Retrieving the Next Subscription Code

When you specify your subscription code, you can request the next consecutive alphabetical or numeric subscription code based on the last subscription code you specified. For example, if the last subscription code that you specified was
24B
, the system returns the code
24C
.
Follow these steps to retrieve the next subscription code:
  1. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    GET https://<
    url_prefix
    >/rbs/v1/subscriptions/code

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  2. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.

Amending a Subscription

Subscriptions store customer details using a Token Management Service (TMS) token and have an assigned payment plan. Subscriptions consist of this information:
  • Subscription code
  • Subscription name
  • Start date
  • Token Management Service (TMS) token
  • Plan: standard or one-time
IMPORTANT
The subscription information that you can amend depends on the status of the subscription. Note the limitations described in in the paragraphs that follow.
For a
pending
 subscription, you cannot change this information:
  • Customer ID
  • Currency
  • Billing period unit and length
For an
active
 subscription, you cannot change this information:
  • Customer ID
  • Currency
  • Start date (Payment processing time starts at 2:00a.m. in your time zone.)
  • Billing period unit and length
  • Set-up fee
For a
delinquent
,
suspended
,
cancelled
, or
completed
 subscription, you can update only the subscription name and code.
IMPORTANT
When you change the plan ID assigned to a subscription, the first payment is processed immediately. If proration is required after the change, it must be managed outside of the recurring billing service.
Follow these steps to amend a subscription:
  1. Include any optional amendable fields in the request.
  2. In the endpoint path, include the subscription ID that you received when you retrieved a list of subscriptions.
  3. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    PATCH https://<
    url_prefix
    >/rbs/v1/subscriptions/{id}

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  4. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.

Re-activating a Suspended Subscription

You can reactivate a suspended subscription for the next billing cycle. The payment processing time starts at 2:00a.m. in your time zone.
You cannot reactivate a cancelled or completed subscription.
Follow these steps to re-activate a subscription:
  1. In the endpoint path, include the subscription ID that you received when you retrieved a list of subscriptions.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    POST https://<url_prefix>/rbs/v1/subscriptions{id}/activate

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  3. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.

Suspending a Subscription

You can suspend a pending, active, or delinquent subscription. Subscriptions cannot be suspended 10 minutes before or after a payment begins processing.
Follow these steps to suspend a subscription:
  1. In the endpoint path, include the subscription ID that you received when you retrieved a list of subscriptions.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    POST https://<url_prefix>/rbs/v1/subscriptions/{id}/suspend

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  3. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.

Cancelling a Subscription

You can cancel a pending, active, suspended, or delinquent subscription. Subscriptions cannot be canceled within 10 minutes before or after a payment begins processing.
Follow these steps to cancel a subscription:
  1. In the endpoint path, include the subscription ID that you received when you retrieved a list of subscriptions.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    POST https://<
    url_prefix
    >/rbs/v1/subscriptions/{id}/cancel

    ADDITIONAL INFORMATION

    Use one of these URL prefixes:
    • Test:
      apitest.cybersource.com
    • Production:
      api.cybersource.com
    • Production in India:
      api.in.cybersource.com
  3. Check the response message to make sure that the request was successful. A 200-level HTTP response code indicates success.
    For information about response codes, see Transaction Response Codes.