Metadata is a powerful feature in Straddle that allows you to attach custom key-value pairs to various objects. This guide will explain how to use metadata effectively, its benefits, and best practices.

​
What is Metadata?

Metadata in Straddle is a set of key-value pairs that you can attach to objects such as customers, charges, payouts, and more. It allows you to store additional, structured information that is important for your business but isn’t covered by Straddle’s standard fields.
Metadata is not used by Straddle for any purpose other than storing on the object for your use in the future. It’s purely for your own record-keeping.

​
Benefits of Using Metadata

  1. Custom Data Storage: Store information specific to your business needs.
  2. Improved Searchability: Use metadata to filter objects in API requests.
  3. Enhanced Reporting: Include metadata in exported reports for better analysis.
  4. Integration Flexibility: Facilitate integrations with other systems by storing external IDs or references.

​
How to Use Metadata

You can add metadata when creating or updating objects via the Straddle API. Here are some examples:

​
Adding Metadata When Creating a Customer

curl https://api.straddle.io/v1/customers \
  -H "Authorization: Bearer sk_test_51NBBbbDBkrcnHrnR0nBGsOvFHQrM0n8T1FKZmAUWbJqq8oRsAM3dEZzBIbHwzKrVUUFOyRvX1Ib8Sn3VWWQMW00r300IIrGBWb1" \
  -d email="john@example.com" \
  -d metadata[order_id]="6735" \
  -d metadata[customer_group]="premium"

​
Updating Metadata on an Existing Charge

curl https://api.straddle.io/v1/charges/ch_1234567890 \
  -H "Authorization: Bearer sk_test_51NBBbbDBkrcnHrnR0nBGsOvFHQrM0n8T1FKZmAUWbJqq8oRsAM3dEZzBIbHwzKrVUUFOyRvX1Ib8Sn3VWWQMW00r300IIrGBWb1" \
  -d metadata[sales_rep]="Jane Doe" \
  -d metadata[promotion_code]="SUMMER2023"

​
Retrieving Metadata

When you retrieve an object via the API, its metadata is included in the response. Here’s an example of retrieving a customer: 
curl https://api.straddle.io/v1/customers/cus_1234567890 \
  -H "Authorization: Bearer sk_test_51NBBbbDBkrcnHrnR0nBGsOvFHQrM0n8T1FKZmAUWbJqq8oRsAM3dEZzBIbHwzKrVUUFOyRvX1Ib8Sn3VWWQMW00r300IIrGBWb1"

​
Best Practices

  1. Use Consistent Keys: Establish a naming convention for your metadata keys and stick to it.
  2. Keep It Simple: Metadata is best suited for simple key-value pairs. For complex data structures, consider storing a reference ID in metadata and keep the full data in your own database.
  3. Avoid Sensitive Data: Don’t store sensitive information (like credit card numbers or social security numbers) in metadata.
  4. Update Carefully: When updating metadata, be aware that you’re replacing the entire metadata object. To add or modify a single field without affecting others, first retrieve the current metadata, modify it, then update the object with the new metadata.
  5. Use for Searchability: Leverage metadata for fields you’ll want to search or filter by later.

​
Limitations

  • Metadata keys and values must be 80 characters or less.
  • You can have up to 20 keys in the metadata dictionary.
  • Metadata is not indexed, so searching large volumes of objects by metadata can be slow.
Changes to metadata are not versioned. Once you change a metadata value, you cannot retrieve its previous value.

​
Conclusion

Metadata is a flexible and powerful feature in Straddle that allows you to customize and extend the platform to fit your specific business needs. By following these guidelines and best practices, you can effectively use metadata to enhance your integration with Straddle. For more information on how metadata behaves with specific API endpoints, refer to our API Reference documentation.