# Fields
Use fields to document parameters, request body properties, headers, attributes, nested objects, defaults, and validation notes.
Source: /docs/components/fields
Last modified: 2026-06-20
Fields make structured data scanable. Use them when a page needs to explain request parameters, component props, response objects, or configuration attributes.


> **Pair fields with examples**
>

  Fields explain the contract. A request or response example shows the contract in motion. On API pages, use both inside an `ApiEndpoint`.


## Parameter field

Use `ParamField` to define API or SDK parameters. Set one location prop such as `path`, `query`, `body`, or `header`; the prop value becomes the field name and the location badge tells the reader where the value belongs.


- `param` (string; required):
  An example of a parameter field.


```mdx title="param-field.mdx"

- `param` (string; required):
  An example of a parameter field.


```

## Response field

Use `ResponseField` to define API return values when a page needs to show a response shape alongside request fields.


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


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

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


```

## Request fields


### Create checkout session body


- `offer` (string; required):
    Published offer slug, Sqid route key, or UUID.


- `customer` (object):
    Buyer context to attach to the checkout session when your app already knows the visitor.


- `customer.email` (string; required):
      Email address used for receipts, account matching, and follow-up automation.


- `customer.external_id` (string):
      Your app's stable customer or account identifier.


- `metadata` (object):
    Optional implementation metadata, such as source page or account ID.


- `Accept` (string; default: application/json):
    Ask the route to return JSON.


````mdx title="fields.mdx"

### Create checkout session body


- `offer` (string; required):
    Published offer slug, Sqid route key, or UUID.


- `customer` (object):
    Buyer context to attach to the checkout session.


- `customer.email` (string; required):
      Email address used for receipts and account matching.


- `Accept` (string; default: application/json):
    Ask the route to return JSON.


````

## Locations

Use location props when the same endpoint has path, query, body, and header fields. The location badge helps readers distinguish where each value belongs.


### Endpoint inputs


- `offer` (string; required):
    Offer route key from the URL.


- `include` (products | prices | components):
    Optional related records to include in the response.


- `Authorization` (string; Bearer, required):
    Server-side API credential.


- `mode` (modal | hosted | inline; default: modal):
    Checkout presentation mode.


## Parameter field properties

Mintlify documents the `ParamField` API with `body` rows because these are props of the component, not endpoint parameters.


### ParamField properties


- `query, path, body, or header` (string):
    Whether the parameter is a query, path, body, or header value. The prop value becomes the parameter name.


- `type` (string):
    Expected type of the parameter's value. Arrays use the `[]` suffix, such as `string[]`.


- `required` (boolean):
    Indicate whether you require the parameter.


- `deprecated` (boolean):
    Indicate whether you have deprecated the parameter.


- `default` (any):
    Default value populated when the request value is empty.


- `placeholder` (string):
    Placeholder text for the input in a playground or request builder.


- `children` (string):
    Markdown-enabled description of the parameter.


## Field states

Use state props to communicate required values, defaults, placeholders, deprecations, and labels without writing that information into prose.


### Field state examples


- `success_url` (string; required, placeholder: https://example.com/thanks):
    Redirect destination after a completed checkout.


- `cancel_url` (string; optional):
    Redirect destination when the buyer closes checkout.


- `legacy_token` (string; deprecated):
    Older URL-token integrations should move behind server-side bearer authentication.


- `mode` (string; default: modal, SDK):
    Default checkout presentation when no explicit mode is supplied.


## Props

Mintlify documents `ParamField` properties with `ParamField` rows and `ResponseField` properties with `ResponseField` rows. Plandalf keeps that split so copied MDX reads the same way.

### ResponseField properties


- `name` (string; required):
  The name of the response value.


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


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


- `required` (boolean):
  Indicate whether you require the response.


- `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 field group extensions


- `title` (string):
  Section heading shown above the field list or inside the panel header.


- `description` (string):
  Short context for the whole group.


- `variant` (panel | list; default: panel):
  Use `panel` for standalone API blocks and `list` inside `ApiEndpoint` sections.


- `icon | iconType` (string):
  Optional shared docs icon props for the group header.


- `optional` (boolean; default: false):
  Marks a field as optional when the page wants to be explicit.


- `expandable` (boolean; default: false):
  Lets nested `ParamField` or `ResponseField` children collapse under an object or array field.


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


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


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


## Authoring rules

- Use `variant="list"` inside endpoint sections so the API block stays compact.
- Use `expandable` for object and array fields with meaningful children.
- Prefer `path`, `query`, `body`, and `header` over encoding the location in the field text.
- Do not document fake fields just to make a schema look complete.

## Related components


  - [Response fields](/docs/components/response-fields): Document response shapes.
  - [Examples](/docs/components/examples): Pair fields with request and response code.
  - [API fields guide](/docs/components/api-fields-examples): See endpoint docs patterns.