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.

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

Ruby
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

The transaction flow depends on when the subscription is set to start and whether it includes a trial period.

If there is no trial period and the subscription is set to bill immediately:

If there is no trial period and the subscription is set to bill in the future:

  • The subscription will be created immediately, but its status will be Pending until the first billing date is reached
  • On the first billing date, we'll attempt to charge the customer and submit the transaction for settlement
  • If that transaction attempt is successful, the subscription status will change to Active
  • If that transaction attempt fails, the subscription status will change to Past Due

If the subscription has a trial period:

  • The subscription will be created and its status will be Active immediately
  • We'll attempt to charge the customer at the end of the trial period
  • If that transaction attempt is successful, the subscription status will remain Active
  • If that transaction attempt fails, the subscription status will change to Past Due
note

Before setting up trial periods, be sure to read the risks and requirements in the Trial Periods support article.

Check out this diagram to see all of the possible transaction flows for subscriptions.

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.