Metadata

Metadata allows you to store additional information as key-value pairs on Frame objects. You can use this feature to attach custom data, such as your system's unique identifiers, to Frame Customer objects.

Configuration

Data

You can store up to 20 key-value pairs with the following constraints:

  • key: 40 character limit (square brackets [ ] not allowed)
  • value: 100 character limit.

If you need to store more data, we recommend keeping it in your external database and using metadata to store the reference ID.

Important: Frame does not use metadata for processing (like authorizing or declining charges), and metadata is not visible to customers unless you choose to display it.

Security tip

Never store sensitive data like bank account or credit card details in metadata.

Requests

Metadata is only returned when using a secret key in your requests. For security reasons, metadata is automatically redacted from responses to publishable key requests (like Frame.js or Mobile SDKs client-side requests).

Add and update metadata

Add key-values pairs to metadata, update metadata values, and replace keys using the API. You can combine different actions into a single request to perform multiple metadata additions, updates, and deletions simultaneously.

Add key-value pairs

To add key-value pairs to metadata when creating an object, provide the keys and values in the object creation request.

Command Line
curl --request POST \
  --url https://api.framepayments.com/v1/customers \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "John",
  "email": "john@example.com",
  "metadata": {
    "company": "Acme Inc"
  }
}'
RESPONSE
{
  "id": "6018cf7b-809a-46e6-b3c6-d15ab5d85645",
  "object": "customer",
  ...
  "metadata": {
    "company": "Acme Inc"
  }
  ...
}

Add key-value pairs to existing metadata

To add key-value pairs to an existing object's metadata, provide the keys and values in an update request.

Note

When updating existing objects, metadata uses a merge mechanism. This means new key-value pairs are added without affecting existing ones. For example, adding key3 to an object with key1 and key2 results in an object containing all three keys.

Command Line
curl --request PATCH \
  --url https://api.framepayments.com/v1/customers/{{CUSTOMER_ID}} \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "reference_id": "e4db55f4-60b5-4249-9406-caaae17c28df"
  }
}'
RESPONSE
{
  "id": "6018cf7b-809a-46e6-b3c6-d15ab5d85645",
  "object": "customer",
  ...
  "metadata": {
    "reference_id": "e4db55f4-60b5-4249-9406-caaae17c28df",
    "company": "Acme Inc"
  }
  ...
}

Update metadata values

To update the value for an existing key in metadata, pass in the new value using the existing key. For example, you can update a Customer object with an existing key-value pair of "company": "Acme Inc" to "company": "Frame Payments Inc".

Command Line
curl --request PATCH \
  --url https://api.framepayments.com/v1/customers/{{CUSTOMER_ID}} \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "company": "Frame Payments Inc"
  }
}'
RESPONSE
{
  "id": "6018cf7b-809a-46e6-b3c6-d15ab5d85645",
  "object": "customer",
  ...
  "metadata": {
    "company": "Frame Payments Inc"
  }
  ...
}

Update metadata keys

To update a key that has an existing value, delete the key and pass its value to a new key. For example, you can update a Customer object to delete its "company" key and pass the key's value of "Frame Payments Inc" to a new "company_name" key.

Command Line
curl --request PATCH \
  --url https://api.framepayments.com/v1/customers/{{CUSTOMER_ID}} \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "company": "",
    "company_name": "Frame Payments Inc"
  }
}'
RESPONSE
{
  "id": "6018cf7b-809a-46e6-b3c6-d15ab5d85645",
  "object": "customer",
  ...
  "metadata": {
    "company_name": "Frame Payments Inc"
  }
  ...
}

Delete metadata

Delete a single key or an entire set of keys using the API.

Delete a single key

Pass in the key with an empty string as the value to remove the key from the metadata.

Command Line
curl --request PATCH \
  --url https://api.framepayments.com/v1/customers/{{CUSTOMER_ID}} \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "reference_id": ""
  }
}'
RESPONSE
{
  "id": "6018cf7b-809a-46e6-b3c6-d15ab5d85645",
  "object": "customer",
  ...
  "metadata": {
    "company_name": "Frame Payments Inc"
  }
  ...
}

Delete all keys

Pass an empty string as the value for the metadata attribute to delete all of the keys simultaneously.

Command Line
curl --request PATCH \
  --url https://api.framepayments.com/v1/customers/{{CUSTOMER_ID}} \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": ""
}'
RESPONSE
{
  "id": "6018cf7b-809a-46e6-b3c6-d15ab5d85645",
  "object": "customer",
  ...
  "metadata": {}
  ...
}