Skip to main content

Quick Start Guide

Get your first checkout session running in under 5 minutes

API Reference & Live Testing

Explore the full API documentation and interactively test Checkout Session requests and responses.
Session Validity: Checkout sessions are valid for 24 hours by default. If you pass confirm=true in your request, the session will only be valid for 15 minutes.

​
Prerequisites

1

Dodo Payments Account

You’ll need an active Dodo Payments merchant account with API access.
2

API Credentials

Generate your API credentials from the Dodo Payments dashboard:
3

Products Setup

Create your products in the Dodo Payments dashboard before implementing checkout sessions.

​
Creating Your First Checkout Session

  • Node.js SDK
  • Python SDK
  • REST API
import DodoPayments from 'dodopayments';

// Initialize the Dodo Payments client
const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});

async function createCheckoutSession() {
  try {
    const session = await client.checkoutSessions.create({
      // Products to sell - use IDs from your Dodo Payments dashboard
      product_cart: [
        {
          product_id: 'prod_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example usage in an Express.js route
app.post('/create-checkout', async (req, res) => {
  try {
    const session = await createCheckoutSession();
    res.json({ checkout_url: session.checkout_url });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

​
API Response

All methods above return the same response structure: 
{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
1

Get the checkout URL

Extract the checkout_url from the API response.
2

Redirect your customer

Direct your customer to the checkout URL to complete their purchase.
// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');
3

Handle the return

After payment, customers are redirected to your return_url with additional query parameters for payment status.

​
Request Body

Required Fields

Essential fields needed for every checkout session

Optional Fields

Additional configuration to customize your checkout experience

​
Required Fields

​
product_cart
array
required
Array of products to include in the checkout session. Each product must have a valid product_id from your Dodo Payments dashboard.
Important: Multiple product carts can only contain one-time payment products. You cannot mix subscription products with one-time products in the same checkout session.
Find Your Product IDs: You can find product IDs in your Dodo Payments dashboard under Products → View Details, or by using the List Products API.

​
Optional Fields

Configure these fields to customize the checkout experience and add business logic to your payment flow.
​
customer
object
Pre-fill customer details to reduce checkout friction and improve conversion rates.
​
billing_address
object
Billing address information for accurate tax calculation, fraud prevention, and regulatory compliance.
When confirm is set to true, all billing address fields become required for successful session creation.
​
allowed_payment_method_types
array
Control which payment methods are available to customers during checkout. This helps optimize for specific markets or business requirements.Available Options: credit, debit, upi_collect, upi_intent, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, sepa, ach
Critical: Always include credit and debit as fallback options to prevent checkout failures when preferred payment methods are unavailable.
Example:
["apple_pay", "google_pay", "credit", "debit"]
​
billing_currency
string
Override the default currency selection with a fixed billing currency. Uses ISO 4217 currency codes.Supported Currencies: USD, EUR, GBP, CAD, AUD, INR, and moreExample: "USD" for US Dollars, "EUR" for Euros
This field is only effective when adaptive pricing is enabled. If adaptive pricing is disabled, the product’s default currency will be used.
​
show_saved_payment_methods
boolean
default:"false"
Display previously saved payment methods for returning customers, improving checkout speed and user experience.
​
return_url
string
URL to redirect customers after successful payment or cancellation.
​
confirm
boolean
default:"false"
If true, finalizes all session details immediately. API will throw an error if required data is missing.
​
discount_code
string
Apply a discount code to the checkout session.
​
metadata
object
Custom key-value pairs to store additional information about the session.
​
customization
object
Customize the appearance and behavior of the checkout interface.
​
feature_flags
object
Configure specific features and behaviors for the checkout session.
​
subscription_data
object
Additional configuration for checkout sessions containing subscription products.

​
Usage Examples

Here are 10 comprehensive examples showcasing different checkout session configurations for various business scenarios:

​
1. Simple Single Product Checkout

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  return_url: 'https://yoursite.com/success'
});

​
2. Multi-Product Cart

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_laptop',
      quantity: 1
    },
    {
      product_id: 'prod_mouse',
      quantity: 2
    },
    {
      product_id: 'prod_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '123 Tech Street',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://electronics-store.com/order-confirmation'
});

​
3. Subscription with Trial Period

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: 'user@startup.com',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

​
4. Pre-confirmed Checkout

When confirm is set to true, the customer will be taken directly to the checkout page, bypassing any confirmation steps.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: 'student@university.edu',
    name: 'Alex Johnson',
    phone_number: '+1555123456'
  },
  billing_address: {
    street: '456 University Ave',
    city: 'Boston',
    state: 'MA',
    country: 'US',
    zipcode: '02134'
  },
  confirm: true,
  return_url: 'https://learning-platform.com/course-access',
  metadata: {
    course_category: 'programming',
    enrollment_date: '2024-01-15'
  }
});

​
5. Checkout with Currency Override

The billing_currency override only takes effect when adaptive currency is enabled in your account settings. If adaptive currency is disabled, this parameter will have no effect.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: 'client@company.co.uk',
    name: 'Oliver Williams'
  },
  billing_address: {
    street: '789 Business Park',
    city: 'London',
    state: 'England',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  billing_currency: 'GBP',
  feature_flags: {
    allow_currency_selection: true,
    allow_tax_id: true
  },
  return_url: 'https://consulting-firm.com/service-confirmation'
});

​
6. Saved Payment Methods for Returning Customers

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: 'returning.customer@example.com',
    name: 'Robert Johnson',
    phone_number: '+1555987654'
  },
  show_saved_payment_methods: true,
  feature_flags: {
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://subscription-service.com/welcome-back',
  metadata: {
    customer_tier: 'premium',
    account_age: 'returning'
  }
});

​
7. B2B Checkout with Tax ID Collection

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: 'procurement@enterprise.com',
    name: 'Sarah Davis',
    phone_number: '+1800555000'
  },
  billing_address: {
    street: '1000 Corporate Blvd',
    city: 'New York',
    state: 'NY',
    country: 'US',
    zipcode: '10001'
  },
  feature_flags: {
    allow_tax_id: true,
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://enterprise-software.com/license-delivery',
  metadata: {
    customer_type: 'enterprise',
    contract_id: 'ENT-2024-001',
    sales_rep: 'john.sales@company.com'
  }
});

​
8. Dark Theme Checkout with Discount Code

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_gaming_chair',
      quantity: 1
    }
  ],
  discount_code: 'BLACKFRIDAY2024',
  customization: {
    theme: 'dark',
    show_order_details: true,
    show_on_demand_tag: false
  },
  feature_flags: {
    allow_discount_code: true
  },
  customer: {
    email: 'gamer@example.com',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

​
9. Regional Payment Methods (UPI for India)

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'upi_intent',
    'credit',
    'debit'
  ],
  customer: {
    email: 'student@example.in',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    street: 'MG Road',
    city: 'Bangalore',
    state: 'Karnataka',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  return_url: 'https://education-platform.in/course-access',
  metadata: {
    region: 'south_india',
    language: 'hindi'
  }
});

​
10. BNPL (Buy Now Pay Later) Checkout

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'affirm',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'fashion.lover@example.com',
    name: 'Emma Thompson',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '555 Fashion Ave',
    city: 'Los Angeles',
    state: 'CA',
    country: 'US',
    zipcode: '90210'
  },
  feature_flags: {
    allow_phone_number_collection: true
  },
  return_url: 'https://luxury-store.com/purchase-confirmation',
  metadata: {
    product_category: 'luxury',
    price_range: 'high_value'
  }
});

​
Key Differences

Previously, when creating a payment link with Dynamic Links, you were required to provide the customer’s complete billing address. With Checkout Sessions, this is no longer necessary. You can simply pass along whatever information you have, and we’ll handle the rest. For example:
  • If you only know the customer’s billing country, just provide that.
  • The checkout flow will automatically collect the missing details before moving the customer to the payment page.
  • On the other hand, if you already have all the required information and want to skip directly to the payment page, you can pass the full data set and include confirm=true in your request body.

​
Migration Process

Migrating from Dynamic Links to Checkout Sessions is straightforward:
1

Update your integration

Update your integration to use the new API or SDK method.
2

Adjust request payload

Adjust the request payload according to the Checkout Sessions format.
3

That's it!

Yes. No additional handling or special migration steps are needed on your side.