Skip to main content

​
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

// 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'
    }
});

​
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.
Product metadata interface in Dodo Payments dashboard
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: 
// 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
// Example: Find a checkout session using metadata
const checkoutSessions = await client.checkoutSessions.list({
  limit: 100
});

const matchingSession = checkoutSessions.data.find(
  session => session.metadata?.order_id === 'ORD-123'
);

// Example: Find a payment using your order ID
const payments = await client.payments.list({
  limit: 100
});

const matchingPayment = payments.data.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 TypeSupport
Payments✓
Subscriptions✓
Products✓
Refunds✓
Checkout Sessions✓
Customers✓

​
Webhooks and Metadata

Metadata is included in webhook events, making it easy to handle notifications with your custom data: 
// 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
  }
});