Basket Item Limits by Shop Category

Introduction

SCAYLE allows you to cap how many items a customer can add to their basket from a specific shop category. This is useful when you want to discourage excessive returns from high-volume categories, protect stock on limited drops, or enforce fair distribution during high-demand sales.

You configure each limit per shop category through customData. The basket validates against the limit in real time whenever a customer adds, updates, or moves items, and reduces the requested quantity (or rejects the action) when the limit is reached.

Use Case

You can use category limits to:

• limit the number of items from a single category in a single basket (e.g. 3 pairs of glasses per order).
• prevent excessive returns by capping high-return categories.
• protect stock on limited-edition or collaboration drops by allowing only 1 item from a campaign category per order.
• safeguard "Buy 1 Get 1" or similar promotions from being abused.
• restrict bulk orders on low-stock essential items during high-demand periods.

Prerequisites

Before you set up category limits, you should be familiar with how categories work in SCAYLE. Please read the following chapters:

• Master Categories
• Shop Categories

You also need:

• the basket.categoryImport.enabled tenant configuration enabled. This setting is disabled by default. Please reach out to your SCAYLE Account Manager to enable it.

Configure a Category Limit

Category limits are stored as JSON in the customData field on a shop category.

1. In the SCAYLE Panel, navigate to Shops → [Shop] → Products → Categories.
2. Select the category you want to limit.
3. Open the Custom Data field on the category's general info tab.
4. Add a purchase_logic object with a max_quantity integer:
   json

   Copy
5. Click Save.

Country-Level vs Shop-Level Limits

You can set purchase_logic.max_quantity at country level (countryLevelCustomData) or at shop level (shopLevelCustomData).

• If both are set for the same category, the country-level value takes precedence.
• If only the shop-level value is set, the shop-level value is used.
• If neither is set, the category has no limit.

This lets you define a default limit at shop level and override it for specific countries where the rule should be stricter or looser.

Inheritance Across the Category Tree

A limit set on a parent category applies to the sum of items across all of its child categories. You only need to set the limit on the parent — it is automatically enforced across the entire descendant subtree.

For example, the Glasses parent category has a limit of 3, and a customer adds 2 pairs of Red Glasses and 2 pairs of Blue Glasses (both children of Glasses). The total of 4 exceeds the parent limit of 3, so the basket reduces the quantities until the total is 3 or lower.

If a child category also defines its own purchase_logic.max_quantity, both limits are enforced — the basket respects the child limit and the parent limit at the same time, applying whichever is reached first.

Basket Validation Behavior

Once a limit is configured and the cache has refreshed, the basket validates every change against the relevant category limits.

The validation runs on these actions:

• adding a new item to the basket.
• increasing the quantity of an existing item.
• bulk promotion updates and bulk quantity updates.
• moving an item from the unavailable list back to the available list.

The basket calculates the remaining allowance for each category as max_quantity minus the sum of available items already in the basket from that category (and its descendants).

The possible outcomes are:

• Within the allowance. The item is added or updated at the requested quantity. The basket returns 200 or 201.
• Partial — quantity reduced. The item is added or updated at the remaining allowance. The basket returns 206 Partial Content.
• Category fully blocked. When max_quantity is set to 0, the category is effectively blocked and no items from it can be added. The basket returns 413 Request Entity Too Large and the item is not added.
• Quantity reductions. Reducing an existing item's quantity always succeeds, regardless of category limits.

Only available items count toward the limit. Items on the unavailable list (for example, because they went out of stock) are excluded from the sum.

Examples

• The basket is empty. The category limit is 2. The customer tries to add 3 items → the basket adds 2 items and returns 206 Partial Content.
• The basket already contains 2 items from the category. The category limit is 2. The customer tries to add 1 more → no items are added (allowance is 0), but because the limit is greater than 0, the basket returns 206 Partial Content.
• The category limit is 0. The customer tries to add 1 item → no items are added and the basket returns 413 Request Entity Too Large.

Frontend Implementation

Your storefront should handle two new responses on basket write endpoints when a category limit is in effect:

• 206 Partial Content — the request was processed, but the resulting basket state differs from what was requested. This is returned whenever a category limit caps the quantity, including when the allowance is 0 but the category limit itself is greater than 0. Inspect the returned basket to see the applied quantity per item.
• 413 Request Entity Too Large — the request was rejected because the category's max_quantity is 0. No items from that category can be added to the basket. The item is not added.

Endpoints that can return 206 because of a category limit:

• POST /v1/baskets/{basket_key}/items — add basket item.
• PATCH /v1/baskets/{basket_key}/items/{item_key} — update basket item.
• bulk promotion update.
• bulk quantity update.

Inspect the returned basket to see the applied quantity per item.

Best Practices

• Set limits on the parent category where possible. This keeps the configuration in one place and lets the inheritance rules apply across all child categories.
• Use country-level overrides sparingly. Define your default at shop level and only override at country level when local rules require it. This makes the configuration easier to audit.
• Plan for the cache delay. New or updated limits are not picked up by active baskets immediately. Allow up to 15 minutes for the next category sync to complete before testing a new limit. Communicate this delay to merchandising teams who set up campaign limits close to launch time.