Your own data on an order

Kustom stores data of yours alongside an order and returns it whenever the order is read. There are three distinct slots, and they aren’t interchangeable. Two reference fields hold your own order number, merchant_data holds arbitrary blobs on the order and on each line, and attachment holds extra merchant data — a structure Kustom validates against a published JSON schema.

The three slots, and which to use

Slot	Where it lives	Shape	Use it for
merchant_reference1, merchant_reference2	on the order	short string	Your internal order reference, so a Kustom order can be found from your system and vice versa.
merchant_data	on the order, and on each order line	arbitrary string	Anything of yours that only your code reads.
attachment	on the order	content_type plus a body of serialized JSON matching Kustom’s extra merchant data schema	Structured detail about what was bought — travel, events, marketplaces, customer history.

The distinction that matters is validation. merchant_data is opaque to Kustom and is returned exactly as you sent it, while attachment.body is parsed against a schema. Putting travel details in merchant_data means nothing downstream can read them. Putting free-form notes in attachment gets you a 400.

Merchant references

merchant_reference1 and merchant_reference2 carry your own order identifiers. They are _reference fields, which by Kustom’s identifier convention means you mint the values, not Kustom.

They can be set when the order is created and updated afterwards through Order Management, so an order created before your own order number exists can still be reconciled later. See Update or cancel an order.

merchant_data on the order and each line

merchant_data exists twice: once on the order, and once on every order line. It’s returned verbatim on every read.

Two cautions. It has its own length limit — 6000 characters on the order, 1024 on each order line — and an over-length value is rejected, so it isn’t a document store. And it’s returned to anything that can read the order, so it isn’t a place for secrets or for personal data you would not otherwise be sending Kustom.

Extra merchant data in attachment.body

Extra merchant data is optional, and a new integration does not need it. “EMD” and attachment name the same thing: EMD is the payload, and attachment is where you send it.

The Checkout and Customer Token APIs accept an attachment object with two required properties. content_type names the schema Kustom validates against, and body is a string containing serialized JSON — not a nested JSON object. Serialize, then assign.

{
  "attachment": {
    "content_type": "application/vnd.klarna.internal.emd-v2+json",
    "body": "{\"event\":[{\"event_name\":\"Concert\",\"start_time\":\"2026-09-14T19:00:00Z\"}]}"
  }
}

Both are required: an attachment sent without content_type is rejected with Attachment must have content type, and without body with Attachment must have body. The body is capped at 1MB.

The structure inside that string is fixed by Kustom’s extra merchant data JSON schema, which is published with the Checkout API description — ask Kustom for the current schema file rather than inferring it from the table below. A body that doesn’t validate comes back as a 400 naming the attachment field.

Extra merchant data fields

Every field is an array of objects.

Field	What it describes
air_reservation_details	Air travel reservations and passengers.
bus_reservation_details	Bus travel reservations and passengers.
train_reservation_details	Train travel reservations and passengers.
ferry_reservation_details	Ferry travel reservations and passengers.
hotel_reservation_details	Hotel room reservations.
car_rental_reservation_details	Car rentals and drivers.
event	Events, including venue and ticket details. Entertainment and educational alike.
voucher	Purchased vouchers.
subscription	Subscriptions, with their start and end time and whether they renew automatically.
marketplace_seller_info	Merchants selling goods in a marketplace.
marketplace_winner_info	Customers purchasing goods in a marketplace.
customer_account_info	Customers registered in your store.
payment_history_full	Detailed purchase history for a registered customer.
payment_history_simple	Basic history for a customer with at least one prior purchase.
other_delivery_address	Non-residential delivery addresses, such as a store or a pick-up point.

Send only the sections that describe the purchase. Sending a section with placeholder values is worse than omitting it.

Related

• Serializing the values inside these fields — amounts, dates and identifier conventions
• Updating references after the order exists — the Order Management call that changes them
• Staying under the request body cap — the 1MB limit a large attachment hits
• Checking where attachment sits in the order body — the generated Checkout schema