CheckoutOS
API ReferenceHelp Center

Manual Rules

Override AI recommendations with custom rules and curated suggestions

Last updated: 2025-01-16

Manual rules let you override AI recommendations when you know better. Pin specific products, exclude items, boost categories, or create curated recommendation sets for special occasions.

When to Use Manual Rules

Use manual rules for: new product launches, seasonal promotions, clearance items, margin optimization, or when you have domain knowledge the AI lacks.

Rule Types

Pinned Products

Force specific products to appear in recommendations:

Pinned Products Rule
{
  "rule": {
    "name": "New Product Launch",
    "type": "pin",
    "products": ["new-serum-001", "new-cream-002"],
    "position": "first",
    "placements": ["product_page", "cart_page"],
    "conditions": {
      "date_range": {
        "start": "2025-02-01",
        "end": "2025-02-28"
      }
    },
    "priority": 100
  }
}

Excluded Products

Prevent certain products from appearing in recommendations:

Exclusion Rule
{
  "rule": {
    "name": "Exclude Discontinued",
    "type": "exclude",
    "products": ["discontinued-001", "recalled-002"],
    "reason": "Product no longer available"
  }
}

Common Exclusions

  • Discontinued products
  • Out of stock items (if not auto-excluded)
  • Products with quality issues
  • Items being phased out
  • Competitor products (marketplace)

Category Boost

Increase visibility of products from specific categories:

Category Boost Rule
{
  "rule": {
    "name": "Summer Collection Boost",
    "type": "boost",
    "target": {
      "type": "collection",
      "id": "summer-2025"
    },
    "boost_factor": 2.0,
    "conditions": {
      "date_range": {
        "start": "2025-06-01",
        "end": "2025-08-31"
      }
    }
  }
}

Margin Optimization

Boost higher-margin products in recommendations:

Margin Boost Rule
{
  "rule": {
    "name": "High Margin Priority",
    "type": "boost",
    "target": {
      "type": "margin",
      "threshold": 0.4
    },
    "boost_factor": 1.5,
    "max_boosted_products": 2
  }
}

Curated Recommendation Sets

Create hand-picked recommendation collections:

Curated Set
{
  "rule": {
    "name": "Valentine's Day Gift Guide",
    "type": "curated_set",
    "trigger": {
      "type": "date_range",
      "start": "2025-02-01",
      "end": "2025-02-14"
    },
    "products": [
      { "id": "gift-box-001", "position": 1 },
      { "id": "perfume-002", "position": 2 },
      { "id": "jewelry-003", "position": 3 },
      { "id": "flowers-004", "position": 4 }
    ],
    "title": "Valentine's Day Picks",
    "override_ai": true
  }
}

Product Relationships

Define explicit product-to-product relationships:

Product Relationships
{
  "relationships": [
    {
      "source_product": "camera-body-001",
      "related_products": ["lens-001", "memory-card-002", "camera-bag-003"],
      "relationship_type": "accessories",
      "priority": "high"
    },
    {
      "source_product": "shampoo-001",
      "related_products": ["conditioner-001", "hair-mask-001"],
      "relationship_type": "companion",
      "priority": "high"
    },
    {
      "source_product": "phone-basic-001",
      "related_products": ["phone-pro-001"],
      "relationship_type": "upgrade",
      "priority": "medium"
    }
  ]
}

Conditional Rules

Apply rules based on conditions:

Conditional Rule
{
  "rule": {
    "name": "VIP Customer Exclusives",
    "type": "curated_set",
    "conditions": {
      "customer_tag": "vip",
      "cart_value_min": 100
    },
    "products": ["exclusive-001", "limited-edition-002"],
    "title": "Exclusive for You"
  }
}

Available Conditions

  • Date range — Seasonal or promotional periods
  • Customer segment — VIP, new, returning
  • Cart contents — Specific products or categories
  • Cart value — Minimum threshold
  • Device type — Mobile vs desktop
  • Traffic source — Organic, paid, email
  • Geographic location — Country or region

Rule Priority

When multiple rules apply, priority determines which takes precedence:

Priority Example
{
  "rules": [
    {
      "name": "Global New Arrivals",
      "priority": 50,
      "type": "boost",
      "target": { "type": "tag", "value": "new-arrival" }
    },
    {
      "name": "Flash Sale Override",
      "priority": 100,
      "type": "curated_set",
      "products": ["sale-item-001", "sale-item-002"]
    }
  ]
}
Priority Scale

Priority ranges from 1-100. Higher numbers take precedence. AI-generated recommendations have a default priority of 0.

Managing Rules

1

Navigate to Rules

Go to CheckoutOS → Smart Recommendations → Manual Rules.
2

Create New Rule

Click "Create Rule" and select the rule type.
3

Configure Rule

Set products, conditions, and priority.
4

Test Rule

Preview how the rule affects recommendations.
5

Activate

Save and enable the rule.

Best Practices

Manual Rule Tips
  • Use sparingly — Let AI do the heavy lifting
  • Set end dates — Don't let temporary rules become permanent
  • Monitor impact — Compare performance to AI recommendations
  • Document reasoning — Note why rules were created
  • Review regularly — Audit rules quarterly

Related Topics

AI Engine

How AI recommendations work

Learn more

Placements

Where to show recommendations

Learn more
Was this page helpful?

Need more help? Contact support