> ## 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.
# メタデータガイド
> Dodo Paymentsオブジェクトに関する追加情報を保存するためのメタデータの使用方法を学びます
## はじめに
メタデータを使用すると、Dodo Paymentsのオブジェクトに関する追加の構造化情報を保存できます。メタデータは、支払い、サブスクリプションなど、ほとんどのDodo Paymentsオブジェクトに添付できます。
## 概要
* メタデータのキーは最大40文字まで
* メタデータの値は文字列、数値、またはブール値が利用可能。文字列は最大500文字まで
* オブジェクト、配列、および`null`はメタデータの値として受け入れられません
* オブジェクトごとに最大50のメタデータのキーと値のペアを持つことができます
* キーには英数字、ダッシュ、アンダースコアのみを含めることができます
* メタデータはAPIで検索可能ではありませんが、APIのレスポンスとWebhookで返されます
## ユースケース
メタデータは以下の用途に役立ちます：
* 外部IDや参照の保存
* 内部注釈の追加
* Dodo Paymentsオブジェクトをシステムにリンク
* トランザクションの分類
* レポート用のカスタム属性の追加
## メタデータの追加
APIを通じてオブジェクトを作成または更新する際にメタデータを追加できます。製品の場合、ダッシュボードUIから直接メタデータを追加するオプションもあります。
### 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'
}
});
```
### ダッシュボードUI経由（製品のみ）
製品の場合、製品を作成または編集する際にDodo Paymentsダッシュボードから直接メタデータを追加できます。メタデータセクションでは、コードを書くことなくカスタムキー-バリューペアを簡単に追加できます。
製品メタデータの管理にダッシュボード UI を使用することは、製品情報やカテゴリを管理する必要がある非技術系チームメンバーにとって特に有用です。
## メタデータの取得
メタデータは、オブジェクトを取得する際のAPIレスポンスに含まれます：
```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'
```
## 検索とフィルタリング
メタデータはAPIを通じて直接検索できませんが、以下のことができます：
1. メタデータに重要な識別子を保存する
2. プライマリIDを使用してオブジェクトを取得する
3. アプリケーションコードで結果をフィルタリングする
```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'
);
```
## ベストプラクティス
### やること:
* メタデータキーに一貫した命名規則を使用する
* メタデータスキーマを社内で文書化する
* 値は短く意味のあるものにする
* メタデータは静的データのみに使用する
* 異なるシステム用にプレフィックスの使用を検討する（例: `crm_id`, `inventory_sku`）
### しないべきこと：
* メタデータに機密データを保存する
* 頻繁に変更される値にメタデータを使用する
* 重要なビジネスロジックにメタデータに依存する
* オブジェクト内の他の場所で利用可能な重複情報を保存する
* メタデータキーに特殊文字を使用する
## サポートされているオブジェクト
メタデータは以下のオブジェクトでサポートされています：
| オブジェクトタイプ | サポート |
| -------------- | ---- |
| 支払い | ✓ |
| サブスクリプション | ✓ |
| サブスクリプション変更プラン | ✓ |
| 製品 | ✓ |
| 返金 | ✓ |
| チェックアウトセッション | ✓ |
| 顧客 | ✓ |
| 割引 | ✓ |
## Webhookとメタデータ
メタデータはWebhookイベントに含まれており、カスタムデータを使用して通知を簡単に処理できます：
```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
}
});
```