> ## 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. # Hướng dẫn Metadata > Tìm hiểu cách sử dụng metadata để lưu trữ thông tin bổ sung về các đối tượng Dodo Payments của bạn ## Giới thiệu Metadata cho phép bạn lưu trữ thông tin bổ sung, có cấu trúc về các đối tượng của bạn trong Dodo Payments. Bạn có thể gán metadata cho hầu hết các đối tượng Dodo Payments, bao gồm thanh toán, đăng ký, và nhiều hơn nữa. ## Tổng quan * Các khóa siêu dữ liệu có thể dài tới 40 ký tự * Các giá trị siêu dữ liệu có thể là chuỗi, số hoặc boolean; chuỗi có thể dài tới 500 ký tự * Các đối tượng, mảng và `null` không được chấp nhận làm giá trị siêu dữ liệu * Bạn có thể có tối đa 50 cặp khóa-giá trị siêu dữ liệu mỗi đối tượng * Khóa chỉ nên chứa các ký tự chữ và số, dấu gạch ngang và dấu gạch dưới * Siêu dữ liệu không thể tìm kiếm được bằng API của chúng tôi nhưng được trả về trong các phản hồi API và webhook ## Trường hợp sử dụng Metadata hữu ích cho: * Lưu trữ ID hoặc tham chiếu bên ngoài * Thêm chú thích nội bộ * Liên kết các đối tượng Dodo Payments với hệ thống của bạn * Phân loại giao dịch * Thêm thuộc tính tùy chỉnh cho báo cáo ## Thêm Metadata Bạn có thể thêm metadata khi tạo hoặc cập nhật các đối tượng thông qua API. Đối với sản phẩm, bạn cũng có tùy chọn thêm metadata trực tiếp từ giao diện bảng điều khiển. ### Qua 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' } }); ``` ### Qua Giao diện Bảng điều khiển (Chỉ Sản phẩm) Đối với sản phẩm, bạn cũng có thể thêm metadata trực tiếp từ bảng điều khiển Dodo Payments khi tạo hoặc chỉnh sửa một sản phẩm. Phần metadata cho phép bạn dễ dàng thêm các cặp khóa-giá trị tùy chỉnh mà không cần viết mã. Giao diện metadata sản phẩm trong bảng điều khiển Dodo Payments Việc sử dụng giao diện bảng điều khiển cho metadata sản phẩm đặc biệt hữu ích đối với các thành viên không chuyên về kỹ thuật cần quản lý thông tin và danh mục sản phẩm. ## Lấy Metadata Metadata được bao gồm trong các phản hồi API khi lấy các đối tượng: ```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' ``` ## Tìm kiếm và Lọc Mặc dù metadata không thể tìm kiếm trực tiếp qua API của chúng tôi, bạn có thể: 1. Lưu trữ các định danh quan trọng trong metadata 2. Lấy các đối tượng bằng ID chính của chúng 3. Lọc kết quả trong mã ứng dụng của bạn ```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' ); ``` ## Thực hành tốt nhất ### Do: * Sử dụng quy ước đặt tên nhất quán cho các khóa metadata * Ghi chép sơ đồ metadata nội bộ * Giữ giá trị ngắn và có ý nghĩa * Chỉ sử dụng metadata cho dữ liệu tĩnh * Cân nhắc dùng tiền tố cho các hệ thống khác nhau (ví dụ, `crm_id`, `inventory_sku`) ### Không nên: * Lưu trữ dữ liệu nhạy cảm trong metadata * Sử dụng metadata cho các giá trị thay đổi thường xuyên * Dựa vào metadata cho logic kinh doanh quan trọng * Lưu trữ thông tin trùng lặp có sẵn ở nơi khác trong đối tượng * Sử dụng ký tự đặc biệt trong các khóa metadata ## Các đối tượng được hỗ trợ Metadata được hỗ trợ trên các đối tượng sau: | Loại Đối Tượng | Hỗ Trợ | | -------------------- | ------ | | Payments | ✓ | | Subscriptions | ✓ | | Thay Đổi Gói Đăng Ký | ✓ | | Sản Phẩm | ✓ | | Hoàn Tiền | ✓ | | Phiên Thanh Toán | ✓ | | Khách Hàng | ✓ | | Giảm Giá | ✓ | ## Webhook và Metadata Metadata được bao gồm trong các sự kiện webhook, giúp dễ dàng xử lý thông báo với dữ liệu tùy chỉnh của bạn: ```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 } }); ```