Modify a Subscription (Update)

Update, amend, or modify a Subscription. See Subscription Scenarios in the Subscribe Product Description. 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 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 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) 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).
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) 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 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

Home

Guides

APIs

HTTP Request

Route (URL) Parameters

Query Parameters

Accepts

Returns

Example Request (multiple modifications)

​HTTP Request

​Route (URL) Parameters

​Query Parameters

​Accepts

​Returns

​Example Request (multiple modifications)

HTTP Request

Route (URL) Parameters

Query Parameters

Accepts

Returns

Example Request (multiple modifications)