Roll out to companies, not users (bucketBy)

B2B rollout bucketed on company_id so a whole account flips together — never half a team on each version.

Production readyOn this page · 4 min readUpdated · June 19, 2026Works with · Server SDK · Dashboard

You're shipping a redesigned admin panel to a B2B product. With a normal 20% user rollout, "Acme Corp" gets a problem: eight of their forty seats see the new panel, thirty-two see the old one. Their admin files a confused ticket, your support team can't reproduce, and the account's trust takes a hit — all because the rollout split inside the account.

The fix is to bucket on the company, not the user, so a whole account flips together.

The primitive: a feature flag (or experiment) with bucketBy set to company_id. Same deterministic, sticky hashing — just on a coarser unit.

1. Configure bucketBy on the flag

Set bucketBy: "company_id" on the flag in the dashboard, CLI, or Admin API. A 20% rollout now means 20% of companies, and every teammate in a selected company resolves to the same answer.

2. Carry the attribute on the user

Your only job in code is to make sure the bucketing attribute is present on the user object the Client is bound to. Carry it through the attributes transform you give configure:

import { configure, Client } from "@shipeasy/sdk/server";

configure({
  apiKey: process.env.SHIPEASY_SERVER_KEY!,
  attributes: (u) => ({
    user_id: u.userId,
    company_id: u.companyId, // ← the bucketing unit
  }),
});

const flags = new Client(session);
const enabled = flags.getFlag("admin-panel-v2");

return enabled ? <AdminPanelV2 /> : <AdminPanelV1 />;

Missing attribute = fallback bucketing

If company_id is absent on the user object, that user falls back to individual user_id bucketing — and you get exactly the split-account problem you were avoiding. Make the attribute non-optional on your session type so it can't go missing.

3. Ramp by account

# 5% of companies — internal + a few design partners
shipeasy flags rollout admin-panel-v2 5

# 25% of companies once support is quiet
shipeasy flags rollout admin-panel-v2 25

# everyone
shipeasy flags rollout admin-panel-v2 100

Each step adds whole accounts. A company is either fully on or fully off — never split.

Rollout & measurement plan

Whitelist your design partners first. Add specific company_ids to a targeting allow-list so they flip on at 0% rollout, independent of the percentage ramp.
Watch per-account, not per-user. A bad rollout shows up as a few accounts churning, not a diffuse user metric. Slice your dashboards by company.
Effective sample size is companies. If you turn this into an experiment, remember the unit of analysis is the account — see Analysis. Fewer units means you need a larger effect or longer run to reach significance.

Was this page helpful?

✎ Edit this page