Skip to main content
POST
Simulate Margin
Base URL: https://api.nozle.app/engine/api/v1. Simulate the margin of one metric at a new unit price before you change it. The simulation replays the metric’s recorded usage at the new price and keeps the recorded cost. Auth: sk_ only. With API key permissions, the key needs analytic:read; without it the call returns 403 with code: permission_denied.
All margin endpoints require a secret key (sk_). These endpoints expose cost data that should never be visible to your end users.
string
required
Code of the metric to simulate. A missing or empty value returns 400 with {"code": "invalid_request", "error": "metric_code required"}.
number
required
New price per unit of usage, in dollars (a JSON number, not a string). It must be 0 or more. A missing, negative or string value returns 400 with code invalid_request.
The simulation covers the date range given by the from and to query parameters, which default to the last month. They take a YYYY-MM-DD date (a plain to includes that whole day) or an RFC3339 timestamp (an exclusive instant), with from_date and to_date as aliases. When you send only one end, the API derives the other: only to covers the month before it, and only from runs until now (one month after from if it is not in the past). An unparseable value, or an end that is not after the start, returns 400 with {"code": "invalid_date_range", "error": "..."}. See Margin Summary for the full rules. The body takes no other fields: an unknown field such as plan_code or new_price_cents returns 400 with code invalid_request. The query string is read only for from, to, from_date and to_date. The body is checked before the range, so a body error is returned first.

Response

All amounts are integer cents. new_revenue_cents is the total recorded quantity multiplied by new_price_dollars and 100, truncated to a whole cent. new_cost_cents equals current_cost_cents: the simulation changes price only. The deltas are new minus current. A metric with no events in the range returns zeros with event_count 0.