> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Metadata Guide
> Learn how to use metadata to store additional information about your Dodo Payments objects
## Introduction
Metadata allows you to store additional, structured information about your objects in Dodo Payments. You can attach metadata to most Dodo Payments objects, including payments, subscriptions, and more.
## Overview
* Metadata keys can be up to 40 characters long
* Metadata values can be up to 500 characters long
* You can have up to 50 metadata key-value pairs per object
* Keys should only contain alphanumeric characters, dashes, and underscores
* Metadata is not searchable using our API but is returned in API responses and webhooks
## Use Cases
Metadata is useful for:
* Storing external IDs or references
* Adding internal annotations
* Linking Dodo Payments objects to your system
* Categorizing transactions
* Adding custom attributes for reporting
## Adding Metadata
You can add metadata when creating or updating objects through the API. For products, you also have the option to add metadata directly from the dashboard UI.
### Via API
```javascript theme={null}
// Adding metadata when creating a checkout session
const checkoutSession = await client.checkoutSessions.create({
product_cart: [{ product_id: 'product_id', quantity: 1 }],
return_url: 'https://example.com/return',
metadata: {
order_id: 'ORD-123',
campaign_source: 'email',
customer_segment: 'premium'
}
});
// Adding metadata when creating a payment
const payment = await client.payments.create({
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { customer_id: 'customer_id' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
metadata:{order_id: 'ORD-123', customer_notes: 'Customer notes'}
});
// Adding metadata when creating a product
const product = await client.products.create({
name: 'Premium Software License',
price: 9900,
currency: 'USD',
metadata: {
category: 'software',
license_type: 'premium',
support_tier: 'priority'
}
});
// Adding metadata when creating a customer
const customer = await client.customers.create({
email: 'customer@example.com',
name: 'John Doe',
metadata: {
crm_id: 'CRM-12345',
customer_segment: 'enterprise',
referral_source: 'website'
}
});
// Adding metadata when changing a subscription plan
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_premium',
proration_billing_mode: 'prorated_immediately',
quantity: 1,
metadata: {
upgrade_reason: 'feature_request',
previous_plan: 'basic',
sales_rep: 'john@company.com'
}
});
// Adding metadata when creating a discount
const discount = await client.discounts.create({
type: 'percentage',
amount: 1500, // 15%
code: 'SUMMER2025',
metadata: {
campaign: 'summer_promo',
source: 'email_blast',
team: 'marketing'
}
});
```
### Via Dashboard UI (Products Only)
For products, you can also add metadata directly from the Dodo Payments dashboard when creating or editing a product. The metadata section allows you to easily add custom key-value pairs without writing code.
Using the dashboard UI for product metadata is particularly useful for non-technical team members who need to manage product information and categories.
## Retrieving Metadata
Metadata is included in API responses when retrieving objects:
```javascript theme={null}
// Retrieving checkout session metadata
const checkoutSession = await client.checkoutSessions.retrieve('cs_123');
console.log(checkoutSession.metadata.order_id); // 'ORD-123'
// Retrieving payment metadata
const payment = await client.payments.retrieve('pay_123');
console.log(payment.metadata.order_id); // '6735'
// Retrieving customer metadata
const customer = await client.customers.retrieve('customer_123');
console.log(customer.metadata.crm_id); // 'CRM-12345'
// Retrieving refund metadata
const refund = await client.refunds.retrieve('refund_123');
console.log(refund.metadata.refund_reason); // 'customer_request'
```
## Searching and Filtering
While metadata is not directly searchable via our API, you can:
1. Store important identifiers in metadata
2. Retrieve objects using their primary IDs
3. Filter the results in your application code
```javascript theme={null}
// Example: Find a payment using your order ID
const payments = await client.payments.list({
page_size: 100
});
const matchingPayment = payments.items.find(
payment => payment.metadata.order_id === '6735'
);
```
## Best Practices
### Do:
* Use consistent naming conventions for metadata keys
* Document your metadata schema internally
* Keep values short and meaningful
* Use metadata for static data only
* Consider using prefixes for different systems (e.g., `crm_id`, `inventory_sku`)
### Don't:
* Store sensitive data in metadata
* Use metadata for frequently changing values
* Rely on metadata for critical business logic
* Store duplicate information that's available elsewhere in the object
* Use special characters in metadata keys
## Supported Objects
Metadata is supported on the following objects:
| Object Type | Support |
| ------------------------ | ------- |
| Payments | ✓ |
| Subscriptions | ✓ |
| Subscription Change Plan | ✓ |
| Products | ✓ |
| Refunds | ✓ |
| Checkout Sessions | ✓ |
| Customers | ✓ |
| Discounts | ✓ |
## Webhooks and Metadata
Metadata is included in webhook events, making it easy to handle notifications with your custom data:
```javascript theme={null}
// Example webhook handler
app.post('/webhook', (req, res) => {
const event = req.body;
if (event.type === 'payment.succeeded') {
const orderId = event.data.object.metadata.order_id;
// Process order using your internal order ID
}
if (event.type === 'checkout.session.completed') {
const orderId = event.data.object.metadata.order_id;
const campaignSource = event.data.object.metadata.campaign_source;
// Handle checkout session completion with custom metadata
}
});
```