Marketplace Pricing Controls: 5 API Patterns for Auditable Feature Flags
Marketplace Pricing Controls: 5 API Patterns for Auditable Feature Flags
Short answer: put one typed flag evaluation behind Node.js middleware, record its key and revision with the request trace, and make timeout fallback a separate outcome from an intentional disabled decision.
The useful trade-off in a marketplace pricing rollout is signal quality versus noise. A flag middleware layer should make the pricing decision, its input context, and its evaluation result observable without turning every request into a diagnostic transcript. My default is a small API boundary: read a flag snapshot, evaluate it once per request, attach a stable decision record to request context, and emit one structured event when the decision matters.
This article uses Python snippets to show the contracts and tests. The same boundaries map to Node.js middleware: request context becomes req, an async handler becomes the middleware continuation, and the flag client remains an injected dependency. The important design is the data flow, not a particular SDK.
Keep it small.
Suppose the marketplace enables the rule for 10 percent of sellers in the UK. A request arrives with seller s-17, market uk, and revision r-12; the middleware records that the rule was enabled for the returned cohort, then the pricing layer calculates the business result. Later, the flag is edited to revision r-13, but an order investigation still contains an event from r-12. That old event is useful because it answers which configuration was evaluated, while the pricing record answers what amount was produced. If the flag API times out, the event carries source=fallback and reason=evaluation_timeout instead of looking like an ordinary disabled decision. The same small set of fields supports a replay fixture, an operational query, and a post-rollout audit. It also keeps raw seller attributes out of the event stream. This is the boundary I want the middleware to enforce: enough context to explain a decision, no accidental copy of the request or a hidden second pricing system.
1. Put the pricing decision behind one narrow boundary
A marketplace may expose a new pricing rule to a controlled cohort, such as 10 percent of sellers in one region or orders above a known basket threshold. Middleware should receive the request facts needed for that rule, call the flag API, and return a decision object. Downstream pricing code should not know how flags are stored, refreshed, or authenticated.
That separation gives an eval harness a stable seam. I can replay fixed marketplace requests against the rule without replaying a web server, network retries, or a whole observability stack. Notebook-to-prod is less dramatic when the decision function is explicit.
from dataclasses import dataclass from typing import Mapping, Optional @dataclass(frozen=True) class FlagDecision: key: str enabled: bool variant: Optional[str] source: str revision: str class FlagClient: def evaluate(self, key: str, attributes: Mapping[str, str]) -> FlagDecision: raise NotImplementedError class PricingFlagMiddleware: def __init__(self, client: FlagClient): self.client = client def evaluate_request(self, request: Mapping[str, str]) -> FlagDecision: attributes = { "market": request["market"], "seller_id": request["seller_id"], "order_id": request["order_id"], } return self.client.evaluate("pricing-rule-v2", attributes) In Node.js, the equivalent middleware would put the returned decision on a request-scoped property before calling next(). Keep that property typed and boring. A string such as "enabled" cannot carry the revision or reason needed to explain a later price.
2. How can Node middleware manage feature flags via an API?
Record fields that let an engineer reproduce the decision, not fields that merely make an event look busy. A practical decision event has a flag key, enabled state, variant, evaluation source, revision, market, and correlation identifier. It can carry a boolean indicating that evaluation failed. It should not copy the full request body, payment data, or an unbounded set of user attributes.
The common pitfall is treating a successful HTTP response from the flag API as proof that the pricing decision was healthy. A response can be valid while the request used the wrong market or an old revision. The event needs both the outcome and the context used to obtain it.
The OpenTelemetry logs model treats logs as a signal that can be correlated with traces and other telemetry. The pricing decision can be a short event associated with the request span, while the full calculation remains in the application’s domain records. Correlation is more valuable than verbosity.
I use one stable event name and a bounded vocabulary for outcomes. flag.evaluated with enabled, disabled, and error outcomes is easier to aggregate than a free-form message. The revision matters because a flag can change while an order is still being investigated.
def decision_event(request_id: str, request: Mapping[str, str], decision: FlagDecision) -> dict: return { "event.name": "flag.evaluated", "request.id": request_id, "flag.key": decision.key, "flag.enabled": decision.enabled, "flag.variant": decision.variant, "flag.source": decision.source, "flag.revision": decision.revision, "market": request["market"], } Do not log the resolved price as a substitute for the flag decision. The price is a separate business result and may reflect tax, inventory, seller rules, or rounding. Mixing those causes makes an incident query harder.
3. Make API failure behavior an explicit policy
The dangerous choice is allowing a flag API timeout to become an accidental pricing policy. Decide what happens before rollout. For a pricing rule, a conservative default may be the existing rule, with the evaluation marked as a failure and the request continuing. Another system may require a hard failure. The correct answer depends on the business invariant; it should never emerge from an uncaught exception.
I first expected the enabled state to answer most rollout questions. It does not. The revision and fallback reason are the details that separate a policy decision from an evaluation problem.
The middleware also needs a timeout, bounded retries, and a distinction between a stale local snapshot and a live evaluation. A retry that doubles traffic during an API incident can create more noise precisely when the team needs a clean signal.
from typing import Callable def evaluate_with_fallback( evaluate: Callable[[], FlagDecision], existing_rule: str, ) -> tuple[FlagDecision, str]: try: return evaluate(), "live" except TimeoutError: fallback = FlagDecision( key="pricing-rule-v2", enabled=False, variant=existing_rule, source="fallback", revision="unknown", ) return fallback, "evaluation_timeout" The unknown revision is deliberate. It prevents a fallback event from pretending that it came from a known flag configuration. In production, the fallback path should be counted separately from ordinary disabled evaluations.
4. Test the decision stream, not just the happy path
A unit test that asserts only the new price is too narrow. Test the contract between middleware and observability: one evaluation per request, required context fields present, no sensitive attributes, and a distinct outcome for timeout. Then run a small replay set containing a seller in each cohort, a request with missing context, a changed revision, and a simulated API failure.
This is where eval-driven development pays off. The expected output is a compact table of decisions, not a vague statement that the feature “seems enabled.” Keep fixture data synthetic and deterministic. Token cost matters here too: if an agent later summarizes rollout events, sending every raw request field into a model is an expensive way to lose the important dimensions. Aggregate first.
def test_timeout_is_visible_and_uses_the_existing_rule(): def timed_out() -> FlagDecision: raise TimeoutError decision, reason = evaluate_with_fallback(timed_out, existing_rule="legacy") assert decision.enabled is False assert decision.variant == "legacy" assert decision.source == "fallback" assert reason == "evaluation_timeout" def test_event_has_no_request_body(): request = {"market": "uk", "seller_id": "s-17", "order_id": "o-44"} decision = FlagDecision("pricing-rule-v2", True, "cohort-a", "live", "r-12") event = decision_event("req-9", request, decision) assert "body" not in event assert event["flag.revision"] == "r-12" The tests should fail loudly if a refactor starts emitting one event per internal retry. That is a signal-to-noise regression even if the customer-facing price remains correct.
5. Compare tools by boundaries, then write the checklist
Different observability and flagging products make different trade-offs. OpenTelemetry provides portable telemetry concepts and APIs, but it does not define a complete feature-flag control plane. A hosted flag service can provide targeting and configuration workflows, while the application still owns fallback policy and business audit records. A log platform can make events searchable, but it does not decide which pricing attributes are safe to emit. These boundaries are why I evaluate products by interfaces and failure behavior rather than dashboard screenshots.
Before enabling the pricing rule, I check that the flag key and revision are present, evaluation has a bounded timeout, fallback events are distinguishable, and the event can be joined to a request trace. I verify that cohort attributes are allowlisted and that the replay fixture covers both sides of the rule. During rollout, I watch decision counts, timeout counts, and business outcomes separately. Afterward, I remove temporary high-cardinality fields and keep the durable audit record small.
The final decision rule is straightforward: if a metric cannot tell “disabled by policy” from “could not evaluate,” it is not ready to guide a rollout. Middleware has done its job when a pricing change can be explained from a few stable fields, without reconstructing an entire request from noisy logs.