# Checkout options

The `options` block on the order — branding colors, corner radius, VAT display, the delivery note, the custom checkboxes and the flags that change what the checkout shows a customer.

Most of what makes one Kustom Checkout look and behave differently from another is set on
the order itself, at creation, in its `options` block. This page covers the options you're most
likely to set. Every option is in the
[Checkout API reference](/api/checkout/create-order-merchant/#body.options). They apply to the
embedded checkout and to the [Hosted Payment Page](/checkout/surfaces/hosted-payment-page/)
alike, since both render the same order.

**An update replaces the whole `options` block.** It doesn't merge into the one you sent at
creation. Any option you leave out of the update goes back to its default, so resend every
option you set at creation, not only the one you're changing.

The settings that exist to serve one particular job are documented with that job, because the
fields alone never explain when to reach for them: [selling to
businesses](/checkout/use-cases/b2b/), [verifying an age](/checkout/use-cases/age-verification/),
[discounting a cart](/checkout/use-cases/discounts-and-gift-cards/) and [opening a second
market](/checkout/use-cases/multi-market/).

## Branding and layout

Colors and corner radius are usually set in the Kustom Portal. You can also set them per order
with the options below, as hexadecimal values. Anything you leave out keeps the default.

| Option | Element |
|---|---|
| `options.color_button` | The primary button |
| `options.color_button_text` | Text on that button |
| `options.color_checkbox` | Checkbox body |
| `options.color_checkbox_checkmark` | The checkmark itself |
| `options.color_header` | Section headers |
| `options.color_link` | Links |
| `options.color_background` | The background inside the iframe |
| `options.radius_border` | Corner radius on bordered elements |

Every `color_*` value is a CSS hex color, `#RRGGBB`. `radius_border` is a string carrying a
pixel count — `"5"`, not `"5px"`.

```json
{
  "options": {
    "color_button": "#ff0000"
  }
}
```

**Hide VAT** from the order summary with `options.vat_removed`:

```json
{
  "options": {
    "vat_removed": true
  }
}
```

**Add a delivery note** of up to 255 characters, shown on the confirmation page under the
Delivery heading. It can be set at creation or on an update. A longer note isn't rejected —
it's silently truncated at 255, so check the length yourself if the tail matters. On an update,
send it together with every other option you set at creation, here the button color:

```json
{
  "options": {
    "color_button": "#ff0000",
    "shipping_details": "Delivered within 1-3 days"
  }
}
```

The confirmation page can carry more than a note — see
[Upselling on the confirmation page](/checkout/use-cases/confirmation-page-upsell/).

## Custom checkboxes

Extra checkboxes can be added to the checkout — a newsletter opt-in is the usual case.
Their text takes Markdown, so it can contain a link, and is truncated at 1000 characters.
`checked` sets the initial state and `required` makes the purchase conditional on the box
being ticked.

Checkboxes go in
[`options.additional_checkboxes`](/api/checkout/create-order-merchant/#body.options.additional_checkboxes),
and each one needs an `id` of your own. That id is how you tell the answers apart, so make it
stable and meaningful:

```json
{
  "options": {
    "additional_checkboxes": [
      {
        "id": "newsletter",
        "text": "Sign me up for the newsletter. [Terms](https://kustom.co)",
        "checked": true,
        "required": false
      },
      {
        "id": "loyalty",
        "text": "Enroll me in the loyalty program",
        "checked": false,
        "required": false
      }
    ]
  }
}
```

The `id` is mandatory. Omitting it fails the create call with `BAD_VALUE` on
`additional_checkboxes[0].id`.

There's also an older, singular `options.additional_checkbox` that takes one checkbox and no
`id`. Prefer the list for anything new: its answers arrive keyed by an id you chose.

The customer's answers come back under `merchant_requested` when you read the order:

```json
{
  "merchant_requested": {
    "additional_checkboxes": [
      { "id": "newsletter", "checked": true },
      { "id": "loyalty", "checked": false }
    ]
  }
}
```

They also arrive as `checkbox_change` client-side events while the customer is still in the
checkout. That event's `key` is the checkbox id you chose.

## Related

- [Create and update an order](/checkout/integrate/create-order/) — the call these options belong to
- [Checkout API reference](/api/checkout/) — the authoritative schema for every field here
- [Sell to businesses (B2B)](/checkout/use-cases/b2b/), [Age verification](/checkout/use-cases/age-verification/) and [Selling into several markets](/checkout/use-cases/multi-market/) — the jobs these options serve, each with the fields it needs
- [Charge a customer later](/checkout/recurring/) — customer tokens, in full
- [Shipping options in the checkout](/checkout/shipping/) — delivery choices, which follow the same order-line rules
- [Integration models](/checkout/#integration-models) — which integration model renders the order you're configuring