OnKustomCheckboxes hook
Kustom Checkout can render additional checkboxes beneath the purchase button — for example a marketing-consent opt-in or a "create an account" toggle. The Kustom app fires the custom hook OnKustomCheckboxes while building the Kustom order in the checkout ingress. Merchant rules listen to it and return the checkboxes to render for the current cart and channel.
Unlike external payment methods, checkboxes do not change the payment flow. They collect a boolean from the customer that is read back on completion and stored on the created order as a dynamic field, where downstream rules (e.g. a customer/CRM sync) can act on it.
When It Fires
Once per Kustom order creation, from the checkout ingress, before the order is sent to Kustom. The effects returned by listeners are added to the Kustom order's merchant_requested.additional_checkboxes array. If no listener returns a checkbox, the array is omitted.
Hook Input
{
hook: 'OnKustomCheckboxes'
cartId: uuid
channelKey: text
currencyCode: text
orderTotal: number
locale: text
}| Field | Notes |
|---|---|
cartId | The cart being checked out. |
channelKey | Channel the cart belongs to — use this to scope which channels show which checkboxes. |
currencyCode | Order currency. |
orderTotal | Order total (in major units). |
locale | The cart locale (e.g. sv-SE), so the label can be localized. |
Emitting a Checkbox
Listeners emit a custom effect with type = 'checkbox'. The Kustom app maps these to KCO additional_checkboxes entries.
| Field | Required | Notes |
|---|---|---|
effect | yes | Must be 'custom'. |
type | yes | Must be 'checkbox'. |
id | yes | Stable identifier for the checkbox. Used to read the value back on completion. |
name | yes | The label shown to the customer. Localize this using the locale input. |
checked | no | Initial checked state. Defaults to false. |
required | no | Whether the customer must tick it to complete checkout. Defaults to false. |
Reading the Value Back
When the order completes, the Kustom app reads the customer's selection from the returned order's merchant_requested.additional_checkboxes (matched by id) and stores it on the created order as a dynamic field. A merchant rule listening on the order can then act on it — for example flipping marketing-consent flags on the customer record.
Example: Marketing-consent opt-in
import 'iterators'
param input: {
hook: 'OnKustomCheckboxes'
cartId: uuid
channelKey: text
currencyCode: text
orderTotal: number
locale: text
}
let label = input.locale match
'da_DK' |> 'Ja tak, jeg vil gerne modtage nyheder og tilbud.'
'de_DE' |> 'Ja, ich möchte Neuigkeiten und Angebote erhalten.'
'fi_FI' |> 'Kyllä, haluan vastaanottaa uutisia ja tarjouksia.'
'fr_FR' |> 'Oui, je souhaite recevoir des actualités et des offres.'
'nb_NO' |> 'Ja takk, jeg vil motta nyheter og tilbud.'
'sv_SE' |> 'Ja tack, jag vill ta emot nyheter och erbjudanden.'
|> 'Yes please, I would like to receive news and offers.'
from [{
effect = 'custom'
type = 'checkbox'
id = 'marketingConsent'
name = label
checked = false
required = false
}]On completion, the marketingConsent value is stored on the order. A separate order rule can read it and, when true, update the customer's marketing preferences.