Preview recipe

POST

/v1/recipes/{key}/preview

curl --request POST \
  --url http://localhost:8080/v1/recipes/example/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "overrides": {} }'

• Local development

Renders the recipe with caller-supplied overrides and returns the would-be-created object graph. Pure in-memory — no DB writes, no audit row.

Authorizations

• BearerAuth

Parameters

Path Parameters

key

required

string

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body

Media typeapplication/json

object

overrides

object

key

additional properties

any

Example ^generated

{
  "overrides": {}
}

Responses

200

Rendered object graph

Media typeapplication/json

object

key

required

string

version

required

string

objects

required

What an install creates: the meters, and each plan with its prices. Both arrays are always present. An install reuses a meter that already exists with the same event_name and aggregation.

object

meters

required

Array<object>

object

event_name

required

string

name

required

string

unit

required

string

aggregation

required

string

plans

required

Array<object>

object

code

required

string

name

required

string

currency

required

string

billing_interval

required

string

Allowed values: monthly yearly

base_amount_cents

required

integer format: int64

base_bill_timing

Optional when the base fee is 0; the plan is then in_arrears (ADR-031).

string

Allowed values: in_advance in_arrears

prices

required

The plan’s usage prices. Each takes the plan’s currency.

Array

One usage price of a recipe plan. It takes the plan’s currency.

object

meter

required

The event_name of the recipe meter the price is on.

string

dimension_match

required

object

key

additional properties

string

mode

required

per_unit bills quantity × unit_amount_cents. graduated bills each tier’s part of the quantity at that tier’s rate. package bills ceil(quantity ÷ package_size) × package_amount_cents: a part package bills as a whole one.

string

Allowed values: per_unit graduated package

unit_amount_cents

required

Price per unit in cents, as a decimal string (e.g. “0.0003” = $3.00 per 1,000,000 units). Used when mode is per_unit. 0 or more, under 10^18, at most 12 decimal places (trailing zeros do not count), and at most 100 characters. A JSON number is also read. A value outside them is refused with 422 and param naming the field. Invoice line amounts round to whole cents.

string

tiers

required

Used when mode is graduated. Each up_to is a whole number above the one before. The last tier has up_to: null (no upper bound), and only the last. Otherwise 422 with param tiers. A tier’s rate takes the limits of unit_amount_cents; a refusal names tiers[i].unit_amount_cents (i counts from 0).

Array<object>

object

up_to

required

The tier’s upper bound in whole units: the tier prices the quantity above the previous tier’s bound, up to this one. null on the last tier, which has no upper bound. Only the last tier is null, and it must be.

integer format: int64

nullable

unit_amount_cents

required

Price per unit in cents in this tier, as a decimal string.

string

package_size

required

Used when mode is package. Must be above 0.

integer format: int64

package_amount_cents

required

Price of one package in cents, as a decimal string (e.g. “0.2” with package_size 1000 = $0.002 per 1,000 units), with the limits of unit_amount_cents. Used when mode is package.

string

warnings

required

Array<string>

Example

{
  "objects": {
    "plans": [
      {
        "billing_interval": "monthly",
        "base_bill_timing": "in_advance",
        "prices": [
          {
            "mode": "per_unit"
          }
        ]
      }
    ]
  }
}

404

Unknown recipe key

422

Overrides failed the recipe’s overridable schema