Parameter and Expandable

Parameter documents one field: its name, its type, labels like required or a default, and a description. It suits anything with a name and a type - API parameters, response fields, configuration options, environment variables. Every field on this site’s configuration pages is a Parameter.

amount integer required

The amount to charge, in the currency’s smallest unit - 1000 is $10.00.

currency string default: usd

A three-letter currency code, in lowercase.

<Parameter name="amount" type="integer" required>
  The amount to charge, in the currency's smallest unit - `1000` is $10.00.
</Parameter>

<Parameter name="currency" type="string" default="usd">
  A three-letter currency code, in lowercase.
</Parameter>

The description can hold any content - paragraphs, lists, code blocks - unlike a table cell.

Deprecated

deprecated marks a field you’d rather readers didn’t use, and strikes out its name:

source string deprecated

Use payment_method instead.

<Parameter name="source" type="string" deprecated>
  Use `payment_method` instead.
</Parameter>

More labels

pre adds labels before the name, and post after the other labels:

read-only id string since v2

The payment’s ID, set by the API.

<Parameter name="id" type="string" pre={["read-only"]} post={["since v2"]}>
  The payment's ID, set by the API.
</Parameter>

Nested fields

Expandable holds the fields of an object, behind a button that shows and hides them - the way API reference pages show nested objects:

customer object required

The customer who pays.

Hide customer fields

email string required

Where the receipt is sent.

address object

Show address fields

country string required

A two-letter country code.

postal_code string

The postal or ZIP code.

<Parameter name="customer" type="object" required>
  The customer who pays.

  <Expandable title="customer fields">
    <Parameter name="email" type="string" required>
      Where the receipt is sent.
    </Parameter>
    <Parameter name="address" type="object">
      <Expandable title="address fields" defaultOpen={false}>
        <Parameter name="country" type="string" required>
          A two-letter country code.
        </Parameter>
        <Parameter name="postal_code" type="string">
          The postal or ZIP code.
        </Parameter>
      </Expandable>
    </Parameter>
  </Expandable>
</Parameter>

Expandables nest to any depth.

Parameter props

name string required

The field’s name.

type string

The field’s type, like string or object. Without it, there’s no type label.

required boolean default: false

A required label.

default any

A default label with this value. Any value works: default="usd", default={10}, default={false}.

deprecated boolean default: false

A deprecated label, and the name struck out.

pre string[]

Labels before the name.

post string[]

Labels after the other labels.

Expandable props

title string default: properties

The button’s text.

defaultOpen boolean default: true

Open when the page loads.