Pricing Rule: How to limit auto-apply discount to 1 item when multiple qualifying items are in cart?

Questions
1

We use Customer Group Discounts (per the Configure Customer Group Discounts guide) for a custom loyalty program. When a customer earns “Buy 12 get 13th Free,” we create a pricing rule with a 100% discount on their qualifying variations, gated by a per-customer group.

Problem: When the customer has multiple qualifying items in the cart, the discount applies to ALL of them instead of just one. 9 qualifying items → all 9 free instead of 1.

Tried:

  • FIXED_PERCENTAGE: 100% + quantity_exact: 1 on product set → match threshold, not a cap

  • FIXED_AMOUNT set to one item’s price → applied per-item, not order total

  • maximum_amount_money → caps per-item, not per-order

Aware of but can’t use:

  • pricing_blocklists (section 3.3 of Auto-Apply Discounts) — requires controlling CreateOrder, which POS handles natively

  • UpdateOrder with fields_to_clear — race condition with cashier completing payment before our API call lands

  • BOGO pattern with exclude_products_id — requires buy quantity in current cart, not accumulated over visits

Is there a way to limit a pricing rule to discount at most 1 matched item? Something like max_applications on the rule, or ORDER-scoped auto-apply discounts?

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Create Volume Discounts
Automatically Apply Discounts
Order Discounts

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

Currently, Square’s Catalog API does not support a direct way to limit a discount to apply to only one item in a cart when using customer group discounts. The existing mechanisms, such as quantity_exact, maximum_amount_money, and pricing_blocklists, do not provide a solution for limiting the discount to a single item per order when multiple qualifying items are present.

The quantity_exact attribute is used to define the threshold for applying a discount but does not cap the number of items the discount applies to. Similarly, maximum_amount_money caps the discount per item rather than per order, and pricing_blocklists requires control over the order creation process, which is not feasible if the POS handles it natively.

Given these limitations, a potential workaround could involve implementing a custom logic layer outside of Square’s APIs. This layer could track customer purchases and apply the discount manually by adjusting the order after it is created, though this approach may introduce complexities such as race conditions.

Unfortunately, without a feature like max_applications or an ORDER-scoped auto-apply discount, achieving the desired behavior directly through Square’s current API offerings is not possible. You may want to consider submitting a feature request to Square for more flexible discount application rules that could accommodate such use cases.

This answer was reviewed by @Bryan-Square.