Core Concepts

Shelfie has four core building blocks. This page explains each one and — critically — how they interact when multiple rules could apply to the same product.

Aging

Every product has an aging value — the number of days since it last sold. Shelfie computes this on every sync using your Shopify order history (looking back 365 days).

• If a product sold yesterday: aging = 1
• If a product last sold 45 days ago: aging = 45
• If a product has never sold: aging is measured from its creation date

Aging is the single input that drives risk levels, rule matching, and action queuing.

Risk levels

Aging is translated into a risk level using thresholds configured on each rule:

These defaults are on the catch-all rule and apply to every product unless a more specific rule overrides them. You can change them in Settings → Rules.

Rules

A rule ties together three things:

• Scope — which products it applies to
• Thresholds — when those products are considered at risk
• Action — what to do when a product goes Dead under this rule

Rule: "Winter Coats - Clearance"
  scope:      Collection "Winter 2025"
  warningDays: 14
  dangerDays:  30
  deadDays:    45
  action:      "40% Off Clearance"

Every store starts with a catch-all rule that matches all products and uses the default 7/14/30-day thresholds. It's the foundation — everything else overrides it for specific product groups.

Scopes

A scope defines what a rule targets. Shelfie supports 8 scope types, each with a priority:

Higher priority = more specific. When multiple rules match a product, the highest-priority match wins.

How rule resolution works — a real example

This is the most important concept to understand. Let's walk through it.

Store setup:

• Catch-all rule: 30-day dead threshold, 20% markdown
• Vendor rule "Nike": 14-day dead threshold, NO action (tag: review-needed)
• Tag rule seasonal-clearance: 7-day dead threshold, 40% clearance

Product A — Nike Air Max, tagged seasonal-clearance, in "Footwear" collection:

Matching rules:
  ✓ Catch-all         (priority 0)  — matches all products
  ✓ Vendor "Nike"     (priority 20) — product is from Nike
  ✓ Tag "seasonal-clearance" (priority 80) — product has this tag

Winner: Tag rule (priority 80)
Result: 7-day dead threshold, 40% clearance action

Product B — Nike Air Max, NOT tagged seasonal-clearance:

Matching rules:
  ✓ Catch-all         (priority 0)
  ✓ Vendor "Nike"     (priority 20)

Winner: Vendor "Nike" rule (priority 20)
Result: 14-day dead threshold, add tag "review-needed"

Product C — Generic t-shirt, no special vendor/tags:

Matching rules:
  ✓ Catch-all (priority 0)

Winner: Catch-all
Result: 30-day dead threshold, 20% markdown

The key insight: you can always override with a more specific rule. Start with the catch-all as your baseline, then layer more specific rules on top for the parts of your catalog that need different treatment.

Actions

An action is what Shelfie executes when you click Apply on a product. Available types:

Every action is reversible. Shelfie stores the original state so Revert can undo exactly what was applied.

Actions vs action configs:

• An action type is a kind (e.g. markdown)
• An action config is a named instance with parameters (e.g. "Quiet 15% Drop" at 15%)

You create named configs in Settings → Actions, then assign them to rules. One config can be used by multiple rules.

Savings tracking

When you apply an action, Shelfie records the timestamp. Going forward, every order that includes that product contributes to its Recovered amount:

recovered = Σ (line_item.quantity × line_item.price)
            for all orders where order.createdAt > actionAppliedAt

This resets to $0 if you revert. The dashboard's top-line Recovered KPI is the sum across all currently-applied products.

On Pro, this runs in real time via the orders/create webhook. On Free and Growth, it updates on the next sync.