> ## 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.
# Metadatenleitfaden
> Erfahren Sie, wie Sie Metadaten verwenden, um zusätzliche Informationen über Ihre Dodo Payments-Objekte zu speichern
## Einführung
Metadaten ermöglichen es Ihnen, zusätzliche, strukturierte Informationen über Ihre Objekte in Dodo Payments zu speichern. Sie können Metadaten an den meisten Dodo Payments-Objekten anhängen, einschließlich Zahlungen, Abonnements und mehr.
## Übersicht
* Metadaten-Schlüssel können bis zu 40 Zeichen lang sein
* Metadaten-Werte können eine Zeichenkette, eine Zahl oder ein boolean sein; Zeichenketten können bis zu 500 Zeichen lang sein
* Objekte, Arrays und `null` werden nicht als Metadaten-Werte akzeptiert
* Sie können bis zu 50 Metadaten-Schlüssel-Wert-Paare pro Objekt haben
* Schlüssel sollten nur alphanumerische Zeichen, Bindestriche und Unterstriche enthalten
* Metadaten sind nicht durch unsere API durchsuchbar, werden jedoch in API-Antworten und Webhooks zurückgegeben
## Anwendungsfälle
Metadaten sind nützlich für:
* Speichern externer IDs oder Referenzen
* Hinzufügen interner Anmerkungen
* Verknüpfen von Dodo Payments-Objekten mit Ihrem System
* Kategorisieren von Transaktionen
* Hinzufügen benutzerdefinierter Attribute für Berichte
## Hinzufügen von Metadaten
Sie können Metadaten beim Erstellen oder Aktualisieren von Objekten über die API hinzufügen. Für Produkte haben Sie auch die Möglichkeit, Metadaten direkt über die Dashboard-Benutzeroberfläche hinzuzufügen.
### Über die 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'
}
});
```
### Über die Dashboard-Benutzeroberfläche (nur Produkte)
Für Produkte können Sie Metadaten auch direkt über das Dodo Payments-Dashboard hinzufügen, wenn Sie ein Produkt erstellen oder bearbeiten. Der Metadatenbereich ermöglicht es Ihnen, benutzerdefinierte Schlüssel-Wert-Paare einfach hinzuzufügen, ohne Code schreiben zu müssen.
Die Verwendung der Dashboard-Benutzeroberfläche für Produktmetadaten ist besonders nützlich für nicht-technische Teammitglieder, die Produktinformationen und Kategorien verwalten müssen.
## Abrufen von Metadaten
Metadaten sind in API-Antworten enthalten, wenn Objekte abgerufen werden:
```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'
```
## Suchen und Filtern
Während Metadaten über unsere API nicht direkt durchsuchbar sind, können Sie:
1. Wichtige Identifikatoren in Metadaten speichern
2. Objekte anhand ihrer primären IDs abrufen
3. Die Ergebnisse in Ihrem Anwendungscode filtern
```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:
* Verwenden Sie konsistente Namenskonventionen für Metadaten-Schlüssel
* Dokumentieren Sie Ihr Metadatenschema intern
* Halten Sie Werte kurz und aussagekräftig
* Verwenden Sie Metadaten nur für statische Daten
* Erwägen Sie die Verwendung von Präfixen für verschiedene Systeme (z. B. `crm_id`, `inventory_sku`)
### Nicht tun:
* Sensible Daten in Metadaten speichern
* Metadaten für häufig wechselnde Werte verwenden
* Sich auf Metadaten für kritische Geschäftslogik verlassen
* Duplizierte Informationen speichern, die anderswo im Objekt verfügbar sind
* Sonderzeichen in Metadaten-Schlüsseln verwenden
## Unterstützte Objekte
Metadaten werden für die folgenden Objekte unterstützt:
| Objekttyp | Unterstützung |
| ------------------------ | ------------- |
| Zahlungen | ✓ |
| Abonnements | ✓ |
| Abonnement-Änderungsplan | ✓ |
| Produkte | ✓ |
| Rückerstattungen | ✓ |
| Checkout-Sitzungen | ✓ |
| Kunden | ✓ |
| Rabatte | ✓ |
## Webhooks und Metadaten
Metadaten sind in Webhook-Ereignissen enthalten, was es einfach macht, Benachrichtigungen mit Ihren benutzerdefinierten Daten zu verarbeiten:
```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 === 'subscription.active') {
const orderId = event.data.object.metadata.order_id;
const campaignSource = event.data.object.metadata.campaign_source;
// Handle subscription activation with custom metadata
}
});
```