Guia de Metadados

Aprenda como usar metadados para armazenar informações adicionais sobre seus objetos de Pagamentos Dodo

​

Introdução

Metadados permitem que você armazene informações adicionais e estruturadas sobre seus objetos nos Pagamentos Dodo. Você pode anexar metadados à maioria dos objetos de Pagamentos Dodo, incluindo pagamentos, assinaturas e mais.

​

Visão Geral

• As chaves de metadados podem ter até 40 caracteres
• Os valores de metadados podem ser uma string, número ou booleano; strings podem ter até 500 caracteres
• Objetos, arrays e null não são aceitos como valores de metadados
• Você pode ter até 50 pares de chave-valor de metadados por objeto
• As chaves devem conter apenas caracteres alfanuméricos, hífens e sublinhados
• Os metadados não são pesquisáveis usando nossa API, mas são retornados nas respostas da API e webhooks

​

Casos de Uso

Metadados são úteis para:

• Armazenar IDs ou referências externas
• Adicionar anotações internas
• Vincular objetos de Pagamentos Dodo ao seu sistema
• Categorizar transações
• Adicionar atributos personalizados para relatórios

​

Adicionando Metadados

Você pode adicionar metadados ao criar ou atualizar objetos através da API. Para produtos, você também tem a opção de adicionar metadados diretamente da interface do painel.

​

Via 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: '[e-mail]',
    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: '[e-mail]'
    }
});

​

Via Interface do Painel (Apenas Produtos)

Para produtos, você também pode adicionar metadados diretamente do painel de Pagamentos Dodo ao criar ou editar um produto. A seção de metadados permite que você adicione facilmente pares de chave-valor personalizados sem escrever código.

Usar a interface do painel para metadados de produtos é especialmente útil para membros de equipes não técnicas que precisam gerenciar informações e categorias de produtos.

​

Recuperando Metadados

Metadados estão incluídos nas respostas da API ao recuperar objetos:

// 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'

​

Pesquisa e Filtragem

Embora metadados não sejam diretamente pesquisáveis via nossa API, você pode:

1. Armazenar identificadores importantes em metadados
2. Recuperar objetos usando seus IDs primários
3. Filtrar os resultados no seu código de aplicação

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

​

Melhores Práticas

​

Faça:

• Use convenções de nomenclatura consistentes para chaves de metadados
• Documente seu esquema de metadados internamente
• Mantenha os valores curtos e significativos
• Use metadados apenas para dados estáticos
• Considere usar prefixos para diferentes sistemas (por exemplo, crm_id, inventory_sku)

​

Não Faça:

• Armazenar dados sensíveis em metadados
• Usar metadados para valores que mudam frequentemente
• Confiar em metadados para lógica de negócios crítica
• Armazenar informações duplicadas que estão disponíveis em outro lugar no objeto
• Usar caracteres especiais nas chaves de metadados

​

Objetos Suportados

Metadados são suportados nos seguintes objetos:

Tipo de Objeto	Suporte
Pagamentos	✓
Assinaturas	✓
Alterar Plano de Assinatura	✓
Produtos	✓
Reembolsos	✓
Sessões de Checkout	✓
Clientes	✓

​

Webhooks e Metadados

Metadados estão incluídos em eventos de webhook, facilitando o manuseio de notificações com seus dados personalizados:

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