# Response fields
Use response fields to describe API response objects, nested properties, and returned resource shapes.
Source: /docs/components/response-fields
Last modified: 2026-06-20
Response fields are the response-side partner to parameter fields. Use them inside `Responses` when documenting API output.

## Basic example


- `response` (string; required):
  A response field example.


```mdx title="response-field-basic.mdx"

- `response` (string; required):
  A response field example.


```

## Response group


### Checkout session response


- `id` (string; required):
    Checkout session route key.


- `totals` (object):
    Calculated monetary totals for the session.

- `totals.total` (integer):
      Final total in the smallest currency unit.


```mdx title="response-fields-example.mdx"

### Checkout session response


- `id` (string; required):
    Checkout session route key.


- `totals` (object):
    Calculated monetary totals for the session.

- `totals.total` (integer):
      Final total in the smallest currency unit.


```

## Nested objects

Response fields can expand nested objects so the visible page stays readable while still documenting the full returned shape.


### Offer response


- `offer` (object; required):
    The offer returned by a catalog or checkout API call.

- `offer.id` (string; required):
      Stable offer identifier.


- `offer.slug` (string; optional):
      Public slug when the offer has a hosted route.


- `offer.components` (array<object): " expandable>
      Checkout blocks such as order bumps, add-ons, and save offers.

- `offer.components[].type` (string; required):
        Component kind used by the checkout renderer.


- `request_id` (string; optional):
    Trace identifier returned for support and debugging.


```mdx title="nested-response-fields.mdx"

### Offer response


- `offer` (object; required):
    The offer returned by a catalog or checkout API call.

- `offer.id` (string; required):
      Stable offer identifier.


- `offer.components` (array<object): " expandable>
      Checkout blocks such as order bumps, add-ons, and save offers.


```

## With examples

Pair response fields with a `ResponseExample` or an `ApiEndpoint` so the schema and the payload teach the same object.


### Response example


### 200 offer


    ```json title="Offer response"
    {
      "offer": {
        "id": "off_123",
        "slug": "launch-plan",
        "components": [
          { "type": "order_bump", "title": "Add the workbook" }
        ]
      },
      "request_id": "req_abc"
    }
    ```


````mdx title="response-field-with-example.mdx"

### Offer response


- `offer` (object; required):
    The offer returned by the API.


### Response example


### 200 offer


    ```json title="Offer response"
    { "offer": { "id": "off_123" }, "request_id": "req_abc" }
    ```


````

## Authoring rules


### Response field rules


- `Mirror the payload` (schema and example):
    If the example includes a property, document it or intentionally omit it from the example.


- `Expand objects` (nested detail):
    Use expandable fields for objects and arrays where nested keys matter.


- `Prefer exact names` (dot notation):
    Use `offer.components[].type` for nested array values so agents and readers can copy the shape accurately.


## Props


- `name` (string; required):
  The name of the response value. Dot notation is supported for nested fields.


- `type` (string; required):
  Expected type of the response value. This can be any arbitrary string.


- `default` (string):
  The default value.


- `required` (boolean):
  Show `required` beside the field name.


- `deprecated` (boolean):
  Whether you have deprecated a field.


- `pre` (string[]):
  Labels that appear before the name of the field.


- `post` (string[]):
  Labels that appear after the name of the field.


## Plandalf extensions


- `optional` (boolean):
  Marks the property as conditional or nullable when the page wants to be explicit.


- `response` (string):
  Alias for `name`, used when imported MDX describes response values with a response prop.


- `expandable` (boolean):
  Renders the row as a collapsible object container.


- `defaultOpen` (boolean; default: false):
  Opens an expandable response field on first render.


- `id` (string):
  Stable anchor for direct links to a field.


- `class | className` (string):
  Optional classes for layout adjustments.


## Related


  - [Fields](/docs/components/fields): Document request fields.
  - [Examples](/docs/components/examples): Show request and response samples.
  - [API fields and examples](/docs/components/api-fields-examples): Build complete endpoint pages.