Variable Interpolation

Pro and Enterprise only.

Overview

Variable interpolation lets your mock responses reflect — and compute from — data in the incoming request: path parameters, query strings, request body fields, and headers.

This is useful when:

• You want to echo back data the client sends (e.g., return the same id that was passed in)
• Your tests assert that specific request fields appear in the response
• You want to simulate computed values like totals, discounts, or adjusted quantities
• You want to simulate dynamic responses without running a real server

---

Syntax

Use curly-brace templates anywhere in a response body or header value:

{source.field}

To apply arithmetic, add an operator and operand inside the braces:

{source.field op operand}

op is one of +, -, *, /. operand is either a numeric literal or another source.field reference. Spaces around the operator are required.

Where source is one of:

Source	What it reads
body	JSON request body field
path	URL path parameter
query	Query string parameter
header	Request header

---

Source examples

Request body

Given a POST /orders request with body:

{
  "customer_id": 42,
  "item": "widget",
  "quantity": 3
}

Response body template:

{
  "order_id": "ord_001",
  "customer_id": {body.customer_id},
  "status": "pending",
  "item": "{body.item}",
  "quantity": {body.quantity}
}

Rendered response:

{
  "order_id": "ord_001",
  "customer_id": 42,
  "status": "pending",
  "item": "widget",
  "quantity": 3
}

Path parameters

Given a route /users/:id called as GET /users/99:

Response body template:

{
  "id": {path.id},
  "name": "Alice"
}

Rendered response:

{
  "id": 99,
  "name": "Alice"
}

Query string

Given GET /search?q=laptops&page=2:

Response body template:

{
  "query": "{query.q}",
  "page": {query.page},
  "results": []
}

Request headers

Given a request with header X-User-Id: usr_abc:

Response header template:

X-Echo-User: {header.x-user-id}

Header names are lowercased when matching.

---

Arithmetic expressions

You can apply +, -, *, or / to any numeric variable directly inside the template token.

Multiply by a literal

Apply a 10% markup to a price from the request body:

{
  "unit_price": {body.price},
  "total": {body.price * 1.1}
}

Given body.price = 50, the response is:

{
  "unit_price": 50,
  "total": 55
}

Add a literal

{ "next_page": {query.page + 1} }

Given ?page=3:

{ "next_page": 4 }

Use another variable as the operand

Subtract one request field from another:

{ "remaining": {body.total - body.used} }

Given body.total = 100, body.used = 37:

{ "remaining": 63 }

Divide by a literal

Convert cents to dollars:

{ "amount_dollars": {body.amount_cents / 100} }

Arithmetic in partial templates (string context)

Arithmetic tokens inside a larger string are coerced to a string, like any other token:

{ "message": "Your total is {body.price * 1.1} USD" }

Result: { "message": "Your total is 55 USD" }

Error handling

If either operand cannot be parsed as a number, or if a divide-by-zero would occur, the token is left unchanged in the response — no error is thrown.

---

Nested fields

Dot notation traverses nested JSON objects:

{
  "user": {
    "address": {
      "city": "Portland"
    }
  }
}

Template: {body.user.address.city} → "Portland"

---

Type preservation

When a template is the only content in a JSON string value, Mockra preserves the original type:

{ "count": "{body.count}" }

If body.count is 5 (integer), the response is:

{ "count": 5 }

The surrounding quotes are removed and the native type is used.

When a template is mixed with other text, the result is always a string:

{ "message": "You have {body.count} items" }

Result: { "message": "You have 5 items" }

---

Missing variables

If a variable cannot be resolved (e.g., the field doesn't exist in the request body), the placeholder is left as-is in the response. No error is thrown.

---

Applying interpolation to stateful mocks

Variable interpolation works in all response types — static mock configs and stateful sequence steps. Each step's body and headers are independently interpolated against the incoming request.

---

Enabling interpolation

To use interpolation:

1. Open the mock config editor for any endpoint
2. Add a {source.field} template to the body or a header value
3. Save

The plan gate is enforced at save time. If you're on the Free or Starter tier, saving a config with templates will return a 403 error. Upgrade to Pro or Enterprise to use this feature.

---

Performance

Interpolation has zero overhead on endpoints that don't use templates. Mockra checks for { in the response body before running the resolver — if no templates are present, the response is returned directly from cache with no additional processing.