On This Page
You can create a subscription with either a standard plan, with plan overrides, or with a fully-customized one-time plan specifically for an individual subscription.
When you create a subscription before the subscription start date, account verification (zero amount authorization) is performed to ensure that the card details stored are still valid before creating a subscription.
When you create a subscription on the subscription start date, account verification is not performed, as the first recurring payment will be taken immediately.
When a subscription is created, an ID is assigned to the subscription, and the subscription ID is used for these services:
IMPORTANT
A subscription's plan duration (billing cycles) cannot exceed 12 months.
Assigning a Subscription Code
When you create a subscription, you can supply a subscription code that relates to your business and is used for reference to the subscription. This code can be numeric or alphanumeric with dash (-) and dot (.) characters, and up to 10 characters long.
If you do not supply a subscription code, the recurring billing system automatically assigns a code.
Plan Overrides
When assigning a plan to a subscription or amending a subscription, you can amend standard plan details at an individual subscription level. For examples, an amendment to billing amount, plan duration (billing cycles) amendment, or removal of setup.
IMPORTANT
Plan overrides are only applicable to the individual subscription and will not amend the standard plan details used for other subscriptions. To amend plan details, see Amend a Plan.

Required Fields for Creating a Subscription

A request for creating a subscription requires these fields:
subscriptionInformation.planId
If using a standard plan.
subscriptionInformation.name
subscriptionInformation.startDate
paymentInformation.customer.id

Optional Fields for Creating a Subscription

These fields are optional for creating a subscription:
clientReferenceInformation.code
clientReferenceInformation.partner.developerId
clientReferenceInformation.partner.solutionId
clientReferenceInformation.transactionId
orderInformation.amountDetails.billingAmount
orderInformation.amountDetails.currency
orderInformation.amountDetails.setupFee
planInformation.billingPeriod.billingCycles
Required for a plan with a defined plan period.
planInformation.billingPeriod.length
planInformation.billingPeriod.unit
planInformation.description
planInformation.name
planInformation.status
subscriptionInformation.code

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

Examples for Creating a Subscription

Request to Create a Subscription with a Pre-Existing Plan
{
    "subscriptionInformation": {
        "planId":"1619214515",
        "name": "Daily Gym Subscription",
        "startDate": "2021-04-25"
    },
    "paymentInformation": {
        "customer": {
            "id": "C09F227C54F94951E0533F36CF0A3D91"
        }
    }
}
Response from a Request to Create a Subscription with a Pre-Existing Plan
{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619214690",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619214690",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619214690/cancel",
            "method": "POST"
        }
    },
    "id": "1619214690",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "AWC-47",
        "status": "PENDING"
    }
}
Error Response to a Request to Create a Subscription with a Pre-Existing Plan
{
    "status": "INVALID_REQUEST",
    "reason": "INVALID_DATA",
    "message": "One or more fields in the request contains invalid data.",
    "details": [
        {
            "field": "subscriptionInformation.startDate",
            "reason": "INVALID_DATA"
        }
    ]
}
Request to Create a Subscription With Subscription Overrides
{
    "subscriptionInformation": {
        "planId": "1619214515",
        "name": "SubName With Overrides",
        "startDate": "2021-04-26"
    },
    "planInformation": {
        "billingCycles": {
            "total": "3"
        }
    },
    "orderInformation": {
        "amountDetails": {
            "billingAmount": "13.14",
            "setupFee": "1.27"
        }
    },
    "paymentInformation": {
        "customer": {
            "id": "C09F227C54F94951E0533F36CF0A3D91"
        }
    }
}
Successful Response to a Request to Create a Subscription with Subscription Overrides 
{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619214795",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619214795",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619214795/cancel",
            "method": "POST"
        }
    },
    "id": "1619214795",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "AWC-48",
        "status": "PENDING"
    }
}
Error Response to a Request to Create a Subscription with Subscription Overrides 
{
    "status": "INVALID_REQUEST",
    "reason": "DUPLICATE_REQUEST",
    "message": "Duplicate requests are not supported within 15 minutes.",
    "details": [
        {
            "field": "subscriptionInformation.planId or paymentInformation.customer.id or subscriptionInformation.startDate or subscriptionInformation.name",
            "subscriptionId": "1619214795",
            "reason": "INVALID_DATA"
        }
    ]
}
Request to Create a Fully Customized Subscription with a One-Time Payment
{
    "subscriptionInformation": {
        "name": "SubName Testing",
        "startDate": "2021-04-28"
    },
    "planInformation": {
        "billingCycles": {
            "total":"5"
        },
         "billingPeriod": {
            "length": "3",
            "unit":"D"
        }
    },
    "orderInformation": {
        "amountDetails": {
            "billingAmount": "1.21",
            "setupFee": "1.44",
            "currency":"USD"
        }
    },
    "paymentInformation": {
        "customer": {
            "id": "C09F227C54F94951E0533F36CF0A3D91"
        }
    }
}
Successful Response to a Request to Create a Fully Customized Subscription with a One-Time Payment
{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619214861",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619214861",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619214861/cancel",
            "method": "POST"
        }
    },
    "id": "1619214861",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "AWC-49",
        "status": "PENDING"
    }
}
Error Response to a Request to Create a Fully Customized Subscription with a One-Time Payment
{
    "status": "INVALID_REQUEST",
    "reason": "INVALID_DATA",
    "message": "One or more fields in the request contains invalid data.",
    "details": [
        {
            "field": "planInformation.billingPeriod.length",
            "reason": "MAX_LENGTH"
        }
    ]
}