> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata Update Behavior

> Handle updates to trusted and untrusted metadata objects.

When updating `trusted_metadata` and `untrusted_metadata` objects, update payloads will be **merged with the existing objects at the top level only**.

## Adding a new field

To add a new field, pass a key-value pair.  Note that this will be **merged** with the existing object.
To add a new field, pass a key-value pair.  Note that this will be **merged** with the existing object.

```json Initial theme={null}
{
  "trusted_metadata": {
    "key1": "value1"
  }
}
```

```json Update theme={null}
{
  "trusted_metadata": {
    "key2": "value2"
  }
}
```

```json Result theme={null}
{
  "trusted_metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}
```

## Replacing an existing field

Pass a new value to an existing top-level key to replace field's value.

```json Initial theme={null}
{
  "untrusted_metadata": {
    "key1": "value1"
  }
}
```

```json Update theme={null}
{
  "untrusted_metadata": {
    "key1": "value2"
  }
}
```

```json Result theme={null}
{
  "untrusted_metadata": {
    "key1": "value2"
  }
}
```

## Updating a deeply nested field

Stytch will not merge deeply nested objects or arrays. To add a field to a deeply nested object, or update an array, replace the entire top-level key.

```json Initial theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
```

```json Update theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }, { "deep": "value2" }]
  }
}
```

```json Result theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }, { "deep": "value2" }],
    "other_key": "other_value"
  }
}
```

## Deleting a field

Pass a value of `null` to a top-level key to delete an existing field.

```json Initial theme={null}
{
  "untrusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
```

```json Update theme={null}
{
  "untrusted_metadata": {
    "key1": null
  }
}
```

```json Result theme={null}
{
  "untrusted_metadata": {
    "other_key": "other_value"
  }
}
```

## Deleting all fields

Pass a value of `null` to every top-level key to delete all fields.

```json Initial theme={null}
{
  "trusted_metadata": {
    "key1": [{ "deep": "value1" }],
    "other_key": "other_value"
  }
}
```

```json Update theme={null}
{
  "trusted_metadata": {
    "key1": null,
    "other_key": null
  }
}
```

```json Result theme={null}
{
  "trusted_metadata": {}
}
```