Introduction
Les métadonnées vous permettent de stocker des informations supplémentaires et structurées sur vos objets dans Dodo Payments. Vous pouvez attacher des métadonnées à la plupart des objets Dodo Payments, y compris les paiements, les abonnements, et plus encore.
Aperçu
- Les clés de métadonnées peuvent comporter jusqu’à 40 caractères
- Les valeurs de métadonnées peuvent comporter jusqu’à 500 caractères
- Vous pouvez avoir jusqu’à 50 paires clé-valeur de métadonnées par objet
- Les clés ne doivent contenir que des caractères alphanumériques, des tirets et des underscores
- Les métadonnées ne sont pas recherchables via notre API mais sont renvoyées dans les réponses API et les webhooks
Cas d’utilisation
Les métadonnées sont utiles pour :
- Stocker des identifiants ou références externes
- Ajouter des annotations internes
- Lier des objets Dodo Payments à votre système
- Catégoriser les transactions
- Ajouter des attributs personnalisés pour les rapports
Ajout de métadonnées
Vous pouvez ajouter des métadonnées lors de la création ou de la mise à jour d’objets via l’API. Pour les produits, vous avez également la possibilité d’ajouter des métadonnées directement depuis l’interface du tableau de bord.
Via l’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'
}
});
Via l’interface du tableau de bord (Produits uniquement)
Pour les produits, vous pouvez également ajouter des métadonnées directement depuis le tableau de bord Dodo Payments lors de la création ou de l’édition d’un produit. La section des métadonnées vous permet d’ajouter facilement des paires clé-valeur personnalisées sans écrire de code.
Utiliser l’interface du tableau de bord pour les métadonnées des produits est particulièrement utile pour les membres non techniques de l’équipe qui doivent gérer les informations et catégories des produits.
Récupération des métadonnées
Les métadonnées sont incluses dans les réponses API lors de la récupération d’objets :
// 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'
Recherche et filtrage
Bien que les métadonnées ne soient pas directement recherchables via notre API, vous pouvez :
- Stocker des identifiants importants dans les métadonnées
- Récupérer des objets en utilisant leurs identifiants principaux
- Filtrer les résultats dans votre code d’application
// 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'
);
Meilleures pratiques
À faire :
- Utilisez des conventions de nommage cohérentes pour les clés de métadonnées
- Documentez votre schéma de métadonnées en interne
- Gardez les valeurs courtes et significatives
- Utilisez les métadonnées uniquement pour des données statiques
- Envisagez d’utiliser des préfixes pour différents systèmes (par exemple,
crm_id, inventory_sku)
À ne pas faire :
- Stocker des données sensibles dans les métadonnées
- Utiliser les métadonnées pour des valeurs changeantes fréquemment
- Compter sur les métadonnées pour une logique commerciale critique
- Stocker des informations en double qui sont disponibles ailleurs dans l’objet
- Utiliser des caractères spéciaux dans les clés de métadonnées
Objets pris en charge
Les métadonnées sont prises en charge sur les objets suivants :
| Type d’objet | Support |
|---|
| Paiements | ✓ |
| Abonnements | ✓ |
| Produits | ✓ |
| Remboursements | ✓ |
| Sessions de paiement | ✓ |
| Clients | ✓ |
Webhooks et métadonnées
Les métadonnées sont incluses dans les événements de webhook, ce qui facilite la gestion des notifications avec vos données personnalisées :
// 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
}
});
