Guides
Start typing to search…

Quantities & Contraints

This page explains how minQuantity, maxQuantity, and recommendedQuantity work, how default quantities are chosen when a buyer starts a order from an Operation, and how validations are enforced.

Keep in mind

  • You configure quantity rules per Operation line (product variant).
  • Default quantity when starting from an Operation is recommended, else min, else 1.
  • Validations apply on every add/update: stock, pack multiples, min/max.
  • Lines are editable only in DRAFT on the admin side; buyers can edit their order within the constraints.

🔢 Field definitions

  • minQuantity (optional): the minimum quantity the buyer is required to purchase for that product variant in the context of this Operation. When set to 0, the line is optional and may be removed by the buyer.
  • maxQuantity (optional): the maximum quantity allowed for that product variant within the Operation context.
  • recommendedQuantity (optional): the suggested quantity to prefill when the buyer starts an order from the Operation; must be between Min and Max when they exist.

Rules

  • If Min and Max are both set, enforce Min ≤ Max.
  • Recommended must satisfy the bounds when they exist.
  • Quantity fields are per line and only editable while the Operation is DRAFT.

🧮 Default quantity selection (buyer start)

When a Customer User starts an order from an Operation, each visible line is initialized with a default quantity:

  1. recommendedQuantity, else
  2. minQuantity, else
  3. 1.
graph TD
    A[Start default<br>quantity] --> R[Recommended defined<br>and valid]
    R -- Yes --> Q1[Use recommendedQuantity]
    R -- No  --> M[Min defined<br>and > 0]
    M -- Yes --> Q2[Use minQuantity]
    M -- No  --> Q3[Use 1]

After initialization, the buyer can adjust quantities in his order within allowed bounds and pack multiples.

✅ Validation on add/update

Every time a line is added or updated to an order, the platform enforces all applicable checks:

graph TD
    X[Input quantity q] --> A[q >= Min<br>if Min set]
    A -- Yes --> B[If Max set,<br>check q <= Max]
    A -- No  --> ERR_MIN[Reject: below minimum]

    B -- Yes --> C[Check pack multiple]
    B -- No  --> ERR_MAX[Reject: above maximum]

    C -- Pass --> D[Check stock availability]
    C -- Fail --> ERR_PACK[Reject: invalid multiple]

    D -- Available --> OK[Accept]
    D -- Not available --> ERR_STOCK[Reject: insufficient stock]

Notes:

  • If Min is not set, treat it as 0 for validation.
  • If Max is not set, no upper bound is applied.
  • Pack multiple uses the product’s pack rules (same as standard carts).

🧑‍💻 Admin — managing quantities

  • Create lines: POST /admin/operations/{id}/lines — set Min/Max/Recommended in the payload.
  • Read lines: GET /admin/operations/{id}/lines (paginated).
  • Update lines: PUT /admin/operations/{id}/lines — batch update of Min/Max/Recommended.
  • Delete lines: DELETE /admin/operations/{id}/lines — remove product variants from the Operation.

Lines are add/update/delete only in DRAFT. After ACTIVE/INACTIVE, lines are locked to protect existing orders.

Creation example

POST /admin/operations/{operationId}/lines
[
  { "variantExternalId": "VAR-001", "minQuantity": 0, "maxQuantity": 50, "recommendedQuantity": 20 },
  { "variantExternalId": "VAR-002", "minQuantity": 1, "recommendedQuantity": 5 }
]

Update example

PUT /admin/operations/{operationId}/lines
[
  { "variantExternalId": "VAR-001", "minQuantity": 0, "maxQuantity": 40, "recommendedQuantity": 15 },
  { "variantExternalId": "VAR-002", "minQuantity": 2 }
]

Delete example

DELETE /admin/operations/{operationId}/lines
[ "VAR-001", "VAR-002" ]

🛒 Buyer — editing after start

  • Buyers can increase or decrease quantities within Min/Max and pack rules.
  • If Min = 0, the buyer may remove the line from the order.
  • Buyers may add other products not part of the Operation; standard rules apply.

If the Operation becomes INACTIVE after the order is started, follow your normal lifecycle rules (e.g., allow checkout with already-added lines vs. block new adds).

🧠 Practical tips

  • For optional lines, set Min = 0 and a Recommended value to guide the buyer without forcing it.
  • For strict packs, ensure the Recommended value is already a valid multiple.
  • Avoid setting a Max that is lower than typical pack multiples to reduce validation friction.

🔗 API quicklinks

Admin — Operation Lines (min / max / recommended)


Related Admin endpoints (for context)


Shop (how quantities behave for buyers)

  • 🔜 POST /operations/(operationId)/order (Checkout v3)
    • Default quantity per visible line: recommendedQuantity, else minQuantity, else 1.
    • Validation on add/update: standard stock and pack multiples checks plus Operation min/max constraints.
📘

Notes

All write operations on lines are DRAFT-only to protect existing carts/orders once the Operation is ACTIVE/INACTIVE.


Updated 17 days ago