> ## 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.
# Panduan Metadata
> Pelajari cara menggunakan metadata untuk menyimpan informasi tambahan tentang objek Dodo Payments Anda
## Pendahuluan
Metadata memungkinkan Anda untuk menyimpan informasi tambahan yang terstruktur tentang objek Anda di Dodo Payments. Anda dapat melampirkan metadata ke sebagian besar objek Dodo Payments, termasuk pembayaran, langganan, dan lainnya.
## Ikhtisar
* Kunci metadata dapat memiliki panjang hingga 40 karakter
* Nilai metadata dapat berupa string, angka, atau boolean; string dapat memiliki panjang hingga 500 karakter
* Objek, array, dan `null` tidak diterima sebagai nilai metadata
* Anda dapat memiliki hingga 50 pasang kunci-nilai metadata per objek
* Kunci hanya boleh berisi karakter alfanumerik, tanda hubung, dan garis bawah
* Metadata tidak dapat dicari menggunakan API kami tetapi dikembalikan dalam respons API dan webhook
## Kasus Penggunaan
Metadata berguna untuk:
* Menyimpan ID atau referensi eksternal
* Menambahkan anotasi internal
* Menghubungkan objek Dodo Payments ke sistem Anda
* Mengkategorikan transaksi
* Menambahkan atribut kustom untuk pelaporan
## Menambahkan Metadata
Anda dapat menambahkan metadata saat membuat atau memperbarui objek melalui API. Untuk produk, Anda juga memiliki opsi untuk menambahkan metadata langsung dari UI dasbor.
### Melalui 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'
}
});
```
### Melalui UI Dasbor (Hanya Produk)
Untuk produk, Anda juga dapat menambahkan metadata langsung dari dasbor Dodo Payments saat membuat atau mengedit produk. Bagian metadata memungkinkan Anda untuk dengan mudah menambahkan pasangan kunci-nilai kustom tanpa menulis kode.
Menggunakan UI dashboard untuk metadata produk sangat berguna bagi anggota tim non-teknis yang perlu mengelola informasi produk dan kategori.
## Mengambil Metadata
Metadata disertakan dalam respons API saat mengambil objek:
```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'
```
## Pencarian dan Penyaringan
Meskipun metadata tidak dapat dicari secara langsung melalui API kami, Anda dapat:
1. Menyimpan pengidentifikasi penting dalam metadata
2. Mengambil objek menggunakan ID utama mereka
3. Menyaring hasil dalam kode aplikasi Anda
```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'
);
```
## Praktik Terbaik
### Lakukan:
* Gunakan konvensi penamaan yang konsisten untuk kunci metadata
* Dokumentasikan skema metadata Anda secara internal
* Jaga nilai tetap singkat dan bermakna
* Gunakan metadata hanya untuk data statis
* Pertimbangkan menggunakan awalan untuk sistem yang berbeda (misalnya, `crm_id`, `inventory_sku`)
### Jangan:
* Menyimpan data sensitif dalam metadata
* Menggunakan metadata untuk nilai yang sering berubah
* Mengandalkan metadata untuk logika bisnis yang kritis
* Menyimpan informasi duplikat yang tersedia di tempat lain dalam objek
* Menggunakan karakter khusus dalam kunci metadata
## Objek yang Didukung
Metadata didukung pada objek berikut:
| Jenis Objek | Dukungan |
| -------------------- | -------- |
| Pembayaran | ✓ |
| Langganan | ✓ |
| Ubah Paket Langganan | ✓ |
| Produk | ✓ |
| Pengembalian Dana | ✓ |
| Sesi Checkout | ✓ |
| Pelanggan | ✓ |
| Diskon | ✓ |
## Webhook dan Metadata
Metadata disertakan dalam peristiwa webhook, memudahkan untuk menangani notifikasi dengan data kustom Anda:
```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
}
});
```