Subscription

Subscription: Create

Node.jsSDK

• Current Braintree SDKs
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

See also the Subscription response object.

A subscription can be created using either a payment method token or - under certain conditions – a payment method nonce.

The payment method must be vaulted before you can associate it with a subscription, so it's usually simplest to refer to the payment method using its paymentMethodToken. Here's an example:

gateway.subscription.create({
  paymentMethodToken: "the_token",
  planId: "the_plan_id"
}, (err, result) => {
});

However, payment method tokens do not carry any 3D Secure data. If you use 3D Secure and need to apply 3DS to the first transaction of a new subscription, you must create the subscription using a 3DS-enriched payment method nonce.

Parameters

Examples

Specify 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. If you would like to change which merchant account is default, contact us.

important

The specified merchant account must be in the same currency as the subscription plan, or any attempted subscription transactions will trigger a validation error. If you want to use a merchant account with a different currency, you must create a new plan with the indicated currency.

gateway.subscription.create({
  paymentMethodToken: "theToken",
  planId: "silverPlanGbp",
  merchantAccountId: "gbpAccount"
}, (err, result) => {
});

Create with 3D Secure enriched payment method nonce

If you use 3D Secure and need to apply 3DS to the first transaction of a new subscription, you must create the subscription using a 3DS-enriched nonce. See 3D Secure for Recurring Transactions for details on how to properly obtain and use a 3DS-enriched nonce for subscription transactions.

Once you've obtained a 3DS-enriched nonce, provide it on the subscription create call:

gateway.subscription.create({
  paymentMethodNonce: "nonce_from_the_client",
  planId: "the_plan_id"
}, (err, result) => {
});

Override plan details

When creating the subscription, you can modify the default behavior in three 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.

gateway.subscription.create({
  paymentMethodToken: "the_token",
  planId: "thePlanId",
  addOns: {
    add: [
      { inheritedFromId: "addOnId1", amount: "20.00" },
      { inheritedFromId: "addOnId2", amount: "30.00" }
    ],
    update: [
      { existingId: "addOnId3", quantity: 2 },
      { existingId: "addOnId4", quantity: 3 }
    ],
    remove: [ "addOnId5", "addOnId_6" ]
  },
  discounts: {
    add: [
      { inheritedFromId: "discountId1", amount: "7.00" }
    ],
    update: [
      { existingId: "discountId2", amount: "15.00" }
    ],
    remove: ["discountId3"]
  }
}, (err, result) => {
});

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

gateway.subscription.create({
  paymentMethodToken: "the_token",
  planId: "thePlanId",
  addOns: {
    add: [
      {
        inheritedFromId: "addOnId1",
        amount: "20.00",
        numberOfBillingCycles: 2,
        quantity: 4
      }
    ],
    update: [
      {
        existingId: "addOnId2",
        amount: "15.00",
        neverExpires: true,
        quantity: 3
      }
    ]
  },
  discounts: {
    add: [
      {
        inheritedFromId: "discountId1",
        amount: "20.00",
        numberOfBillingCycles: 2,
        quantity: 4
      }
    ],
    update: [
      {
        existingId: "discountId2",
        amount: "15.00",
        neverExpires: true,
        quantity: 3
      }
    ]
  }
}, (err, result) => {
});

note

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.

Override trial details

gateway.subscription.create({
  paymentMethodToken: "the_token",
  planId: "silverPlan",
  trialPeriod: true,
  trialDuration: 3,
  trialDurationUnit: "month"
}, (err, result) => {
});

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

• Valid values for trialDurationUnit are day and month.
• You can disable the trial period (if the plan has one) by passing trialPeriod as false.

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

important

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

gateway.subscription.create({
  paymentMethodToken: "the_token",
  planId: "silverPlan",
  billingDayOfMonth: 19
}, (err, result) => {
  result.subscription.billingDayOfMonth;
  // 19
});

gateway.subscription.create({
  paymentMethodToken: "the_token",
  planId: "silverPlan",
  options: {
    startImmediately: true
  }
}, (err, result) => {
  result.subscription.status;
  // "Active"

  result.subscription.transactions.length;
  // 1
});

Dynamic descriptors

subscription.create({
  paymentMethodToken: "the_token",
  planId: "planWithoutTrial",
  descriptor: {
    name: "company*my product",
    phone: "3125551212",
    url: "company.com"
  }
}, (err, result) => {
  result.subscription.descriptor.name;
  // "company#my product"

  result.subscription.descriptor.phone;
  // "3125551212"

  const transaction = result.subscription.transactions[0];
  transaction.descriptor.name;
  // "company*my production"

  transaction.descriptor.phone;
  // "3125551212"
});

See also

• Creating subscriptions