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(array(
  'paymentMethodToken' => 'a_token',
  'planId' => '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(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan',
  'price' => '12.34'
));

Trial Period

$result = Braintree_Subscription::create(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan',
  'trialDuration' => 5,
  'trialDurationUnit' => 'month'
));

If you specify a trialDuration 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(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan',
  'trialPeriod' => false
));

Number of Billing Cycles

$result = Braintree_Subscription::create(array(
  'numberOfBillingCycles' => '10',
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan'
));

Start Date

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

Set firstBillingDate to a specific date.
Set billingDayOfMonth.
Set the option startImmediately, which overrides any plan start date and starts the subscription immediately.

Examples of billingDayOfMonth:

If today is May 3, and the billingDayOfMonth is 10, the first bill date will be May 10.
If today is May 3, and the billingDayOfMonth is 1, the first bill date will be June 1.
If today is May 3, and the billingDayOfMonth is 3, the subscription will be charged immediately (as if startImmediately was true).
If you want the billing to occur on the last day of the month, regardless of the length of the month, set billingDayOfMonth 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.

$tomorrow = new DateTime("now + 1 day");
$tomorrow->setTime(0,0,0);

$result = Braintree_Subscription::create(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan',
  'firstBillingDate' => $tomorrow
));

$result->subscription->firstBillingDate
# tomorrow

$result->subscription->status
# Braintree_Subscription::PENDING

$result = Braintree_Subscription::create(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan',
  'billingDayOfMonth' => 14
));

$result->subscription->billingDayOfMonth
# 14

$result = Braintree_Subscription::create(array(
    'paymentMethodToken' => 'the_token',
    'planId' => 'silver_plan',
    'options' => array('startImmediately' => true)
));

sizeof($result->subscription->transactions)
# 1

$result->subscription->status
# Braintree_Subscription::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(array(
    'paymentMethodToken' => 'the_token',
    'planId' => 'silver_plan',
    'id' => 'some_token'
));

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(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan',
  'price' => '2000',
  'trialPeriod' => false
));

$result->transaction->status
#=> Braintree_Transaction::PROCESSOR_DECLINED

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

$result = Braintree_Subscription::create(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan'
));

$subscription = $result->subscription;
$transaction = $subscription->transactions[0];
# Initial transaction on subscription

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(array(
  'paymentMethodToken' => 'the_token',
  'planId' => 'silver_plan',
  'merchantAccountId' => '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(array(
    'paymentMethodToken' => 'thePaymentMethodToken',
    'planId' => 'thePlanId',
    'addOns' => array(
        'add' => array(
            array(
                'inheritedFromId' => 'addOnId1',
                'amount' => '20.00'
            )
        ),
        'update' => array(
            array(
                'existingId' => 'addOnId2',
                'quantity' => 2
            )
        ),
        'remove' => array('addOnId3')
    ),
    'discounts' => array(
        'add' => array(
            array(
                'inheritedFromId' => 'discountId1',
                'amount' => '15.00'
            )
        ),
        'update' => array(
            array(
                'existingId' => 'discountId2',
                'quantity' => 3
            )
        ),
        'remove' => array('discountId3')
    )
));

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

$result = Braintree_Subscription::create(array(
    'paymentMethodToken' => 'thePaymentMethodToken',
    'planId' => 'thePlanId',
    'addOns' => array(
        'add' => array(
            array(
                'inheritedFromId' => 'addOnId1',
                'amount' => '20.00'
            ),
            array(
                'inheritedFromId' => 'addOnId2',
                'amount' => '30.00'
            )
        ),
        'update' => array(
            array(
                'existingId' => 'addOnId3',
                'quantity' => 2
            ),
            array(
                'existingId' => 'addOnId4',
                'quantity' => 3
            )
        ),
        'remove' => array('addOnId5', 'addOnId6')
    )
));

When adding add-ons/discounts to a subscription, all details will be inherited from the add-on/discount specified by the inheritedFromId. When updating add-ons/discounts, all details will be inherited from the add-on/discount specified by the existingId. You can override any of the following:

amount
numberOfBillingCycles or neverExpires
quantity

$result = Braintree_Subscription::create(array(
    'paymentMethodToken' => 'thePaymentMethodToken',
    'planId' => 'thePlanId',
    'addOns' => array(
        'add' => array(
            array(
                'inheritedFromId' => 'addOnId1',
                'amount' => '20.00',
                'numberOfBillingCycles' => 2,
                'quantity' => 4
            )
        ),
        'update' => array(
            array(
                'existingId' => 'addOnId2',
                'amount' => '15.00',
                'neverExpires' => 2,
                'quantity' => 3
            )
        )
    )
));

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

$result = Braintree_Subscription::create(array(
    'paymentMethodToken' => 'thePaymentMethodToken',
    'planId' => 'thePlanId',
    'options' => array(
        'doNotInheritAddOnsOrDiscounts' => 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.