Recurring Billing

Plans

Before creating subscriptions, you must create a plan. You can also retrieve existing plans via the API. A plan is a template for your subscriptions: when you create a plan, it will be used to populate the following attributes when a new subscription is created:

plan name
description
trial period
billing day of month
number of billing cycles
amount
currency
billing cycle

Ruby

result = gateway.plan.create(
  :name => "the_name",
  :billing_frequency => "the_billing_frequency",
  :currency_iso_code => "the_currency_iso_code",
  :price => "the_price"
)

You will need to specify the plan_id when creating a subscription.

Important

Merchants operating in the European Union must give customers 4 weeks' notice before changing the price of their recurring billing plan; 4 weeks' notice is also required before billing customers if it has been 6+ months since their last payment. If you don't operate in the EU, these notices aren't required (but they're still good practice).

Add-ons and discounts

Add-ons and discounts are created in the Control Panel. You can't create or update them through the API.

Add-ons and discounts can be applied manually on a case-by-case basis, or you can associate them with certain plans to apply them automatically to new subscriptions. When creating a subscription, it will automatically inherit any add-ons and/or discounts associated with the plan. You can override those details at the time you create or update the subscription.

When creating an add-on or discount you can specify:

id
name
description
amount
number_of_billing_cycles

If an add-on or discount is active on an existing subscription, it will appear in the add_ons or

discounts array in the subscription response object.

Recurring Billing

Plans

Add-ons and discounts

See also