Skip to content

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:

  1. No record for the shop → granted. Fail open.
  2. Record exists, subscription no longer entitling (cancelled, unpaid, incomplete, paused) → refused. past_due still 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.
  3. The stored limits map carries the key → that value decides it. The map is the live source of truth, because a plan's customLimits can override its edition's defaults.
  4. Otherwise → the edition default from the table above.
  5. 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:

  1. the plan's edition defaults (the table above);
  2. the plan's own capability overrides;
  3. each add-on's capability overrides, in the order the shop took them;
  4. 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;
  5. the plan's application fee, as applicationFeePercent and applicationFeeFixedMinor (pence). This is the fee taken on the shop's paid orders and POS sales, unless the shop has its own badgerApplicationFeePercentage / badgerApplicationFeeFixed setting (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

POST /v1/webhooks/sett/subscriptions

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 in data.toolSlug.
  • Compared in constant time.
  • The older X-Badger-Signature covers only the re-serialised data sub-object, which would mean reproducing JavaScript's JSON.stringify byte-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

badger:
  sett:
    entitlements:
      enforce: ${SETT_ENFORCE_ENTITLEMENTS:false}

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