Resolving conflicts

Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.

Several rules can target the same product, from the same campaign or from different ones. One of them wins. Knowing which is what lets you write a broad policy and a narrow exception without them fighting.

The order

The winner is decided per product, in this order:

Specificity. A rule matching by identity beats one matching by criteria, which beats one matching everything. A hand-picked exception always survives a broad rule. A pin on a list of several IDs counts as criteria here; only a pin on one product is identity.
Effect type, at equal specificity. ban is the most assertive and wins: an identity-level ban removes a product an identity-level pin wanted at position 1. Between a boost and a bury on one product, bury wins — the stricter direction, for the same reason. Hard and soft mode play no part: mode appears in no sort key, so a soft bury still beats a hard boost. A pin does not compete with a boost or a bury at all: one places a product, the others move it, and a product can carry both.
Source, then campaign age, then rule order. If specificity and effect type both tie, three things decide in turn. A sponsored placement beats any rule you wrote — a fixed rank, not a matter of which was created later, so no campaign of yours can outrank one by being newer. Then, between two of your campaigns, the one created more recently wins. Then, between two rules of the same campaign, the one listed first wins. See the last tiebreak below.

Each step only runs when the one above it ties.

Soft is not a weaker rank

mode: "soft" does not put a rule lower in the order. A soft pin wins its conflicts exactly as a hard one does; mode changes only how the winner is applied — the placement fades over its decay window instead of holding in full. A soft rule never loses to a hard one for being soft.

A pin that fits the filters takes the position first

Step 3 has one exception, and it applies when two pins selecting by criteria want the same position on a filtered page.

A criteria pin does not name its product, so which one it places depends on what the shopper is looking at. It is offered the page’s filters in widening steps: first it looks for a product the shopper’s own filters admit, then one that contradicts only the fields its own selector names, then any product it is allowed to take. Every contending pin takes its first attempt before any of them takes its second.

So a pin that can fill the position from what the shopper filtered to takes it, even when a pin earlier in the list would have had to widen. Order in the list decides between pins attempting the same step, not between one attempting an earlier step and one attempting a later one.

Pin your best Northwear and your best Southpeak to position 1, with Northwear first, and a shopper who filters to blue gets the Southpeak if only the Southpeak comes in blue. The Northwear rule would have reached a red one on its second attempt, but by then the position is taken.

This is deliberate: a shopper who filtered to blue should not be shown a red product at the top of the page while a blue one was available to place there. If a position must go to a particular product whatever the shopper filters, pin that product by ID — an identity pin names what it places, so it has nothing to widen and never waits a step.

Per product, not per rule

Resolution does not decide “rule A beats rule B” — it decides, for each product, which rule applies to that product.

A boost covering two products, one of which a ban also covers, loses that one product and keeps the other. The boost is not discarded; it has one fewer product.

Two boosts, or two buries, on one product do not add up. One wins by the same chain and the other is discarded; the stronger one does not win by being stronger.

Two pins conflict when they claim the same position, or the same product at two positions. The chain picks one and drops the other for that position and product only, so a campaign with several pins can have one lose and the rest place normally.

Two consequences for rule design

A broad rule plus a narrow exception works. Bury a whole brand, then pin one of its products by ID. The pin wins on specificity, and every other product in the brand stays buried. When a policy has exceptions, write the policy broadly and the exceptions specifically, rather than writing the policy as a list that excludes them.

A ban is the strongest thing you can write. Only a more specific rule beats it. A criteria-level ban and an identity-level pin is a coherent pair — the pinned product survives, everything else the ban matches disappears. A ban and a pin at the same specificity is not: the ban wins, and the pin does nothing.

When a specific product is protected

A surviving pin, or an identity-level boost or bury, protects the products it names from a broader ban. Without that, a criteria ban would remove a pinned product before the pin could place it, and the pin’s win on specificity would be theoretical.

The exception is not only ranked higher; it is kept in the results so the exception can apply.

The exception has to be a pin on a single product. A pin selecting by criteria, or by a list of IDs, picks its product after ranking — the highest-ranked match no other pin has claimed — and is never protected from a criteria ban: the ban removes the product first, and the pin takes the next match.

A sponsored placement is protected the same way, and for the same reason: it arrives as a pin on one product, so it outranks a broad ban on specificity. A ban that names the product outright still removes it — identity against identity, where ban is the more assertive effect. So a broad “never show what is out of stock” does not stop a paid placement of such a product; a ban naming that product does.

The last tiebreak

Two rules can reach the final step: same specificity, same effect type, one product. What picks depends on where the two rules come from.

From different campaigns, the newer campaign wins. Campaigns are ranked by when they were created, most recent first, and every rule inherits its campaign’s rank. So a campaign you add today outranks one from last month at every tie — which is usually what you want from a new promotion. There is no priority field to set.

Do not reach for recreating a campaign to change the order. A campaign’s reporting is keyed to its identity, so a recreated one starts its history over and the old campaign’s results stop accruing to the work you are continuing. Where two campaigns disagree, make them stop competing instead: narrow one to an ID, change an effect type, or split the overlapping targeting.

From the same campaign, the rule listed first wins. Rules are ordered within a campaign, and that is the order you see when you open it. Move a rule above another to make it win the products the two share.

Editing a rule leaves its place alone, and so does deleting a different one — the rules after it close the gap but keep their order relative to each other. Reordering is the only thing that changes the outcome.

Two rules competing for the same product is still worth avoiding where you can make them differ on something real: narrow one to an ID, change an effect type, or move it to its own campaign. The difference is that when they do compete, the result is now yours to set rather than something to work around.

One case where this used to bite and no longer can: within one campaign targeting a single catalog, two pins that each name a single product may no longer claim the same position, or the same product — the campaign is rejected when you save it. Across different campaigns, and across a campaign’s own catalogs where a position is filled once per catalog, the pair is still accepted and the chain above decides it.