Plan: Update
- Java
PlanRequest request = new PlanRequest()
.id("new_id")
.name("Awesome Bar")
.description("Incredibly Mediocre")
.price(new BigDecimal("2.00"));
Result<plan> result = gateway.plan().update("a_plan_id", request);
NotFoundException
.
Arguments
id
required, 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.
.add(…)
arrayArray of add-ons to add to the plan
.amount(…)
BigDecimalPrice of the add-on. This will override the inherited add-on amount.
.description(…)
stringA description of the add-on. Its value will always be nil for add-ons that are attached to a subscription.
.inheritedFromId(…)
stringSpecify 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.
.name(…)
stringThe name of the add-on.
Number of billing cycles to apply the add-on. It must be greater than 0.
.remove(…)
arrayArray of add-on IDs that are associated with the subscription. IDs specified will be removed from the plan.
.update(…)
arrayArray of add-ons that are associated with the plan.
.amount(…)
BigDecimalPrice of the add-on. This will override the inherited add-on amount.
.description(…)
stringA description of the add-on.
.existingId(…)
stringUpdate a particular add-on by specifying the add-on ID.
.name(…)
stringThe name of the add-on.
Number of billing cycles to apply the add-on. Must be greater than 0.
.billingDayOfMonth(…)
integer or stringThe value that specifies the day of the month that the gateway will charge the subscription on every billing cycle.
.billingFrequency(…)
integer or stringSpecifies the billing interval of the plan.
.currencyIsoCode(…)
stringThe currency for the transaction. The three-letter alphabetic codes for the transaction's currency (e.g. "USD" for US dollars).
.description(…)
stringA description of the plan.
A collection of discounts associated with this plan. Discount details can only be managed within the Control Panel.
.add(…)
arrayArray of discounts to add to the plan.
.amount(…)
BigDecimalPrice of the discount. This will override the inherited discount amount.
.description(…)
stringA description of the discount.
.inheritedFromId(…)
stringSpecify a discount ID to apply to the plan. You can't duplicate an discount for a plan, but you can update the quantity.
.name(…)
stringThe name of the discount.
Number of billing cycles to apply the discount. It must be greater than 0.
.remove(…)
arrayArray of discount IDs that are associated with the subscription. IDs specified will be removed from the plan.
.update(…)
arrayArray of discounts that are associated with the plan.
.amount(…)
BigDecimalPrice of the discount. This will override the inherited discount amount.
.description(…)
stringA description of the discount.
.existingId(…)
stringUpdate a particular discount by specifying the discount ID.
.name(…)
stringThe name of the discount.
Number of billing cycles to apply the discount. It must be greater than 0.
.id(…)
stringA 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.
.modificationTokens(…)
stringThe 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.
.name(…)
stringThe name of the plan.
.neverExpires(…)
boolean or stringWhether a subscription's billing cycle is set to never expire, or to run for a specific number of billing cycles.
.numberOfBillingCycles(…)
integer or stringSpecifies the number of billing cycles of the plan.
.price(…)
decimal or stringThe base price specified for a plan, formatted like "10" or "10.00".
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.
.trialDurationUnit(…)
stringThe trial unit specified in a plan. Specify
day
or month
..trialPeriod(…)
booleanA 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.
- Java
string[] modification_tokens = {"modification1_token", "modification2_token"};
PlanRequest request = new PlanRequest()
.id("new_id")
.name("Awesome Bar")
.description("Incredibly Mediocre")
.price(new BigDecimal("2.00"))
.modification_tokens(modification_tokens);
Result<plan> result = gateway.plan().update("a_plan_id", request);
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
- Java
PlanRequest request = new PlanRequest()
.addOns()
.add()
.inheritedFromId("add_on_id_1")
.amount(new BigDecimal("25.00"))
.done()
.update("add_on_id_2")
.amount(new BigDecimal("50.00"))
.done()
.remove("add_on_id_3")
.done()
.discounts()
.add()
.inheritedFromId("discount_id_1")
.amount(new BigDecimal("7.00"))
.done()
.update("discount_id_2")
.amount(new BigDecimal("15.00"))
.done()
.remove("discount_id_3")
.done();
Result<Plan> result = gateway.plan().update(
"the_plan_id",
request
);
Multiple updates
You can also add, update and remove multiple add-ons/discounts at the same time.
- Java
PlanRequest request = new PlanRequest()
.addOns()
.add()
.inheritedFromId("add_on_id_1")
.amount(new BigDecimal("20.00"))
.done()
.add()
.inheritedFromId("add_on_id_2")
.amount(new BigDecimal("30.00"))
.done()
.update("add_on_id_3")
.quantity(2)
.done()
.update("add_on_id_4")
.quantity(3)
.done()
.remove("add_on_id_5", "add_on_id_6")
.done();
Result<Plan> result = gateway.plan().update("the_plan_id", request);
Override details
When adding add-ons/discounts, all details will be inherited from the add-on/discount specified by
the inheritedFromId. When updating add-ons/discounts, all details will
be inherited from the add-on/discount specified by the existingId. You
can override any of the following:
- amount
- numberOfBillingCycles
- name
- description
- Java
PlanRequest request = new PlanRequest()
.addOns()
.add()
.inheritedFromId("add_on_id_1")
.amount(new BigDecimal("20.00"))
.numberOfBillingCycles(2)
.name("NewName")
.description("NewDescription")
.done()
.update("add_on_id_2")
.amount(new BigDecimal("15.00"))
.numberOfBillingCycles(2)
.name("NewName")
.description("NewDescription")
.done()
.done()
.discounts()
.add()
.inheritedFromId("discount_id_1")
.amount(new BigDecimal("20.00"))
.numberOfBillingCycles(2)
.name("NewName")
.description("NewDescription")
.done()
.update("discount_id_2")
.amount(new BigDecimal("15.00"))
.numberOfBillingCycles(2)
.name("NewName")
.description("NewDescription")
.done()
.done();
Result<Plan> result = gateway.plan().update(
"the_plan_id",
request
);
Update trail period
Updating a plan removes "billing day of the month" when trialPeriod is
passed. In the example below, the plan will not have its "billing day of the month" after it is
updated.
- Java
PlanRequest request = new PlanRequest()
.description("Incredibly Mediocre")
.trialPeriod("2");
Result<plan> result = gateway.plan().update("a_plan_id", request);