Plan

Plan: Update

See also the Plan response object.

  1. Ruby
result = gateway.plan.update(
  "a_plan_id", # id of the plan to update
  :id => "new_id",
  :name => "Awesome Bar",
  :description => "Incredibly Mediocre",
  :price => "2.00"
)

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

Arguments
idrequired, String
A string value representing a specific plan. When updating a plan, you can only use tokens associated with the same customer that the plan is currently associated with.
Additional Parameters
:add_ons

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

:addarray
Array of add-ons to add to the plan
:amountBigDecimal
Price of the add-on. This will override the inherited add-on amount.
:descriptionString
A description of the add-on. Its value will always be nil for add-ons that are attached to a subscription.
:inherited_from_idString
Specify an add-on ID to apply to the pan. You can't duplicate an add-on for a plan, but you can update the quantity.
:nameString
The name of the add-on.
:number_of_billing_cyclesString
Number of billing cycles to apply the add-on. It must be greater than 0.
:removearray
Array of add-on IDs that are associated with the subscription. IDs specified will be removed from the plan.
:updatearray
Array of add-ons that are associated with the plan.
:amountBigDecimal
Price of the add-on. This will override the inherited add-on amount.
:descriptionString
A description of the add-on.
:existing_idString
Update a particular add-on by specifying the add-on ID.
:nameString
The name of the add-on.
:number_of_billing_cyclesString
Number of billing cycles to apply the add-on. Must be greater than 0.
:billing_day_of_monthinteger or string
The value that specifies the day of the month that the gateway will charge the subscription on every billing cycle.
:billing_frequencyinteger or string
Specifies the billing interval of the plan.
:currency_iso_codeString
The currency for the transaction. The three-letter alphabetic codes for the transaction's currency (e.g. "USD" for US dollars).
:descriptionString
A description of the plan.
:discounts

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

:addarray
Array of discounts to add to the plan.
:amountBigDecimal
Price of the discount. This will override the inherited discount amount.
:descriptionString
A description of the discount.
:inherited_from_idString
Specify a discount ID to apply to the plan. You can't duplicate an discount for a plan, but you can update the quantity.
:nameString
The name of the discount.
:number_of_billing_cyclesString
Number of billing cycles to apply the discount. It must be greater than 0.
:removearray
Array of discount IDs that are associated with the subscription. IDs specified will be removed from the plan.
:updatearray
Array of discounts that are associated with the plan.
:amountBigDecimal
Price of the discount. This will override the inherited discount amount.
:descriptionString
A description of the discount.
:existing_idString
Update a particular discount by specifying the discount ID.
:nameString
The name of the discount.
:number_of_billing_cyclesString
Number of billing cycles to apply the discount. It must be greater than 0.
:idString
A string value representing a specific plan in the Vault. Max 36 characters; must be unique within a merchant's Vault; valid characters are letters, numbers, - and _. If not specified on creation, the gateway will generate an alphanumeric ID that can be accessed on the result. The generated IDs will never start with a leading 0 and are case-insensitive.
:modification_tokensString
The collection of Modification Tokens associated with a plan. A modification is an add_on or a discont. So modification tokens can be passed to assiciate with a plan when creating the plan.
:nameString
The name of the plan.
:never_expiresboolean or string
Whether a subscription's billing cycle is set to never expire, or to run for a specific number of billing cycles.
:number_of_billing_cyclesinteger or string
Specifies the number of billing cycles of the plan.
:pricedecimal or string
The base price specified for a plan, formatted like "10" or "10.00".
:trial_durationInteger

The trial timeframe specified in a plan. It is required if the trial period is set to true and must be 1-3 digits. If you specify a trial duration of 0, the gateway will start the subscription immediately and not consider it to include a trial period.

:trial_duration_unitString
The trial unit specified in a plan. Specify day or month.
:trial_periodbool

A value indicating whether a subscription should begin with a trial period. If not specified on creation, the gateway will generate false by default. It cannot have both a specified billing date and a trial period.

Add-ons and discountsanchor

There are two ways to add add_ons/discounts when updating a plan.

First, modification tokens can be passed along when updating a plan. A modification is either an add_on or a discount.

  1. Ruby
result = gateway.plan.update(
  "a_plan_id", # id of the plan to update
  :id => "new_id",
  :name => "Awesome Bar",
  :description => "Incredibly Mediocre",
  :price => "2.00",
  :modification_tokens => ["modification1_token", "modification2_token"]
)
note

You have to pass modification tokens if there are add-ons/dicounts belonging to a plan when updating the plan. Otherwise it removes all modifications associated with this plan after updating the plan

Secondly, you can modify the add-ons and discounts by passing add_ons/discounts when updating a plan.

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

Multiple updatesanchor

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

  1. Ruby
result = gateway.plan.update(
  "the_plan_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. When updating add-ons/discounts, all details will be inherited from the add-on/discount specified by the existing_id. You can override any of the following:

  • amount
  • number_of_billing_cycles
  • name
  • description
  1. Ruby
result = gateway.plan.update(
  "the_plan_id",
  :add_ons => {
    :add => [
      {
        :inherited_from_id => "add_on_id_1",
        :amount => BigDecimal.new("20.00"),
        :number_of_billing_cycles => 2,
        :name => "NewName",
        :description => "NewDescription"
      }
    ],
    :update => [
      {
        :existing_id => "add_on_id_2",
        :amount => BigDecimal.new("20.00"),
        :number_of_billing_cycles => 2,
        :name => "NewName",
        :description => "NewDescription"
      }
    ]
  },

 :discounts => {
    :add => [
      {
        :inherited_from_id => "discount_id_1",
        :amount => BigDecimal.new("20.00"),
        :number_of_billing_cycles => 2,
        :name => "NewName",
        :description => "NewDescription"
      }
    ],
    :update => [
      {
        :existing_id => "discount_id_2",
        :amount => BigDecimal.new("15.00"),
        :number_of_billing_cycles => 2,
        :name => "NewName",
        :description => "NewDescription"
      }
    ]
  }
)

Update trail periodanchor

Updating a plan removes "billing day of the month" when trial_period is passed. In the example below, the plan will not have its "billing day of the month" after it is updated.

  1. Ruby
result = gateway.plan.update(
  "a_plan_id", # id of the plan to update
  :description => "Incredibly Mediocre",
  :trial_period => "2"
)

See also