As per the documentation swap() method swap the current subscription with the new one on the next billing date, means after end of current plan. And swapAndInvoice() will take immediate effect without waiting for the current plan to end.
But the swap() method is not working as described. It is taking immediate effect.
$subscription_result = $user->subscription('primary')->swap('new_price_id');
This is what I am using to swap subscription.
example
,
Plan A :- 3 days ($3)
Plan B :- 7 days ($7)
User subscribed to Plan A on 25th March, next billing cycle is on 28th March.
User changed subscription to Plan B on 25th March, it should take effect on 28th (using swap() method). But it is taking effect immediately and showing next billing cycle is on 1st April.
I have tried using swapAndInvoice() instead of swap(), but both the methods are giving same output, no difference.
The reason for this behavior is not related to the swap() method specifically, but instead to how Subscription upgrades and downgrades behave. When you update a subscription to a price with a different interval than the previous price (like with your example a 3 day interval vs. 7 day interval), then the billing_cycle_anchor will be reset immediately and a new invoice will be generated. The swapAndInvoice() method will cut a new invoice at the time of the Subscription update regardless of whether the intervals of the price update stay the same. Whereas just using swap() in the case where the interval of the two prices are the same would result in an invoice not being created until the next natural billing cycle.
The Stripe API way to accomplish your use-case here would be to utilize Subscription Schedules. However, Cashier may not support this feature directly.