Plans

A plan defines the payment amount and billing schedule for recurring or subscription payments.
After you create a plan, you can assign it to multiple subscriptions and manage changes for multiple subscriptions.
IMPORTANT
Installment-based plans are currently not supported.
Recurring Billing supports two types of plans:
  • Standard plans
    : created and stored within the recurring billing service for re-use. You can assign these plans to multiple subscriptions.
  • One-time plans
    : created specifically for a single subscription and not stored for re-use nor assigned to other subscriptions.
Both plan types have two billing cycle options. Choose one of these billing cycles when defining the number of recurring payments to be made:
  • Bill indefinitely
  • Fixed number of payments

Bill Indefinitely

This option has a fixed payment amount and a payment schedule with no end date. This option comprises these elements:
  • Plan code
  • Plan name
  • Plan description (optional)
  • Billing frequency
  • Currency
  • Payment amount
  • Set-up fee (optional)
IMPORTANT
One-time plans do not include a plan code, plan name, or plan description.

Fixed Number of Payments

This option has a fixed payment amount, a payment schedule, and a fixed number of payments. This option comprises these elements:
  • Plan code
  • Plan name
  • Plan description (optional)
  • Billing frequency
  • Currency
  • Payment amount
  • Number of billing cycles
  • Set-up fee (optional)
IMPORTANT
One-time plans do not include a plan code, plan name, or plan description.

Plan Statuses

A plan has one of these statuses:

Figure:

Plan Status Flow
Diagram of the plan flow and possible plan statuses.
  • Draft
    : a draft plan cannot be assigned to new or existing subscriptions. Draft plans can be changed to active or deleted.
  • Active
    : an active plan can be used when creating a new subscription or assigned to an existing subscription. Active plans can be changed to inactive or deleted.
  • Inactive
    : subscriptions assigned to an inactive plan continue to be billed until the subscription is completed or cancelled. Inactive plans cannot be used to create new subscriptions and subscriptions are not allowed to switch to an inactive plan. Inactive plans can be changed to active.
  • Deleted
    : a deleted plan is removed from the system.
IMPORTANT
You cannot amend an inactive plan. To make changes, move the plan to active or draft status.
IMPORTANT
You can delete a standard plan that has a draft status or has an active or inactive status and has never been assigned to any subscriptions.

Assigning a Plan Code

When you create a standard plan, you can choose to supply a plan code that relates to your business and is used for reference to the plan. This code can be numeric or alphanumeric with dash (-) and dot (.) characters, and up to 10 characters long.
If no plan code is assigned, the system automatically assigns a system-generated value.

Creating a Plan

Create a plan to define the billing schedule, which includes the amount, frequency, and billing cycles for a subscription. A subscription's plan duration (number of billing cycles) cannot exceed 12 months. The interval between subscription payments cannot exceed 12 months.
IMPORTANT
If a subscription is to use a one-time plan instead of a standard plan, you create the one-time plan when you create the subscription. The plan details are embedded in the subscription request.
When you create a plan, the system assigns an ID to the plan. Use the plan ID to request these actions:
  • Creating a subscription
  • Retrieving a plan
  • Amending a plan
  • Activating a plan
  • Deactivating a plan
  • Deleting a plan
Follow these steps to create a plan:
  1. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

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

    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 Plans

A list of plans provides these details for each plan:
  • Plan ID
  • Plan code
  • Plan name
  • Description
  • Status
  • Billing period unit
  • Billing period length
  • Billing cycles total
  • Currency
  • Billing amount
  • Set-up fee
After you retrieve the list of plans, use the plan ID to retrieve, amend, activate, deactivate, or delete a subscription.
Follow these steps to retrieve a list of plans:
  1. Filter the list of plans by these query string parameters:

    ADDITIONAL INFORMATION

    • filters
      : Use Lucene query syntax. Only keyword-matching and
      AND
       are supported. Example:
      name:"Test plan" AND code:"009" AND status:"ACTIVE"
    • 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/plans

    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 Plan

You can retrieve the details of a specific plan using the plan ID. The plan details returned in the response include:
  • Plan ID
  • Plan code
  • Plan name
  • Description
  • Status
  • Billing period unit
  • Billing period length
  • Billing cycles total
  • Currency
  • Billing amount
  • Set-up fee
Follow these steps to retrieve a plan:
  1. In the endpoint path, include the plan ID that you received when you retrieved a list of plans.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    GET https://<
    url_prefix
    >/rbs/v1/plans/{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 a Plan Code

When you specify your own plan codes, you can request the next consecutive alphabetical or numeric plan code based on the last plan code that you specified. For example, if the last plan code that you specified was
Plan104
, the system returns the code
Plan105
.
Follow these steps to retrieve a plan code:
  1. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    GET https://<url_prefix>/rbs/v1/plans/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 Plan

Amend a plan by entering one of two values in the
processingInformation.subscriptionBillingOptions.applyTo
 field. Possible values:
  • ALL
    : change is applied to all subscriptions (existing and new).
  • NEW
     (default): change is applied to new subscriptions only.
You can also make changes to individual subscriptions. See Amending a Subscription.
For a
draft
 plan, you can amend all plan information.
For an
active
 plan, you can amend only the information in these fields:
  • planInformation.billingPeriod
  • planInformation.billingCycles
  • orderInformation.amountDetails.currency
IMPORTANT
You cannot amend an inactive plan. To make changes, move the plan to active or draft status.
Follow these steps to amend a plan:
  1. Include any optional fields.
  2. In the endpoint path, include the plan ID that you received when you retrieved a list of plans.
  3. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    PATCH https://<
    url_prefix
    >/rbs/v1/plans/{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.

Activating a Plan

You can activate a plan that has a draft or inactive status and that has never been assigned to any subscriptions.
Follow these steps to activate a plan:
  1. In the endpoint path, include the plan ID that you received when you retrieved a list of plans.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    POST https://<url_prefix>/rbs/v1/plans{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.

Deactivating a Plan

You can deactivate a specific plan that has an active status.
Follow these steps to deactivate a plan:
  1. In the endpoint path, include the plan ID that you received when you retrieved a list of plans.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    POST https://<url_prefix>/rbs/v1/plans{id}/deactivate

    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.

Deleting a Plan

You can delete a standard plan that has a draft status or has an active or inactive status and has never been assigned to any subscriptions.
Follow these steps to delete a plan:
  1. In the endpoint path, include the plan ID that you received when you retrieved a list of plans.
  2. Send the request to the recurring billing endpoint:

    ADDITIONAL INFORMATION

    DELETE https://<
    url_prefix
    >/rbs/v1/plans/{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.