​
Overview

All primary resources in the OpenFX v1 API support a metadata field — a flexible key-value store where you can attach your own data. Metadata is useful for linking OpenFX resources to records in your internal systems, categorizing resources, or storing contextual information that does not fit into the standard resource fields. 
{
  "id": "pmt_01953e1a5f4b7005",
  "status": "completed",
  "metadata": {
    "internal_invoice_id": "INV-2026-00142",
    "erp_reference": "SAP-PO-88721",
    "cost_center": "engineering",
    "priority": "high"
  }
}

​
Constraints

ConstraintValue
Maximum number of keys50
Key pattern^[a-zA-Z0-9_]{1,40}$ (alphanumeric and underscores, 1-40 characters)
Value typeString (max 500 characters) or null
Available onAll primary resources (entities, customers, accounts, counterparties, payments, etc.)
Metadata keys must match the pattern ^[a-zA-Z0-9_]{1,40}$. Keys containing spaces, dashes, dots, or other special characters will be rejected with a 400 invalid_request_error.

​
Setting Metadata

You can set metadata when creating a resource or update it later with a PATCH request.

​
On Resource Creation

Include the metadata object in the request body: 
import requests

response = requests.post(
    "https://sandbox.api.openfx.com/v1/payments",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": idempotency_key,
        "Content-Type": "application/json",
    },
    json={
        "sourceAccountId": "acc_01953e1a5f4b7002",
        "counterpartyId": "cpt_01953e1a5f4b7004",
        "paymentMethodId": "pm_01953e1a5f4b7300",
        "rail": "ach",
        "sendAmount": {"currency": "USD", "value": "150000"},
        "metadata": {
            "internal_invoice_id": "INV-2026-00142",
            "erp_reference": "SAP-PO-88721",
            "department": "finance",
        },
    },
)

​
Updating Metadata

Update metadata on an existing resource using PATCH. The metadata object in a PATCH request is merged with existing metadata — keys you include are added or updated, and keys you omit are left unchanged. To remove a key, set its value to null. 
# Add a new key and update an existing one
response = requests.patch(
    "https://sandbox.api.openfx.com/v1/accounts/acc_01953e1a5f4b7002",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": idempotency_key,
        "Content-Type": "application/json",
    },
    json={
        "metadata": {
            "cost_center": "engineering",       # Add new key
            "department": "product_engineering", # Update existing key
            "old_reference": None,               # Remove this key
        }
    },
)

​
Reading Metadata

Metadata is included in all GET responses for resources that support it: 
GET /v1/accounts/acc_01953e1a5f4b7002

{
  "id": "acc_01953e1a5f4b7002",
  "type": "demand_deposit",
  "currency": "USD",
  "status": "active",
  "metadata": {
    "cost_center": "engineering",
    "department": "product_engineering",
    "internal_account_code": "ACC-1042"
  },
  "createdAt": "2026-02-23T12:00:00Z",
  "updatedAt": "2026-02-23T14:30:00Z"
}
Metadata is also included when resources appear in list endpoint responses and webhook event payloads.

​
Common Use Cases

​
Internal Reference IDs

Link OpenFX resources to your internal systems: 
{
  "metadata": {
    "internal_order_id": "ORD-2026-88721",
    "erp_reference": "SAP-PO-88721",
    "salesforce_opportunity": "0061R00001ABC"
  }
}

​
Categorization and Tagging

Categorize resources for reporting and filtering: 
{
  "metadata": {
    "department": "treasury",
    "cost_center": "CC_4200",
    "payment_category": "vendor_payment",
    "region": "emea"
  }
}

​
Workflow Tracking

Track processing state in your application: 
{
  "metadata": {
    "approval_status": "approved",
    "approved_by": "jane_smith",
    "approval_date": "2026-02-20",
    "batch_id": "BATCH-2026-02-20-001"
  }
}

​
Best Practices

Use consistent key naming conventions. Adopt a standard pattern across your team (e.g., snake_case keys). This makes metadata easier to query and manage.
Store references, not duplicates. Use metadata to store IDs that link to your internal systems rather than duplicating data that already exists elsewhere. For example, store internal_invoice_id rather than copying the entire invoice payload.
Keep values concise. The 500-character limit per value is intentional. Metadata is for lightweight key-value tags, not for storing large documents or JSON blobs.
Do not store sensitive data in metadata. Metadata is returned in API responses, webhook payloads, and event payloads. Do not store passwords, API keys, personally identifiable information (PII), or financial credentials in metadata fields.
Do not exceed 50 keys per resource. If you need to store more than 50 key-value pairs, consider whether some of this data belongs in your own database rather than in OpenFX metadata.