Skip to main content
Vindicia Knowledge Center

Modify a subscription (Update)

Modify a subscription (Update)

Update, amend, or modify a Subscription. See Vindicia Knowledgebase regarding various modify scenarios and additional approaches. REST approaches for the 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

Modification can include: * Changing the Billing Plan

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to retrieve 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 next_billing 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 ids; providing an id or vid in the URL indicates to CashBox that this is an update, not a create – as such, id and vid cannot be updated. Certain changes will modify the subscribed service:

Plan ChangeProviding a new Billing Plan will change the billing plan/schedule for the subscription as of the effective_date.

Replace an existing/active Item with a new Item Include a new Subscription_Item populating the “replaces” parameter 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)

Remove an existing Item Include a new but empty/undefined Subscription_Item populating ONLY the “replaces” parameter with the id of the existing item being removed.

All changes will take effect as of the effective_date provided; Proration cacluations, when required, will use the period between the last scheduled billing and the effective_date (calculated to whole days).

Returns

JSON A full Subscription object representing the new version of the Subscription.

  • cURL
  • Java
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.prodtest.vindicia.com/subscriptions/sub_2?effective_date=today&bill_prorated_period=true&dry_run=false"
          
The above command returns JSON structured like this:
{
    "object": "Subscription",
    "id": "sub_2",
    "vid": "83320657fd8d463b336ee2c6a87bbda37e962299",
    "created": "2016-06-01T12:02:07-07:00",
    "account": {`...cust_2234...`},
    "billing_plan": {
        "object": "BillingPlan",
        "id": "plan_2234",
        "vid": "56c48b2d29885cd93104827acb5f6d9531214297",
        "created": "2016-06-06T11:34:53-07:00",
        "description": "Simple Monthly Plan (No Trial)",
        "status": "Active",
        "periods": {`...`},
        "entitlements": {`...`}
    },
    "payment_method": {`...`},
    "currency": "USD",
    "description": "Sub2",
    "status": "Active",
    "billing_state": "Good Standing",
    "starts": "2016-06-01T12:02:04-07:00",
    "items": {
        "object": "List",
        "data": [
            {
                "object": "SubscriptionItem",
                "id": "sub_2.1a",
                "vid": "ec8d2448e923583670f2962ea70e455e7c9774d6",
                "index": 0,
                "product": {`...prod_2234...`},
                "quantity": 1,
                "created": "2016-06-06T12:02:04-07:00",
                "starts": "2016-06-06T00:00:00-07:00",
                "replaced": "sub_2.1"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_2.2",
                "vid": "47bfa048fd749a5de8cac8eb5ae27657cb3673e5",
                "index": 1,
                "product": {`...prod_1235...`},
                "quantity": 1,
                "created": "2016-06-01T12:02:04-07:00",
                "starts": "2016-06-01T00:00:00-07:00",
                "ends": "2016-06-06T12:02:04-07:00"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_2.3",
                "vid": "a7e388f65de8a09c9ee3a7b3323137aa0c122fa1",
                "index": 2,
                "product": {`...prod_1236...`},
                "quantity": 1,
                "created": "2016-06-01T12:02:04-07:00",
                "starts": "2016-06-01T00:00:00-07:00"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_2.4",
                "vid": "a7e388f65de8a09c9ee3a7b3323137aa0c122fa1",
                "index": 2,
                "product": {`...prod_3234...`},
                "quantity": 1,
                "created": "2016-06-06T12:02:04-07:00",
                "starts": "2016-06-06T00:00:00-07:00"
            }
        ],
        "total_count": 4
    },
    "billing_day": 6,
    "minimum_commitment": 0,
    "notify_on_transition": false,
    "most_recent_billing": null,
    "next_billing": {`...`}
}
          
The above command returns JSON structured like this:
{
    "object": "Subscription",
    "id": "sub_2",
    "vid": "83320657fd8d463b336ee2c6a87bbda37e962299",
    "created": "2016-06-01T12:02:07-07:00",
    "account": {`...cust_2234...`},
    "billing_plan": {
        "object": "BillingPlan",
        "id": "plan_2234",
        "vid": "56c48b2d29885cd93104827acb5f6d9531214297",
        "created": "2016-06-06T11:34:53-07:00",
        "description": "Simple Monthly Plan (No Trial)",
        "status": "Active",
        "periods": {`...`},
        "entitlements": {`...`}
    },
    "payment_method": {`...`},
    "currency": "USD",
    "description": "Sub2",
    "status": "Active",
    "billing_state": "Good Standing",
    "starts": "2016-06-01T12:02:04-07:00",
    "items": {
        "object": "List",
        "data": [
            {
                "object": "SubscriptionItem",
                "id": "sub_2.1a",
                "vid": "ec8d2448e923583670f2962ea70e455e7c9774d6",
                "index": 0,
                "product": {`...prod_2234...`},
                "quantity": 1,
                "created": "2016-06-06T12:02:04-07:00",
                "starts": "2016-06-06T00:00:00-07:00",
                "replaced": "sub_2.1"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_2.2",
                "vid": "47bfa048fd749a5de8cac8eb5ae27657cb3673e5",
                "index": 1,
                "product": {`...prod_1235...`},
                "quantity": 1,
                "created": "2016-06-01T12:02:04-07:00",
                "starts": "2016-06-01T00:00:00-07:00",
                "ends": "2016-06-06T12:02:04-07:00"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_2.3",
                "vid": "a7e388f65de8a09c9ee3a7b3323137aa0c122fa1",
                "index": 2,
                "product": {`...prod_1236...`},
                "quantity": 1,
                "created": "2016-06-01T12:02:04-07:00",
                "starts": "2016-06-01T00:00:00-07:00"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_2.4",
                "vid": "a7e388f65de8a09c9ee3a7b3323137aa0c122fa1",
                "index": 2,
                "product": {`...prod_3234...`},
                "quantity": 1,
                "created": "2016-06-06T12:02:04-07:00",
                "starts": "2016-06-06T00:00:00-07:00"
            }
        ],
        "total_count": 4
    },
    "billing_day": 6,
    "minimum_commitment": 0,
    "notify_on_transition": false,
    "most_recent_billing": null,
    "next_billing": {`...`}
}
          

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top