Zum Hauptinhalt springen

​
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 bis zu 500 Zeichen lang sein
  • 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 über unsere API nicht 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

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

​
Ü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.
Produktmetadaten-Schnittstelle im Dodo Payments-Dashboard
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: 
// 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
// 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

​
Tun:

  • Verwenden Sie konsistente Namenskonventionen für Metadaten-Schlüssel
  • Dokumentieren Sie Ihr Metadaten-Schema 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:
ObjekttypUnterstützung
Zahlungen✓
Abonnements✓
Produkte✓
Rückerstattungen✓
Checkout-Sitzungen✓
Kunden✓

​
Webhooks und Metadaten

Metadaten sind in Webhook-Ereignissen enthalten, was es einfach macht, Benachrichtigungen mit Ihren benutzerdefinierten Daten zu verarbeiten: 
// 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
  }
});