# Metadata

The Trustap API transaction supports a metadata field.

* The metadata field stores key-value pairs in a JSON format.
* You can store up to 100 key-value pairs.
* The maximum length of each JSON key is 40 characters and each JSON value is 100 characters.
* Only strings are supported.


If you exceed your 100 key-value pairs, you will receive an error `too_many_metadata_fields`.

## Add metadata to an existing transaction

Metadata can only be added to existing transactions. In this example, the transaction ID is `tx_01kv7vtr9vfr5rnttm3n4x17z2`.
The response is the entire transaction object including all metadata associated with a

Add metadata
```CURL
curl -i -X POST \
  -u '<API_KEY>:​' \
  'https://api.test.trustap.com/v2/transactions/tx_01kv7vtr9vfr5rnttm3n4x17z2/metadata' \
  -H 'Content-Type: application/json' \
  -d '{"customer_url":"https://my-bike-parts.com/","part_number":"98932"}'
```

Response
```JSON
{
	"buyer": {
		"id": "1-506ec116-f0b3-4ea8-bfd0-ea0e7b9d18aa",
		"is_guest": true
	},
	"client_id": "5a3d7990-9f1c-4e11-8d67-3da5b160c50a",
	"contains_shipping": true,
	"deadlines": {
		"complaints": null
	},
	"description": "Trustap socks",
	"events": {
		"by_key": {
			"created": "2026-06-16T09:22:35Z",
			"joined": "2026-06-16T09:22:35Z"
		},
		"by_time": [
			{
				"at": "2026-06-16T09:22:35Z",
				"code": "created"
			},
			{
				"at": "2026-06-16T09:22:35Z",
				"code": "joined"
			}
		]
	},
	"id": "tx_01kv7vtr9vfr5rnttm3n4x17z2",
	"metadata": {
		"customer_url": "https://my-bike-parts.com/",
		"part_number": "98932"
	},
	"pricing": {
		"amount": 20000,
		"amount_extra": 0,
		"currency": "eur",
		"fees": {
			"buyer": 1050,
			"buyer_client": 0,
			"seller": 0,
			"seller_client": 0
		}
	},
	"seller": {
		"id": "8e5cbedc-e57b-42e5-a3bd-2f9ced81a2d0",
		"is_guest": false
	},
	"status": "joined"
}
```

## Read metadata

Metadata is part of the transaction object. To read metadata, retrieve the transaction and extract the `metadata` field.

Read metadata
```CURL
 curl -i -X GET \
  -u '<API_KEY>:' \
  'https://api.test.trustap.com/v2/transactions/tx_01kv7vtr9vfr5rnttm3n4x17z2'
```

Response
```JSON
{
	"buyer": {
		"id": "1-506ec116-f0b3-4ea8-bfd0-ea0e7b9d18aa",
		"is_guest": true
	},
	"cancellation": {
		"description": "Transaction cancelled by bot on behalf of: seller"
	},
	"client_id": "5a3d7990-9f1c-4e11-8d67-3da5b160c50a",
	"contains_shipping": true,
	"deadlines": {
		"complaints": null
	},
	"description": "Trustap socks",
	"events": {
		"by_key": {
			"cancelled": "2026-06-16T09:30:55Z",
			"created": "2026-06-16T09:22:35Z",
			"joined": "2026-06-16T09:22:35Z"
		},
		"by_time": [
			{
				"at": "2026-06-16T09:22:35Z",
				"code": "created"
			},
			{
				"at": "2026-06-16T09:22:35Z",
				"code": "joined"
			},
			{
				"at": "2026-06-16T09:30:55Z",
				"code": "cancelled"
			}
		]
	},
	"id": "tx_01kv7vtr9vfr5rnttm3n4x17z2",
	"metadata": {
		"customer_url": "https://my-bike-parts.com/",
		"part_number": "98932"
	},
	"pricing": {
		"amount": 20000,
		"amount_extra": 0,
		"currency": "eur",
		"fees": {
			"buyer": 1050,
			"buyer_client": 0,
			"seller": 0,
			"seller_client": 0
		}
	},
	"seller": {
		"id": "8e5cbedc-e57b-42e5-a3bd-2f9ced81a2d0",
		"is_guest": false
	},
	"status": "cancelled"
}
```

## Update metadata

You cannot delete a metadata entry but you can update an existing entry.
You can add additional key-value pairs without overwriting existing metadata up to the maximum of 100 key-value pairs.
The Trustap API supports updating existing values and adding new key-value pairs in the same call.

Update metadata
```CURL
curl -i -X POST \
  -u '<API_KEY>:'​ \
  'https://api.test.trustap.com/v2/transactions/tx_01kv7vtr9vfr5rnttm3n4x17z2/metadata' \
  -H 'Content-Type: application/json' \
  -d '{"customer_url":"https://my-bike-parts.com/","part_number":"55555"}'
```

Response
```JSON
{
	"buyer": {
		"id": "1-506ec116-f0b3-4ea8-bfd0-ea0e7b9d18aa",
		"is_guest": true
	},
	"cancellation": {
		"description": "Transaction cancelled by bot on behalf of: seller"
	},
	"client_id": "5a3d7990-9f1c-4e11-8d67-3da5b160c50a",
	"contains_shipping": true,
	"deadlines": {
		"complaints": null
	},
	"description": "Trustap socks",
	"events": {
		"by_key": {
			"cancelled": "2026-06-16T09:30:55Z",
			"created": "2026-06-16T09:22:35Z",
			"joined": "2026-06-16T09:22:35Z"
		},
		"by_time": [
			{
				"at": "2026-06-16T09:22:35Z",
				"code": "created"
			},
			{
				"at": "2026-06-16T09:22:35Z",
				"code": "joined"
			},
			{
				"at": "2026-06-16T09:30:55Z",
				"code": "cancelled"
			}
		]
	},
	"id": "tx_01kv7vtr9vfr5rnttm3n4x17z2",
	"metadata": {
		"customer_url": "https://my-bike-parts.com/",
		"part_number": "55555"
	},
	"pricing": {
		"amount": 20000,
		"amount_extra": 0,
		"currency": "eur",
		"fees": {
			"buyer": 1050,
			"buyer_client": 0,
			"seller": 0,
			"seller_client": 0
		}
	},
	"seller": {
		"id": "8e5cbedc-e57b-42e5-a3bd-2f9ced81a2d0",
		"is_guest": false
	},
	"status": "cancelled"
}
```