Plan
Plan: Update
- 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"
);Braintree::NotFoundError.
Arguments
idrequired, StringA 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
The collection of add-ons associated with a plan. Add-on details can only be managed within the Control Panel.
:addarrayArray of add-ons to add to the plan
:amountBigDecimalPrice of the add-on. This will override the inherited add-on amount.
:descriptionStringA description of the add-on. Its value will always be nil for add-ons that are attached to a subscription.
:inherited_from_idStringSpecify 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.
:nameStringThe name of the add-on.
Number of billing cycles to apply the add-on. It must be greater than 0.
:removearrayArray of add-on IDs that are associated with the subscription. IDs specified will be removed from the plan.
:updatearrayArray of add-ons that are associated with the plan.
:amountBigDecimalPrice of the add-on. This will override the inherited add-on amount.
:descriptionStringA description of the add-on.
:existing_idStringUpdate a particular add-on by specifying the add-on ID.
:nameStringThe name of the add-on.
Number of billing cycles to apply the add-on. Must be greater than 0.
:billing_day_of_monthinteger or stringThe value that specifies the day of the month that the gateway will charge the subscription on every billing cycle.
:billing_frequencyinteger or stringSpecifies the billing interval of the plan.
:currency_iso_codeStringThe currency for the transaction. The three-letter alphabetic codes for the transaction's currency (e.g. "USD" for US dollars).
:descriptionStringA description of the plan.
A collection of discounts associated with this plan. Discount details can only be managed within the Control Panel.
:addarrayArray of discounts to add to the plan.
:amountBigDecimalPrice of the discount. This will override the inherited discount amount.
:descriptionStringA description of the discount.
:inherited_from_idStringSpecify a discount ID to apply to the plan. You can't duplicate an discount for a plan, but you can update the quantity.
:nameStringThe name of the discount.
Number of billing cycles to apply the discount. It must be greater than 0.
:removearrayArray of discount IDs that are associated with the subscription. IDs specified will be removed from the plan.
:updatearrayArray of discounts that are associated with the plan.
:amountBigDecimalPrice of the discount. This will override the inherited discount amount.
:descriptionStringA description of the discount.
:existing_idStringUpdate a particular discount by specifying the discount ID.
:nameStringThe name of the discount.
Number of billing cycles to apply the discount. It must be greater than 0.
:idStringA 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_tokensStringThe 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.
:nameStringThe name of the plan.
:never_expiresboolean or stringWhether 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 stringSpecifies the number of billing cycles of the plan.
:pricedecimal or stringThe base price specified for a plan, formatted like "10" or "10.00".
:trial_durationIntegerThe 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_unitStringThe trial unit specified in a plan. Specify
day or month.:trial_periodboolA 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 discounts
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.
- 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
- 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
- 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 updates
You can also add, update and remove multiple add-ons/discounts at the same time.
- 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 details
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
- 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 period
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.
- Ruby
result = gateway.plan.update(
"a_plan_id",
# id of the plan to update
:description => "Incredibly Mediocre",
:trial_period => "2"
);