Quantity Restrictions

Quantity restrictions let you control the quantities customers can choose for your plans and addons in checkout. You define the restriction in the JSON metadata of an item price, as either a fixed set of values or a range. You can enable or disable product-level quantity restrictions across all products through a single setting.

To learn how metadata works in Chargebee, see Metadata.

Prerequisites

The following settings must be enabled to apply product-level quantity restrictions.

Go to Settings > Configure Chargebee > Checkout & Self-Serve Portal > Configuration > Checkout and enable:

• Allow customers to edit quantity for plans.
• Allow customers to change addon and charge quantity.

Enable quantity restrictions

When you enable quantity restrictions, Chargebee reads the quantity configuration in the item price metadata and sets the quantity based on it.

Go to Settings > Configure Chargebee > Checkout & Self-Serve Portal > Advanced settings and enable Customize plan/addon quantity based on meta configuration.

Set up metadata for your item price

After you enable Customize plan/addon quantity based on meta configuration, follow these steps:

1. Go to Product Catalog > Plans.
2. Under the Pricing list, select the corresponding item price. Chargebee reads the JSON metadata set at the item price level, not at the item level.
3. Click Add for JSON metadata.
4. On the Add JSON Metadata page, add the necessary code to restrict the quantity.
5. Click Add.

Configure the checkout to allow only specific quantities

To configure the checkout to allow only specific quantities, enter the values you want to allow in the checkout and set the type as fixed.

Sample JSON:

{ 
  "quantity_meta": {
    "type": "fixed",
    "values": [5, 6, 7, 8, 9, 10]
  }
}

Sample checkout screen:

Configure limited quantity range in checkout

To allow a quantity limited to a specific range in your checkout, provide the min (minimum), max (maximum), and step values along with the type as range.

Sample JSON:

{
  "quantity_meta": {
    "type": "range",
    "min": 10,
    "max": 100,
    "step": 10
  }
}

Each time your customer increases the quantity, it increments by the step value configured in the JSON.

Enter a valid quantity meta and click Add to save the metadata.

Edit the metadata

To edit the metadata:

1. Go to Product Catalog > Plans.
2. Select the plan, then the item price, and click the ellipsis menu.
3. Select Edit and make the necessary changes.
4. Click Update.

After you add the quantity restrictions, open the checkout for the corresponding item price to test your changes.

Changes in checkout based on quantity meta

The following metadata types are supported for quantity restrictions:

• Fixed
• Range

Checkout changes based on the metadata type in the JSON for an item price.

Changes in checkout when quantity meta is of type fixed

When the quantity meta is of type fixed, the checkout process undergoes the following changes:

• Quantity restriction: Restrict quantities to a set of numbers listed in the checkout for selection.
• Dropdown display: The dropdown lists the valid quantity values configured in the JSON metadata within the product card's specific plan, addon, or charge section.
• Invalid quantity handling: If you create a hosted page with a quantity not present in the values array, the quantity resets to the lowest value in the array (not necessarily the first value).
• Configuration setting: These quantity checks run only when the Customize plan/addon quantity based on meta configuration setting is enabled.

Changes in checkout when quantity meta is of type range

When the quantity meta is of type range, the checkout process is adjusted as follows:

• Quantity restriction: Set the quantity directly from the checkout page to restrict quantities to a range of numbers.
• Stepper display: The quantity is displayed with a stepper, allowing customers to increment or decrement the quantity as needed.
• Invalid quantity handling: If an invalid quantity is passed through the API or a plan URL, the value resets to the minimum configured value within the defined range.
• Step increment: Each time a customer increments or decrements the quantity with the stepper, it changes by the step value you set.
• Custom error display: If a customer enters an invalid value in the quantity text box, an error message guides them. You can customize the message. To add a custom error, see working with labels.

Sample error screens: