Order is invisible when everything is simple, and decisive when it is not.

The simple world

In a small product, one flag might have one special group. Staff see the new page, everyone else does not. There is nothing to rank, because nobody can be in two places at once. Teams in this world rarely think about priority at all.

The crowded world

Products grow. Soon the same flag has special settings for staff, for premium customers, for people in one country, for users of an old app version and for a pilot customer. Real people fit into many of these groups at the same time. A premium customer in India using an old app version belongs to three groups. If each group wants a different value, only one value can be used. Something must choose.

What goes wrong without a clear order

• Surprise values. A user sees a setting that nobody expected, and nobody can explain why.
• Silent swallowing. A broad group placed too high swallows a narrow group below it, so the narrow group’s special setting never applies.
• Broken promises. A pilot customer is promised a higher limit, but a general rule above it overrides the promise.
• Unsafe launches. A safety switch for one browser is hidden behind a friendlier rule that matches first.
• Fear of change. Teams stop adding new groups because they cannot predict what will happen.

The key idea in one line

Flagsmith looks at the ranked list of segment overrides for a feature, from top to bottom, and uses the first one whose group the user belongs to. Everything else in this guide is about doing that well.

Priority only makes sense once the pieces it orders are clear. Here is a short refresher.

Organisations, projects and environments

Flagsmith organises everything in three layers. An organisation is usually a company or team. Inside it live projects, each normally one product. Inside each project are environments, such as Development, Staging and Production. A feature is a named switch defined once per project. What it does in each environment, whether it is on and what value it carries, is stored separately for each environment.

Identities and traits

An identity is a record standing for one user. A trait is one named fact about that user, such as “plan” or “country”. Traits are the raw material that segment rules look at.

Segments

A segment is a named group defined by rules over traits. “Premium Users” might mean that the trait “plan” equals “premium”. Membership is worked out automatically each time flags are requested. Nobody adds users to a segment by hand. Segment definitions belong to the project, so every environment can see them.

Segment overrides

A segment override connects a segment to a feature in one environment. It says: “For this feature, in this environment, for people in this segment, use this state and this value.” A feature can carry many segment overrides at once, and that is where order comes in.

Identity overrides

An identity override gives one named user a special setting for a feature. It is the most personal kind of setting.

flowchart TD
    PRJ["Project"] --> FEAT["Feature: upload_limit_mb"]
    PRJ --> SEG["Segments: Staff, Premium, India, Old App"]
    PRJ --> ENV["Environment: Production"]
    ENV --> DEF["Environment default value"]
    ENV --> LIST["Ranked list of segment overrides for this feature"]
    LIST --> O1["1: Staff"]
    LIST --> O2["2: Premium"]
    LIST --> O3["3: India"]
    LIST --> O4["4: Old App"]
    ENV --> IDO["Identity overrides for named users"]

A map of where things live

The idea is short. The consequences are long. Let us define it carefully.

A plain definition

Segment priority is the rank that Flagsmith gives each segment override attached to a feature in an environment. When a user qualifies for more than one override, Flagsmith uses the one with the highest rank, meaning the one nearest the top of the list. Lower ones are ignored for that user and that feature.

First match wins

The method is often described as “first match wins”. Flagsmith reads the list from the top. For each entry it asks, “Does this user belong to this segment?” The first time the answer is yes, it stops, takes that entry’s state and value, and ignores the rest. Entries below are never consulted.

What priority is not

• It is not a score. Nothing is added up. There is no “strongest match”.
• It is not about how many conditions a segment has. A tiny, simple segment placed first beats a detailed one placed second.
• It is not the same as the rule logic inside a segment. The words ALL, ANY and NONE decide who is in the segment. Priority decides which segment’s setting is used once many segments say yes.
• It is not about time. A segment created last year can outrank one created yesterday if it is higher on the list.

Two separate questions

It helps to keep two questions apart. The first is membership: “Is this user in this segment?” That is decided by rules and traits. The second is priority: “Among all the segments this user is in, whose setting do we use?” That is decided by the order of the list. Mixing these two questions up is the most common source of confusion.

One of the most important facts about priority is where it is stored. Many mistakes come from misplacing it.

One list per feature per environment

Each feature, in each environment, has its own list of segment overrides, and each list has its own order. If you have ten features and three environments, you may have up to thirty separate lists. Reordering one does not touch the others.

The same segment, different ranks

Consider the segment “Premium Users”. For the feature “upload_limit_mb” it might be second in the list, below Staff. For the feature “show_ads” it might be first, because the business wants premium users to be free of ads before any other rule applies. The segment is the same. The ranks are independent.

flowchart LR
    subgraph F1["Feature: upload_limit_mb in Production"]
    A1["1: Staff"] --> A2["2: Premium"] --> A3["3: India"]
    end
    subgraph F2["Feature: show_ads in Production"]
    B1["1: Premium"] --> B2["2: Staff"] --> B3["3: Old App"]
    end

Different environments, different lists

The list for a feature in Staging is separate from the list in Production. It is common for Staging to have extra segments for testing, such as “QA Team”, that do not exist in Production’s list. It is also common for the two lists to drift apart in order, which surprises teams who test in Staging and expect the same behaviour in Production.

What this means for your habits

• When you change the order for one feature, remember that other features are unaffected.
• When you add a new segment, you must place it in each feature’s list where it matters.
• When you promote a change from Staging to Production, repeat the ordering there on purpose. Do not assume it follows.
• When you document your scheme, document it per feature, or per family of features.

What about segments created for a single feature

Some versions of Flagsmith let you create a segment that is meant for one feature only, sometimes called a feature-specific segment. It still takes part in the same ranked list for that feature. Check how your version handles these, and keep their names clear so that people do not mistake them for project-wide segments.

Let us follow Flagsmith step by step as it works out the answer for one feature and one user.

The steps

flowchart TD
    START["Request: feature X for user U"] --> Q0{"Identity override for U?"}
    Q0 -- "Yes" --> W0["Use identity override"]
    Q0 -- "No" --> Q1{"U in segment at rank 1?"}
    Q1 -- "Yes" --> W1["Use rank 1 override"]
    Q1 -- "No" --> Q2{"U in segment at rank 2?"}
    Q2 -- "Yes" --> W2["Use rank 2 override"]
    Q2 -- "No" --> Q3{"U in segment at rank 3?"}
    Q3 -- "Yes" --> W3["Use rank 3 override"]
    Q3 -- "No" --> D["Use environment default"]

Why order of testing equals order of authority

Because Flagsmith stops at the first match, the position of an entry is exactly its power. Entry number one can never be overruled by an entry below it. Entry number five can only apply to users who did not match entries one to four.

A worked example

Suppose the list for “upload_limit_mb” is: 1 Staff gives 1000, 2 Premium gives 500, 3 India gives 40, and the default is 25. Priya is a premium customer in India. Flagsmith checks Staff, and Priya is not staff, so no. It checks Premium, and Priya is premium, so yes. It stops and gives 500. The India entry is never even looked at for her. Her friend Dev is a free user in India. Staff, no. Premium, no. India, yes. Dev receives 40. A free user in Brazil matches none and receives 25.

Segment order is the middle layer of a three-layer system. Knowing all three prevents most surprises.

Layer 1: Identity overrides

An identity override is a setting for one named user. It is checked first and beats every segment. Teams use it for one-off cases, such as an executive who wants an early preview, or a customer with a promised exception. Because it beats everything, it is also the easiest way to create confusion if it is forgotten.

Layer 2: Segment overrides, in ranked order

This is the layer this guide is mainly about. The ranked list is read from the top, and the first matching entry wins.

Layer 3: The environment default

If nothing above applied, the user receives the feature’s default state and value for that environment. This is the setting that everyone gets unless something special matches.

flowchart TD
    A["Layer 1: Identity override, one named user"] --> B["Layer 2: Segment overrides in ranked order"]
    B --> C["Layer 3: Environment default"]
    A -. "if none" .-> B
    B -. "if none match" .-> C

Why the layers are ordered this way

The more specific the instruction, the more likely it was made on purpose for this case. A personal exception is the most deliberate. A group rule is deliberate for the group. The default is only a starting position. Letting specific instructions beat general ones is a pattern found in many systems, from legal rules to computer firewalls.

Examples make the idea stick. Here are several, from simple to subtle.

Example 1: Plans and staff

Feature “monthly_export_limit”. Default 3. List: 1 Staff gives 1000, 2 Premium gives 100, 3 Standard gives 30.

Notice that the staff member on premium receives the staff value, because Staff is higher. Whether that is what the business wants is a design decision, and the order is how you express it.

Example 2: A swallowed segment

Feature “new_checkout”. Default off. List: 1 All Logged-In Users gives off, 2 Beta Testers gives on. The segment “All Logged-In Users” contains almost everybody, including every beta tester. Flagsmith always matches rank 1 first, so beta testers receive “off”. The Beta Testers entry is dead weight. Moving Beta Testers above the broad segment fixes it.

Example 3: Safety first

Feature “payment_screen_v2”. Default on. List: 1 Old Browser Bug gives off, 2 Premium gives on. A bug in one browser breaks the new screen. The safety entry is first, so even premium customers on that browser see the old screen, which is what you want during an incident.

Example 4: Regions and plans together

Feature “delivery_fee”. Default 5. List: 1 Premium gives 0, 2 India gives 2, 3 Canada gives 4. A premium user in India receives 0. A standard user in India receives 2. A standard user in Canada receives 4. Think about whether a premium user should really beat a regional promotion, and choose the order accordingly.

Example 5: Percentages

Feature “smart_search”. Default off. List: 1 Staff gives on, 2 Ring 10 percent of users gives on. Staff always get it. Ten percent of everyone else get it too. Everyone else stays off. If the percentage segment were first, staff outside the ten percent would only get the feature through rank 2, which would still work here, but the order would matter if Staff had a different value.

Example 6: Equal-looking, unequal results

The two lists contain exactly the same entries. Only the order differs. That one swap changes the answer for every user who qualifies for both.

Ordering is only hard when groups overlap. Seeing the shapes of overlap makes the right order obvious.

Three shapes of overlap

Which shape do you have?

Finding hidden overlaps

Overlaps are sometimes invisible from names alone. Two segments called “Heavy Users” and “Frequent Buyers” may look different but contain nearly the same people. Check overlaps by looking at real identities, and by using the identity view in the dashboard to see which segments a sample of users belong to. Before you finalise the order, test at least one user from every overlap.

The overlap count grows fast

With two segments, there is one possible overlap. With four, there are six pairs. With ten, forty-five pairs. This is why long lists become hard to reason about, and why a small, clear set of segments, ordered by a simple principle, scales better than a long list with special cases.

There is no single correct order, but there are sound principles that most teams end up following.

Principle 1: Safety rules go on top

Entries whose job is to protect customers, such as turning a feature off for a buggy browser or an unsupported app version, should be at the very top. They must win even over friendly business rules. If a bug breaks checkout on one browser, nobody wants a premium discount rule to switch the broken screen back on.

Principle 2: Exceptions above rules

Narrow, deliberate exceptions belong above broad, general rules. A pilot customer’s special limit should sit above the general plan limits. Staff access should sit above customer plans. This mirrors how rules work in law and in many systems: the most specific instruction applies first.

Principle 3: Specific above general

If one group is a subset of another, the subset goes first. “Premium in India” before “India”. “Staff in Production” before “Staff”. If the broad group were first, the narrow one could never apply.

Principle 4: Business rules by importance

Among the remaining entries, place the one the business cares most about higher. Decide in advance, with the product owner, which of two overlapping groups should win. Write the decision down.

Principle 5: Rollouts below entitlements

Temporary rollout segments, such as percentage rings, usually sit below plan and safety rules, unless the rollout is meant to override them. Keep temporary things easy to spot and easy to remove.

Principle 6: Keep a pattern

Use the same pattern for every feature you can, so that people learn it once. A common pattern is: safety, personal pilots, staff, paid plans, regions, rollouts.

Here is the usual path in the dashboard. Labels and controls may vary a little between versions.

Before you begin

• Open the feature in the right environment. Read the environment name twice.
• Write down the current order, for example in a note or a screenshot, so you can undo.
• Decide the new order and the business rule it expresses.
• List the test users you will use afterwards: one for each overlap.
• If the environment needs approvals, prepare the change request and the reason.

The steps

Automation

Flagsmith exposes an API that includes ways to read and update the order of segment overrides. Teams use this in scripts that apply a standard order across many features. If you do this, keep the script in your code repository so that the order is reviewed like code, and always test on Staging first.

The moment of greatest risk is not reordering. It is quietly adding a new entry and forgetting to place it.

New entries and the list

When you attach a segment to a feature for the first time, the new override appears somewhere in the list. Depending on your version, it may land at the top, at the bottom, or in some default position. Do not guess. Add a test entry in Staging and see where it lands, then write that down for your team.

Why this matters

• A new entry landing at the top may suddenly outrank safety rules.
• A new entry landing at the bottom may be swallowed by broader segments above it, and appear not to work.
• Either way, the user’s experience changes the moment the entry is saved.

The two-step habit

Removing an entry

Removing an entry changes the winner for everyone who relied on it. Users who matched that entry now fall to the next matching one below, or to the default. Before you delete, think about who they will land on, and test those users.

Disabling instead of deleting

Some versions let you switch an override off without deleting it, which keeps its place in the list. If available, this is a gentle way to test the effect of removal. Check your version before relying on it.

Flags are not always a simple yes or no. Priority interacts with several-valued flags and random-looking splits in specific ways.

Multivariate flags

A multivariate flag has several possible values, split by percentages. A button might be blue for half of users, green for thirty percent and orange for twenty percent. A segment override can change this: for one group, the split can be different, or fixed to one value.

Priority works the same way. The first matching segment entry decides the state and the split used for that user. The user is then given one of the values according to that entry’s percentages. Entries below are not consulted.

An example

Percentage-split segments

A percentage-split rule picks a stable share of users using their identifier. It can be used inside a segment, for example “ten percent of users”, and that segment can then be attached to a feature like any other. Because the share is stable, the same user is always inside or always outside for a given percentage.

Where to place percentage segments

• Below entitlements. If a paid plan has a guaranteed feature, it should not depend on a lucky ten percent.
• Below safety rules. A safety switch must apply to everyone it needs to, not only to those outside the ring.
• Above the default. The ring is meant to pull people away from the default, so it must be checked before the default is used.
• Ordered by size when stacked. If several rings exist, such as ten and fifty percent, put the smaller, more specific ring first, so its users get the early value. Then the larger ring, then the default.

flowchart TD
    U["User requests feature"] --> S1{"In safety segment?"}
    S1 -- "Yes" --> R1["Safety value"]
    S1 -- "No" --> S2{"In paid plan segment?"}
    S2 -- "Yes" --> R2["Plan value"]
    S2 -- "No" --> S3{"In 10 percent ring?"}
    S3 -- "Yes" --> R3["Ring value"]
    S3 -- "No" --> S4{"In 50 percent ring?"}
    S4 -- "Yes" --> R4["Wider ring value"]
    S4 -- "No" --> R5["Default"]

A subtle trap with nested rings

Rings are usually nested: everyone in the ten percent ring is also in the fifty percent ring. If you place the fifty percent ring above the ten percent ring, and they give different values, the ten percent entry will never be used, because fifty percent matches first. Always put the narrower ring first.

Two kinds of ordering-like ideas live in Flagsmith. Keeping them separate saves hours of confusion.

Inside a segment: ALL, ANY and NONE

A segment is made of rules, and each rule contains conditions. Conditions combine as ALL (every one must match, like “and”), ANY (at least one must match, like “or”) or NONE (none may match, like “not”). These control membership. They do not carry a rank, and the order in which you list conditions inside a rule makes no difference to who is a member.

Across segments: priority

Priority is only about which segment’s override wins when several segments say yes. It does not change who is a member of any segment.

Do not simulate priority with rules

Some teams try to build order into segment rules, for example by writing “plan is premium AND NOT staff” so that staff and premium never overlap. This can work, but it hides the order inside the rules, spreads the logic across many segments and makes later changes harder. In most cases, it is clearer to keep segment definitions simple and describe their precedence through the ordered list.

A short rule of thumb

Use rules to describe who belongs. Use order to describe who wins. If you find yourself adding “and not in group X” to many rules, consider whether a plain ordered list would be clearer.

Segment membership is not fixed. It follows the user’s facts. That makes priority dynamic, and a little surprising.

Traits change, winners change

Flagsmith evaluates segment membership every time flags are requested, using the user’s latest traits. If a customer upgrades from standard to premium, the trait “plan” changes. On the very next request, the user matches Premium, not Standard, and the winner changes. Nobody moves the user between groups by hand.

sequenceDiagram
    participant B as Billing System
    participant F as Flagsmith
    participant U as User App
    B->>F: Set trait plan to premium
    U->>F: Request flags for user
    F->>F: Evaluate segments in priority order
    F-->>U: Value from the Premium entry

Temporary double membership

During a change, a user may briefly belong to two segments. For example, a user who just became premium may still carry an old “trial” trait. Priority decides the result, and a poorly chosen order can give the user the wrong value until the old trait is cleared. Good housekeeping of traits and sensible ordering work together.

Segments that flip often

Some traits change quickly, such as “orders this month” or “minutes active today”. Users may move in and out of segments during a day. If priority makes those segments produce very different values, the experience can flicker. Avoid using fast-changing facts for high-impact settings, or add a small buffer, such as a “weekly” trait that updates once a day.

Anonymous and missing traits

A user with no value for a trait does not match rules about that trait, unless the rule is about the trait being absent. If a high-ranked entry depends on a trait that is sometimes missing, those users fall through to lower entries. Test the missing case for each trait that appears in a high-ranked segment.

A debugging question to ask

When a user gets an unexpected value, ask two questions in this order: “Which segments is this user in right now?” and then “In what order are those segments in the feature’s list?” The first question is about data. The second is about priority. Do not skip the first.

Orders do not travel automatically. Knowing when they do and do not move prevents classic launch-day surprises.

Each environment has its own order

The ranked list for a feature in Staging is a separate list from the one in Production. Changing the order in Staging does nothing to Production. It is easy to test an order in Staging, be happy, and forget that Production still has the old one.

Promotion is a repeat, not a copy

Moving a change from Staging to Production usually means repeating the same change in Production, by hand or by script. The order must be set again, on purpose. Treat the order as part of the change, and include it in the plan: “Add Beta Testers entry, place it below Staff and above Premium.”

Cloning an environment

Flagsmith can create a new environment by cloning an existing one. A clone generally copies feature states, values and segment overrides. Whether it preserves the order of overrides exactly is something to check in your own version, by opening a few features in the clone and comparing the lists to the source. Do not assume. If the clone will be used to rehearse a launch, confirm the order before you trust it.

Drift between environments

Over time, small differences creep in. Production gains a hotfix entry that Staging lacks. Staging gets a test segment that Production never needs. Once a quarter, compare the lists of your most important features in all environments and write down why each difference exists.

Flagsmith can decide the answer in two places. The priority rules are the same in both.

Remote evaluation

In remote evaluation, the app asks Flagsmith for flags and Flagsmith works out the answer on its servers, using stored traits and any sent with the request. Segment priority is applied by Flagsmith.

Local evaluation

In local evaluation, a trusted server program downloads the whole environment configuration, including features, segments, overrides and their order, and works out answers by itself using the traits you supply. The same priority order is applied, using the same rules, by code inside the SDK.

What can differ

Planning around the delay

• After reordering, expect servers using local evaluation to catch up only after their refresh.
• For urgent safety changes, check that your servers refresh quickly enough, or use a short refresh interval for those services.
• Do not test a new order from a service that uses an old copy, or you will think the change failed.

Different SDKs, same promise

Flagsmith aims for every SDK to give the same answer for the same data. If you ever see a different result between two SDKs for the same user, check the trait values being supplied, and check SDK versions. Differences are usually in the input, not in the ordering logic.

Reordering is a real change with real effects. Flagsmith offers controls that help you handle it with care.

Reordering as a guarded change

Some plans of Flagsmith offer an approval workflow, sometimes called change requests, where a second person must approve a change to a protected environment before it goes live. Changes to segment overrides, and potentially their order, may be covered. Which actions are guarded can differ by version, so test it once in Staging and write down the result. If reordering is guarded, use the workflow for production lists that affect many users.

What a reviewer should check

Versioning

Some versions of Flagsmith keep numbered versions of a feature’s settings in an environment, so that you can see earlier states and prepare a future state. If your version has this, the order of segment overrides may be part of each version. Check whether you can see how the order looked a week ago. This is very helpful when someone asks, “What was the order last Tuesday, when this complaint happened?”

Scheduling

Where scheduling is available, a planned change can take effect at a chosen time. If a launch needs a new order to apply at the same moment as a new entry, plan both changes together, so that the list is never in an in-between state that nobody reviewed.

The audit log

Flagsmith’s audit log records who changed what and when. Reordering should appear there. If a group of users suddenly receive different values, look at the audit log for the feature in that environment, and see whether anyone changed an entry or moved one a few minutes earlier.

To trust a system, it helps to know what it is made of. Here are the parts behind segment ordering.

The building blocks

flowchart LR
    TEAM["Team in Dashboard"] --> API["Flagsmith API"]
    API --> DB[("Database")]
    DB --> OV["Segment override records with rank"]
    DB --> SEG["Segments and rules"]
    DB --> ID["Identities and traits"]
    APP["App with SDK"] --> API
    API --> ENG["Evaluation Engine"]
    ENG --> OV
    ENG --> SEG
    ENG --> ID
    ENG --> CACHE["Read Cache or Edge Layer"]
    CACHE --> APP

The rank is just a number

Inside the database, each segment override record carries a rank, essentially a number that says where it sits in its feature’s list. The dashboard shows this as an ordered list. When you drag an entry, the numbers are updated so that the list reads in the new order. The engine sorts by these numbers and walks the list.

Two kinds of traffic

Flagsmith handles flag reading, which is constant and heavy, and management actions such as reordering, which are occasional. The two paths are kept apart, so a busy dashboard does not slow down apps. A reordering is saved on the management side, then copied to the fast read layers, after which apps see the new order.

Let us follow a single drag-and-drop from the dashboard until the apps see the new order.

Step by step

sequenceDiagram
    participant T as Team Member
    participant D as Dashboard
    participant A as Flagsmith API
    participant S as Database
    participant C as Read Cache
    participant P as Apps and SDKs
    T->>D: Drag Premium above India
    D->>A: Save new order for feature and environment
    A->>S: Update ranks together
    A->>S: Write audit entry
    A->>C: Refresh cached data
    P->>C: Request flags
    C-->>P: Answers using the new order

All-or-nothing updates

The rank updates are saved as a group, called a transaction. A transaction either completes fully or not at all. Think of paying in a shop: either the money leaves your account and you get the goods, or neither happens. For ordering, this means the list is never left half-reordered, with two entries sharing a rank or an entry missing.

Why the read path stays fast

Apps do not wait for the reorder. They keep reading from fast layers, and receive the updated data when it arrives. The management write takes a moment, the read refresh takes another moment, and in total most changes appear within seconds.

A ranked list is not a one-time creation. It grows, drifts and eventually needs cleaning. Planning for its life prevents decay.

Stage 1: Birth

The first segment override is added to a feature. The list has one entry, and order is meaningless. This is the cheapest moment to decide on a pattern.

Stage 2: Growth

More entries arrive: staff, plans, regions, a pilot customer. Each new entry must be placed. Without a pattern, the list grows in the order things were added, which is rarely the order things matter.

Stage 3: Complexity

Overlaps multiply. Exceptions are added above rules. Someone adds an entry to fix an urgent problem and puts it on top. The list becomes hard to read from top to bottom.

Stage 4: Drift

The list no longer matches the original plan. Entries remain whose purpose nobody remembers. Staging and Production differ. Documentation is out of date.

Stage 5: Cleaning

A team reviews the list, deletes dead entries, moves entries back to the pattern and rewrites the plan. The list becomes short and readable again.

stateDiagram-v2
    [*] --> Born: First override added
    Born --> Growing: More segments attached
    Growing --> Complex: Overlaps and exceptions pile up
    Complex --> Drifting: Plan and reality diverge
    Drifting --> Cleaned: Review, delete, reorder
    Cleaned --> Growing
    Growing --> Retired: Feature fully launched and flag removed
    Cleaned --> Retired
    Retired --> [*]

What to do at each stage

Temporary entries need exits

Rollout rings, incident switches and pilot groups are meant to be temporary. If nobody removes them, they remain in the list long after their purpose is gone, still holding positions of power. Attach an end date or a ticket to every temporary entry, so that someone is responsible for removing it.

Products with millions of users need targeting that stays fast. Here is how list length and order interact with performance.

The cost of walking a list

For each flag request, Flagsmith must walk the ranked list for each feature until it finds a match. A short list costs almost nothing. A long list, with many entries and complicated rules, costs more, because each test of membership means comparing traits against rules. Because the walk stops at the first match, placing entries that match many users near the top can also save work.

Ways to keep it light

Availability

If Flagsmith has a bad day, apps should keep working. Give every flag a safe default value in the code, so features fall back to sensible behaviour. Let SDKs keep a recent copy of flags where possible. Managed Flagsmith spreads reads across fast layers. A self-hosted installation can run several copies of the API behind a load balancer, with a standby database.

Scaling the human side

The more entries a list has, the more people it takes to understand it. Splitting products into separate projects, keeping a clear pattern and documenting precedence scale the human side far better than any software setting.

Whoever controls the order controls what users receive. That deserves care.

Order is power

Moving one entry can switch a safety rule behind a convenience rule, or hand a premium feature to a group that should not have it. Because the power is so concentrated in one list, limit who can edit it in production.

A sensible permission model

Separation of duties

Many standards want one person to propose an important change and another to approve it. Use the approval workflow, where your plan offers it, for production lists. The record shows who proposed and who approved each reorder.

Audit and traceability

The audit log answers: who changed the order, when, and in which environment. For regulated businesses, this is part of the evidence that changes are controlled. Combine the audit log with a written plan, so reviewers can see both what changed and why.

Least privilege

The principle of least privilege says people should have only the access their work needs. In this context: engineers who only occasionally change production lists should propose and let others approve, instead of holding permanent edit rights.

Protect the keys

Servers that use local evaluation download the entire set of rules and orders using a server-side key. That key can read your targeting rules. Store it in a secrets manager, keep it out of client apps, and rotate it from time to time.

The most common support question about priority is “why did this user get that value?” A calm routine answers it quickly.

The routine

Read the list aloud

A surprisingly effective technique is to read the list aloud like a bouncer: “Is this person Staff? No. Premium? Yes. Then Premium wins.” Saying it slowly often reveals an entry that does not belong.

Common explanations in order of frequency

A ranked list is a small program. Like any program, it needs tests, especially where groups overlap.

Build an overlap test matrix

For each feature, list the segments in order. Then list imaginary users who belong to each combination that matters. For every one, write down the expected value, and check it against Flagsmith using fake identities in a safe environment.

Test in Staging that looks like Production

Use a staging environment with the same segments and the same order as Production. Name test users so they cannot be mistaken for real ones, such as “test-premium-india-01”. Never test by editing real customers’ traits.

Test after every change

• After adding an entry: test one user inside the new segment and one who is also inside an older, higher segment.
• After reordering: test every overlap that involves the moved entry.
• After deleting an entry: test users who used to match it, and see where they land.
• After changing a segment’s rule: test users near the edge of the rule.

Keep the test table

Store the matrix with the feature’s documentation. When the list changes, update the table. A table that is reused gets better over time and catches mistakes in future changes.

Mistakes will happen. Good teams know the usual ones and have a calm response ready.

Scenario 1: A new entry swallowed an old one

A broad segment was added at the top. A narrow segment below it stopped working, and nobody noticed until a pilot customer complained. Response: move the narrow entry above the broad one, test the overlap, and add the case to your test table.

Scenario 2: A safety entry was pushed down

During a launch, a new rollout entry landed above the safety entry. A bug on one browser reappeared for users in the rollout. Response: move the safety entry back to the top at once, then review the pattern and who may edit the list.

Scenario 3: A reorder was applied in the wrong environment

Someone meant to change Staging and changed Production. Response: restore the old order, which you wrote down beforehand, check a few users and write a short incident note. Reduce the chance of a repeat by using clear environment names and approval workflows for production.

Scenario 4: A segment was deleted

Entries that depended on it disappear from lists, and users fall to the next match or the default. Response: recreate the segment with the same rule, reattach it in the correct positions and test. This is why deletion should be rare and planned.

Scenario 5: Staging and Production disagree

A launch works in Staging and fails in Production because the order differs. Response: compare the lists, align them with the plan and note which differences are intended.

Scenario 6: Local evaluation shows an old order

A server keeps behaving the old way after a reorder. Response: check its refresh interval, force a refresh if possible and look for an old SDK version.

flowchart TD
    S["Unexpected value for some users"] --> Q1{"Did the list change recently?"}
    Q1 -- "Yes" --> A1["Compare with the old order and restore if needed"]
    Q1 -- "No" --> Q2{"Is the user's data right?"}
    Q2 -- "No" --> A2["Fix traits and sync sources"]
    Q2 -- "Yes" --> Q3{"Is the app using the right environment and a fresh copy?"}
    Q3 -- "No" --> A3["Correct the key or refresh the app"]
    Q3 -- "Yes" --> A4["Read the ranked list from the top and look for swallowing"]

Habits that make recovery easy

• Write down the old order before every change.
• Keep a short, tested reference order for each feature family.
• Use approvals for production lists that affect many users.
• Have a one-minute undo plan for every launch.
• Practise: once a quarter, rehearse restoring a list in Staging.

Ranked lists are simple and powerful. They also have costs. Here is an honest look.

First match versus combining

In some systems, several matching rules can add their effects together. In Flagsmith’s ranked list, the first match wins and nothing is combined. This is simple and predictable, but it means that if you want “premium customers in India get both the premium limit and the India bonus”, you must create a segment for that exact combination and place it above both.

One list versus many segments

Flexibility versus safety

The freedom to add any entry anywhere is also the freedom to break precedence. Use permissions, approvals and written patterns to keep the freedom useful.

Patterns are habits that other teams have already tested. Anti-patterns are habits that looked clever and then caused pain.

Pattern 1: The standard ladder

Use one standard order for all features: safety, deliberate exceptions, staff, plans from highest to lowest, regions, rollout rings. Every feature starts from this ladder, and teams delete the rungs they do not need.

Pattern 2: Combination segments above components

When a combination of groups needs a special result, create a segment for the combination and place it above the two component segments. Name it clearly, such as “Premium in India”.

Pattern 3: Derived traits

Compute a single label in your backend, such as “customer_tier”, from many raw facts. Segments then read one trait, and overlaps shrink because the tiers do not overlap.

Pattern 4: Safety shelf

Keep a small set of segments, such as “Known Bad Browser” or “Unsupported App”, whose only job is to protect users. They always sit at the top, and only a few trusted people may edit them.

Pattern 5: Temporary rungs with tickets

Every temporary entry carries a ticket number in its name or description and an expected removal date. Review them weekly during a launch.

Experienced teams build a few simple habits. Beginners tend to make the same few slips.

Best practices

Common mistakes

Troubleshooting guide

A good order is easy to break and easy to forget. Written habits keep it alive when people change jobs.

The priority map

A priority map is a one-page document that shows, for each important feature family, the intended order of segments and the reason for each position. It is the plan against which reality is checked. It does not need to be fancy. A table is enough.

Who owns the order?

Every feature has an owning team, and that team owns its list. The owner decides the order, with advice from the owners of the segments involved. A shared segment such as Staff has its own owner, who must be told when its position or definition changes.

Change notes

Whenever you change an order, write a short note: which feature, which environment, what moved, why, who is affected, how to undo. Put it in a change log or in the change request. A year later, these notes answer questions that nobody else can.

Regular reviews

• Weekly during a launch. Check temporary entries and the status of rings.
• Quarterly in normal times. Compare actual lists with the priority map, and clean up.
• After incidents. If a surprise was caused by order, update the map and the tests.

Teaching newcomers

New teammates should learn four things in their first week: the three layers of authority, the standard ladder, how to debug a user’s value and where the priority map lives. A short walk-through with a real example from your own project is worth more than a long manual.

Once you master the basics, the real art is keeping lists short, consistent and easy to change.

Combination segments and the explosion problem

Because the first match wins and nothing is combined, special results for combinations need their own segments. With three plans and three regions, covering every pairing could mean nine combination segments. With more dimensions, it explodes. If you find yourself creating combination segments again and again, step back.

Solution 1: Derived traits

Compute in your own backend a single trait, such as “offer_tier”, that already includes the logic you want: “gold_india”, “gold_other”, “basic”. Flagsmith then needs one segment per tier, and there are no overlaps. The complexity moves into code you control, where it can be tested with ordinary tools.

Solution 2: Separate features for separate decisions

If one feature must answer too many questions, split it. Instead of a single “delivery_fee” with a long list, create “delivery_fee_by_plan” and “delivery_fee_regional_discount”, each with a short list, and let the app combine the two answers. Each list stays simple, and the combination is explicit in code.

Solution 3: Use values, not segments

Sometimes the app can receive a value and do the combining itself. A feature that returns a base number and another that returns a bonus number can be added in code. This keeps Flagsmith simple and puts arithmetic where it belongs.

Consistency across features

If twenty features use the same five segments, strive for the same relative order in every list. When a rule must be different, note why. Consistency lets reviewers spot mistakes by pattern: “This list has Premium above Staff, which is different from all the others. Is that on purpose?”

flowchart TD
    A["Many overlapping segments in lists"] --> B{"Are the same combinations repeated across features?"}
    B -- "Yes" --> C["Create a derived trait in the backend"]
    B -- "No" --> D{"Does one feature answer unrelated questions?"}
    D -- "Yes" --> E["Split it into separate features"]
    D -- "No" --> F["Keep the list and use the standard ladder"]
    C --> G["Shorter lists, fewer overlaps"]
    E --> G
    F --> G

Replacing a segment safely

When a segment must change in a major way, create the new version beside the old one, attach it to features just below the old one, compare results with test users, switch the order, and then delete the old one. This avoids a sudden change in who matches many features at once.

Measuring list health

• Average and longest list length per feature.
• Number of entries not matched by any user in the last month.
• Number of temporary entries past their end date.
• Number of differences between Staging and Production lists.
• Number of identity overrides per feature.

Let us follow a made-up online shop, “Acme Cart”, through a full piece of work to see how the ideas fit together.

The situation

Acme Cart has two million monthly shoppers, three plans (free, standard, premium), staff accounts and operations in several countries. The team wants a feature called “delivery_fee” with the following business rules, agreed with the product owner: premium customers always pay nothing; staff always pay nothing; customers in a launch region get a reduced fee during the launch; everyone else pays the standard fee. An old app version cannot show fees correctly and must see a flat fee.

Stage 1: Write the rules as sentences

The team writes each overlap as a sentence. “When a user is premium and in the launch region, they pay nothing.” “When a user is on the old app and premium, they still see a flat fee, because the old app cannot show nothing correctly.” The second sentence reveals that the old-app rule is a safety rule and must be on top.

Stage 2: Choose the order

flowchart TD
    U["User asks for delivery_fee"] --> I{"Identity override?"}
    I -- "Yes" --> V0["Personal value"]
    I -- "No" --> A{"Old App Versions?"}
    A -- "Yes" --> V1["Flat 5"]
    A -- "No" --> S{"Staff?"}
    S -- "Yes" --> V2["0"]
    S -- "No" --> P{"Premium Users?"}
    P -- "Yes" --> V3["0"]
    P -- "No" --> L{"Launch Region?"}
    L -- "Yes" --> V4["2"]
    L -- "No" --> V5["Default 5"]

Stage 3: Build and test in Staging

The team builds the list in Staging and creates test users: a free user in the launch region, a premium user in the launch region, a staff member on the old app, a standard customer elsewhere and a user with no plan trait. They check each result against the table. They notice that the staff member on the old app gets a flat fee, as designed, and that the user with no plan falls to the Launch Region entry if in the region. All match their expectations.

Stage 4: Review and apply in Production

An engineer proposes the same list in Production through a change request, including the order and the test table. A second engineer reviews each overlap against the written sentences and approves. The change is applied. The team checks a handful of real accounts and watches checkout graphs for an hour.

Stage 5: A surprise and a fix

Two days later, a customer success manager reports that a loyal customer, who was promised free delivery in a contract, is being charged the launch-region fee. The team finds that the customer is not premium, and so lands on Launch Region. They create a segment “Pilot Customer A” with a rule on the trait “company_id”, place it at rank 2, below the safety entry and above Staff, add a test user and update the priority map. The customer receives free delivery on the next request.

Stage 6: Clean up after the launch

When the promotion ends, the team removes the Launch Region entry, checks which users fall to the default and confirms that nothing else depended on it. They update the priority map and close the ticket.

Ordered, first-match-wins lists are everywhere in engineering and in daily life. Seeing them elsewhere makes Flagsmith’s behaviour feel familiar. The descriptions below are general patterns, not details of any private system.

Network firewalls

Many firewalls hold a list of rules, from top to bottom, and apply the first rule that matches a network packet. Administrators learn quickly that a broad “allow all” rule placed too high makes later “block” rules useless. The advice is the same as in this guide: specific rules first, broad rules last, and review the list regularly.

Web server and routing rules

Web servers and routers often check rewrite or routing rules in order. A rule that catches every address, placed early, hides all rules after it. Teams that run big websites keep these lists short and tested, for the same reasons.

Email filters

Many email programs apply filters in order: “if from my manager, mark as important; if contains the word offer, move to promotions”. When two filters could match, the earlier one wins. Anyone who has seen an important email hidden in a promotions folder has met the problem of priority.

Style rules on web pages

On web pages, the more specific a style rule is, the more it wins over general ones. This is an example of “specific beats general” that developers meet daily, and it mirrors the guidance to place narrow segments above broad ones.

Large product companies and feature gates

Facebook has described internal gating systems that decide who sees a feature using attributes such as employee status and country, usually starting with employees and widening step by step. Netflix and Google have written about careful, staged exposure of changes. In all these systems, clear precedence between groups is part of keeping rollouts predictable.

Airlines and queues

Airlines board passengers by a fixed order of groups, so that no gate agent needs to decide on the spot. The principle of a written, ranked list that anyone can follow is the same.

Laws and contracts

Legal systems often have a rule that a specific provision overrides a general one. Contracts often say which document prevails if two clauses disagree. The pattern gives predictable outcomes when instructions overlap.

Experienced pilots do not trust memory for routine steps, and neither should you. Copy these into your team wiki.

Before you add a segment override

• Write the business rule as a sentence for every overlap with existing entries.
• Decide the position using the standard ladder.
• Check the environment and the feature twice.
• Prepare test users for each overlap.
• Write the old order and the undo step.

Before you reorder

• Copy or screenshot the current list.
• Check for safety entries that must stay on top.
• Check for identity overrides that may hide the effect.
• Ask for a review if the environment needs it.
• Pick a quiet time and tell the people who need to know.

After a change

• Test every overlap with fake users.
• Check a few real accounts.
• Watch error and business graphs for the next hour.
• Update the priority map and the change log.

When a user reports a surprise

• Check identity overrides first.
• Check traits for spelling, type and freshness.
• List the user’s segments, then read the list from the top.
• Check the environment key and any cache or refresh delay.
• Check the audit log for recent edits.

Every quarter

• Compare real lists with the priority map.
• Remove entries nobody matches and temporary entries past their date.
• Compare Staging and Production lists.
• Review who can edit lists in production.
• Rehearse a restore of an old order in Staging.

A short reference for the words used in this guide.

Quick answers to the questions that come up most often.

Let us pull the whole story together in a few lines you can remember.