Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add ability to update Subscription Items with different proration modes for addition and removal. #246

Conversation

HelgeSverre
Copy link
Contributor

@HelgeSverre HelgeSverre commented Feb 16, 2024

Summary

This PR introduces a new method updateItemsWithDifferentProration to the Subscription model.

It allows the consumer of the package to specify the proration mode to be used for adding new items or incrementing the
quantity of existing items already on the subscription, with a separate proration mode than removing items or
decrementing the quantity of existing items.

Why

In non-trivial subscription scenarios, it is sometimes desirable to apply different proration behaviors for addition and
removal of a item on a subscription,

A Specific example of this is the following scenario:

  • A customer has a subscription with a monthly billing cycle.
  • The customer has a subscription with 3 items with a quantity of 1 each.
    • Item 1 - SaaS license - Light Version
    • Item 2 - Add-on - Extra Storage (+1gb)
    • Item 3 - Add-on - Ability to use the API
  • The customer wants to add additional storage to their subscription. (increment the quantity of the existing item)
  • The customer no longer needs the API access and wants to remove it from their subscription. (remove the existing item)
  • The billing date is the 1. of each month, the customer performs the actions on the 15th of the month. (aka half month
    has passed)

In this scenario, the following is expected:

  • Item 1 - no change is done to the SaaS license.
  • Item 2 - Customer is charged for rest of the month, (aka prorated_immediately on addition of item)
  • Item 3 - Customer is not refunded for half the month, but rather keeps the API Access until it lapses at the end of
    the month. (aka full_next_billing_period on removal of item)

Usage

$subscription->updateItemsWithDifferentProration(
    items: [
        ['price_id' => '123', 'quantity' => 2],
        ['price_id' => '456', 'quantity' => 1],
    ],
    additionProrationBehaviour: 'prorated_immediately',
    removalProrationBehaviour: 'full_next_billing_period'
);

Etc

The logic could probably be simplified a bit, but i have provided tests for various scenarios so we can refactor it if needed.

Fully understand if this use-case is too niche to put in "core", but it's fairly common practice for B2B SaaS, and is a PITA to implement with Paddle.

(Package does not have pint, so my editor messed with the formatting, assuming this will be auto-fixed by GitHub actions)

Copy link

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

@HelgeSverre HelgeSverre marked this pull request as ready for review February 16, 2024 14:30
@HelgeSverre HelgeSverre changed the title Add ability to update Subscription Items with different proration for addition and removal. Add ability to update Subscription Items with different proration modes for addition and removal. Feb 16, 2024
@taylorotwell
Copy link
Member

Too many other formatting changes here.

@HelgeSverre
Copy link
Contributor Author

Shall reformat and resubmit later, is this repo using the default pint with Laravel preset?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants