Updating Subscriptions

You can update the subscription id, price, plan, payment method token, add-on and discount details, and/or merchant account. Updating the plan only changes the association; we do not automatically change the price. You can only update to a plan with the same billing cycle. At this time we do not allow you to update from a yearly plan to a monthly plan and vice versa. Canceled and expired subscriptions cannot be updated.

Updateable Fields

Example

var result = gateway.Subscription.Update(subscription.Id,
    new SubscriptionRequest
    {
        Id = "new_id",
        PaymentMethodToken = "new_payment_method_token",
        Price = 14.00M,
        PlanId = "new_plan",
        MerchantAccountId = "new_merchant_account"
    });

Since merchant account determines currency, updating the merchant account could also change which currency the subscription is processed in.

Proration

If you increase the price and have proration enabled, we will create a prorated transaction based on the change in price for the remainder of the billing cycle. If you decrease the price, the change will take effect in the next billing period. Currently we do not do proration on downgrades.

By default, if the proration transaction fails, we continue with the update to the subscription, accumulate the proration amount on the balance, and include that amount in the next period’s billing.

SubscriptionRequest updateRequest = new SubscriptionRequest
{
    Price = 2100.00M,
    Options = new SubscriptionOptionsRequest
    {
        ProrateCharges = true
    }
};

Result<Subscription> result = gateway.Subscription.Update(subscription.Id, updateRequest);

result.Target.Transactions[0].Status;
// TransactionStatus.PROCESSOR_DECLINED

result.IsSuccess();
// true

result.Target.Price;
// 2100.00M

subscription.Balance;
// the prorated amount

You have the option of having subscription updates reverted if the proration transaction fails.

subscription.Price;
// 1000.00M

SubscriptionRequest updateRequest = new SubscriptionRequest
{
    Price = 2100.00M,
    Options = new SubscriptionOptionsRequest
    {
        ProrateCharges = true,
        RevertSubscriptionOnProrationFailure = true
    }
};

Result<Subscription> result = gateway.Subscription.Update(subscription.Id, updateRequest);

result.Target.Transactions[0].Status;
// TransactionStatus.PROCESSOR_DECLINED

result.IsSuccess();
// false

result.Target.Price;
// 1000.00M

subscription.Balance;
// 0.00M

Add-ons/Discounts

When updating a subscription, you can modify the add-ons and discounts in 3 ways:

var request = new SubscriptionRequest
{
    AddOns = new AddOnsRequest
    {
        Add = new AddAddOnRequest[]
        {
            new AddAddOnRequest
            {
                InheritedFromId = "add_on_id_1",
                Amount = 25.00M
            }
        },
        Update = new UpdateAddOnRequest[]
        {
            new UpdateAddOnRequest
            {
                ExistingId = "add_on_id_2",
                Amount = 50.00M
            }
        },
        Remove = new String[] { "add_on_id_3" }
    },
    Discounts = new DiscountsRequest
    {
        Add = new AddDiscountRequest[]
        {
            new AddDiscountRequest
            {
                InheritedFromId = "discount_id_1",
                Amount = 7.00M
            }
        },
        Update = new UpdateDiscountRequest[]
        {
            new UpdateDiscountRequest
            {
                ExistingId = "discount_id_2",
                Amount = 15.00M
            }
        },
        Remove = new String[] { "discount_id_3" }
    }
};

Result<Subscription> result = gateway.Subscription.Update(
    "the_subscription_id",
    request
);

When updating a subscription you can add, update and remove multiple add-ons/discounts at the same time.

var request = new SubscriptionRequest
{
    AddOns = new AddOnsRequest
    {
        Add = new AddAddOnRequest[]
        {
            new AddAddOnRequest
            {
                InheritedFromId = "add_on_id_1",
                Amount = 20.00M
            },
            new AddAddOnRequest
            {
                InheritedFromId = "add_on_id_2",
                Amount = 30.00M
            }
        },
        Update = new UpdateAddOnRequest[]
        {
            new UpdateAddOnRequest
            {
                ExistingId = "add_on_id_3",
                Quantity = 2
            },
            new UpdateAddOnRequest
            {
                ExistingId = "add_on_id_4",
                Quantity = 3
            }
        },
        Remove = new String[] { "add_on_id_5", "add_on_id_6" }
    }
};

Result<Subscription> result = gateway.Subscription.Update("the_subscription_id", request);

When adding add-ons/discounts, all details will be inherited from the add-on/discount specified by the InheritedFromId. You can override any of the following:

var request = new SubscriptionRequest
{
    AddOns = new AddOnsRequest
    {
        Add = new AddAddOnRequest[]
        {
            new AddAddOnRequest
            {
                InheritedFromId = "add_on_id_1",
                Amount = 20.00M,
                NumberOfBillingCycles = 2,
                Quantity = 4
            }
        },
        Update = new UpdateAddOnRequest[]
        {
            new UpdateAddOnRequest
            {
                ExistingId = "add_on_id_2",
                Amount = 15.00M,
                NeverExpires = true,
                Quantity = 3
            }
        }
    }
};

Result<Subscription> result = gateway.Subscription.Update(
    "the_subscription_id",
    request
);

If you prefer to update a subscription and remove all existing add-ons and discounts, you can pass the ReplaceAllAddOnsAndDiscounts option.

var request = new SubscriptionRequest
{
    Options = new SubscriptionOptionsRequest
    {
       ReplaceAllAddOnsAndDiscounts = true
    }
};

Result<Subscription> result = gateway.Subscription.Update(
    "the_subscription_id",
    request
);

You can only add an add-on or discount to a subscription once. If you’d like to apply an add-on or discount to a subscription several times, you can pass Quantity when creating or updating the add-on/discount.

See Also