Core Concepts

Evaluation Priority Order

Evaluation Examples

Example: Italian Pro Users

Scenario: You want to enable a new feature only for users who are from Italy AND have a Pro or Growth plan.

// Rule: "Italian Pro Users"
// Conditions (AND):
//   - country equals "IT"
//   - plan in "pro,growth"

// User: { country: "IT", plan: "pro" }
// ✓ country = "IT"? YES
// ✓ plan in "pro,growth"? YES
// Result: flag = true

Available Operators

See GET /api/v1/operators for the full list with descriptions.

Use Case 1: Premium Feature for Pro Users Only

Goal: Show a feature only to users with plan=pro or plan=enterprise. Everyone else should NOT see it.

Flag: premium-analytics
├── Rule 1: plan IN "pro,enterprise" → rollout 100%
└── Global Rollout: 0%  ← non-matching users get FALSE

| User              | Result  | Reason           |
|-------------------|---------|------------------|
| { plan: "pro" }   | TRUE    | Rule 1 matches   |
| { plan: "free" }  | FALSE   | Global 0%        |
| { }               | FALSE   | Global 0%        |

Use Case 2: Gradual Rollout with Beta Testers First

Goal: Roll out a new feature starting with beta testers (100%), then internal team (100%), then gradually to everyone else (start at 10%).

Flag: new-checkout
├── Rule 1: beta_tester EQUALS true → rollout 100%
├── Rule 2: email ENDS_WITH "@company.com" → rollout 100%
└── Global Rollout: 10%  ← everyone else gets 10% chance

| User                          | Result  | Reason              |
|-------------------------------|---------|---------------------|
| { beta_tester: true }         | TRUE    | Rule 1 matches      |
| { email: "[email protected]" }  | TRUE    | Rule 2 matches      |
| { email: "[email protected]" }   | ~10%    | Global 10% rollout  |

Increase global rollout over time: 10% → 25% → 50% → 100%

Use Case 3: Block Feature for Specific Country

Goal: Enable a feature for everyone EXCEPT users in Germany (due to legal restrictions).

Flag: gdpr-analytics
├── Rule 1: country EQUALS "DE" → rollout 0%  ← block Germany
└── Global Rollout: 100%  ← everyone else gets it

| User               | Result  | Reason              |
|--------------------|---------|---------------------|
| { country: "DE" }  | FALSE   | Rule 1 blocks       |
| { country: "IT" }  | TRUE    | Global 100%         |
| { country: "US" }  | TRUE    | Global 100%         |

Use Case 4: A/B Test with 50/50 Split

Goal: Show new pricing page to 50% of users for A/B testing. Same user always sees the same variant (consistent).

Flag: new-pricing-page
├── (no rules)
└── Global Rollout: 50%

| User                | Result    | Reason                    |
|---------------------|-----------|---------------------------|
| { id: "user-123" }  | TRUE      | Hash puts them in 50%     |
| { id: "user-456" }  | FALSE     | Hash puts them out        |
| { id: "user-123" }  | TRUE      | Same user = same result   |

Note: Consistent hashing ensures user-123 always gets TRUE.

Use Case 5: VIP Access Override

Goal: Feature is disabled globally, but specific VIP users should always have access.

Flag: early-access-feature
├── Target Users: ["vip-user-1", "vip-user-2"]  ← always TRUE
├── (no rules)
└── Global Rollout: 0%

| User                  | Result  | Reason                |
|-----------------------|---------|----------------------|
| { id: "vip-user-1" }  | TRUE    | In target users list |
| { id: "vip-user-2" }  | TRUE    | In target users list |
| { id: "normal-user" } | FALSE   | Global 0%            |

Note: Target users override everything, even 0% rollout.

Example: E-commerce Black Friday Campaign

Scenario: You run an e-commerce store and want to show a special Black Friday banner with 40% off. The sale runs from November 29th at midnight to December 2nd at 11:59 PM.

Problem: Without scheduled changes, someone needs to be awake at midnight to enable the flag, and remember to disable it after the sale ends. Human error, timezone confusion, and forgotten tasks can cause the banner to appear too early, too late, or never disappear.

Solution: Schedule the flag in advance:

POST /api/v1/flags/:flagId/environments/:envId/schedule
{
  "enable_at": "2026-11-29T00:00:00Z",
  "disable_at": "2026-12-02T23:59:00Z"
}

Result: The banner appears automatically at midnight on Black Friday and disappears when the sale ends. Your team can enjoy the holiday without worrying about manual toggles.

Example: Planned Maintenance Window

Scenario:Your payment provider is performing maintenance on Saturday from 2 AM to 6 AM. You want to show a "Payments temporarily unavailable" message and disable the checkout button during this window.

Solution: Create a payment-maintenance flag and schedule it to be enabled only during the maintenance window:

// Schedule maintenance mode
POST /api/v1/flags/:flagId/environments/:envId/schedule
{
  "enable_at": "2026-01-18T02:00:00Z",
  "disable_at": "2026-01-18T06:00:00Z"
}

In your code:

const isMaintenanceMode = useFlag('payment-maintenance', false);

if (isMaintenanceMode) {
  return <MaintenanceBanner message="Payments back at 6 AM" />;
}
return <CheckoutButton />;

Example: Broken Feature in Production

Scenario: You enabled the new-checkoutflag for 100% of users. Within 5 minutes, your error monitoring (Sentry, Datadog) shows a spike in checkout failures. Users are complaining they can't complete purchases.

Problem: Finding and fixing the bug could take hours. Every minute costs you sales and customer trust.

Solution: One API call to rollback:

POST /api/v1/flags/:flagId/environments/:envId/rollback

// Response:
{
  "message": "Rollback successful",
  "enabled": false,
  "rollout_percentage": 50,
  "rolled_back_to": "2026-01-07T14:00:00Z"
}

Result: The flag instantly reverts to the previous state (disabled, or 50% rollout). Users see the old checkout, errors stop, and your team can debug without pressure.

Example: Accidental Change by Team Member

Scenario: A new team member accidentally disabled thepayment-gateway flag in production while exploring the dashboard. The flag was at 100% rollout with a specific list of beta tester user IDs.

Problem:Re-enabling the flag is easy, but what was the rollout percentage? What were the target user IDs? Without history, you'd need to guess or check the code.

Solution: Check history and rollback:

// View what changed
GET /api/v1/flags/:flagId/environments/:envId/history

// Rollback restores EVERYTHING: enabled, percentage, target users
POST /api/v1/flags/:flagId/environments/:envId/rollback

Result: The exact previous configuration is restored, including the 100% rollout and beta tester user IDs. No guessing, no mistakes.

Example: API Outage During Peak Traffic

Scenario:It's Black Friday and your site has 50,000 concurrent users. Rollgate API becomes temporarily unreachable due to a network issue.

Without circuit breaker: Every page load waits for API timeout (5 seconds), your site becomes unusable, users leave, you lose sales.

With circuit breaker:After 5 failed requests, the circuit opens. All subsequent flag checks return instantly from cache. Your site stays fast, users don't notice anything.

// Monitor circuit state in your health endpoint
app.get('/health', (req, res) => {
  const circuit = rollgate.getCircuitState();
  res.json({
    status: circuit === 'open' ? 'degraded' : 'healthy',
    circuit: circuit,
    flagsCached: true
  });
});

// Alert when circuit opens
rollgate.on('circuit-open', () => {
  alertOps('Rollgate circuit breaker opened - using cached flags');
});

Result: Your app gracefully degrades. Features controlled by flags continue working with the last known values. When Rollgate recovers, the circuit closes and fresh data flows again.