To create a subscription, you only need a stored payment_method_token and a plan_id, which must be created via the Control Panel. The subscription will be created using the price, trial duration (if any), billing details, and any add-ons or discounts specified within the plan's details.

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

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"

Overriding plan details

Certain plan attributes can be overridden when you pass the details you want to change along with the payment_method_token and plan_id.

You can override the following plan details:

Transaction flow

If a subscription does not have a trial period and is set to start immediately, we'll charge the customer and the transaction will be submitted for settlement right away.

If the initial transaction fails, the subscription will not be created. If the initial transaction succeeds, the subscription will be Active and you'll be able to see the subscription details in the result object. Regardless of whether the transaction is successful, you'll be able to see the transaction information in the result object.

If the first billing date of the subscription is in the future, the subscription status will be Pending until that date is reached. If you specify a trial period, the subscription will be Active and we'll attempt to bill the subscription at the end of the trial period. Before setting up trial periods, be sure to read the risks and requirements in the Trial Periods support article.

Subscriptions that are either Pending or Active and fail to bill successfully will be Past Due.

Subscription days

Each subscription day runs from midnight to midnight in the time zone associated with your gateway account, regardless of the time of day the subscription was created. For example, a subscription created at 11pm in your Control Panel time zone will be in its second day at midnight.

Email notifications

The gateway can send emails to customers based on recurring billing events. You'll need to set up your DNS record to allow the gateway to send email from your domain, and then contact our Support team to enable this feature.

Next: Managing Subscriptions →

Still have questions?

If you can’t find an answer, contact our Support team.