Targeting rules

A targeting rule narrows the population that can match a feature flag. Without rules, the rollout percentage applies to everyone — every user who hits the SDK is a candidate. With rules, only the users matching every predicate are candidates; the rollout then samples within that filtered set.

Rules let you say things like "100% of plan=pro users in country IN ['US','CA']" without ever touching code. The predicates evaluate against the ctx object you pass to gate().

The shape

A rule is a list of predicates:

{ attr: "plan",    op: "eq",  value: "pro" }
{ attr: "country", op: "in",  value: ["US", "CA"] }
{ attr: "signup",  op: "gte", value: "2025-01-01" }

Predicates are ANDed. To get true from the feature flag, a user must match every predicate and fall inside the rollout percentage.

Operators

regex is RE2, so no backreferences or lookarounds — but it's safe (no catastrophic backtracking). The pattern is anchored: use .* explicitly at start/end if you want partial matches.

Passing context to the Client

The ctx object you bind to the Client is what gets matched against:

const flags = new Client({
  userId: session.user.id,
  plan: session.account.plan,
  country: request.geo.country,
  appVersion: request.headers.get("x-app-version"),
  email: session.user.email,
});
flags.getFlag("checkout-v2");

Three things to internalise:

1. userId is special — it's the bucketing key. Required for sticky bucketing. The other attributes are matched against rules.
2. Attributes are matched by name. A rule against plan looks for ctx.plan. If you pass ctx.userPlan, the rule misses and the user falls out of the eligible set.
3. Missing attributes never match. A rule country eq "US" against a ctx with no country key returns false for the predicate, dropping the user from eligibility. Pass country: null and it still won't match — eq requires non-null equality.

Defining rules

In the dashboard, expand a feature flag, add rules under Targeting. Each row is one predicate; rows are ANDed. Equivalent JSON shape if you'd rather edit raw via the Admin API:

"rules": [
  { "attr": "plan",    "op": "eq", "value": "pro" },
  { "attr": "country", "op": "in", "value": ["US", "CA"] }
]

Or directly via the Admin API (resolve the feature flag's id first, then PATCH it):

GATE_ID=$(curl -sS \
  -H "Authorization: Bearer $SHIPEASY_ADMIN_KEY" \
  "https://shipeasy.ai/api/admin/gates?name=checkout-v2" | jq -r '.data[0].id')

curl -X PATCH "https://shipeasy.ai/api/admin/gates/$GATE_ID" \
  -H "Authorization: Bearer $SHIPEASY_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      { "attr": "plan", "op": "eq", "value": "pro" },
      { "attr": "country", "op": "in", "value": ["US","CA"] }
    ]
  }'

Common shapes

Beta allow-list

A small set of accounts get the feature, no one else. Rule on an account attribute, rollout 100% of the matched set:

plan eq "beta-tier"   AND   rollout 100%

Adding an account to the beta becomes a database update on your side, not a config push on ours.

Regional progressive rollout

Ramp safely by geography. Start with countries where you control the integrations end-to-end:

country in ["US","CA"]    AND   rollout 5%   →   25%   →   100%

Then expand the country set, not the percentage:

country in ["US","CA","GB","DE"]   AND   rollout 100%

Internal-only feature

Test in production with employees first. Use an attribute that's hard to spoof from outside your auth system:

email contains "@yourcompany.com"   AND   rollout 100%

Don't use country eq "internal-test" or anything fake — anyone can spoof their request headers. Use an attribute your auth system signs.

Power-user soft launch

Roll out to high-engagement users first because they're more forgiving of UI changes:

sessionsPerWeek gte 10   AND   rollout 25%

This requires you to actually pass sessionsPerWeek in ctx — i.e. compute it server-side or pass it from your analytics layer.

Rule evaluation order

For gate(name, ctx), the SDK runs:

1. killswitch ON                                → false
2. enabled OFF                                  → false
3. ctx.userId ∈ overrides[true]                 → true
4. ctx.userId ∈ overrides[false]                → false
5. any rule predicate fails                     → false   ← rules
6. hash(salt + bucketBy) % 10000 < rolloutPct   → true    ← rollout
7. otherwise                                    → false

Rules run before the rollout. "100% of plan=pro" means 100% of pro users — not a global 100% bucket then filtered. If you want random sampling on top of targeting, set the rollout to the percentage you want within the targeted set.

Custom attributes

You can pass anything into ctx — the SDK doesn't validate against a schema. Common patterns beyond user/account:

const flags = new Client({
  userId: user.id,
  plan: account.plan, // identity
  signupDays: daysSince(account.createdAt), // tenure
  trialsUsed: account.trialsConsumed, // usage
  cohort: account.cohortLabel, // bucketing tag
  device: request.device.type, // request shape
  feature: { betaTester: account.isBeta }, // nested
});
flags.getFlag("paywall-v2");

For nested attributes, refer to them with dot paths in rules: feature.betaTester eq true.

Keep ctx small. The SDK serialises it for sticky bucketing only when bucketBy references a nested path; everything else stays local. Still, payloads in the megabytes are wasteful — pass what your rules use, not your whole user record.

Debugging a rule

When a user complains "I should be in this beta but I'm not," check four things in order:

1. Is the feature flag enabled? shipeasy release flags list shows enabled and the current rollout per feature flag; the feature flag detail page in the dashboard also shows killswitch state at the top of the header.
2. Does the user match the rule? Open Feature flags → checkout-v2 → Test evaluator in the dashboard and paste a JSON ctx — same evaluator the SDK runs, prints the matched rule + bucket.
3. Is there an override? Overrides win over rules. Check Feature flags → checkout-v2 → Overrides.
4. Are you passing the attribute the rule expects? A rule on plan won't match ctx.userPlan. Log the user you bind to the Client and compare against the rule shape.