Custom metadata consists of user-defined data fields that can be added onto transactions. This is convenient for vendors using PartnerStack as a single source of truth for transaction records, and require additional fields for reporting purposes. (Ex. quote number, product description, campaign IDs).

These are stored as key-value pairs alongside the transaction. Metadata is not used by PartnerStack, and will not be shown to your partners unless you choose to show it to them.

You can add metadata at the time of a transaction's creation (using the POST endpoint) by specifying an object within the metadata attribute, for example:

curl -X "POST" "https://api.partnerstack.com/api/v2/transactions" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -u 'PUBLIC_KEY_HERE:PRIVATE_KEY_HERE' \
     -d $'{
  "amount": 1000,
  "currency": "USD",
  "metadata": {
    "order_company": "The Metadata Company",
    "order_number": 12345
  },
  "customer_external_key": "crust_lGuMlbMBqdIrbA"
}'

Afterwards, this metadata can be retrieved using our GET transactions endpoint, or by exporting your program's data to a CSV from within your dashboard.

The following restrictions apply to metadata:

Metadata cannot be updated (as transactions cannot be updated once created)
You can have a maximum of 25 metadata values stored in a single transaction
Each metadata key (e.g order_company) can be at most 30 characters long
- Metadata keys can only have letters, numbers or _ in them
Metadata values (e.g the The Metadata Company in the example above) can be either:
- null
- A string with a 100 character length limit
- An integer, or a decimal value