Introducción
Los metadatos te permiten almacenar información adicional y estructurada sobre tus objetos en Dodo Payments. Puedes adjuntar metadatos a la mayoría de los objetos de Dodo Payments, incluidos pagos, suscripciones y más.
Descripción General
- Las claves de metadatos pueden tener hasta 40 caracteres de longitud
- Los valores de metadatos pueden tener hasta 500 caracteres de longitud
- Puedes tener hasta 50 pares clave-valor de metadatos por objeto
- Las claves solo deben contener caracteres alfanuméricos, guiones y guiones bajos
- Los metadatos no son buscables a través de nuestra API, pero se devuelven en las respuestas de la API y en los webhooks
Casos de Uso
Los metadatos son útiles para:
- Almacenar identificadores o referencias externas
- Agregar anotaciones internas
- Vincular objetos de Dodo Payments a tu sistema
- Categorizar transacciones
- Agregar atributos personalizados para informes
Puedes agregar metadatos al crear o actualizar objetos a través de la API. Para productos, también tienes la opción de agregar metadatos directamente desde la interfaz del panel de control.
A través de la 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: '[email protected]',
name: 'John Doe',
metadata: {
crm_id: 'CRM-12345',
customer_segment: 'enterprise',
referral_source: 'website'
}
});
A través de la Interfaz del Panel de Control (Solo Productos)
Para productos, también puedes agregar metadatos directamente desde el panel de control de Dodo Payments al crear o editar un producto. La sección de metadatos te permite agregar fácilmente pares clave-valor personalizados sin escribir código.
Usar la interfaz del panel de control para metadatos de productos es particularmente útil para miembros del equipo no técnicos que necesitan gestionar información y categorías de productos.
// 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'
Búsqueda y Filtrado
Aunque los metadatos no son directamente buscables a través de nuestra API, puedes:
- Almacenar identificadores importantes en metadatos
- Recuperar objetos utilizando sus ID primarios
- Filtrar los resultados en el código de tu aplicación
// 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'
);
Mejores Prácticas
Haz:
- Usa convenciones de nomenclatura consistentes para las claves de metadatos
- Documenta tu esquema de metadatos internamente
- Mantén los valores cortos y significativos
- Usa metadatos solo para datos estáticos
- Considera usar prefijos para diferentes sistemas (por ejemplo,
crm_id, inventory_sku)
No Hagas:
- Almacenar datos sensibles en metadatos
- Usar metadatos para valores que cambian con frecuencia
- Confiar en metadatos para lógica empresarial crítica
- Almacenar información duplicada que esté disponible en otro lugar en el objeto
- Usar caracteres especiales en las claves de metadatos
Objetos Soportados
Los metadatos son compatibles con los siguientes objetos:
| Tipo de Objeto | Soporte |
|---|
| Pagos | ✓ |
| Suscripciones | ✓ |
| Productos | ✓ |
| Reembolsos | ✓ |
| Sesiones de Pago | ✓ |
| Clientes | ✓ |
// 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
}
});
