Plandalf

Fields

Use fields to document parameters, request body properties, headers, attributes, nested objects, defaults, and validation notes.

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.

pathparamstringrequired

An example of a parameter field.

<ParamField path="param" type="string" required>
  An example of a parameter field.
</ParamField>

Response field

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

responsestringrequired

A response field example.

<ResponseField name="response" type="string" required>
  A response field example.
</ResponseField>

Request fields

Create checkout session body

bodyofferstringrequired

Published offer slug, Sqid route key, or UUID.

Buyer context to attach to the checkout session when your app already knows the visitor.

customer.emailstringrequired

Email address used for receipts, account matching, and follow-up automation.

customer.external_idstring

Your app’s stable customer or account identifier.

bodymetadataobject

Optional implementation metadata, such as source page or account ID.

headerAcceptstringdefault: application/json

Ask the route to return JSON.

<Fields title="Create checkout session body" variant="list">
  <ParamField body="offer" type="string" required>
    Published offer slug, Sqid route key, or UUID.
  </ParamField>
  <ParamField body="customer" type="object" expandable>
    Buyer context to attach to the checkout session.

    <ParamField name="customer.email" type="string" required>
      Email address used for receipts and account matching.
    </ParamField>
  </ParamField>
  <ParamField header="Accept" type="string" default="application/json">
    Ask the route to return JSON.
  </ParamField>
</Fields>

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

Fields
pathofferstringrequired

Offer route key from the URL.

queryincludeproducts | prices | components

Optional related records to include in the response.

BearerheaderAuthorizationstringrequired

Server-side API credential.

bodymodemodal | hosted | inlinedefault: 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

bodyquery, path, body, or headerstring

Whether the parameter is a query, path, body, or header value. The prop value becomes the parameter name.

bodytypestring

Expected type of the parameter’s value. Arrays use the [] suffix, such as string[].

bodyrequiredboolean

Indicate whether you require the parameter.

bodydeprecatedboolean

Indicate whether you have deprecated the parameter.

bodydefaultany

Default value populated when the request value is empty.

bodyplaceholderstring

Placeholder text for the input in a playground or request builder.

bodychildrenstring

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_urlstringrequiredplaceholder: https://example.com/thanks

Redirect destination after a completed checkout.

cancel_urlstringoptional

Redirect destination when the buyer closes checkout.

legacy_tokenstringdeprecated

Older URL-token integrations should move behind server-side bearer authentication.

modestringdefault: modalSDK

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

namestringrequired

The name of the response value.

typestringrequired

Expected type of the response value. This can be any arbitrary string.

defaultstring

The default value.

requiredboolean

Indicate whether you require the response.

deprecatedboolean

Whether you have deprecated a field.

prestring[]

Labels that appear before the name of the field.

poststring[]

Labels that appear after the name of the field.

Plandalf field group extensions

titlestring

Section heading shown above the field list or inside the panel header.

descriptionstring

Short context for the whole group.

variantpanel | listdefault: panel

Use panel for standalone API blocks and list inside ApiEndpoint sections.

icon | iconTypestring

Optional shared docs icon props for the group header.

optionalbooleandefault: false

Marks a field as optional when the page wants to be explicit.

expandablebooleandefault: false

Lets nested ParamField or ResponseField children collapse under an object or array field.

defaultOpenbooleandefault: false

Opens an expandable field on first render.

idstring

Stable anchor for direct links to a field.

class | classNamestring

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.
Response fields Document response shapes.
Examples Pair fields with request and response code.
API fields guide See endpoint docs patterns.

Feature detail