> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modify a Subscription (Update)

Update, amend, or modify a Subscription. See [Subscription Scenarios in the Subscribe Product Description](https://docs.vindicia.com/bundle/Vindicia_Subscribe_Product_Description/page/topics/subscriptions.html). REST approaches for the following most common modifications are below (see “Accepts” section for this operation).

* Billing Plan Change
* Add or Remove a Subscription Item
* Replace an existing Subscription Item with a new one

## HTTP Request

`POST https://api.vindicia.com/subscriptions/:subscription`

## Route (URL) Parameters

| Parameter | Default | Description | Required |
| - | - | - | - |
| subscription | n/a | The **id** or the **vid** of the Subscription to modify | Yes |

## Query Parameters

| Parameter | Default | Description | Required |
| - | - | - | - |
| bill\_prorated\_period | false | Indicates whether to prorate for unused service portions. | No |
| effective\_date | today | Billing date at which changes take effect; `today` or `nextBill` | No |
| new\_billing\_date | none | Use this parameter to change the billing date and have Subscribe automatically prorate the charges thereby extending or shortening the billing cycle. **Note:** If you don't want to have proration while changing the billing date, use the [Change the Subscription Billing Day](Change_the_Subscriptions_billing_day) call instead. You can change the billing date to a later date (extend the billing cycle), or change the billing date to an earlier date (shorten the billing cycle) for monthly billing cycles only. **Important:** To change and prorate the billing date, you must also set`bill_prorated_period` query parameter to `true`, which allows Subscribe to calculate the prorated changes. - **Extend the billing cycle example**: A $30 monthly subscription bills on the 1st of the month. On February 20,*new\_billing\_date* is set to the 16th of March, effective immediately. Subscribe calculates a new charge for the period 3-1 through 3-15, for an immediate prorated charge of $15. Next regular monthly billing is performed on the 16th of March. - **Shorten the billing cycle example**: A $30 monthly subscription bills on the 1st of the month. On February 10,*new\_billing\_date* is set to the 16th of February, effective immediately. Subscribe calculates a refund for the period 2-16 through 2-28 and applies it against the initial charge of $30 billed on February 1st. Next regular monthly billing is performed on the 16th of February. **Note:** This parameter supports monthly billing cycles only. Other billing cycle frequencies such as weekly, quarterly, or yearly ar not supported. | No |
| dry\_run | false | Indicates whether to commit changes or return results without execution | No |

## Accepts

JSON - This request supports the same arguments as 'create’ (a full [Subscription](Subscriptions) object) excepting the behavior of the **id**. Providing an **id** or **vid** in the URL indicates to Subscribe that this is an update, not a create call. Therefore, **id** and **vid** cannot be updated. The following changes will modify the subscribed service:

* **Plan Change**: Providing a new Billing Plan will change the billing plan/schedule for the subscription as of the effective\_date.
* **Replacing an existing/active Item with a new Item**: Include a new Subscription Item populating the \`replaces\` attribute (in the [Subscription Item](Subscription_Item)) with the id of the existing item being replaced.
* **Add a new Item**: Include a new Subscription Item (leaving undefined the \`replaced\_by\` and \`replaces\` parameters in the [Subscription Item](Subscription_Item)).
* **Remove an existing Item**: Include a new but empty/undefined Subscription Item populating \*\*ONLY\*\* the \`replaces\` attribute with the id of the existing item being removed. All changes will take effect as of the effective\_date provided; Proration calculations, when required, will use the period between the last scheduled billing and the \`effective\_date\` (calculated to whole days).
* **Apply a Campaign Code to a Subscription Item**: Use the \`replaced\_by\` and \`replaces\` attributes (in the [Subscription Item](Subscription_Item)) to apply a Campaign Code to a Subscription Item by replacing the existing item with the same item and including the Campaign Code.

## Returns

JSON - A full [Subscription](Subscriptions) object representing the new version of the Subscription.

## Example Request (multiple modifications)

Billing Plan Change, Replace an Item, Remove an Item, add an Item

```

curl -X POST -u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d ' {
    "object": "Subscription",
    "id": "sub_2",
    "billing_plan": {
       "object": "BillingPlan",
       "id": "plan_2234"
    },
    "items": [
       {
          "object": "SubscriptionItem",
          "id": "sub_2.1a",
          "product": {
             "object": "Product",
             "id": "prod_2234"
          },
          "replaces": "sub_2.1"
       },
       {
          "object": "SubscriptionItem",
          "replaces": "sub_2.2"
       },
       {
          "object": "SubscriptionItem",
          "id": "sub_2.4",
          "product": {
             "object": "Product",
             "id": "prod_3234"
          }
       }
    ]
 }'"https://api.staging.us-west.vindicia.com/subscriptions/sub_2?effective_date=today&bill_prorated_period=true&dry_run=false"
```

**Parent topic:**[Subscriptions](../topics/Subscriptions)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.