# Your own data on an order

The three places you can put your own data on a Kustom order — merchant_reference1 and 2, merchant_data on the order and each line, and the extra merchant data attachment used for travel, events and marketplaces.

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](/api/requests-and-responses/) 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](/order-management/update-and-cancel/).

## 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](/api/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.

```json
{
  "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](/api/requests-and-responses/) — amounts, dates and identifier conventions
- [Updating references after the order exists](/order-management/update-and-cancel/) — the Order Management call that changes them
- [Staying under the request body cap](/api/limits/) — the 1MB limit a large attachment hits
- [Checking where `attachment` sits in the order body](/api/checkout/) — the generated Checkout schema