v1.81.0 (February 6, 2026) - Dodo Payments Documentation

New Features

1. Third-Party Analytics Support

Track customer behavior across Storefront, Checkout, and Customer Portal with Google Analytics 4, Google Tag Manager, and Meta Pixel. Add your tracking IDs in Settings → Analytics to start collecting e-commerce events. Supported Platforms

Platform	ID Format
Google Analytics 4	`G-XXXXXXXXXX`
Google Tag Manager	`GTM-XXXXXXX`
Meta Pixel	Numeric (10-20 digits)

Tracked Events Events like purchase, add_payment_info, view_item, and view_item_list are automatically sent to your analytics platforms as customers browse and complete purchases.

Supported on Storefront, hosted Checkout, overlay/inline Checkout, and Customer Portal.

Learn more: Third-Party Analytics

2. Checkout Theme Customization

Customize checkout appearance via the customization.theme_config parameter when creating checkout sessions. Configure colors, fonts, border radius, and button text for both light and dark modes. Configuration Options

Property	Description
`light` / `dark`	Color schemes for each mode
`font_primary_url`	Custom font URL
`font_size`	`xs`, `sm`, `md`, `lg`, `xl`, `2xl`
`radius`	Border radius (e.g., `8px`)
`pay_button_text`	Custom button text

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_123', quantity: 1 }],
  customization: {
    theme_config: {
      radius: '8px',
      pay_button_text: 'Complete Purchase',
      light: { button_primary: '#0066ff', text_primary: '#1a1a1a' },
      dark: { button_primary: '#3385ff', text_primary: '#ffffff' }
    }
  },
  return_url: 'https://yoursite.com/return'
});

Learn more: Checkout Theme Customization

3. Prevent Plan Change on Payment Failure

New on_payment_failure parameter for subscription plan changes controls behavior when payment fails.

Mode	Behavior
`prevent_change`	Keep subscription on current plan until payment succeeds
`apply_change`	Apply plan change immediately regardless of payment outcome (default)

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});

Use prevent_change for critical upgrades where you want to ensure payment before granting access to premium features.

Learn more: Handling Payment Failures

API Updates

Balance Ledger API

New GET /balances/ledger endpoint to retrieve your account’s ledger entries with filtering and pagination.

Parameter	Description
`created_at_gte` / `created_at_lte`	Filter by date range
`event_type`	Filter by `payment`, `refund`, `dispute`, `payout`, etc.
`currency`	Filter by currency code
`reference_object_id`	Filter by specific payment/refund/dispute ID

Learn more: Balance Ledger API

Payment Response: `refund_status`

Added refund_status field to GET /payments/{paymentId} response to quickly check if a payment has been refunded without querying the refunds endpoint separately.

​New Features

​1. Third-Party Analytics Support

​2. Checkout Theme Customization

​3. Prevent Plan Change on Payment Failure

​API Updates

​Balance Ledger API

​Payment Response: refund_status

New Features

1. Third-Party Analytics Support

2. Checkout Theme Customization

3. Prevent Plan Change on Payment Failure

API Updates

Balance Ledger API

Payment Response: `refund_status`