Recurring Billing


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


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 discountsanchor

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.

See also

Next Page: Creating Subscriptions