Subscription

Subscription: Update

See also the Subscription response object.

  1. Ruby
result = gateway.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"
)

If the subscription can't be found, it will raise a Braintree::NotFoundError.

Arguments
idrequired, String
A string value representing a specific subscription in the Vault.
Additional Parameters
:add_ons

The collection of add-ons associated with a subscription. Add-on details can only be managed within the Control Panel.

:addarray
Array of add-ons to add to the subscription
:amountBigDecimal
Price of the add-on. This will override the inherited add-on amount.
:inherited_from_idString
Specify an add-on ID to apply to the subscription. You can't duplicate an add-on for a subscription, but you can update the quantity.
:never_expiresbool
Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.
:number_of_billing_cyclesString
Number of billing cycles to apply the add-on. Must be greater than 0.
:quantityInteger
How many of this add-on to apply to the subscription. The default is 1.
:removearray
Array of add-on IDs that are associated with the subscription. IDs specified will be removed from the subscription.
:updatearray
Array of add-ons that are associated with the subscription.
:amountBigDecimal
Price of the add-on. This will override the existing add-on amount.
:existing_idString
Update a particular add-on by specifying the add-on ID.
:never_expiresbool
Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.
:number_of_billing_cyclesString
Number of billing cycles to apply the add-on. Must be greater than 0.
:quantityInteger
How many of this add-on to apply to the subscription. This will override the existing add-on quantity.
:descriptor

Dynamic descriptors are not enabled on all accounts by default. If you receive a validation error of 92203 or if your dynamic descriptors are not displaying as expected, please contact us.

Dynamic descriptors are sent on a per-transaction basis and define what will appear on your customers' credit card statements for a specific purchase. The clearer the description of your product, the less likely customers will issue chargebacks due to confusion or non-recognition.



See the dynamic descriptor example for additional information.

:nameString

The value in the business name field of a customer's statement. The specific length/character requirements for this value depend on your processor. Contact us for assistance.

:phoneString
The value in the phone number field of a customer's statement. Phone must be 10-14 characters and can only contain numbers, hyphens and parentheses.
:urlString
The value in the URL/web address field of a customer's statement. The URL must be 13 characters or shorter.
:discounts

A collection of discounts associated with this subscription. Discount details can only be managed within the Control Panel.

:addarray
Array of discounts to add to the subscription.
:amountBigDecimal
Amount of the discount. This will override the inherited discount amount.
:inherited_from_idString
Specify a discount ID to apply to the subscription. You can't duplicate a discount for a subscription, but you can update the quantity.
:never_expiresbool
Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.
:number_of_billing_cyclesString
Number of billing cycles to apply the discount. Must be greater than 0.
:quantityInteger
How many of this discount to apply to the subscription. The default is 1.
:removearray
Array of discount IDs that are associated with the subscription. IDs specified will be removed from the subscription.
:updatearray
Array of discounts that are associated with the subscription.
:amountBigDecimal
Price of the discount. This will override the existing discount amount.
:existing_idString
Update a particular discount by specifying the discount ID.
:never_expiresbool
Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.
:number_of_billing_cyclesString
Number of billing cycles to apply the discount. Must be greater than 0.
:quantityInteger
How many of this discount to apply to the subscription. This will override the existing discount quantity.
:idString
If this option is provided, the subscription's current ID will be replaced with the value specified. Max 36 characters; must be unique within a merchant's Vault; valid characters are letters, numbers, - and _.
:merchant_account_idString

The merchant account ID used to create the subscription's transactions. Currency is also determined by merchant account ID and it must match the Plan's currency. See the Transaction merchant_account_id parameter for more information.

:never_expiresbool

Whether a subscription's billing cycle is set to never expire instead of running for a specific number of billing cycles. If this is set to true, number_of_billing_cycles will be set to nil as a subscription can't have a limited number of billing cycles and never expire. If set to false, number_of_billing_cycles can't be nil.

:number_of_billing_cyclesInteger

The number of billing cycles of the subscription. If this is set to a non-nil value, never_expires will be set to false as a subscription can't both have a limited number of billing cycles and never expire. This value must be greater than or equal to the value of current_billing_cycle.

:options
Optional values that can be passed with a request.
:paypal
PayPal-specific options.
:descriptionString
The description of the transaction that is displayed to customers in email receipts from PayPal. 127 character maximum.
:prorate_chargesbool
A flag that specifies whether the change in subscription price should be prorated.
:replace_all_add_ons_and_discountsbool

When set to true, the plan's add-ons and discounts are removed, setting the value to 0. This parameter can also be used in conjunction with the add parameters to replace a plan's existing add-ons and discounts with those specified.

:revert_subscription_on_proration_failurebool

By default, if the transaction for the prorated amount fails, the subscription is reverted. If you would like to continue with the update to the subscription and add the prorated amount to the balance even though the transaction failed, you should set this field to false.

:payment_method_nonceString

One-time-use reference to a payment method provided by your customer, such as a credit card or PayPal account.

A payment method must be vaulted before you can associate it with a subscription, so it's usually simplest to refer to the payment method using its payment_method_token. However, there are 2 cases where you can pass a payment method nonce instead of a payment method token:

  • If the nonce was generated by our Drop-in UI and you passed a customer_id when generating the client token, or
  • If the nonce was generated from a vaulted payment method belonging to the customer that owns the subscription
:payment_method_tokenString

An alphanumeric value that references a specific payment method stored in your Vault. If provided, this will change the payment method associated with the subscription. Under certain circumstances, you can pass a payment_method_nonce instead.

:plan_idString
Plans must be created in the Control Panel. Updating a plan only changes the association; we do not automatically change the price of the subscription. 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. You can't edit the plan on a Past Due, Expired, or Canceled subscription.
:priceBigDecimal

The price specified for a subscription. Billing price must be formatted like 10 or 10.00. If you provide a price, it can't be an empty string. You must update the price in this parameter; updating the plan_id will not automatically change the price of a subscription. You can't update the price of a Past Due, Expired, or Canceled subscription. Price can't be greater than the maximum allowed by the processor. Contact us for your specific limit.

important

Merchants operating in the European Union must give customers 4 weeks’ notice before changing the price of their recurring billing plan; 4 weeks’ notice is also required before billing customers if it has been 6+ months since their last payment. If you don’t operate in the EU, these notices aren't required (but they're still good practice).

Examplesanchor

Add-ons and discountsanchor

note

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.

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

  • New add-ons/discounts can be added
  • Existing add-ons/discounts associated with the subscription can be updated
  • Existing add-ons/discounts associated with the subscription can be removed
  1. Ruby
result = gateway.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"]
  }
)

Update with 3D Secure enriched payment method nonceanchor

If you use 3D Secure and need to apply 3DS to the next transaction of an existing subscription, you must update the subscription using a 3DS-enriched nonce. See the 3D Secure guide for details on how to properly obtain a 3DS-enriched nonce, and see the 3D Secure for Recurring Transactions page for more information on utilizing 3DS for subscription transactions.

Once you've obtained a 3DS-enriched nonce, provide it on the subscription update call:

  1. Ruby
result = gateway.subscription.update(
  :payment_method_nonce => "nonce_from_the_client",
  :id => "subscription_id"
)

Multiple updatesanchor

You can also add, update and remove multiple add-ons/discounts at the same time.

  1. Ruby
result = gateway.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"]
  }
)

Override detailsanchor

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:

  • amount
  • number_of_billing_cycles or never_expires
  • quantity
  1. Ruby
result = gateway.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
      }
    ]
  }
)

Remove add-ons and discountsanchor

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.

  1. Ruby
result = gateway.subscription.update(
  "the_subscription_id",
  :options => {
    :replace_all_add_ons_and_discounts => true
  }
)

See also