On This Page

{#jumplink-list}  
[Markdown](/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-dev/recur-bill-subscriptions/rb-amend-subs.md)  
Filter  
FILTER BY TAG

Amending a Subscription {#rb-amend-subs}
========================================

Subscriptions store customer details using a Token Management Service (TMS) token and have an assigned payment plan. Subscriptions consist of this information:

Subscription code
:
Use the subscriptionInformation.code REST API field to specify an amended value.

Subscription name
:
Use the subscriptionInformation.name REST API field to specify an amended value.

Start date
:
Use the subscriptionInformation.startDate REST API field to specify an amended value.

Token Management Service (TMS) token
:
You cannot change this information.

Plan: standard or one-time
:
A **standard plan** is created and stored within the recurring billing service for re-use. You can assign these plans to multiple subscriptions.
:
A **one-time plan** is created specifically for a single subscription, and you create the plan when you create the subscription. A one-time plan does not include a plan code, plan name, or plan description.

> 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.
> IMPORTANT
> When you change the plan ID ( subscriptionInformation.planId field) 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.

Basic Steps {#rb-amend-subs_section_ht1_mjt_fdc}
------------------------------------------------

Follow these steps to amend a subscription.

1. Create the request with the API fields that contain new values.

2. Send the request to one of these endpoints. In the endpoint path, replace the `{id}` portion of the URL with the subscription ID that you received when you retrieved a list of subscriptions:

   * **Production:** `PATCH https://api.cybersource.com/rbs/v1/subscriptions/{id}`
   * **Test:** `PATCH https://apitest.cybersource.test.com/rbs/v1/subscriptions/{id}`

3. Verify the response messages to make sure that the request was successful. A 200-level HTTP response code indicates success. See the [Transaction Response Codes](https://developer.cybersource.com/api/reference/response-codes.md "").

Amendable Fields {#rb-amend-subs-amend-fields}
==============================================

The status of the subscription determines which fields you can amend.

Subscriptions That Are Delinquent, Suspended, Canceled, or Completed
--------------------------------------------------------------------

For a subscription in one of these states, you can *modify only these fields:*

subscriptionInformation.code
:

subscriptionInformation.name
:

clientReferenceInformation.code
:
Merchant reference number.

Pending Subscriptions
---------------------

You *cannot modify* these fields when the subscription is in the **pending** state:

orderInformation.amountDetails.currency
:

paymentInformation.customer.id
:

planInformation.billingPeriod.length
:

planInformation.billingPeriod.unit
:

Active Subscriptions
--------------------

You *cannot modify* these fields when the subscription is in the **active** state:

orderInformation.amountDetails.currency
:

orderInformation.amountDetails.setupFee
:

paymentInformation.customer.id
:

planInformation.billingPeriod.length
:

planInformation.billingPeriod.unit
:

subscriptionInformation.startDate
:
Payment processing time starts at 2:00 a.m. in your time zone.

Related Information
-------------------

* [API field reference guide for the REST API](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md "")

REST Example: Switching a Subscription to a Different Plan {#rb-amend-subs-ex}
==============================================================================

Request

```
{
    "subscriptionInformation": {
        "planId": 7379850138646475304951,
        "name": "Update Sub Name - Switch Plan 6192115800926177701960",
        "code":"1619215852Code"
    },
    "orderInformation": {
        "amountDetails": {
            "billingAmount": "13.23"
        }
    }
}
```

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 to a Failed Request

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

RELATED TO THIS PAGE