Checkout options

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. They apply to the embedded checkout and to the 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, verifying an age, discounting a cart and opening a second 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".

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

Hide VAT from the order summary with options.vat_removed:

{
  "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:

{
  "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.

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, and each one needs an id of your own. That id is how you tell the answers apart, so make it stable and meaningful:

{
  "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:

{
  "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 — the call these options belong to
• Checkout API reference — the authoritative schema for every field here
• Sell to businesses (B2B), Age verification and Selling into several markets — the jobs these options serve, each with the fields it needs
• Charge a customer later — customer tokens, in full
• Shipping options in the checkout — delivery choices, which follow the same order-line rules
• Integration models — which integration model renders the order you’re configuring