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.

Questions about Paddle?

If you need any help regarding your Paddle integration, please get in touch with our Customer Success team using the form below.