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

result = Braintree::Subscription.update(
  "m476", # id of subscription to update
  :id => "new_id",
  :payment_method_token => "new_payment_method_token",
  :price => "14.00",
  :plan_id => "new_plan",
  :merchant_account_id => "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.

result = Braintree::Subscription.update(subscription.id,
  :price => 2100,
  :options => {
    :prorate_charges => true
  }
)

transaction = result.subscription.transactions.first
transaction.status
#=> Braintree::Transaction::Status::ProcessorDeclined

result.success?
#=> true

result.subscription.price
#=> 2100

result.subscription.balance
#=> the prorated amount

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

subscription.price
#=> 1000

result = Braintree::Subscription.update(subscription.id,
  :price => 2100,
  :options => {
    :revert_subscription_on_proration_failure => true
  }
)

result.subscription.transactions.first.status
#=> Braintree::Transaction::Status::ProcessorDeclined

result.success?
#=> false

result.subscription.price
#=> 1000

result.subscription.balance
#=> 0

Add-ons/Discounts

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

result = Braintree::Subscription.update(
  "the_subscription_id",
  :add_ons => {
    :add => [
      {
        :inherited_from_id => "add_on_id_1",
        :amount => BigDecimal.new("25.00")
      }
    ],
    :update => [
      {
        :existing_id => "the_add_on_id_2",
        :amount => BigDecimal.new("50.00")
      }
    ],
    :remove => ["the_add_on_id_3"]
  },
  :discounts => {
    :add => [
      {
        :inherited_from_id => "discount_id_1",
        :amount => BigDecimal.new("7.00")
      }
    ],
    :update => [
      {
        :existing_id => "discount_id_2",
        :amount => BigDecimal.new("15.00")
      }
    ],
    :remove => ["discount_id_3"]
  }
)

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

result = Braintree::Subscription.update(
  "the_subscription_id",
  :add_ons => {
    :add => [
      {
        :inherited_from_id => "add_on_id_1",
        :amount => BigDecimal.new("20.00")
      },
      {
        :inherited_from_id => "add_on_id_2",
        :amount => BigDecimal.new("30.00")
      }
    ],
    :update => [
      {
        :existing_id => "add_on_id_3",
        :quantity => 2
      },
      {
        :existing_id => "add_on_id_4",
        :quantity => 3
      }
    ],
    :remove => ["add_on_id_5", "add_on_id_6"]
  }
)

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

result = Braintree::Subscription.update(
  "the_subscription_id",
  :add_ons => {
    :add => [
      {
        :inherited_from_id => "add_on_id_1",
        :amount => BigDecimal.new("20.00"),
        :number_of_billing_cycles => 2,
        :quantity => 4
      }
    ],
    :update => [
      {
        :existing_id => "add_on_id_2",
        :amount => BigDecimal.new("15.00"),
        :never_expires => true,
        :quantity => 3
      }
    ]
  }
)

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

result = Braintree::Subscription.update(
  "the_subscription_id",
  :options => {
    :replace_all_add_ons_and_discounts => true
  }
)

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