Metadata Guide

// 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
// Note: POST /payments is deprecated — prefer checkout sessions for new integrations
const payment = await client.payments.create({
    billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: '12345' },
    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',
    tax_category: 'digital_products',
    price: {
        type: 'one_time_price',
        currency: 'USD',
        price: 9900,
        discount: 0,
        purchasing_power_parity: false
    },
    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: 'pdt_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'
    }
});

// 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('cus_123');
console.log(customer.metadata.crm_id); // 'CRM-12345'

// Retrieving refund metadata
const refund = await client.refunds.retrieve('ref_123');
console.log(refund.metadata.refund_reason); // 'customer_request'

// Example: Find a payment using your order ID.
// list() is auto-paginating, so iterating searches across pages instead of
// only the first one.
let matchingPayment;
for await (const payment of client.payments.list({ page_size: 100 })) {
  if (payment.metadata?.order_id === '6735') {
    matchingPayment = payment;
    break;
  }
}

// Example webhook handler
app.post('/webhook', (req, res) => {
  const event = req.body;

  if (event.type === 'payment.succeeded') {
    const orderId = event.data.metadata.order_id;
    // Process order using your internal order ID
  }
  
  if (event.type === 'subscription.active') {
    const orderId = event.data.metadata.order_id;
    const campaignSource = event.data.metadata.campaign_source;
    // Handle subscription activation with custom metadata
  }
});