This section will guide you through some common subscription management scenarios.
- Subscription ID
- Payment method
- Add-on and discount details
- Number of billing cycles
- Merchant account
$result = $gateway->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 can't be found, you'll receive a
If you update a subscription's plan, the subscription will not inherit the new plan's price. Additionally, you can only update to a plan with the same billing cycle (e.g. you can't update from a yearly plan to a monthly plan and vice versa).
You can update the payment method associated with a Pending, Active, or Past Due subscription using either of the following:
*If you delete a payment method using its payment method token, all associated subscriptions will be canceled immediately and the customer will forfeit any remaining days they've already paid for.
When you update a Past Due subscription's payment method and you have proration enabled, the subscription will be automatically retried.
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
$result = $gateway->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'] ] ]);
You can use proration to charge or credit a customer if a change is made to the subscription price in the middle of a billing cycle. Enabling proration adjusts the price based on how many days are left in the billing cycle, and charges the customer the newly-calculated rate immediately. Without proration enabled, any changes made to a customer’s subscription mid-cycle will go into effect at the beginning of the next cycle.
By default, if the transaction for the prorated amount fails, the update to the subscription no longer goes through. 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 can set this preference in the Control Panel or pass the option
Add-ons and discounts will only be prorated when you pass the option
true. If existing add-ons or discounts were not originally passed with this option set to
true, they will not be prorated.
For example, if a request is sent to update an add-on's
prorateCharges set to
true, and the original add-ons did not also pass this option as
true, the subscriber will only be charged a prorated amount for the additional 2 add-ons.
merchantAccountId determines currency, updating the merchant account used to process transactions for a subscription may change which currency the subscription is processed in.
A subscription's balance represents the amount of outstanding charges associated with that subscription. If a customer’s payment method fails or is declined, their subscription status will change to Past Due, and the subscription's balance is incremented by the amount of the transaction that failed. This amount includes the subscription base price as well as any associated add-ons and/or discounts.
If the subscription has add-ons and discounts with a specified number of billing cycles, the number of billing cycles are also reflected in the subscription's balance. For example, let's say that a subscription was created with these settings:
Subscription price: $12 for 12 billing cycles
Add-on price: $10 for 2 billing cycles
The subscription and the first add-on were charged successfully when it was created, but it is now 2 billing cycles past due. The balance is $34.
2 failed billing cycles, $12 each = $24
1 failed billing cycle for the add-on charge for $10
Total balance = $34
Since the add-on was designated to apply for 2 billing cycles and we already had one successful billing cycle, it will only count one billing cycle for the add-on in the balance. This same logic also applies to discounts.
The balance on Past Due subscriptions will continue to increase every billing cycle—either indefinitely or until the number of cycles in the subscription is reached.
When updating a subscription that is Past Due, you can only update fields that do not change the price:
- Subscription ID
- Payment method
- Merchant account
We will automatically attempt to charge past due subscriptions at the beginning of each new billing cycle. You can also customize our retry logic in the Control Panel if you would like to charge past due subscriptions in-between billing cycles. Depending on the processor response code, some declines are not retried because they suggest that it's unlikely the transaction will ever be successful.
A subscription's balance will only be adjusted by our retry logic at the beginning of a new billing cycle. In other words, if the automatic retry attempts during one billing cycle are not successful, the subscription's balance will increase in the next billing cycle to incorporate the missed payment.
You can also retry transactions manually, either on a one-off basis or as a part of your own recurring logic.
A negative balance indicates that credit is owed to the customer on that subscription. A subscription's balance can go into the negative if you have configured your processing options to allow proration on downgrades. If a subscription has a negative balance that is enough to cover the charge, the subscription will bill successfully without actually charging the payment method.
By default, we will use the subscription balance when retrying the transaction. If you would like to use a different amount you can optionally specify the amount for the transaction.
A successful manual retry of a past due subscription will always reduce the balance of that subscription to $0, regardless of the amount of the retry.
When retrying a declined transaction via the API, pass
true in the argument to automatically submit the transaction for settlement if the retry request is successful:
$retryResult = $gateway->subscription()->retryCharge( $subscription->id, "24.00", true )
When the transaction is authorized, the subscription status will return to Active unless the number of billing cycles in the subscription has been reached. If the subscription has no further billing cycles, it will become Expired.
Refunds for subscriptions work the same as refunds for individual transactions. You can only issue a refund against an existing sale transaction, and that transaction must have a status of settled or settling.
However, if you do not want to refund the full amount of an existing sale transaction, you can specify the amount of the refund. For example, if your customer has an annual subscription and you wish to refund them for 6 months, you would issue a refund against the original transaction for half the sale amount.
To issue a refund via the API, use
Transaction::refund(). You can also issue a refund within the Control Panel. If you do not want to continue charging the customer for their subscription in the future, be sure to cancel the subscription as well.
- Canceling subscriptions
- Searching for subscriptions
- Advanced recurring billing settings
- Subscription validations
- Subscription object
Still have questions?
If you can’t find an answer, contact us