Plan

Plan: Create

See also the Plan response object.

Before creating a plan, make sure recurring billing feature is enabled for the merchant.

A plan can be created with the required parameters: "name", "price", "billing_frequency", "currency_iso_code". Here is an example for how to crate a plan.

  1. Ruby
result = gateway.plan.create(
  :name => "the_name",
  :billing_frequency => "the_billing_frequency",
  :currency_iso_code => "the_currency_iso_code",
  :price => "the_price"
)
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.
: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. It 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. 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 add_ons/discounts when creating a plananchor

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

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

  1. Ruby
result = gateway.plan.create(
  :name => "the_name",
  :billing_frequency => "the_billing_frequency",
  :currency_iso_code => "the_currency_iso_code",
  :price => "the_price",
  :modification_tokens => ["add_on1_token", "add_on2_token"]
)

Secondly, New add-ons/discounts can also be added to the plan using pramater "add_ons/discounts".

  • Add-ons/discounts that would be inherited from the plan can be updated on the plan.
  • Add-ons/discounts that would be inherited from the plan can be removed from the plan.
  1. Ruby
result = gateway.plan.create(
  :name => "the_name",
  :billing_frequency => "the_billing_frequency",
  :currency_iso_code => "the_currency_iso_code",
  :price => "the_price",
  :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",
        :description => "Updated description"
      },
      {
        :existing_id => "add_on_id_4",
        :description => "Updated description"
      }
    ],
    :remove => ["add_on_id_5", "add_on_id_6"]
  },
  :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"]
  }
)

When adding add-ons/discounts to a plan, 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.create(
  :name => "the_name",
  :billing_frequency => "the_billing_frequency",
  :currency_iso_code => "the_currency_iso_code",
  :price => "the_price",
  :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("15.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"
      }
    ]
  }
)

See also