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. Python
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.

'add'array
Array of add-ons to add to the plan.
'amount'Decimal
Price of the add-on. This will override the inherited add-on amount.
'description'str
A description of the add-on.
'inherited_from_id'str
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.
'name'str
The name of the add-on.
'number_of_billing_cycles'str
Number of billing cycles to apply the add-on. It must be greater than 0.
'remove'array
Array of add-on IDs that are associated with the subscription. IDs specified will be removed from the plan.
'update'array
Array of add-ons that are associated with the plan.
'amount'Decimal
Price of the add-on. This will override the inherited add-on amount.
'description'str
A description of the add-on.
'existing_id'str
Update a particular add-on by specifying the add-on ID.
'name'str
The name of the add-on.
'number_of_billing_cycles'str
Number of billing cycles to apply the add-on. It must be greater than 0.
'billing_day_of_month'integer or string
The value that specifies the day of the month that the gateway will charge the subscription on every billing cycle.
'billing_frequency'integer or string
Specifies the billing interval of the plan.
'currency_iso_code'str
The currency for the transaction. The three-letter alphabetic codes for the transaction's currency (e.g. "USD" for US dollars).
'description'str
A description of the plan.
'discounts'

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

'add'array
Array of discounts to add to the plan.
'amount'Decimal
Price of the discount. This will override the inherited discount amount.
'description'str
A description of the discount.
'inherited_from_id'str
Specify a discount ID to apply to the plan. You can't duplicate an discount for a plan, but you can update the quantity.
'name'str
The name of the discount.
'number_of_billing_cycles'str
Number of billing cycles to apply the discount. It must be greater than 0.
'remove'array
Array of discount IDs that are associated with the subscription. IDs specified will be removed from the plan.
'update'array
Array of discounts that are associated with the plan.
'amount'Decimal
Price of the discount. This will override the inherited discount amount.
'description'str
A description of the discount.
'existing_id'str
Update a particular discount by specifying the discount ID.
'name'str
The name of the discount.
'number_of_billing_cycles'str
Number of billing cycles to apply the discount. It must be greater than 0.
'id'str
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_tokens'str
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.
'name'str
The name of the plan.
'never_expires'boolean 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_cycles'integer or string
Specifies the number of billing cycles of the plan.
'price'decimal or string
The base price specified for a plan, formatted like "10" or "10.00".
'trial_duration'int

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_unit'str
The trial unit specified in a plan. Specify day or month.
'trial_period'bool

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. Python
result = gateway.plan.create({
  "name": "the_name",
  "billing_frequency": "the_billing_frequency",
  "currency_iso_code": "the_currency_iso_code",
  "price": "the_price",
  "modification_tokens": ["modification1_token", "modification2_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. Python
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": Decimal("20.00")
            },
            {
                "inherited_from_id": "add_on_id_2",
                "amount": Decimal("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": Decimal("7.00")
            }
        ],
        "update": [
            {
                "existing_id": "discount_id_2",
                "amount": Decimal("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. Python
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": Decimal("20.00"),
          "number_of_billing_cycles": 2,
          "name": "NewName",
          "description": "NewDescription"
        }
      ],
      "update": [
        {
          "existing_id": "add_on_id_2",
          "amount": Decimal("15.00"),
          "number_of_billing_cycles": 2,
          "name": "NewName",
          "description": "NewDescription"
        }
      ]
    },
    "discounts": {
      "add": [
        {
          "inherited_from_id": "discount_id_1",
          "amount": Decimal("20.00"),
          "number_of_billing_cycles": 2,
          "name": "NewName",
          "description": "NewDescription"
        }
      ],
      "update": [
        {
          "existing_id": "discount_id_2",
          "amount": Decimal("15.00"),
          "never_expires": True,
          "quantity": 3
          "number_of_billing_cycles": 2,
          "name": "NewName",
          "description": "NewDescription"
        }
      ]
    }
})

See also