Checkout Sessions

Create secure, hosted checkout experiences that handle the complete payment flow for both one-time purchases and subscriptions with full customization control.

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

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: '[e-mail]',
        name: 'John Doe',
        phone_number: '[phone]'
      },
      
      // 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' });
  }
});

Python SDK

import os
from dodopayments import DodoPayments

# Initialize the Dodo Payments client
client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
)

def create_checkout_session():
    """
    Create a checkout session for a single product with customer data pre-filled.
    Returns the session object containing checkout_url for customer redirection.
    """
    try:
        session = client.checkout_sessions.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 checkout friction
            customer={
                "email": "[e-mail]",
                "name": "John Doe",
                "phone_number": "[phone]"
            },
            
            # 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
        print(f"Checkout URL: {session.checkout_url}")
        print(f"Session ID: {session.session_id}")
        
        return session
        
    except Exception as error:
        print(f"Failed to create checkout session: {error}")
        raise error

# Example usage in a Flask route
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/create-checkout', methods=['POST'])
def create_checkout():
    try:
        session = create_checkout_session()
        return jsonify({"checkout_url": session.checkout_url})
    except Exception as error:
        return jsonify({"error": "Failed to create checkout session"}), 500

REST API

// Direct API call using fetch - useful for any JavaScript environment
async function createCheckoutSession() {
  try {
    const response = await fetch('https://test.dodopayments.com/checkouts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
      },
      body: JSON.stringify({
        // 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 checkout friction
        customer: {
          email: '[e-mail]',
          name: 'John Doe',
          phone_number: '[phone]'
        },
        
        // 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'
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const session = await response.json();
    
    // 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: Redirect user to checkout
createCheckoutSession().then(session => {
  window.location.href = session.checkout_url;
});

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.

Show Product Cart Item Properties

product_id · string · required

The unique identifier of the product from your Dodo Payments dashboard.

Example: "prod_123abc456def"

quantity · integer · required

Quantity of the product.

Example: 1 for single item, 3 for multiple quantities

addons · array

Array of addons to attach to the product. Only valid if the product is a subscription.

Show Addon item properties

addon_id · string · required

quantity · integer · required

amount · integer

Amount the customer pays if pay_what_you_want is enabled. If disabled, this field will be ignored.

Format: Represented in the lowest denomination of the currency (e.g., cents for USD). For example, to charge $1.00, pass 100.

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 Information

customer · object

Customer information. You can either attach an existing customer using their ID or create a new customer record during checkout.

Attach Existing Customer

Attach an existing customer to the checkout session using their ID.

Show Existing Customer Properties

customer_id · string · required

The unique identifier of an existing customer. Use this to attach the checkout session to an existing customer instead of creating a new one.

New Customer

Create a new customer record during checkout.

Show New Customer Properties

email · string · required

Customer’s email address. Required when creating a new customer.

name · string

Customer’s full name as it should appear on receipts and invoices.

Example: "John Doe" or "Jane Smith"

phone_number · string

Customer’s phone number in international format. Required for some payment methods and fraud prevention.

Format: Include country code, e.g., "[phone]" for US numbers

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.

Show Billing address object properties

street · string

Complete street address including house number, street name, and apartment/unit number if applicable.

Example: "123 Main St, Apt 4B" or "456 Oak Avenue"

city · string

City or municipality name.

Example: "San Francisco", "New York", "London"

state · string

State, province, or region name. Use full names or standard abbreviations.

Example: "California" or "CA", "Ontario" or "ON"

country · string · required

Two-letter ISO country code (ISO 3166-1 alpha-2). This field is always required when billing_address is provided.

Examples: "US" (United States), "CA" (Canada), "GB" (United Kingdom), "DE" (Germany)

Country Code Reference

View complete list of supported countries and their ISO codes

zipcode · string

Postal code, ZIP code, or equivalent based on country requirements.

Examples: "94102" (US), "M5V 3A8" (Canada), "SW1A 1AA" (UK)

Payment Configuration

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, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal

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 more

Example: "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.

Session Management

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.

force_3ds · boolean

Override merchant default 3DS behaviour for this session.

UI Customization & Features

customization · object

Customize the appearance and behavior of the checkout interface.

Show Customization object properties

theme · string · default: "system"

Theme for the checkout interface. Options: light, dark, or system.

show_order_details · boolean · default: "true"

Display order details section in the checkout interface.

show_on_demand_tag · boolean · default: "true"

Show the “on-demand” tag for applicable products.

force_language · string

Force the checkout interface to render in a specific language.

Example: "en" for English, "es" for Spanish

feature_flags · object

Configure specific features and behaviors for the checkout session.

Show Feature flags object properties

allow_currency_selection · boolean · default: "true"

Allow customers to select their preferred currency during checkout.

allow_discount_code · boolean · default: "true"

Show discount code input field in the checkout interface.

allow_phone_number_collection · boolean · default: "true"

Collect customer phone numbers during checkout.

allow_tax_id · boolean · default: "true"

Allow customers to enter tax identification numbers.

always_create_new_customer · boolean · default: "false"

Force creation of a new customer record instead of updating existing ones.

allow_customer_editing_email · boolean

Allow customers to edit their email address during checkout.

allow_customer_editing_name · boolean

Allow customers to edit their name during checkout.

allow_customer_editing_street · boolean

Allow customers to edit the street address during checkout.

allow_customer_editing_city · boolean

Allow customers to edit the city during checkout.

allow_customer_editing_state · boolean

Allow customers to edit the state during checkout.

allow_customer_editing_country · boolean

Allow customers to edit the country during checkout.

allow_customer_editing_zipcode · boolean

Allow customers to edit the zipcode during checkout.

Subscription Configuration

subscription_data · object

Additional configuration for checkout sessions containing subscription products.

Show Subscription data object properties

trial_period_days · integer

Number of days for the trial period before the first charge. Must be between 0 and 10000 days.

on_demand · object

On-demand subscription configuration for usage-based or metered billing.

Show On-demand object properties

mandate_only · boolean · required

If set to true, does not perform any charge and only authorizes payment method details for future use.

product_price · integer

Product price for the initial charge to customer. If not specified, the stored price of the product will be used.

Format: Represented in the lowest denomination of the currency (e.g., cents for USD). For example, to charge $1.00, pass 100.

product_currency · string

Optional currency of the product price. If not specified, defaults to the currency of the product.

product_description · string

Optional product description override for billing and line items. If not specified, the stored description of the product will be used.

adaptive_currency_fees_inclusive · boolean

Whether adaptive currency fees should be included in the product price (true) or added on top (false). Ignored if adaptive pricing is not enabled.

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: '[e-mail]',
    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: '[e-mail]',
    name: 'John Doe',
    phone_number: '[phone]'
  },
  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: '[e-mail]',
    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: '[e-mail]',
    name: 'Alex Johnson',
    phone_number: '[phone]'
  },
  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: '[e-mail]',
    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: '[e-mail]',
    name: 'Robert Johnson',
    phone_number: '[phone]'
  },
  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: '[e-mail]',
    name: 'Sarah Davis',
    phone_number: '[phone]'
  },
  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: '[e-mail]'
  }
});

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: '[e-mail]',
    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: '[e-mail]',
    name: 'Priya Sharma',
    phone_number: '[phone]'
  },
  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: '[e-mail]',
    name: 'Emma Thompson',
    phone_number: '[phone]'
  },
  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'
  }
});

Moving from Dynamic Links to Checkout Sessions

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.