Basket Item Limits by Shop Category

Introduction

A shop category can cap how many items a customer may hold in their basket from that category. When a limit is configured, the basket validates every write against it. The HTTP status code signals the outcome: 206 Partial Content when the requested quantity was capped, 413 Request Entity Too Large when the category is blocked entirely.

This page describes that API behavior. The limit itself is not a Storefront API concept: it is configured as customData on the shop category in the SCAYLE Panel. For the configuration, the country- and shop-level precedence rules, the inheritance across the category tree, and the tenant setting this feature requires, see Shop Categories #Basket Item Limits by Shop Category.

When Validation Runs

The basket validates against the relevant category limits on these actions:

• adding a new item to the basket.
• increasing the quantity of an existing item.
• an unavailable item becoming available again, for example after a restock.

The basket calculates the remaining allowance for a category as the configured limit minus the sum of available items already in the basket from that category and its descendants.

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.

Reducing an existing item's quantity always succeeds, regardless of category limits.

Response Behavior

When a category limit is in effect, a basket write resolves to one of these outcomes:

206 is also returned when the remaining allowance is 0 but the category limit itself is greater than 0. Nothing is added, and the response body reflects the unchanged basket.

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.

Affected Endpoints

Both endpoints can return these responses:

• POST /v1/baskets/{basketId}/items: add basket item.
• PATCH /v1/baskets/{basketId}/items/{itemKey}: update basket item.

Frontend Implementation

Treat 206 as a success that needs reconciliation, not as an error. The call went through, so read the returned basket and render the applied quantities instead of the requested ones. Tell the customer their quantity was capped.

Treat 413 as a rejection: the basket is unchanged. The response does not indicate whether a blocked category or the per-item maximum quantity caused it, so show a generic message and do not retry automatically.