See also the Braintree_Subscription response object.

PHP
$result = Braintree_Subscription::update('a_subscription_id', [
    'id' => 'new_id',
    'paymentMethodToken' => 'new_payment_method_token',
    'price' => '12.34',
    'planId' => 'new_plan',
    'merchantAccountId' => 'another_merchant_account'
]);

If the subscription cannot be found, you'll receive a Braintree_Exception_NotFound exception.

Arguments
id required, string

A string value representing a specific subscription in the Vault.

Additional Parameters
'addOns'

The collection of add-ons associated with a subscription. Add-on details can only be managed within the Control Panel.

'add' Array

Array of add-ons to add to the subscription

Each element contains:
'amount' String

Price of the add-on. This will override the inherited add-on amount.

'inheritedFromId' required, string

Specify an add-on ID to apply to the subscription. You cannot duplicate an add-on for a subscription, but you can update the quantity.

'neverExpires' bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.

'numberOfBillingCycles' string

Number of billing cycles to apply the add-on. Must be greater than 0.

'quantity' int

How many of this add-on to apply to the subscription. The default is 1.

'remove' Array

Array of add-on IDs that are associated with the subscription. IDs specified will be removed from the subscription.

'update' Array

Array of add-ons that are associated with the subscription.

Each element contains:
'amount' String

Price of the add-on. This will override the existing add-on amount.

'existingId' required, string

Update a particular add-on by specifying the add-on ID.

'neverExpires' bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.

'numberOfBillingCycles' string

Number of billing cycles to apply the add-on. Must be greater than 0.

'quantity' int

How many of this add-on to apply to the subscription. This will override the existing add-on quantity.

'descriptor'

Dynamic descriptors are not enabled on all accounts by default. If you receive a validation error of 92203 or if your dynamic descriptors are not displaying as expected, please contact our Support team.

Dynamic descriptors are sent on a per-transaction basis and define what will appear on your customers' credit card statements for a specific purchase. The clearer the description of your product, the less likely customers will issue chargebacks due to confusion or non-recognition.

See the dynamic descriptor example for additional information.

'name' string

The value in the business name field of a customer's statement. Company name/DBA section must be either 3, 7 or 12 characters and the product descriptor can be up to 18, 14, or 9 characters respectively (with an * in between for a total descriptor name of 22 characters).

'phone' string

The value in the phone number field of a customer's statement. Phone must be 10-14 characters and can only contain numbers, dashes, parentheses and periods.

'url' string

The value in the URL/web address field of a customer's statement. The URL must be 13 characters or shorter.

'discounts'

A collection of discounts associated with this subscription. Discount details can only be managed within the Control Panel.

'add' Array

Array of discounts to add to the subscription.

Each element contains:
'amount' String

Amount of the discount. This will override the inherited discount amount.

'inheritedFromId' required, string

Specify a discount ID to apply to the subscription. You cannot duplicate a discount for a subscription, but you can update the quantity.

'neverExpires' bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.

'numberOfBillingCycles' string

Number of billing cycles to apply the discount. Must be greater than 0.

'quantity' int

How many of this discount to apply to the subscription. The default is 1.

'remove' Array

Array of discount IDs that are associated with the subscription. IDs specified will be removed from the subscription.

'update' Array

Array of discounts that are associated with the subscription.

Each element contains:
'amount' String

Price of the discount. This will override the existing discount amount.

'existingId' required, string

Update a particular discount by specifying the discount ID.

'neverExpires' bool

Set a subscription's billing cycle to never expire instead of specifying a number of billing cycles.

'numberOfBillingCycles' string

Number of billing cycles to apply the discount. Must be greater than 0.

'quantity' int

How many of this discount to apply to the subscription. This will override the existing discount quantity.

'id' string

If this option is provided, the subscription's current ID will be replaced with the value specified. Max 36 characters; must be unique within a merchant's Vault; valid characters are letters, numbers, - and _.

'merchantAccountId' string

The merchant account ID used to create the subscription's transactions. Currency is also determined by merchant account ID and it must match the Plan's currency. See the Transaction merchantAccountId parameter for more information.

'neverExpires' bool

Whether a subscription's billing cycle is set to never expire instead of running for a specific number of billing cycles. If this is set to true, numberOfBillingCycles will be set to null as a subscription cannot have a limited number of billing cycles and never expire. If set to false, numberOfBillingCycles cannot be null.

'numberOfBillingCycles' int

The number of billing cycles of the subscription. If this is set to a non-null value, neverExpires will be set to false as a subscription cannot both have a limited number of billing cycles and never expire. This value must be greater than or equal to the value of currentBillingCycle.

'options'

Optional values that can be passed with a request.

'prorateCharges' bool

A flag that specifies whether the change in subscription price should be prorated.

'replaceAllAddOnsAndDiscounts' bool

When true, the plan's add-ons and discounts are replaced by those specified.

'revertSubscriptionOnProrationFailure' bool

By default, if the transaction for the prorated amount fails, the subscription is reverted. If you would like to continue with the update to the subscription and add the prorated amount to the balance even though the transaction failed, you should set this field to false.

'paymentMethodNonce' string

One-time-use token that references a payment method provided by your customer, such as a credit card or PayPal account.

The nonce serves as proof that the user has authorized payment (e.g. credit card number or PayPal details). This should be sent to your server and used with any of Braintree's server-side client libraries that accept new or saved payment details. This can be passed instead of a payment_method_token. When used to create subscriptions, the payment_method_nonce must be Vaulted and must belong to the customer owning the subscription.

'paymentMethodToken' string

An alphanumeric value that references a specific payment method stored in your Vault. If provided, this will change the payment method associated with the subscription.

'planId' string

Plans must be created in the Control Panel. Updating a plan only changes the association; we do not automatically change the price of the subscription. You can only update to a plan with the same billing cycle; at this time we do not allow you to update from a yearly plan to a monthly plan and vice versa. You cannot edit the plan on a Past Due, Expired, or Canceled subscription.

'price' String

The price specified for a subscription. Billing price must be formatted like 10 or 10.00. If you provide a price, it can't be an empty string. You must update the price in this parameter; updating the $planId will not automatically change the price of a subscription. You cannot update the price of a Past Due, Expired, or Canceled subscription. Price cannot be greater than the maximum allowed by the processor. Contact our Support team for your specific limit.

important

Merchants operating in the European Union must give customers 7 business days’ notice before changing the price of their recurring billing plan; 7 business days’ notice is also required before billing customers if it has been 6+ months since their last payment. If you don’t operate in the EU, these notices aren't required (but they're still good practice).

Examples

Add-ons and discounts

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.

When updating a subscription, you can modify the add-ons and discounts in 3 ways:

  • New add-ons/discounts can be added
  • Existing add-ons/discounts associated with the subscription can be updated
  • Existing add-ons/discounts associated with the subscription can be removed
PHP
$result = Braintree_Subscription::update('theSubscriptionId', [
    'addOns' => [
        'add' => [
            [
                'inheritedFromId' => 'addOnId1',
                'amount' => '25.00'
            ]
        ],
        'update' => [
            [
                'existingId' => 'addOnId2',
                'amount' => '50.00'
            ]
        ],
        'remove' => ['addOnId3']
    ],
    'discounts' => [
        'add' => [
            [
                'inheritedFromId' => 'discountId1',
                'amount' => '7.00'
            ]
        ],
        'update' => [
            [
                'existingId' => 'discountId2',
                'amount' => '15.00'
            ]
        ],
        'remove' => ['discountId3']
    ]
]);

Multiple updates

You can also add, update and remove multiple add-ons/discounts at the same time.

PHP
$result = Braintree_Subscription::update("the_subscription_id", [
    'addOns' => [
        'add' => [
            [
                'inheritedFromId' => 'addOnId1',
                'amount' => '20.00'
            ],
            [
                'inheritedFromId' => 'addOnId2',
                'amount' => '30.00'
            ]
        ],
        'update' => [
            [
                'existingId' => 'addOnId3',
                'quantity' => 2
            ],
            [
                'existingId' => 'addOnId4',
                'quantity' => 3
            ]
        ],
        'remove' => ['addOnId5', 'addOnId6']
    ]
]);

Override details

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

  • amount
  • numberOfBillingCyclesOrNeverExpires
  • quantity
PHP
$result = Braintree_Subscription::update('theSubscriptionId', [
    'addOns' => [
        'add' => [
            [
                'inheritedFromId' => 'addOnId1',
                'amount' => '25.00',
                'numberOfBillingCycles' => 2,
                'quantity' => 4
            ]
        ],
        'update' => [
            [
                'existingId' => 'addOnId2',
                'amount' => '25.00',
                'numberOfBillingCycles' => 2,
                'quantity' => 4
            ]
        ]
    ]
]);

Remove add-ons and discounts

If you prefer to update a subscription and remove all existing add-ons and discounts, you can pass the replaceAllAddOnsAndDiscounts option.

PHP
$result = Braintree_Subscription::update('theSubscriptionId', [
    'options' => [
        'replaceAllAddOnsAndDiscounts' => true
    ]
]);

See also

Still have questions?

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