Creating Subscriptions

Minimal Example

To create a subscription, you only need a payment method token from a created credit card and a plan id from a plan created via the control panel. The subscription will then be created using the price, trial duration (if any), and billing cycle of the plan.

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan"
)

Overriding Plan Details

You can override the plan price, trial duration, start date, number of billing cycles per subscription, and add-on and discount details. You can also add additional add-ons and discounts that were not defaulted from the plan.

Price

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :price => "12.00"
)

Trial Period

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :trial_duration => 3,
  :trial_duration_unit => "month"
)

If you specify a trial_duration of 0, we will start the subscription immediately and not consider it in a trial period.

You can also disable the trial period if a subscription would normally have one using the given plan.

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :trial_period => false
)

Number of Billing Cycles

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :number_of_billing_cycles => 3
)

Start Date

You can override the start date from the plan in three different ways:

Set first_billing_date to a specific date.
Set billing_day_of_month.
Set the option start_immediately, which overrides any plan start date and starts the subscription immediately.

Examples of billing_day_of_month:

If today is May 3, and the billing_day_of_month is 10, the first bill date will be May 10.
If today is May 3, and the billing_day_of_month is 1, the first bill date will be June 1.
If today is May 3, and the billing_day_of_month is 3, the subscription will be charged immediately (as if start_immediately was true).
If you want the billing to occur on the last day of the month, regardless of the length of the month, set billing_day_of_month to 31.

Passing in any of these options overrides the trial period from the plan (if one exists).

If the start date is in the future, the new subscription will be in Pending status.

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :first_billing_date => Date.today + 3
)
result.subscription.status
#=> "Pending"

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :billing_day_of_month => 15
)
result.subscription.status
#=> "Pending"

result.subscription.billing_day_of_month
#=> 15

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :options => {
    :start_immediately => true
  }
)
result.subscription.status
#=> "Active"

Note: Passing in more than one of these fields will result in a validation error.

Subscription ID

You can set the subscription ID, or if you leave it blank the gateway will generate one for you.

result = Braintree::Subscription.create(
  :id => "subscription_1234",
  :payment_method_token => "rw54",
  :plan_id => "gold_plan"
)

Start Immediately

If a subscription does not have a trial period and will start immediately, we’ll charge the customer right away. If the transaction is declined, the subscription will not be created. You can get transaction details from the result object.

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :price => "2000.00",
  :trial_period => false
)

result.transaction.status
#=> "processor_declined"

If the transaction is authorized, you can get both the subscription and transaction information from the result object.

result = Braintree::Subscription.create(
  :payment_method_token => "mxt2",
  :plan_id => "silver_plan"
)

if result.success?
  puts result.subscription.id
  puts result.subscription.transactions[0].id
end

Specifying Merchant Account

If you have multiple merchant accounts, you can pass the merchant account ID to specify which merchant account to use to process transactions for the subscription. If a merchant account ID is not passed, we’ll use your default merchant account. Just like when specifying merchant account for transactions, the merchant account will determine the currency for the subscription.

result = Braintree::Subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan",
  :merchant_account_id => "gbp_account"
)

Add-ons/Discounts

By default, a subscription will inherit the add-ons and discounts from its plan. When creating the subscription, you can modify the default behavior in 3 ways:

New add-ons/discounts can be added to the subscription.
Add-ons/discounts that would be inherited from the plan can be updated on the subscription.
Add-ons/discounts that would be inherited from the plan can be removed from the subscription.

result = Braintree::Subscription.create(
  :payment_method_token => "the_payment_method_token",
  :plan_id => "the_plan_id",
  :add_ons => {
    :add => [
      {
        :inherited_from_id => "add_on_id_1",
        :amount => BigDecimal.new("20.00")
      }
    ],
    :update => [
      {
        :existing_id => "add_on_id_2",
        :quantity => 2
      }
    ],
    :remove => ["add_on_id_3"]
  },
  :discounts => {
    :add => [
      {
        :inherited_from_id => "discount_id_1",
        :amount => BigDecimal.new("15.00")
      }
    ],
    :update => [
      {
        :existing_id => "discount_id_2",
        :quantity => 3
      }
    ],
    :remove => ["discount_id_3"]
  }
)

When creating a subscription you can add, update and remove multiple add-ons/discounts at the same time.

result = Braintree::Subscription.create(
  :payment_method_token => "the_payment_method_token",
  :plan_id => "the_plan_id",
  :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",
        :quantity => 2
      },
      {
        :existing_id => "add_on_id_4",
        :quantity => 3
      }
    ],
    :remove => ["add_on_id_5", "add_on_id_6"]
  }
)

When adding add-ons/discounts to a subscription, 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 or never_expires
quantity

result = Braintree::Subscription.create(
  :payment_method_token => "the_payment_method_token",
  :plan_id => "the_plan_id",
  :add_ons => {
    :add => [
      {
        :inherited_from_id => "add_on_id_1",
        :amount => BigDecimal.new("20.00"),
        :number_of_billing_cycles => 2,
        :quantity => 4
      }
    ],
    :update => [
      {
        :existing_id => "add_on_id_2",
        :amount => BigDecimal.new("15.00"),
        :never_expires => true,
        :quantity => 3
      }
    ]
  }
)

If you prefer to create a subscription without inheriting any add-ons/discounts from the plan, you can pass the do_not_inherit_add_ons_or_discounts option.

result = Braintree::Subscription.create(
  :payment_method_token => "the_payment_method_token",
  :plan_id => "the_plan_id",
  :options => {
    :do_not_inherit_add_ons_or_discounts => true
  }
)

You can only add an add-on or discount to a subscription once. If you’d like to apply an add-on or discount to a subscription several times, you can pass quantity when creating or updating the add-on/discount.