FDE Times dataFDE jobs open 881▼8 Change in open roles over 7 days, like-for-like: roles from companies we started tracking this week are left outNew in 7 days 55Companies hiring 185Remote-friendly 25%Median US pay $201kTop hirer Databricks 98
中文VI

The newspaper of the Forward Deployed Engineer

Guides

When customers pay for outcomes, your counter is the invoice

Billing reconciles at the end of the period, but quotas must be checked on every event, so the two run as separate systems on different clocks.

ShareLinkedInFacebookX

In brief

  • Stripe's basic billing meters reconcile only at invoicing, so customers can overspend their credits mid-period. Enforcing quotas requires a separate entitlement layer that runs in real time.
  • Usage pipelines deliver each event at least once by default. Without an idempotency key and deduplication rules, customers get billed twice.
  • With outcome-based pricing, the hardest part is defining the outcome. That definition has to become code, traceable from the product event to the line on the invoice.
Diagram: each agent conversation emits an event, and the event follows two branches. The upper branch, in orange, is the limit check in the request path, based on the real-time balance at each event. The lower branch goes through an outbox to billing, where usage is reconciled only at period end, when the invoice is issued.
Entitlement must decide on every event, at once. Billing charges later, at period end. So the upcoming invoice should not be used to block a customer. Source: Stripe, OpenMeter and Stigg documentation cited in the article.

Picture the last week of a billing period. The customer sends a screenshot of their dashboard: the support agent you deployed has “resolved” far fewer conversations than the invoice claims. They are not asking about the model or the prompt. They want to know why the invoice shows more resolutions than they can count themselves.

For an FDE, this is the moment billing stops being the finance team’s problem. When a customer pays per token or per outcome, every event your code emits is money. A wrong counter means a wrong invoice, and customer trust drains faster than it does after any technical bug.

Your job is to wire the customer’s system into billing so the counts are right and the quotas hold. And when the customer pushes back, you have to show where every number came from.

Billing and entitlements answer different questions

Billing answers “how much do we charge?” Entitlements answer “can this customer keep using the product?” The questions sound similar, but they run on entirely different clocks.

Stripe’s documentation is explicit that basic usage-based billing reconciles usage only at invoicing. During the period, neither the customer nor your team can see a running credit balance or total usage.

Stripe also warns that with prepaid credits in basic mode, customers can overspend their balance mid-period. For new integrations that need real-time balances and credit burn-down, Stripe points users to Metronome.

The consequences are concrete. If the contract says “10 million tokens a month”, the example OpenMeter uses to describe a metered entitlement, you cannot wait for the invoice to find out the customer has gone over. You need a check in the request path that keeps a separate balance for each customer.

OpenMeter links usage events to entitlements through a “subject key”, the field in an event that says who used the feature. It sounds like a detail, but it is where many integrations break. If the subject key is a user ID while the quota is set per workspace, the balances will never match.

One conversation, three actions, one charge

Take a concrete case. Suppose the customer pays for each conversation the agent resolves, on a model like Intercom Fin. Intercom defines a billable resolution in two ways: the customer confirms the issue is sorted, or the customer leaves the conversation without asking for further help. The second case is called an “assumed resolution”.

Intercom has one more rule: each conversation counts as one outcome, even if the agent takes several actions. Say that in a single conversation the agent looks up an order, changes the delivery address and sends a discount code. If your code emits one event per action, the customer is billed three times for something that should be billed once.

So the billing unit has to be the conversation, not the action. The sketch below shows how to build the event:

def build_resolution_event(conv):
    # Only bill once the conversation is closed and matches the contract definition
    if conv.status != "closed":
        return None
    confirmed = conv.customer_confirmed
    assumed = conv.customer_left and not conv.asked_for_more_help
    if not (confirmed or assumed):
        return None
    return {
        "event_name": "resolution",           # must match the name configured on the meter
        "customer_id": conv.billing_customer_id,
        "value": 1,                           # one outcome per conversation
        "identifier": f"resolution:{conv.id}",  # stable idempotency key
        "timestamp": conv.closed_at,
        "trace": {"conversation_id": conv.id, "rule": "confirmed" if confirmed else "assumed"},
    }

Every field is there for a reason. Stripe requires a configured meter, after which meter events must carry the event name, a customer ID, a numeric value and a timestamp (optional). The identifier is built from the conversation ID rather than the time of sending, so however many times it is resent, it remains one outcome.

The trace field is the part many people skip. Stigg, a pricing infrastructure provider, argues that every outcome event must be traceable from the product to the invoice. When the customer sends a dashboard screenshot like the one at the start of this piece, trace tells you which rule each resolution was billed under.

One place worth checking in advance is the “assumed” group: these outcomes are inferred from the customer leaving, so the customer’s own dashboard may not record them as resolutions.

The counter must survive retries, late events and peak load

Stigg writes that usage pipelines are designed to deliver each event at least once. In other words, duplicates will happen; the only question is when.

Stripe also recommends idempotency keys so that an event is not reported twice because of network latency or other errors. Deduplicate at both ends: in your own outbox table and through the identifier sent to the provider.

The second risk is time. Stripe processes meter events asynchronously, so the usage total on the upcoming invoice may not immediately reflect events you have just sent.

Timestamps also have to be close enough to the present. Most importantly, usage must be reported before that period’s invoice is finalised; otherwise an event may still be accepted but never billed.

The third risk is throughput. Stripe’s v1 meter event endpoint is limited to 1,000 calls per second per Stripe account. Imagine the customer running the agent across thousands of conversations in parallel while you send one event per LLM call.

You will hit the ceiling quickly. There are two ways out: pre-aggregate by customer and time window and send the totals, or use the v2 API’s streams.

Finally, there are malformed events. Stripe surfaces invalid events through an error webhook and expects you to fix and resend them. If nobody listens to that webhook, broken events disappear silently. Revenue leaks, and you find out only at end-of-period reconciliation.

The order of work at the customer site

The first step is not writing code. Sit down with the customer and whoever owns pricing, and write the definition of “one billable unit” as a sentence you can test.

For example: “conversation closed, customer confirmed or left without asking for more, at most once per conversation”. Intercom’s definition shows that the rules for recognising an outcome live inside the definition itself, and each such rule becomes an if branch in the code.

Next, choose a subject key that matches the level at which the contract sets quotas: workspace, organisation or customer. Then build an outbox: events are written to your database first, with their idempotency key, and a worker pushes them to billing. That worker needs to know the invoice finalisation date so it can raise an alert when the queue falls behind close to that deadline.

The entitlement layer runs in parallel. Stigg describes outcome-based entitlements as a credit balance drawn down after each confirmed outcome and rechecked on every event. Put this check in the request path, reading from a real-time balance source, rather than asking a billing system that reconciles only at the end of the period.

Last comes a daily reconciliation job: count by trace in your system and compare against the billing-side totals. A small, stable gap is usually late events. A growing gap is usually retries without an idempotency key.

The mistakes that make invoices wrong

The most common mistake is building the identifier from the send time, or from a UUID regenerated on every retry. The idempotency key then exists in name only. The second is using the upcoming invoice as the balance source for blocking customers. As Stripe warns, that number lags, and customers can overspend mid-period.

The third mistake is emitting events per action when the contract bills per outcome. The fourth is having nobody listen to the error webhook. The fifth is harder to spot: not storing the rule that caused an event to be billed. When the customer disputes the invoice, you have nothing to show them.

For your career, this is a skill worth demonstrating in specifics. When you read FDE job postings at AI companies that sell on usage, look for the phrases “usage-based billing”, “metering” or “entitlements”.

On a CV, a line such as “designed an idempotent usage pipeline, reconciled daily against invoices, enforced quotas in real time” carries far more weight than “integrated Stripe”.

This week’s exercise

Take any product flow you are working on and write its definition of “one billable unit” in exactly one sentence. Then write a test that simulates a conversation with three actions and two retries. The test passes only if the system records exactly one event, with a trace an outsider can read and understand.

If you can do that before the customer asks, the end-of-period call gets much shorter: you just open the reconciliation table and show them.

Was this article useful?

Use with your AI assistantAsk Claude ↗Ask ChatGPT ↗
5 sources
Read next on the roadmap · Stage 2: Broad engineeringAn agent that is 90% right gets eight runs in a row right only 43%Running 160 trials on a laptop is enough to tell whether a browser agent is reliable enough to hand over to a client.