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.

Required Fields for Creating a Subscription

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

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

REST Examples: Creating a Subscription

Request to Create a Subscription with a Pre-Existing Plan
{
    "subscriptionInformation": {
        "planId":"1619214515",
        "name": "Daily Gym Subscription",
        "startDate": "2023-04-15T17:01:42Z"
    },
    "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": "2023-04-16T17:01:42Z"
    },
    "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": "2023-04-18T17:01:42Z"
    },
    "planInformation": {
        "billingCycles": {
            "total":"5"
        },
         "billingPeriod": {
            "length": "3",
            "unit":"D"
        }
    },
    "orderInformation": {
        "amountDetails": {
            "billingAmount": "1.21",
            "setupFee": "1.44",
            "currency":"USD"
        }
    },
    "paymentInformation": {
        "customer": {
            "id": "C09F227C54F94951E0533F36CF0A3D91"
        }
    }
}
Response to a Successful 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"
        }
    ]
}