Metadata

Many Odus API resources support a metadata field that lets you attach custom key-value data to objects. This is useful for storing additional structured information that's relevant to your business logic that is not captured by the standard fields.

Common use cases include storing order IDs, internal reference numbers, fulfillment tracking codes, or any other contextual information you need to associate with payments, customers, subscriptions, and other resources.

How metadata works

The metadata field accepts a JSON object where both keys and values must be strings. When you update a resource with metadata, the new data is merged with any existing metadata rather than replacing it entirely. This means you can update specific keys without affecting others.

Initial metadata

{
  "orderId": "12345",
  "source": "mobile_app"
}

Update request

{
  "metadata": {
    "orderId": "67890",
    "priority": "high"
  }
}

Result after merge

{
  "orderId": "67890",
  "source": "mobile_app",
  "priority": "high"
}

Clearing metadata fields

To remove a specific metadata key, set its value to an empty string in your update request. The key will be deleted from the metadata object:

Clearing a single field

{
  "metadata": {
    "orderId": ""
  }
}

Result

{
  "source": "mobile_app",
  "priority": "high"
}

To clear all metadata at once, pass null as the value for the entire metadata field:

Clearing all metadata

{
  "metadata": null
}

Validation rules

Metadata values must conform to the following constraints:

Rule	Limit
Key-value pairs	Maximum 50
Value length	Maximum 500 characters per value
Value type	Only string values are allowed

Requests that violate these constraints will be rejected with a validation error indicating which rule was broken.

Working with metadata

Metadata can be set during resource creation or updated later using the corresponding update endpoint. Here's an example of creating a payment with metadata:

Creating a payment with metadata

{
  "amount": 5000,
  "currency": "usd",
  "metadata": {
    "orderId": "ORD-2024-1234",
    "campaignId": "SPRING_SALE",
    "notes": "Priority shipping requested"
  }
}

The same approach works for customers, subscriptions, and other resources that support metadata. When retrieving resources, the metadata object is included in the response:

Payment response

{
  "id": "pay_abc123",
  "amount": 5000,
  "currency": "usd",
  "status": "succeeded",
  "metadata": {
    "orderId": "ORD-2024-1234",
    "campaignId": "SPRING_SALE",
    "notes": "Priority shipping requested"
  }
}