Core Concepts

Shelfie has four core building blocks. Understanding how they interact will help you set up rules that match how your store actually operates.

Aging

Every product has an aging value — the number of days since it last sold. If a product has never sold, aging is measured from its creation date.

Aging is recomputed on every sync.

Risk levels

Aging is translated into a risk level using thresholds you configure:

Level	Default threshold	Meaning
Healthy	0–29 days	Selling well; no action needed
Warning	30–59 days	Slowing down; consider a sale badge
Danger	60–89 days	At risk; apply markdown or clearance
Dead	90+ days	Capital trapped; archive or aggressive discount

Thresholds are global by default but can be overridden per rule.

Rules

A rule is a (scope, thresholds, action) tuple. It says:

"For products matching this scope, use these thresholds and run this action when they go dead."

Every store starts with a single catch-all rule that matches every product and uses the global thresholds.

Scopes

A scope is what a rule applies to. Shelfie supports 8 scope types, ordered by priority (highest wins when multiple rules match):

Priority	Scope type	Example
100	product	A specific product
80	tag	All products tagged seasonal
60	collection	A specific Shopify collection
40	product_type	All Outerwear products
20	vendor	All products from Nike
15	category	A Shopify product taxonomy node
10	sku_prefix	All SKUs starting with WIN-
5	location	Products stocked at a specific location

See Rule Priority for the full resolution algorithm.

Actions

An action is what Shelfie does to a product. Available action types:

• Markdown — drop price by N%
• Sale badge — drop price + set compareAtPrice so storefront shows "On Sale"
• Clearance price — aggressive markdown (default 40%)
• Add tag — add a tag like clearance for theme/automation use
• Add to collection — move into a designated collection (e.g. a clearance section)
• Unpublish — set product status to draft
• Archive — set product status to archived

Every action is reversible. The original price, status, tags, and collection membership are stored so you can undo with one click.

See Action Types for parameter details.

Savings tracking

When you apply an action, Shelfie records the timestamp. On every sync (and via the orders/create webhook in real time), Shelfie reads the last 365 days of orders from Shopify and sums the line-item revenue for orders placed after each action's apply timestamp:

recovered = Σ ( line_item.quantity × line_item.unitPrice )
             for each order where order.createdAt > product.actionAppliedAt

The dashboard's Recovered KPI is the sum of recovered across all currently-actioned products. Reverting an action resets that product's recovered value to $0.

This attributes real customer-paid revenue to Shelfie's intervention, naturally handling returns, discounts, and partial refunds.

Next: Dashboard tour