---
title: "Concat value to keys"
slug: "concat-value-to-keys"
description: "Transform API data with the concat_value_to_keys adapter, creating distinct field names for charges and refunds by prefixing or suffixing keys."
updated: 2026-06-04T07:44:36Z
published: 2026-06-04T07:44:36Z
canonical: "docs.supermetrics.com/concat-value-to-keys"
---

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

# Concat value to keys

The `concat_value_to_keys` adapter prefixes or suffixes field names on each row with the value of another field. Useful when an API returns mixed rows (such as charges and refunds in the same array) where the same property name means different things depending on a `type` field — joining the type into the key creates distinct field names you can sum independently.

| Field | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `dataPath` | string | – | Yes | JSONPath to the rows whose keys should be modified. |
| `valuePath` | string | – | Yes | JSONPath, relative to each row, to the field whose value is concatenated into the keys. |
| `keysToConcat` | array | `null` | No | Specific keys to modify. When `null`, all keys on the row are modified. |
| `prependValue` | boolean | `false` | No | When `true`, the value is added before the key (`charge_amount`). The default appends instead (`amount_charge`). |
| `preserveOriginalKeys` | boolean | `false` | No | When `true`, both the original and the new key are kept. The default removes the original. |

The examples below use the same input — a `data` array where each row has `amount`/`fee`/`net` values plus a `type` field marking whether it is a `charge` or a `refund`. The variations show how the config options change the resulting keys:

```
{
  "data": [
    {
      "id": "111",
      "amount": "1000",
      "fee": "10",
      "net": "990",
      "type": "charge"
    },
    {
      "id": "222",
      "amount": "2000",
      "fee": "20",
      "net": "1980",
      "type": "refund"
    }
  ]
}
```

## Default: appending the value to keys

By default, the value is appended to each modified key (joined by an underscore). With `type` = "charge" applied to `amount`, the resulting key is `amount_charge`.

After the adapter runs:

```
{
  "data": [
    {
      "id": "111",
      "amount_charge": "1000",
      "fee_charge": "10",
      "net_charge": "990",
      "type": "charge"
    },
    {
      "id": "222",
      "amount_refund": "2000",
      "fee_refund": "20",
      "net_refund": "1980",
      "type": "refund"
    }
  ]
}
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.data.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "concat_value_to_keys",
        "config": {
          "dataPath": "$.data",
          "valuePath": "$.type",
          "keysToConcat": [
            "amount",
            "fee",
            "net"
          ]
        }
      }
    ]
  }
}
```

Below you can find example field definitions that read from the transformed structure:

```
[
  {
    "id": "id",
    "label": "ID",
    "dataType": "string.text.value",
    "value": {
      "source": "jsonPath",
      "value": "$.id"
    }
  },
  {
    "id": "type",
    "label": "Type",
    "dataType": "string.text.value",
    "value": {
      "source": "jsonPath",
      "value": "$.type"
    }
  },
  {
    "id": "amount_charge",
    "label": "Charge amount",
    "dataType": "float.currency.value",
    "value": {
      "source": "jsonPath",
      "value": "$.amount_charge"
    }
  },
  {
    "id": "amount_refund",
    "label": "Refund amount",
    "dataType": "float.currency.value",
    "value": {
      "source": "jsonPath",
      "value": "$.amount_refund"
    }
  }
]
```

## Prepending the value to keys

Set `prependValue: true` to put the value before each modified key. The same input now produces `charge_amount` and `refund_amount`, which often reads more naturally than the default suffix pattern.

After the adapter runs:

```
{
  "data": [
    {
      "id": "111",
      "charge_amount": "1000",
      "charge_fee": "10",
      "charge_net": "990",
      "type": "charge"
    },
    {
      "id": "222",
      "refund_amount": "2000",
      "refund_fee": "20",
      "refund_net": "1980",
      "type": "refund"
    }
  ]
}
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.data.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "concat_value_to_keys",
        "config": {
          "dataPath": "$.data",
          "valuePath": "$.type",
          "keysToConcat": [
            "amount",
            "fee",
            "net"
          ],
          "prependValue": true
        }
      }
    ]
  }
}
```

Below you can find example field definitions that read from the transformed structure:

```
[
  {
    "id": "id",
    "label": "ID",
    "dataType": "string.text.value",
    "value": {
      "source": "jsonPath",
      "value": "$.id"
    }
  },
  {
    "id": "type",
    "label": "Type",
    "dataType": "string.text.value",
    "value": {
      "source": "jsonPath",
      "value": "$.type"
    }
  },
  {
    "id": "charge_amount",
    "label": "Charge amount",
    "dataType": "float.currency.value",
    "value": {
      "source": "jsonPath",
      "value": "$.charge_amount"
    }
  },
  {
    "id": "refund_amount",
    "label": "Refund amount",
    "dataType": "float.currency.value",
    "value": {
      "source": "jsonPath",
      "value": "$.refund_amount"
    }
  }
]
```

## Preserving the original keys

Set `preserveOriginalKeys: true` to keep both the original key and the prefixed (or suffixed) version on each row. Useful when you want both views available — the original keys (such as `amount`) for the per-row transaction value regardless of type, and the prefixed keys (`charge_amount`, `refund_amount`) for type-specific reporting.

After the adapter runs, each row carries both the original keys (`amount`, `fee`, `net`) and the prefixed keys (`charge_amount`, etc.):

```
{
  "data": [
    {
      "id": "111",
      "amount": "1000",
      "fee": "10",
      "net": "990",
      "charge_amount": "1000",
      "charge_fee": "10",
      "charge_net": "990",
      "type": "charge"
    },
    {
      "id": "222",
      "amount": "2000",
      "fee": "20",
      "net": "1980",
      "refund_amount": "2000",
      "refund_fee": "20",
      "refund_net": "1980",
      "type": "refund"
    }
  ]
}
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.data.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "concat_value_to_keys",
        "config": {
          "dataPath": "$.data",
          "valuePath": "$.type",
          "keysToConcat": [
            "amount",
            "fee",
            "net"
          ],
          "prependValue": true,
          "preserveOriginalKeys": true
        }
      }
    ]
  }
}
```

Below you can find example field definitions that read from the transformed structure:

```
[
  {
    "id": "id",
    "label": "ID",
    "dataType": "string.text.value",
    "value": {
      "source": "jsonPath",
      "value": "$.id"
    }
  },
  {
    "id": "amount",
    "label": "Amount",
    "dataType": "float.currency.value",
    "value": {
      "source": "jsonPath",
      "value": "$.amount"
    }
  },
  {
    "id": "charge_amount",
    "label": "Charge amount",
    "dataType": "float.currency.value",
    "value": {
      "source": "jsonPath",
      "value": "$.charge_amount"
    }
  },
  {
    "id": "refund_amount",
    "label": "Refund amount",
    "dataType": "float.currency.value",
    "value": {
      "source": "jsonPath",
      "value": "$.refund_amount"
    }
  }
]
```