メインコンテンツへスキップ

​
はじめに

メタデータを使用すると、Dodo Paymentsのオブジェクトに関する追加の構造化情報を保存できます。メタデータは、支払い、サブスクリプションなど、ほとんどのDodo Paymentsオブジェクトに添付できます。

​
概要

  • メタデータキーは最大40文字まで使用可能
  • メタデータ値は最大500文字まで使用可能
  • オブジェクトごとに最大50のメタデータキー-バリューペアを持つことができます
  • キーには英数字、ダッシュ、アンダースコアのみを含めるべきです
  • メタデータはAPIを使用して検索できませんが、APIレスポンスやWebhookで返されます

​
ユースケース

メタデータは以下の用途に役立ちます：
  • 外部IDや参照の保存
  • 内部注釈の追加
  • Dodo Paymentsオブジェクトをシステムにリンク
  • トランザクションの分類
  • レポート用のカスタム属性の追加

​
メタデータの追加

APIを通じてオブジェクトを作成または更新する際にメタデータを追加できます。製品の場合、ダッシュボードUIから直接メタデータを追加するオプションもあります。

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

​
ダッシュボードUI経由（製品のみ）

製品の場合、製品を作成または編集する際にDodo Paymentsダッシュボードから直接メタデータを追加できます。メタデータセクションでは、コードを書くことなくカスタムキー-バリューペアを簡単に追加できます。
Dodo Paymentsダッシュボードの製品メタデータインターフェース
製品メタデータのためにダッシュボードUIを使用することは、製品情報やカテゴリを管理する必要がある非技術的なチームメンバーにとって特に便利です。

​
メタデータの取得

メタデータは、オブジェクトを取得する際のAPIレスポンスに含まれます： 
// 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'

​
検索とフィルタリング

メタデータはAPIを通じて直接検索できませんが、以下のことができます：
  1. メタデータに重要な識別子を保存する
  2. プライマリIDを使用してオブジェクトを取得する
  3. アプリケーションコードで結果をフィルタリングする
// 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'
);

​
ベストプラクティス

​
するべきこと：

  • メタデータキーの命名規則を一貫して使用する
  • メタデータスキーマを内部で文書化する
  • 値を短く意味のあるものに保つ
  • メタデータは静的データのみに使用する
  • 異なるシステムのためにプレフィックスを使用することを検討する（例：crm_id, inventory_sku）

​
しないべきこと：

  • メタデータに機密データを保存する
  • 頻繁に変更される値にメタデータを使用する
  • 重要なビジネスロジックにメタデータに依存する
  • オブジェクト内の他の場所で利用可能な重複情報を保存する
  • メタデータキーに特殊文字を使用する

​
サポートされているオブジェクト

メタデータは以下のオブジェクトでサポートされています：
オブジェクトタイプサポート
支払い✓
サブスクリプション✓
製品✓
返金✓
チェックアウトセッション✓
顧客✓

​
Webhookとメタデータ

メタデータはWebhookイベントに含まれており、カスタムデータを使用して通知を簡単に処理できます： 
// 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
  }
});