HTTP API

Accepts up to 500 events per request. Each event is processed independently: the response carries one result per event, in request order, and a rejected event does not fail the batch.

Idempotent on eventId. Re-sending an event you already sent returns status duplicate and changes nothing, so a retry after an ambiguous network failure is always safe. To correct a figure you already reported, send a new eventId and set correctsEventId to the original.

Send costUsd when your provider tells you the real charge (gateways such as OpenRouter do). Otherwise omit it and MarginFuse prices the call from token counts, labeling the result as estimated rather than observed.

Evaluates the project's policies against this customer's current margin and returns an action to take before you call the provider:

• allow proceed with the model you asked for
• downgrade proceed, but use the model in the response instead
• topup_required do not call the provider; present the top-up path to the customer
• block do not call the provider

Policies run in dry-run before they run live, so this endpoint records what protection would have done against real traffic without acting on it. A dry-run policy always answers allow.

Report back with /v1/decisions/{id}/ack once you know what your application did. Savings can only be credited as realized on that confirmation.

Sets the plan a customer is on, and optionally a display name, an email and short metadata labels that segment policies can match on.

plan is the key of a plan declared in Settings, not a Stripe price. MarginFuse derives revenue from that plan's price for every period, which is what makes margin per customer, margin policies and plan budgets work with no revenue source connected. Every figure built that way is labeled as a declared price, because nobody confirmed collection: the margin is an upper bound.

Safe to call on every sign-in. Sending the plan the customer is already on changes nothing. Sending a different one ends the current cycle at that moment, prorates the revenue accrued so far, and starts the new plan from there. Pass periodStart when the customer has been paying since an earlier date, and clearPlan to take them off plans entirely.

Once a revenue source bills this customer, that subscription is the truth and this call is refused with provider_subscription_present - the application can keep calling it unchanged.

There is no field for anything but identity here: no prompts, no content, no arbitrary payload.

Closes the loop on a decision. This is evidence, not bookkeeping: MarginFuse will not count an avoided provider call as realized savings without the application confirming the call did not occur.

presented_topup deliberately does not earn realized savings on its own. The customer may have paid and proceeded, so the call may well have happened.

Where RevenueCat delivers purchases, renewals, cancellations and refunds. Not for application traffic: the URL and its secret are generated in Settings → Integrations and pasted into RevenueCat's webhook configuration.

Authenticated by the shared secret MarginFuse minted for this project, sent in the Authorization header exactly as RevenueCat was configured to send it. MarginFuse stores only its hash and compares in constant time. A project that does not exist and a wrong secret are both answered 401, so this endpoint cannot be used to discover project ids.

Answers 200 for events it deliberately ignores as well as for those it records, so RevenueCat does not retry a subscriber alias notification forever. A purchase becomes revenue for the period it paid for, counted as the store's proceeds; the periodic read then replaces that row with the store's own arithmetic, keyed by the same store transaction id so it is never counted twice.

The machine-readable contract, served by the same deployment that enforces it. Unauthenticated, so an SDK author or an agent can read the API before being given a key.

Unauthenticated. Returns 503 when the database is unreachable, so a rotated credential or a dead pooler shows up here and not only as failing traffic.