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:

Include any optional amendable fields in the request.

In the endpoint path, include the subscription ID that you received when you retrieved a list of subscriptions.

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

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.

REST Examples: Amending a Subscription

Request to Switch a Subscription to Different Plan

{
    "note": "Switch Plan Note",
    "reason": "Switch Plan Reason",
    "subscriptionInformation": {
        "name": "Update Sub Name - Switch Plan 6192115800926177701960",
        "code":"1619215852Code",
        "startDate":"2023-04-15T17:01:42Z"
    },
    "orderInformation": {
        "amountDetails": {
            "billingAmount": "13.23",
            "currency": "USD",
            "setupFee": "8.43"
        }
    },
    "reasonCode": "Switch Plan Reason Code"
}

Response to a Successful Request

{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619215852",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619215852",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619215852/cancel",
            "method": "POST"
        }
    },
    "id": "1619215852",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "1619215852Code",
        "status": "PENDING"
    }
}

Error Response

{
    "status": "INVALID_REQUEST",
    "reason": "INVALID_DATA",
    "message": "One or more fields in the request contains invalid data.",
    "details": [
        {
            "field": "subscriptionInformation.code",
            "reason": "DUPLICATE"
        }
    ]
}