Metadata

metadata lets you attach your own custom key-value pairs to certain resources so you can correlate Buckaroo objects with identifiers in your own systems (for example: CRM IDs, channel, campaign tags).

Shape and type

metadata is a JSON object (dictionary/map):

• Keys: string
• Values: string
• Nullable / optional: you can omit it or pass null

Example:

{
  "metadata": {
    "customField": "value",
    "source": "website"
  }
}

Where metadata is supported

• Customers: POST /v1/customers
• Sales: POST /v1/sales

Size limit and errors

• metadata has a practical limit of about 4 KB per resource.
• If you exceed the limit, the API rejects the request with HTTP 413 Payload Too Large.

Recommendations:

• Keep keys and values short.
• Store large context in your own system and only store a reference in metadata (for example: contextId, externalReference).

Usage patterns

Customer create example

{
  "reference": "unique-reference",
  "givenName": "Mat",
  "familyName": "Cauthon",
  "metadata": {
    "crmCustomerId": "C-102938",
    "source": "website"
  }
}

metadata is stored with the customer and is returned when retrieving a customer.