Backend API Feature Flags: Stable Rollout Targeting for Checkout Reconstruction

Reconstructing failed checkout transactions after a percentage rollout deployment requires deterministic decision-making at the backend. Simply knowing the rollout percentage isn't enough, as shoppers may move between cohorts on consecutive requests.

In a Node.js feature flag implementation, the backend API must evaluate each user request using a stable, non-secret key derived from the user. This key, combined with the selected flag variant, rule revision and evaluation reason, is recorded in a compact decision snapshot attached to the checkout trace.

A hash-based bucketing technique ensures consistent subject assignment across requests, while hash-based bucketing keeps the same subject in the same cohort. The decision snapshot contains the flag key, variant, rule revision and evaluation reason. This allows support engineers to reconstruct what actions occurred during a failed checkout by examining the request ID, snapshot and error details.

The evaluation process uses a deterministic algorithm to map the hash of the flag and subject key into a 10,000-bucket scale. If the subject key is in the targeted cohort, the decision returns either "retry_v2" or "control" variant depending on whether the hash enabled the flag. Otherwise, the default variant is returned.

Important considerations include validating percentages before evaluation, defining targeting precedence explicitly, and keeping the hashing input, byte selection, modulus and subject identifier consistent to avoid reshuffling cohorts. The approach minimizes the amount of sensitive user data included in the decision snapshot while still providing enough context for effective incident analysis.