Subscription quantity

Using quantities with subscriptions

Our subscriptions support quantity, both for the initial purchase and recurring payments thereafter. This allows for an improved checkout experience for scenarios like per-seat billing and bulk discounts for bulk license purchases.

  • Quantity selection is visible on the top left corner of the checkout, unlike modifiers.

    Artboard 1 copy 2

  • You can increase/decrease the subscription quantity, using our subscription update API.
  • You can also prorate quantity, unlike modifiers.

How to enable subscription quantity for a plan

If you wish to make use of this feature you will have to tick the ”quantity” tick box when creating a new subscription using the dashboard. Screen Shot 2018-02-15 at 14.30.43

In order to allow users to change the quantity within Paddle’s checkout, you’ll need to set allowQuantity to true for paddle.js or quantity_variable to 1 if implementing the checkout with the custom checkout API

Screen Shot 2018-02-15 at 14.37.42 Screen Shot 2018-02-15 at 14.37.53

Example Flow

Paddle.js implementation

In the below example, we are allowing the user to select the quantity within Paddle’s checkout of a quantity enabled subscription, by setting allowQuantity to true.

<script type="text/javascript">
	jQuery('.js-buy').click(function() {
		Paddle.Checkout.open({
			product: 12345,
			auth:'a289...',
			passthrough: 1939284,
			email: 'example@paddle.com',
			allowQuantity:true,
		});
	});
</script>

<button class="js-buy">Upgrade to Pro</button> 

Amending Quantity & Reducing Recurring Price

After the initial purchase has taken place (example above), a customer may want to increase the quantity of their subscription. Below you can find a curl and JSON payload example of a request to update the quantity for the user subscription 12345 from 5 to 7 and recurring price to $11. This would be a common way to offer a user a discount, as they increase the number of seats (quantity) of their subscription.

You can set a different price for all future payments by setting the new recurring_price per unit. This can also be used to revert a discount when the user reduces the number of seats.

When calling https://vendors.paddle.com/api/2.0/subscription/users/update you will need to set the recurring_price per unit, quantity and currency.

If you don’t know the currency for the specific user’s subscription then this can be retrieved via https://vendors.paddle.com/api/2.0/subscription/users using the user’s subscription_id.



curl -X POST \
  -d 'vendor_id=123' \
  -d 'vendor_auth_code=456bd...' \
  -d 'subscription_id=12345' \
  -d 'quantity=7' \
  -d 'recurring_price=11.00' \
  -d 'currency=USD' \
https://vendors.paddle.com/api/2.0/subscription/users/update

{
   "quantity" : "7",
   "vendor_auth_code" : "456bd...",
   "vendor_id" : "123",
   "recurring_price" : 11,
   "currency" : "USD",
   "subscription_id" : "12345"
}

Example Response

{
    "success": true,
    "response": {
        "subscription_id": 12345,
        "user_id": 425123,
        "plan_id": 525123,
        "next_payment": {
            "amount": 144.06,
            "currency": "GBP",
            "date": "2018-02-15"
        }
    }
}

Implementation details

  • We hold the quantity numerically only, any association to users or accounts needs to be implemented on your end.
  • You can now enable quantity support when setting up your subscription plans, as mentioned above.
  • You cannot enable quantity on a non-quantity subscription plan with active users.
  • Users on non-quantity plans can move to quantity plans but not the inverse.
  • You will be able to pass quantity into the checkout for a subscription.
  • User’s subscriptions’ quantity can be amended via the API.
  • Subscription alert webhooks of quantity enabled plans will contain quantity.
  • bill_immediately defaults to true if moving to a subscription with a different interval, e.g. monthly -> yearly and will fail if set to false.
  • The existing /users/move endpoint is limited to upgrading/downgrading the plan.
  • The new /users/update can be used to upgrade/downgrade a user’s plan but also quantity and bulk discount.

Extra webhook fields

If your subscription plan has quantity enabled, the subscription_payment_succeeded, subscription_payment_failed, subscription_payment_refunded and subscription_updated webhook alerts you receive will include additional fields.