Subscription Entitlements¶
Overview¶
Badger Commerce is sold through Badger Sett as two editions:
| Edition | Sett tool slug | What it is |
|---|---|---|
| Badger Commerce Lite | commerce-lite |
Keyword search, hand-curated collections, no taxonomy engine |
| Badger Commerce Enterprise | commerce-enterprise |
Badger Search, faceted navigation, autocomplete, the taxonomy engine, dynamic collections |
Registered charities buy the Charity plan, which is not a third edition: it is a plan
(charity) inside commerce-lite, so a charity gets Lite's search and collections plus the
charity fundraising features that no self-serve Lite plan
has.
Same platform, same code, same database — the difference is a configuration change, not a replatform. Which means the platform has to know which edition each shop is on. Two things can tell it, and Badger Commerce writes the answer down per shop:
- Platform billing. A shop's own subscription to Badger Commerce, on a plan from the platform's plan catalogue, is projected onto its entitlement record (see Platform billing projection).
- Badger Sett, by webhook, for shops still subscribed through Sett while billing moves in house.
Enforcement ships switched off
The gates are built and running, but they refuse nothing until
badger.sett.entitlements.enforce is turned on. Until then they evaluate, log what they
would have refused, and let the request through. See
Enforcement.
Two rules that govern everything¶
Fail open. A shop with no entitlement record has full access. Every shop on the platform predates this system, and none of them may quietly lose a feature because Badger Sett has not got round to telling us about them. "We have never heard of this shop" is not the same as "this shop is entitled to nothing", and the code treats them differently.
Enforcement is a switch, and it starts off. Recording the tier is the immediate goal. Withholding features on the strength of it comes later, once the recorded data has been checked against reality.
The capability vocabulary¶
The capability vocabulary is Badger Commerce's own. It began as a copy of Badger Sett's keys and still spells every one of them the same way, so a record written by the Sett webhook reads as it always did. Newer capabilities, such as the hospitality ones, exist only on the Badger Commerce side.
| Capability | Lite | Lite charity plan |
Enterprise |
|---|---|---|---|
search |
keyword |
keyword |
badger-search |
facetedNavigation |
false |
false |
true |
autocomplete |
false |
false |
true |
searchSuggestions |
false |
false |
true |
collections |
manual |
manual |
dynamic |
productVariants |
true |
true |
true |
taxonomyEngine |
(absent) | (absent) | true |
taxonomyAttributes |
false |
false |
true |
merchandisingRules |
(absent) | (absent) | true |
largeCatalogue |
false |
false |
true |
giftAid |
false |
true |
true |
regularGiving |
false |
true |
true |
fundraisers |
false |
true |
true |
multiLocationInventory |
false |
false |
true |
clickAndCollect |
false |
false |
true |
storeFulfilment |
false |
false |
true |
tableBookings |
false |
false |
true |
appointments |
false |
false |
true |
restaurantOrdering |
false |
false |
true |
kitchenBoard |
false |
false |
true |
tableService |
false |
false |
true |
payAtTable |
false |
false |
true |
posTerminal |
false |
false |
true |
"Lite" here means the self-serve plans: Starter, Growth and Pro.
The last seven are the hospitality and point-of-sale capabilities: online table bookings, appointments with bookable people, takeaway and delivery ordering, the kitchen board, dine-in table service, paying at the table and in-person card sales on the operator app. Neither edition's Lite defaults include them; the plans that sell them (Bookings, Takeaway, Restaurant) turn them on, and Enterprise has them all. No gate checks them yet.
Two things to notice.
taxonomyEngine and merchandisingRules are absent from Lite rather than set to false.
Absent reads as disabled — the two spellings mean the same thing here.
search and collections are string-valued, not booleans. For gating purposes only the
enterprise value counts as enabled (badger-search, dynamic); the raw string is still readable
for code that needs to tell keyword apart from "no value at all".
Where a capability's answer comes from¶
In order:
- No record for the shop → granted. Fail open.
- Record exists, subscription no longer entitling (cancelled, unpaid, incomplete, paused) →
refused.
past_duestill entitles, deliberately: a failed renewal starts the dunning chase, and switching a live shop's search off the moment a card expires is worse than carrying it through the grace period. - The stored
limitsmap carries the key → that value decides it. The map is the live source of truth, because a plan'scustomLimitscan override its edition's defaults. - Otherwise → the edition default from the table above.
- Absent from both → refused.
Step 5 has one exception: if the stored tool slug is not a Badger Commerce edition at all — a corrupt row, or a tool the platform does not model — there is no edition to fall back to, and refusing on the strength of a row we cannot interpret would break the fail-open promise. That case grants, and logs a warning.
Platform billing projection¶
A shop subscribed to Badger Commerce directly has a platform subscription: a plan, any add-ons, any
extra locations and any one-off limit allowances granted by Badger staff. Whenever that subscription
is saved, or its plan or one of the plan's add-ons is edited, the shop's entitlement record is
rewritten from it. Editing a plan rewrites the record of every shop on it; that runs in the worker
(the billing-plan-reprojection-queue), not in the request that saved the plan, so a plan with many
shops never slows the editor down. Plans, add-ons and subscriptions are managed under
System › Billing.
The capability map is built in this order, each step overriding the one before:
- the plan's edition defaults (the table above);
- the plan's own capability overrides;
- each add-on's capability overrides, in the order the shop took them;
- the shop's effective limits: the plan's limit, plus add-ons, extra locations and allowances
still in force. Staff and monthly active customers are set per location, so the plan's figure
(plus add-ons) is multiplied by the shop's location limit, and an allowance is then added for the
shop as a whole. An unlimited limit is stored as
null; - the plan's application fee, as
applicationFeePercentandapplicationFeeFixedMinor(pence). This is the fee taken on the shop's paid orders and POS sales, unless the shop has its ownbadgerApplicationFeePercentage/badgerApplicationFeeFixedsetting (see Platform billing with Stripe).
The limits are stored under these keys:
| Key | |
|---|---|
maxProducts |
Products |
maxAdmins |
Admin users |
maxLocations |
Locations, including extra locations bought |
maxBookablePeople |
People customers can book appointments with |
maxTableBookingsPerMonth |
Online table bookings per calendar month |
customDomain |
true / false: may the shop use its own domain |
maxStaff |
Staff accounts: admins, POS, kitchen and floor devices. Per location |
maxMonthlyActiveCustomers |
Distinct customers with an order, booking or appointment in the shop's calendar month. Per location. A warning, never enforced |
A missing or unreadable limit reads as unlimited, as does a shop with no record at all. Going over a limit never blocks anyone in admin; what happens on the storefront, how usage is counted and who is told is described in Plan Limits.
Per location means the number on the plan is for one location. A Restaurant shop allowed 20 staff and 5,000 monthly customers per location, with one extra site bought, may have 40 staff and is warned above 10,000 customers a month. Anything that raises the location limit (an extra location, an add-on or an allowance) raises both. A shop whose location limit is unlimited has no limit on either.
maxMonthlyActiveCustomers is advisory. Going over it shows a banner in admin, tells Badger staff
and invites the owner to upgrade, but the shop keeps taking orders and bookings. maxStaff is
enforced: staff beyond the limit can't sign in to the app or the POS, while the owner and admin keep
working.
Every plan a shop can take for itself has limits, Enterprise included: products, admins and locations are always capped. Only a custom plan that Badger staff set up for one customer, and assign to that shop, can be unlimited.
A one-off allowance with an expiry date stops counting within the hour: the record notes when it
is due to be rewritten (reprojectAt), and the worker rewrites every record that is due once an
hour (badger.billing.reprojection-schedule).
A record written by platform billing replaces a Badger Sett one for the same shop. The shop's Sett organisation is kept on the record until Sett is retired. From then on the platform subscription wins: a Sett webhook or a reconcile for that shop changes nothing but the organisation id, so a shop moved onto a platform plan can't fall back to its old Sett plan.
The record follows the subscription a moment after it is saved, not in the same request: the update runs in the background, and always reads the subscription as it is stored then, so two changes made close together end with the record showing the later one.
Charity fundraising: the Charity plan¶
Gift Aid, Gift-Aided regular giving and supporter fundraisers are sold only on the Charity plan (and Enterprise), never on the self-serve Lite plans. One-off donations are not gated: every Lite shop can take them.
| Capability | What it covers |
|---|---|
giftAid |
A donor's Gift Aid declaration (at checkout, on the basket, on the account page) and the monthly HMRC claim |
regularGiving |
Gift Aid on recurring donations. The recurring gift itself still runs on any plan |
fundraisers |
Supporters starting a fundraising page, and an admin creating or approving one |
Why it is a plan and not an edition. A charity's site is a Lite site in every other respect,
and BC models editions as Sett tools, each with its own webhook signing secret and API key. A plan
needs none of that: the charity plan's customLimits carry the three keys as true, they arrive
in the limits map, and the map beats the Lite default (rule 3 above). The Lite default for all
three is false, so a Lite row recorded before Sett shipped these keys reads as "no charity
features", which is what a self-serve Lite plan is.
How a charity gets it. The Charity plan is Contact Sales (isCustomPricing) in Sett, so it
offers no self-serve checkout. Kedos provisions each charity by hand: a CustomPlanOffer for the
organisation, pointing at the charity plan and carrying the charity's Stripe price. The resulting
subscription ships the charity plan's limits.
Charities with no Sett subscription are unaffected. Derby MRT and Peak District MRO, and every other shop without an entitlement record, keep all three features under the fail-open rule.
Linking a shop to a Badger Sett organisation¶
Sett identifies a customer by organisation, never by shop. The join key is a per-shop setting:
| Setting | Where | Default |
|---|---|---|
Badger Sett Organisation ID (sett-organisation-id) |
Admin → Site Configuration → entitlement-config |
(unset) |
Set it to the Sett organisation that owns the shop's subscription. One organisation may run several shops — set the same value on each, and a subscription change applies to all of them.
Leave it blank and the shop is treated as unsubscribed, which — per the fail-open rule — means it keeps every feature.
The webhook¶
Served by the REST app (api.bdgr.co.uk). Configure this URL as the webhook URL on both the
commerce-lite and commerce-enterprise Tools in Badger Sett.
Authentication is the signature¶
The endpoint is unauthenticated at the security layer. The HMAC is the authentication:
X-Badger-Signature-V2— HMAC-SHA256, hex, over the exact raw bytes of the request body, keyed by the signing secret of the Sett Tool named indata.toolSlug.- Compared in constant time.
- The older
X-Badger-Signaturecovers only the re-serialiseddatasub-object, which would mean reproducing JavaScript'sJSON.stringifybyte-for-byte from Java. It is ignored — accepting a weaker signature as a fallback would just move the attack to the weaker one.
The two editions are separate Tools in Sett with separate signing secrets, so the secret is
looked up per tool slug. A delivery naming a tool we hold a secret for is bound to that secret,
which is what stops a leaked commerce-lite secret being used to assert an enterprise
subscription. A delivery naming no tool at all (Sett's user and organisation provisioning events
are not tied to one) falls back to trying every configured secret.
The signature covers the body, so the id and type inside the envelope are authenticated
while the X-Badger-Event-ID and X-Badger-Event-Type headers are not. The signed values win; the
headers are only a fallback for a payload that omits them.
Payload¶
{
"id": "evt_01J8Z4Q0000000000000000000",
"type": "ORGANISATION_SUBSCRIPTION_UPDATED",
"occurredAt": "2026-08-24T10:30:00Z",
"data": {
"organisationId": "org_abc",
"toolSlug": "commerce-enterprise",
"subscription": {
"status": "active",
"plan": "growth",
"currentPeriodEnd": "2026-09-24T10:30:00Z",
"limits": { "search": "badger-search", "facetedNavigation": true }
}
}
}
What gets acted on¶
| Event | Behaviour |
|---|---|
ORGANISATION_SUBSCRIPTION_CREATED |
Recorded |
ORGANISATION_SUBSCRIPTION_UPDATED |
Recorded |
ORGANISATION_SUBSCRIPTION_CANCELLED |
Recorded — status only; the plan and capability map we already had are kept, so the record still shows what the shop used to have |
ORGANISATION_PROVISIONED |
Acknowledged, ignored |
USER_PROVISIONED / USER_DEPROVISIONED / USER_ROLE_UPDATED |
Acknowledged, ignored |
| Anything Sett adds later | Acknowledged, ignored |
Why almost everything answers 2xx¶
Badger Sett retries a non-2xx delivery five times — after 1m, 5m, 15m, 1h and 4h — and then drops it permanently. So anything other than "we cannot authenticate you" or "we cannot read this" is acknowledged:
| Response | When |
|---|---|
200 APPLIED |
Recorded against at least one shop |
200 DUPLICATE |
A retry of something already handled |
200 IGNORED |
An event type this platform does not act on |
200 NOT_A_COMMERCE_TOOL |
A subscription for another Badger tool |
200 UNMAPPED_ORGANISATION |
No shop has that sett-organisation-id. Logged as a warning — it is a configuration gap here, and retrying cannot fix it. Once the organisation id is set on the shop, use the refresh below to pick the subscription up; the missed webhook will not be redelivered |
401 |
Signature missing, malformed, or not verifying |
400 |
Body unreadable as an event envelope |
Idempotency¶
Deliveries are deduplicated on the signed event id, which is stored as the primary key of a receipt document. The insert is the lock: two nodes handed the same retry at the same moment both try, and exactly one wins on the primary key. Receipts expire after 30 days.
If processing fails midway, the claim is released so Sett's retry can still work — a transient database blip must not be recorded as "handled".
Where the gates are¶
Each gate sits at the single chokepoint everything else funnels through, and returns something callers already handle. That is the point: the "not entitled" path is an existing, tested path, not a new error case.
| Capability | Chokepoint | Not entitled → |
|---|---|---|
taxonomyEngine |
TaxonomyService.getActiveTaxonomy |
null — the same as a shop with no active taxonomy. Facet defaults, the search indexer's node resolution, the admin panels and the MCP tools all read through here |
facetedNavigation |
MerchandisingTreeService.resolveFacetConfig |
An empty facet config — the facet rail does not render; products, sorting and pagination are untouched |
autocomplete |
MerchandisingQueryService.suggest and MerchandisingTreeService.suggestNodes |
An empty list — the type-ahead dropdown stays shut, the search box still submits |
giftAid |
DonationProductTypeDecoratorImpl.populateLineItem (add to basket, storefront and REST) and DirectCheckoutServiceImpl.applyLinePatches (unified checkout) |
The donation is taken with giftAidAcceptance=false, as if the box were unticked. The checkbox, the basket's "Add Gift Aid now" prompt, the fundraiser widget's uplift and the account page's "make a declaration" form are not shown, and that form's post is ignored |
giftAid |
GiftAidSubmissionScheduler (monthly claim) and GiftAidRetryListener (admin retry) |
The site is skipped with a warning. Its donations stay unsubmitted, so a later run claims them (within the four-tax-year lookback) if the shop moves onto the Charity plan. GiftAidPollScheduler is not gated: it only follows up claims HMRC already has |
regularGiving |
SubscriptionServiceImpl.createFromStripeSubscription and InvoiceServiceImpl.createDonationForInvoice |
The subscription is not marked Gift Aid eligible, and each payment's donation carries no Gift Aid declaration. The recurring gift still runs |
fundraisers |
FundraiserService.isFundraisingAvailable, checked by the storefront FundraiserController (save and auto-save) and the admin FundraiserAdminController (create and approve) |
The supporter sees "Fundraising pages aren't available on this site"; the admin is told the feature is on the Charity plan. Deleting a draft still works, the "Start a fundraiser" extension renders nothing, and fundraisers that are already live keep running |
multiLocationInventory |
LocationService.save (admin, REST, MCP and site import all save through it) and LocationService.isMultiLocationActive |
A second stock-holding location is refused with CapabilityRequiredException: the admin form explains it, REST answers 403 with the reason, MCP tells the agent the plan doesn't include it, and the import skips it with a warning. The shop keeps its default location and can still add locations that hold no stock |
clickAndCollect |
LocationService.isStoreCollectionActive (with click-and-collect-enabled and multiple stock locations on) |
Collection stays the single pickup from the main location, if the shop offers it: no per-store options at checkout, no store picker or "Collect from Leeds: in stock". The Locations screen shows the "collect from any of my stores" answer locked; see Click and collect. Collecting part of an order and having the rest delivered (split-collection-enabled, HandoverService.isSplitAvailable) sits behind the same gate, so it needs multiLocationInventory too; see Partly collected, partly delivered |
storeFulfilment |
StoreOperationsService.isCapacityManaged (with store-capacity-enabled on) |
Locations take as many orders as come: no daily click and collect or ship-from-store limits, and no capacity-aware routing. The location page shows an Enterprise callout in place of the Capacity card. Temporary closures and special hours work on every plan; see Store operations |
What the admin sees¶
Admin pages never error on a missing charity feature. AdminModelAdvice adds a charityPlan
model attribute (CharityPlanFeatures), and these pages show an "… is available on the Charity
plan" callout (admin/bxFragments :: charityPlanCallout) explaining what does and doesn't happen:
| Page | Capability |
|---|---|
| Fundraisers list and Create fundraiser | fundraisers |
| HMRC submissions and Gift Aid declarations | giftAid |
| Subscriptions list | regularGiving |
Enterprise fulfilment features work the same way: AdminModelAdvice adds an enterprise model
attribute (EnterpriseFeatures), and the Locations pages show an "… is part of Badger Commerce
Enterprise" callout (admin/bxFragments :: enterpriseCallout) saying what the shop keeps and what
Enterprise adds.
The callout uses the enforcing answer (hasCapability), so it appears only once enforcement is on.
While enforcement is off, the feature still works and the admin is not told otherwise.
Not yet gated: the search engine itself
Lite's search: 'keyword' says it does not integrate Badger Search at all, but
MerchandisingQueryService.search is deliberately left ungated. Refusing it outright would
leave Lite shops with no search rather than keyword search, and the keyword fallback does not
exist yet. Gating it needs that fallback built first.
Enforcement is a switch, and it starts off¶
Set in the web, worker and rest apps — the storefront renders gated features, and the worker's search indexer resolves merchandising nodes through the taxonomy, so they have to agree. Keep the three in step or indexing and rendering will disagree about what a shop is entitled to.
With enforcement off (the default), a gate that would have refused something logs it and allows it anyway:
Entitlement shadow-mode: would have refused taxonomyEngine for site acme
(enforcement is off, so it is being allowed)
That log is the point. It lets the recorded entitlement data be checked against what shops are actually using before anything is taken away. Note that a shop with no entitlement record never produces one of these lines at all — it is granted outright, not shadow-granted.
With enforcement on, the same decision is logged as a refusal and takes effect.
Self-serve shops are enforced from day one, whatever the switch says. A shop that signed up and chose its plan through self-serve sign-up never had more than that plan, so there is nothing to check against reality first. Every other shop stays in shadow mode until the switch is turned on: shops on a Badger Sett record, shops migrated from Sett, and shops put on a plan by Badger staff.
The pattern is to build the enforcement, ship it inert, and turn it on per deployment once the shadow log says it is safe.
Drift, and how to repair it¶
A webhook can be lost for good — five failed retries and Sett stops. A shop upgraded during an outage on this side would then sit on a stale tier indefinitely, with nothing to signal it.
Two admin endpoints cover it. Both require an admin or superadmin token and act on the shop in the request's tenant context.
GET /v1/admin/entitlement # what we last heard, and when
POST /v1/admin/entitlement/reconcile # go and ask Badger Sett again
GET returns entitled: false for a shop no subscription has ever been recorded for — which,
again, means it keeps everything rather than nothing. Its enforced flag answers for this shop:
true when enforcement is switched on for every shop, or when the shop signed up self-serve (enforced
from the start), so it never shows a self-serve shop as being in shadow mode.
POST .../reconcile asks Badger Sett what the organisation is currently subscribed to
(GET /api/internal/subscriptions/by-tool) and rewrites the record from the answer. It tries the
recorded edition first, then the other one — because the drift being repaired might be exactly an
upgrade that was missed.
| Result | Meaning |
|---|---|
REFRESHED |
Sett answered and something changed |
UNCHANGED |
Sett answered and we were already up to date |
NOT_MAPPED |
The shop has no sett-organisation-id |
NO_SUBSCRIPTION |
Sett has no Badger Commerce subscription for that organisation |
UNAVAILABLE |
No Sett API configuration, or Sett could not be reached |
Why admin-triggered rather than a scheduled sweep
Sett's internal API answers one organisation and one tool at a time, so a fleet-wide sweep would
be a call per shop per edition against a partner's API, to repair something that should almost
never be wrong — and it would have to run in the worker, which would then need its own copy of
the Sett API keys. Drift is rare, visible through the GET above, and fixable with one request
by whoever spots it. If that stops being true, a scheduled job would call exactly the same
SettSubscriptionService.reconcile method.
There is no Thymeleaf admin panel for this yet — the endpoints are the interface today.
Deployment configuration¶
badger:
sett:
webhook:
signing-secrets:
commerce-lite: ${SETT_WEBHOOK_SECRET_COMMERCE_LITE:}
commerce-enterprise: ${SETT_WEBHOOK_SECRET_COMMERCE_ENTERPRISE:}
api:
base-url: ${SETT_API_BASE_URL:}
keys:
commerce-lite: ${SETT_API_KEY_COMMERCE_LITE:}
commerce-enterprise: ${SETT_API_KEY_COMMERCE_ENTERPRISE:}
entitlements:
enforce: ${SETT_ENFORCE_ENTITLEMENTS:false}
These are deployment secrets rather than per-shop configuration, for a structural reason: an inbound webhook has no tenant. It identifies the shop by a Sett organisation id, which is the thing being looked up — so there is no shop whose configuration the secret could be read from.
Sett enforces that an API key may only query its own tool, which is why the keys are per slug too.
Everything is optional. A deployment with no secrets configured refuses every delivery with a 401 and cannot reconcile — which is correct for a dev box with no Sett behind it, and is why local development works without one.
What is stored¶
One document per shop:
| Field | |
|---|---|
siteId |
The shop |
organisationId |
The Badger Sett organisation, when Sett subscribed the shop |
billingAccountId |
The platform billing account that pays, on a record written by platform billing |
source |
Who wrote the record: SETT or BADGER (platform billing). A record with none predates the field and is Sett's |
selfServe |
true when the shop signed up self-serve; such shops are always enforced |
reprojectAt |
When a time-limited allowance in the record expires, so the record should be rewritten |
toolSlug |
The edition — commerce-lite or commerce-enterprise |
plan |
Plan slug within the edition |
status |
Subscription status (active, trialing, past_due, canceled, …) |
currentPeriodEnd |
End of the billing period |
capabilities |
The projected capability map, or Sett's limits map verbatim |
sourceEventId |
The event, reconcile: marker or billing: marker that last set this |
updatedAt |
When we last wrote it |
The capability map is stored whole rather than projected onto known keys, so a capability Sett
adds tomorrow is already on disk by the time this platform learns to read it — and the numeric plan
limits (maxProducts, perOrderFee, …) stay available without a second round trip.
See also¶
- System › Billing — the plan catalogue, subscriptions and allowances
- Search and Discovery
- Multi-Tenancy
- Self-serve Sign-up and the Plan Catalogue: how a self-serve shop gets its plan, and the public list of plans