Rules Based Pricing

Documentation Index

Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt

Use this file to discover all available pages before exploring further.

Rules Based Pricing runs your pricing rules across the products in a grid and writes the resulting prices into a new column. Use it when you have a known pricing logic - margin floors, competitor matching, percentage changes, promo caps - and want it applied consistently across SKUs. Rules Based Pricing is a deterministic constraint solver: each rule narrows the range of valid prices for a row, and the final price is the value inside that range that’s closest to the row’s current price.

​

When to use Rules Based Pricing

Reach for Rules Based Pricing when you can describe the pricing logic you want:

• Operational pricing - guardrails, promotions, parity to a competitor.
• Margin enforcement - you know the floor or band you want to stay in.
• Sync prices across a product family or set.
• Apply rounding to psychological price endings.
• Relative pricing within a group (good / better / best laddering).

If instead you want the system to suggest prices based on demand and elasticity, that’s Price Optimization.

​

Open Rules Based Pricing

In any grid:

1. Click Agents in the top toolbar (or the pinned Rules Based Pricing button if you have one).
2. Select Rules Based Pricing from the All Agents modal.
3. The configuration panel opens with four tabs: Config by AI, Scope, Inputs, Rules.

The Run button is enabled once Inputs is mapped and at least one rule exists.

​

Configure in four tabs

The four tabs can be filled in any order. The recommended order for first-time setup is Inputs -> Scope -> Rules (or Config by AI).

​

Inputs - map Price and Cost

The Inputs tab maps two grid columns to the algorithm’s reserved fields:

• Price - the current selling price (defaults to price).
• Cost - cost per unit (defaults to unit_cost).

Both are required. Margin Rules need Cost; every rule type uses Price as the anchor for “closest to current price” selection. If your data uses different column names, pick them from the dropdowns. The mappings are non-destructive; your original columns aren’t renamed in the grid.

​

Scope - Full Dataset or Sample 10 Rows

The Scope tab controls which rows the rules run against:

• Full Dataset - every row in the current workbook.
• Sample 10 Rows - server-side sampling against ten rows, intended to validate a rule setup before committing to a full run. Returns quickly and exposes configuration errors (missing references, contradictory rules, invalid conditions) without processing the whole grid.

Sample runs still log to the Runs section and write outputs back to the grid for the sampled rows.

​

Config by AI - describe what you want in plain language

The Config by AI tab lets you describe the rules you want and have Retailgrid generate a valid configuration. Useful when you know the outcome you want but not which rule type fits.

• Prompt - describe your goal in 1-3 sentences. Example: “Set price 5% above cost, but never below the cheapest competitor.”
• AI model - currently Gemini 2.5 Flash.
• Run AI - generates rules and adds them to the Rules tab.

AI-generated rules append to the existing rule list. Use Reset before running AI when you want a clean slate. AI output is a starting point. Review every generated rule before clicking Run - the AI gives a structured guess, not a final answer.

​

Rules - the heart of the configuration

The Rules tab is where you list the rules to apply. Click Add Rule to open the rule type picker, configure each rule, and save it. The list shows all rules with their priorities; the 0 badge on the tab header is the rule count.

​

How rules are evaluated

For every row in scope, independently:

1. Rules are sorted by Priority (1 = highest, max 50).
2. The engine walks rules top-to-bottom. Each rule narrows the row’s feasible price corridor.
3. If a rule’s corridor doesn’t intersect the current corridor, the rule is violated (see Fallback Behavior).
4. After all rules run, the final price is the value in the surviving corridor closest to the row’s current price.
5. Price Rounding is always evaluated last regardless of its priority position; its priority number controls which other rules it can violate.

The execution model is documented internally as the Interval Selection Algorithm (ISA). The result is reproducible - same inputs and rules always give the same output.

​

Universal rule fields

Every rule has the same envelope, regardless of type:

• Name - free text. Make it readable in traces (e.g. “Min margin 25%”).
• Priority (1-50) - lower number = higher priority. The engine evaluates highest-priority rules first.
• Conditions (collapsible) - filter that limits which rows the rule applies to.
• Fallback Behavior (collapsible) - what to do when the rule conflicts with the current corridor or the row is missing required data.
• Rule-specific parameters (see each rule type below).

Maximum 50 rules per execution. The rule list order in the Rules tab is purely visual; only Priority controls evaluation order.

​

The 8 rule types

​

Fixed Price

Locks matching rows to their current price. The final price equals the input price; no later rule can move it.

• Parameters: none.
• Corridor: [current_price, current_price] - a single point.
• Use it for: promo prices, regulated SKUs, manually approved prices.
• Gotcha: any later rule whose corridor doesn’t contain the current price will be marked violated for those rows.

​

Price Change Limit

Caps how far prices can move from the current price. Use it as an outer corridor (Maximum) or as a dead zone forbidding micro-changes (Minimum).

• Limit Type: Maximum (outer corridor) or Minimum (dead zone).
• Increase: Percent or Absolute, with a value.
• Decrease: Percent or Absolute, with a value.
• Maximum corridor: [base - decrease, base + increase]. Prices outside are pulled to the nearest boundary.
• Minimum (dead zone): forbids changes smaller than the threshold. Encoded internally as an inverted corridor; this is the only rule type that legitimately produces lo > hi.

​

Price Change

Moves prices by a percent, an absolute amount, or a reference column. Always produces a single target price.

• Value Type: Percent, Absolute, or Column.
• Value: the percent / absolute number, or the reference column.
• Formulas:
  percent:   target = current_price * (1 + value / 100)
  absolute:  target = current_price + value
  column:    target = current_price + reference_column
  
• Note: always computed relative to the base price (current price), not relative to whatever the running candidate is at this rule’s priority. So a +5% Price Change applied after a Margin Rule still adds 5% to the original price, not to the margin-derived price.

​

Price Match

Aligns the price to a reference column (typically a competitor price), either exactly or within a percentage corridor.

• Reference Column: numeric column.
• Operator: Equals (single point) or Between (corridor).
• From / To values (when Between): lower / upper percent bounds.
• Corridor:
  equals:   [ref, ref]
  between:  [ref - from%, ref + to%]
  
• When violated: the engine clamps the price to the boundary closest to this rule’s wanted corridor (“stretch toward what the rule wanted”).

​

Sync Prices

Forces all rows in a group to share one identical final price. A dynamic rule - it intersects the corridors of all group members and resolves a single group target at its priority moment.

• Group Column: string or categorical column (e.g. product_family).
• Resolution cascade (in order):
  1. Mode - if any current price is shared by 2+ members, use it.
  2. Sales-weighted - if all current prices are unique and a sales_units column exists, use the price of the highest-selling member.
  3. Median of group’s current prices.
• Three cases after intersecting member corridors:
  • Full intersection: all group members get the same price.
  • Partial intersection: the engine drops outlier SKUs (smallest contribution to overlap) one by one until the rest agree. Outliers are marked Sync-violated and priced individually.
  • No intersection: the whole group is marked Sync-violated and each SKU is priced individually.
• Scope gotcha: Sync only groups rows matching its conditions. Rows outside the conditions are completely unaffected - the rule doesn’t appear in their applied / violated lists.
• Special fallback: when Sync is violated, the engine doesn’t “stretch toward Sync’s corridor” (Sync has no numeric corridor). Instead, each affected SKU is priced closest to its own current price.

​

Margin Rule

Constrains the price to a margin or markup target derived from Cost. Static - corridor is computed before the engine runs.

• Margin Type: Margin or Markup.
• Constraint: Exact (single point) or Between (corridor).
• Value Source: Percent, Absolute, or Column.
• Value (or From / To when Constraint is Between).
• Formulas (with T = value / 100 for percent):
  Margin, percent / column:  boundary = cost / (1 - T)
  Markup, percent / column:  boundary = cost * (1 + T)
  Absolute (margin/markup):  boundary = cost + T
  
• Examples: “Margin exactly 25%” -> [cost / 0.75, cost / 0.75]. “Markup between 30% and 50%” -> [cost * 1.30, cost * 1.50].
• Validation: Value Source = Column is only valid with Constraint = Exact. Combining Column with Between returns an error.

​

Price Rounding

Forces final prices to end in psychologically allowed endings (e.g. *.99, *.95, *.00).

• Price Scope: All prices, or a price-range filter (Equals / Between).
• Pattern (allowed endings): comma-separated patterns, e.g. *.99, *.95.
• Excluded endings: patterns to avoid, e.g. *.77.
• Rounding Direction: Up (smallest valid above candidate), Down (largest valid below candidate), or Closest (nearest valid that still falls inside the feasible range).
• Always last: Rounding runs after every other rule, regardless of its position in the priority list. Its priority number determines which other rules it may violate (only those with lower priority).
• Gotcha: if no valid ending exists inside the feasible range, the rule is violated and the price stays unrounded - it isn’t nulled.

​

Price Relations

Maintains a relative price structure within a group. Example: keep the Profit Driver SKU 6% below the Traffic Builder.

• Group Column: string or categorical.
• Price Type: Price or Unit Price.
• Relationship Type: One by one (each item N priced relative to item N-1) or Same gap (same gap from anchor for every member).
• Gap Value Type: Percent or Absolute.
• Gap Value.
• Anchor Logic: Highest priced (anchor = group member with highest current price) or Explicit item.
• Formulas:
  percent:   price(N) = price(N-1) * (1 - gap / 100)
  absolute:  price(N) = price(N-1) - gap
  
• Cascade: each chain SKU gets a single-point corridor. If the anchor moves due to a higher-priority conflict, the entire chain is recomputed.
• Composes with rounding only: because Price Relations leaves single-point corridors, only Price Rounding can compose meaningfully after it. Other lower-priority rules will either intersect the exact point (no conflict) or be violated.

​

Conditions - filter which rows a rule applies to

Open the Conditions section on any rule to limit it to a subset of rows. Rules with no conditions apply to every row in scope.

• Each condition is a column + operator + value triplet.
• Conditions combine via AND (no OR).
• Supported operators: =, !=, >, <, >=, <=, IN, NOT IN, IS TRUE, IS FALSE.

A row is matched by a rule only if every condition evaluates true.

​

Fallback Behavior - what happens when a rule can’t apply cleanly

Open the Fallback Behavior section on any rule to control conflict and missing-data handling. Conflict behavior

• Follow priority (default) - the rule is marked violated, the corridor stays at the last valid range, and the engine picks the boundary closest to what this rule wanted (“stretch toward the violated rule”).
• Return error - calculation stops for this row. The row gets rbp_status = error and the offending rule’s name. Recommended for compliance-critical rules.

Missing value behavior

• Ignore (default) - the rule is skipped for rows missing required data; the row continues evaluating other rules.
• Return error - the run fails when a required column value is missing.

Sync Prices, Price Rounding, and Price Relations have rule-specific fallbacks (described in their sections above).

​

Save and load configurations

Click Config Manager in the top right to save the current configuration as a named config or load a previously-saved one. A config captures the full setup - scope, inputs, AI prompt history, and the entire rule list. You can load a config onto the same grid or a different one. This is the right tool for monthly recurring runs and for sharing setups across teammates.

​

Validate with Sample 10 Rows, then run

The recommended flow:

1. Configure rules.
2. Set Scope to Sample 10 Rows and click Run.
3. Inspect the Rules Based Price column on the sampled rows; open the Price Analysis panel on a few to confirm rules fired as expected.
4. Switch Scope back to Full Dataset and click Run.

Sample runs are fast and surface configuration errors (missing references, contradictory Conditions, validation failures) before you wait through a full execution.

​

Read the result

After a run, the grid shows a new Rules Based Price column with the calculated price per row. Click any cell in that column to open the right-side Price Analysis panel, which explains how the price was derived. The panel header shows the product (image, ID, name) the price was calculated for, plus a Rule-based pricing trace subtitle. The summary block has two columns: Left column - Final Price

• Final Price - the calculated Rules Based Price, large and prominent.
• % delta vs Start Price - how far the calculated price moved from the row’s starting price (positive = up, negative = down).

Right column - inputs and applied rules

• Start Price - the row’s starting price (the input).
• Cost - the row’s unit cost (the input).
• Feasible Range - the price corridor that survived after every applied rule narrowed it. The Final Price is the point inside this range closest to Start Price.
• Applied Rules - count of rules that fired successfully, plus a count of rules that were violated (next to it).

Impact section (three metric cards below the summary)

• New Unit Margin % - margin at the calculated Rules Based Price, with the starting margin shown below as vs Start: X%.
• Unit Margin % pp change - percentage-point change vs the starting margin.
• Unit Margin % Change (%) - relative change in margin (pp change / starting margin).

All values are rounded to 2 decimals. Corridor visualization A horizontal bar at the bottom shows the Feasible Range, with markers for Start Price (input) and Final Price (calculated) - useful for seeing at a glance how aggressively rules constrained the price. Press ESC or click the X in the panel header to close it.

​

Output columns

The agent writes these columns back to the grid: Hide what you don’t need via the Columns panel. Pin Rules Based Price to the right for at-a-glance review.

​

Common pitfalls

• Missing cost - Margin Rules can’t run without it. Either map a Cost column in Inputs or remove margin-based rules.
• Currency mismatch - if products and competitors use different currencies, configure FX in account settings before running competitor-based rules.
• Conditions too narrow - if no rows match, the rule is silently skipped. Watch the row counts in Sample runs.
• Fixed Price followed by other rules - Fixed Price is a single-point corridor; almost any later rule will be violated for those rows. Expected behavior.
• Price Change relative to base - Price Change always starts from the current price, not from whatever earlier rules produced. If you need cascading deltas, use Price Relations instead.
• Rounding never reaches a valid ending - if the surviving corridor is narrower than your Pattern’s tick spacing, Rounding is violated and the price stays unrounded.

​

Related

• Agents overview
• Price Optimization
• Pricing Strategy
• Add columns
• Metrics glossary
• Currency
• Runs