Plan

Plan: Update

See also the Plan response object.
  1. Callback
  2. Promise
gateway.plan.update(
    "aPlanId",
    {
        id: "newId",
        name: "Awesome Bar",
        description: "Incredibly Mediocre",
        price: "2.00"
    }, (err, result) => {
    }
);
If the plan can't be found, it will return a 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
addOns

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
amountString
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.
inheritedFromIdString
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.
numberOfBillingCyclesString
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.
amountString
Price of the add-on. This will override the inherited add-on amount.
descriptionString
A description of the add-on.
existingIdString
Update a particular add-on by specifying the add-on ID.
nameString
The name of the add-on.
numberOfBillingCyclesString
Number of billing cycles to apply the add-on. Must be greater than 0.
billingDayOfMonthinteger or string
The value that specifies the day of the month that the gateway will charge the subscription on every billing cycle.
billingFrequencyinteger or string
Specifies the billing interval of the plan.
currencyIsoCodeString
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.
amountString
Price of the discount. This will override the inherited discount amount.
descriptionString
A description of the discount.
inheritedFromIdString
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.
numberOfBillingCyclesString
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.
amountString
Price of the discount. This will override the inherited discount amount.
descriptionString
A description of the discount.
existingIdString
Update a particular discount by specifying the discount ID.
nameString
The name of the discount.
numberOfBillingCyclesString
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.
modificationTokensString
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.
neverExpiresboolean or string
Whether a subscription's billing cycle is set to never expire, or to run for a specific number of billing cycles.
numberOfBillingCyclesinteger 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".
trialDurationNumber

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.

trialDurationUnitString
The trial unit specified in a plan. Specify day or month.
trialPeriodbool

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 discountsAnchorIcon

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. Callback
  2. Promise
const modification_tokens = ["modification1_token", "modification2_token"];
gateway.plan.update(
    "aPlanId",
    {
        id: "newId",
        name: "Awesome Bar",
        description: "Incredibly Mediocre",
        price: "2.00",
        modification_tokens: modification_tokens
    }, (err, result) => {
    });
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. Callback
  2. Promise
gateway.plan.update("thePlanId", {
    addOns: {
        add: [{
            inheritedFromId: "addOnId1",
            amount: "25.00"
        }],
        update: [{
            existingId: "addOnId2",
            amount: "50.00"
        }],
        remove: ["addOnId3"]
    },
    discounts: {
        add: [{
            inheritedFromId: "discountId1",
            amount: "7.00"
        }],
        update: [{
            existingId: "discountId2",
            amount: "15.00"
        }],
        remove: ["discountId3"]
    }
}, (err, result) => {
    // Handle result or error
});

Multiple updatesAnchorIcon

You can also add, update and remove multiple add-ons/discounts at the same time.
  1. Callback
  2. Promise
gateway.plan.update("thePlanId", {
    addOns: {
        add: [{
            inheritedFromId: "addOnId1",
            amount: "20.00"
        }, {
            inheritedFromId: "addOnId2",
            amount: "30.00"
        }],
        update: [{
            existingId: "addOnId3",
            quantity: 2
        }, {
            existingId: "addOnId4",
            quantity: 3
        }],
        remove: ["addOnId5", "addOnId_6"]
    }
}, (err, result) => {
    // Handle result or error
});

Override detailsAnchorIcon

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
  1. Callback
  2. Promise
gateway.plan.update("thePlanId", {
    addOns: {
        add: [{
            inheritedFromId: "addOnId1",
            amount: "20.00",
            numberOfBillingCycles: 2,
            name: "NewName",
            description: "NewDescription"
        }],
        update: [{
            existingId: "addOnId2",
            amount: "15.00",
            numberOfBillingCycles: 2,
            name: "NewName",
            description: "NewDescription"
        }]
    },
    discounts: {
        add: [{
            inheritedFromId: "discountId1",
            amount: "20.00",
            numberOfBillingCycles: 2,
            name: "NewName",
            description: "NewDescription"
        }],
        update: [{
            existingId: "discountId2",
            amount: "15.00",
            numberOfBillingCycles: 2,
            name: "NewName",
            description: "NewDescription"
        }]
    }
}, (err, result) => {
    // Handle result or error
});

Update trail periodAnchorIcon

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.
  1. Callback
  2. Promise
gateway.plan.update("aPlanId", {
    description: "Incredibly Mediocre",
    trialPeriod: "2"
}, (err, result) => {
    // Handle result or error
});

See also

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.