Using metadata to improve data integration
A generic key-value store
Some of the major entities in Devengo's API support the assignment of metadata. This metadata works like a flexible and generic key-value store that is attached to each one of the entities you create through the API.
This structured storage provides the opportunity to hold any extra, consumer-specific information that you may find helpful to identify, connect or contextualize an entity. See below a list of potential use cases.
Devengo will never update this metadata -unless to remove/reset it as described below- or use it for any internal operation.
You can check if an entity supports this feature by checking for the parameter metadata in the creation/updating endpoint.
Metadata limits and behavior
There are some limits to the information you can store as metadata:
- A maximum of 64 keys for each entity.
- A maximum of 64 bytes for each metadata key.
- A maximum of 512 bytes for each metadata value.
- All the values and keys will be coerced to strings.
Additionally, you can reset the whole metadata store or remove any specific key by setting them up to null.
Good practices
- Do not store any sensitive information (bank account numbers, identification documents, etc.) as metadata.
- Send only UTF-8 valid strings as key/values. Any other JSON valid object will be coerced to strings.
- Store the minimum viable amount of information (usually an ID). Although the limits established for metadata are generous and give you roughly 32Kb of storage per entity we recommend to be frugal in the use of this feature to maximize flexibility and simplicity.
Some potential scenarios for metadata
The whole idea behind metadata is to provide a light, flexible, customizable way to integrate your systems with Devengo. The simplest way to do it is by annotating Devengo's entities with the relevant IDs in your systems (orders, invoices, etc.)
As Devengo API can be used to cover most business scenarios that involve the delivery or reception of money the number of potential integrations is very large but here are some possible use cases:
Marketplace payouts
Are you generating payouts for the merchants in your marketplace? Add their IDs as metadata to each payment so you can retrieve all the payments done to a merchant easily.
Refund details
Are you sending a refund to a customer because of some defect or problem? Just annotate your Payment metadata with your support ticket number or URL. This way you can trace back the outgoing transaction to the original issue.
Invoice & Order automation
Has an incoming payment generated an invoice or order update for one of your customers? Use metadata to include the IDs of any entity generated by the pay-in and retrieve it easily in the future when needed.