Metadata
Updatable objects—including AccountsAPI, CustomersAPI, Payment IntentsAPI, RefundAPI, and SubscriptionsAPI—have a metadata parameter for attaching key-value data. Metadata allows you to attach key-value pairs of data, providing a flexible way to store additional information that is not directly used by , such as a user's full name or unique identifiers.
Overview
Key aspects
- You may specify up to 50 keys.
- Key names can be up to 40 characters long.
- Values can contain up to 500 characters each.
Important considerations
- Only string values are permissible; null values will be disregarded.
- Avoid storing sensitive information within metadata to maintain data security.
- Do not include objects, arrays, or booleans in metadata unless they are converted to strings.
Filter by metadata tags
API supports filtering records by metadata tags. This is useful for segmenting your data and simplifying the retrieval of specific records based on set criteria.
Filtering across metadata is available when using the LIST operation. To filter by a metadata tag, include a query parameter in your API request that specifies the metadata key and value you want to filter by. For example, to filter for customers with a specific membership level, use the query below.
LIST /customers?metadata[membership_level]=gold
This request will return only those customers whose membership_level metadata is set to "gold". Utilizing metadata for filtering is particularly effective for segmenting your data and simplifying the retrieval of specific records based on set criteria.
Sample Use Cases
| USE CASE | OBJECT | METADATA KEY | DESCRIPTION |
|---|---|---|---|
| Enhanced reporting and tracking | Payment IntentsAPI | invoice_number | Attach your platform's invoice number to each payment, facilitating easier cross-referencing and reconciliation across your software and . |
| Custom payment tags | Payment IntentsAPI | payment_tag | Create custom tags for payments to categorize them for various purposes such as marketing campaigns, product lines, or sales channels. |
| Customer identification | CustomersAPI | platform_customer_id | Store unique customer identifiers within the platform, allowing seamless integration and easy lookup of customer information, enhancing customer management and support |
| Additional customer information | CustomersAPI | customer_notes | Add notes or additional information about customers that may be relevant for support or marketing purposes, such as preferences or account status. |
| Subscription tier information | SubscriptionsAPI | subscription_tier | Include details about subscription plans (e.g., gold, silver, platinum) to help manage and categorize subscriptions. |
| Detailed refund reasons | RefundsAPI | refund_reason_detail | Provide detailed reasons for refunds beyond standard reason properties, adding notes and context for complex scenarios. |