# Astro Adaptor
Source: https://docs.dodopayments.com/developer-resources/astro-adaptor

Learn how to integrate Dodo Payments with your Astro App Router project using our Astro Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your Astro app.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/astro
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using the Astro App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Astro app. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript Astro Route Handler expandable theme={null}
      // src/pages/api/checkout.ts
      import { Checkout } from "@dodopayments/astro";
      export const prerender = false;

      export const GET = Checkout({
          bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
          returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
          environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "static", // optional, defaults to 'static'
      });


      export const POST = Checkout({
          bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
          returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
          environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "dynamic", // for dynamic checkout
      });

      export const POST = Checkout({
          bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
          returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
          environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "session", // for checkout sessions
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Astro Route Handler expandable theme={null}
      // src/pages/api/customer-portal.ts
      import { CustomerPortal } from "@dodopayments/astro";
      export const GET = CustomerPortal({
          bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
          environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Astro app.
    </Info>

    <CodeGroup>
      ```typescript expandable theme={null}
      // src/pages/api/webhook.ts
      import { Webhooks } from "@dodopayments/astro";

      export const POST = Webhooks({
          webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
          onPayload: async (payload) => {
              // handle the payload
          },
          // ... other event handlers for granular control
      });
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Astro application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```

You are an expert Astro developer assistant. Your task is to guide a user through integrating the @dodopayments/astro adapter into their existing Astro project.

The @dodopayments/astro adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for the Astro App Router.

First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):

npm install @dodopayments/astro

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/astro adapter would you like to integrate into your project? You can choose one or more of the following:

    Checkout Route Handler (for handling product checkouts)

    Customer Portal Route Handler (for managing customer subscriptions/details)

    Webhook Route Handler (for receiving Dodo Payments webhook events)

    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Route Handler is selected:

Purpose: This handler redirects users to the Dodo Payments checkout page.
File Creation: Create a new file at app/checkout/route.ts in your Astro project.

Code Snippet:

// src/pages/api/checkout.ts
import { Checkout } from "@dodopayments/astro";

export const prerender = false;

export const GET = Checkout({
  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
  environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static", // optional, defaults to 'static'
});


export const POST = Checkout({
  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
  environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic", // for dynamic checkout
});

export const POST = Checkout({
  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
  environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session", // for checkout sessions
});

Configuration & Usage:

    bearerToken: Your Dodo Payments API key. It's recommended to set this via the DODO_PAYMENTS_API_KEY environment variable.

    returnUrl: (Optional) The URL to redirect the user to after a successful checkout.

    environment: (Optional) Set to "test_mode" for testing, or omit/set to "live_mode" for production.

    type: (Optional) Set to "static" for GET/static checkout, "dynamic" for POST/dynamic checkout, or "session" for POST/checkout sessions.

Static Checkout (GET) Query Parameters:

    productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)

    quantity (optional): Quantity of the product

    Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode

    Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode

    Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts

    Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)

    Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}

Dynamic Checkout (POST) - Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}. For a complete list of supported POST body fields, refer to:

    Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments

    Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions


Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

Error Handling: If productId is missing or other query parameters are invalid, the handler will return a 400 response.

If Customer Portal Route Handler is selected:

Purpose: This handler redirects authenticated users to their Dodo Payments customer portal.
File Creation: Create a new file at app/customer-portal/route.ts in your Astro project.

Code Snippet:

// src/pages/api/customer-portal.ts
import { CustomerPortal } from "@dodopayments/astro";

export const GET = CustomerPortal({
  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
  environment: import.meta.env.DODO_PAYMENTS_ENVIRONMENT,
});

Query Parameters:

    customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)

    send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.

    Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at app/api/webhook/dodo-payments/route.ts in your Astro project.

Code Snippet:

// src/pages/api/webhook.ts
import { Webhooks } from "@dodopayments/astro";

export const POST = Webhooks({
  webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // handle the payload
  },
  // ... other event handlers for granular control
});

Handler Details:

    Method: Only POST requests are supported. Other methods return 405.

    Signature Verification: The handler verifies the webhook signature using the webhookKey and returns 401 if verification fails.

    Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:

    401: Invalid signature

    400: Invalid payload

    500: Internal error during verification

Event Routing: Calls the appropriate event handler based on the payload type.

Supported Webhook Event Handlers:

    onPayload?: (payload: WebhookPayload) => Promise<void>

    onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>

    onPaymentFailed?: (payload: WebhookPayload) => Promise<void>

    onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>

    onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>

    onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>

    onRefundFailed?: (payload: WebhookPayload) => Promise<void>

    onDisputeOpened?: (payload: WebhookPayload) => Promise<void>

    onDisputeExpired?: (payload: WebhookPayload) => Promise<void>

    onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>

    onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>

    onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>

    onDisputeWon?: (payload: WebhookPayload) => Promise<void>

    onDisputeLost?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>



    onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>

    onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>

    onDunningStarted?: (payload: WebhookPayload) => Promise<void>

    onDunningRecovered?: (payload: WebhookPayload) => Promise<void>

    onCreditAdded?: (payload: WebhookPayload) => Promise<void>

    onCreditDeducted?: (payload: WebhookPayload) => Promise<void>

    onCreditExpired?: (payload: WebhookPayload) => Promise<void>

    onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>

    onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>

    onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>

    onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>

    onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

    Environment Variable Setup:

To ensure the adapter functions correctly, you will need to manually set up the following environment variables in your Astro project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):

    DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).

    RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

    DODO_PAYMENTS_WEBHOOK_SECRET: Your Dodo Payments Webhook Secret (required for Webhook handler).

Example .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Usage in your code:

bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY
webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance. You can also add comments to their PR or chat depending on the context

```


# Better-Auth Adapter
Source: https://docs.dodopayments.com/developer-resources/better-auth-adaptor

This guide shows you how to integrate Dodo Payments into your authentication flow using the Better-Auth adaptor.

# Overview

The <b>Better Auth Adapter</b> for Dodo Payments provides:

* Automatic customer creation on sign-up
* Checkout Sessions (preferred) with product slug mapping
* Self-service customer portal
* Metered usage ingestion and reporting endpoints for usage-based billing
* Real-time webhook event processing with signature verification
* Full TypeScript support

<Note>
  You need a Dodo Payments account and API keys to use this integration.
</Note>

# Prerequisites

* Node.js 20+
* Access to your Dodo Payments Dashboard
* Existing project using [better-auth](https://www.npmjs.com/package/better-auth)

# Installation

<Steps>
  <Step title="Install dependencies">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/better-auth dodopayments better-auth zod
    ```

    <Check>
      All required packages are now installed.
    </Check>
  </Step>
</Steps>

# Setup

<Steps>
  <Step title="Configure environment variables">
    Add these to your <code>.env</code> file:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
    BETTER_AUTH_URL=http://localhost:3000
    BETTER_AUTH_SECRET=your_better_auth_secret_here
    ```

    <Warning>
      Never commit API keys or secrets to version control.
    </Warning>
  </Step>

  <Step title="Set up server-side integration">
    Create or update <code>src/lib/auth.ts</code>:

    ```typescript expandable theme={null}
    import { betterAuth } from "better-auth";
    import {
      dodopayments,
      checkout,
      portal,
      webhooks,
      usage,
    } from "@dodopayments/better-auth";
    import DodoPayments from "dodopayments";

    export const dodoPayments = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
      environment: "test_mode", // or "live_mode" for production
    });

    export const { auth, endpoints, client } = BetterAuth({
      plugins: [
        dodopayments({
          client: dodoPayments,
          createCustomerOnSignUp: true,
          use: [
            checkout({
              products: [
                {
                  productId: "pdt_xxxxxxxxxxxxxxxxxxxxx",
                  slug: "premium-plan",
                },
              ],
              successUrl: "/dashboard/success",
              authenticatedUsersOnly: true,
            }),
            portal(),
            webhooks({
              webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET!,
              onPayload: async (payload) => {
                console.log("Received webhook:", payload.type);
              },
            }),
            usage(),
          ],
        }),
      ],
    });
    ```

    <Tip>
      Set <code>environment</code> to <code>live\_mode</code> for production.
    </Tip>
  </Step>

  <Step title="Set up client-side integration">
    Create or update <code>src/lib/auth-client.ts</code>:

    ```typescript expandable theme={null}
    import { createAuthClient } from "better-auth/react";
    import { dodopaymentsClient } from "@dodopayments/better-auth/client";

    export const authClient = createAuthClient({
      baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
      plugins: [dodopaymentsClient()],
    });
    ```
  </Step>
</Steps>

# Usage Examples

<Info>
  Prefer <code>authClient.dodopayments.checkoutSession</code> for new
  integrations. The legacy <code>checkout</code> method is deprecated and kept
  only for backward compatibility.
</Info>

## Creating a Checkout Session (Preferred)

<CodeGroup>
  ```typescript Using a slug theme={null}
  const { data: session, error } = await authClient.dodopayments.checkoutSession({
    // Option A: use a configured slug
    slug: "premium-plan",

  // Your internal id for reference
  referenceId: "order_123",
  });

  if (session) {
  window.location.href = session.url;
  }

  ```

  ```typescript Using product cart theme={null}
  const { data: session, error } = await authClient.dodopayments.checkoutSession({
    // Option B: pass a product cart/product id directly
    product_cart: [
      {
        product_id: "pdt_xxxxxxxxxxxxxxxxxxxxx",
        quantity: 1,
      }
    ],

    // Your internal id for reference
    referenceId: "order_123",
  });

  if (session) {
    window.location.href = session.url;
  }
  ```
</CodeGroup>

<Info>
  Unlike the legacy <code>checkout</code> method, <code>checkoutSession</code>
  does not require billing information upfront as it will be taken from the user
  at the checkout page. You can still override it by passing the
  <code>billing</code> key in the argument.
</Info>

<Info>
  Similar to the legacy <code>checkout</code> method,
  <code>checkoutSession</code> takes customer's email and name from their
  better-auth session, however, you can override it by passing the
  <code>customer</code> object with email and name.
</Info>

<Info>
  You can pass the same options in the argument as the request body for [Create
  Checkout
  Session](https://docs.dodopayments.com/api-reference/checkout-sessions/create)
  endpoint.
</Info>

<Note>
  The return URL is taken from the <code>successUrl</code> configured in the
  server plugin. You do not need to include <code>return\_url</code> in the
  client payload.
</Note>

## Legacy Checkout (Deprecated)

<Warning>
  The <code>authClient.dodopayments.checkout</code> method is deprecated. Use
  <code>checkoutSession</code> instead for new implementations.
</Warning>

```typescript expandable theme={null}
const { data: checkout, error } = await authClient.dodopayments.checkout({
  slug: "premium-plan",
  customer: {
    email: "customer@example.com",
    name: "John Doe",
  },
  billing: {
    city: "San Francisco",
    country: "US",
    state: "CA",
    street: "123 Market St",
    zipcode: "94103",
  },
  referenceId: "order_123",
});

if (checkout) {
  window.location.href = checkout.url;
}
```

## Accessing the Customer Portal

```typescript expandable theme={null}
const { data: customerPortal, error } =
  await authClient.dodopayments.customer.portal();
if (customerPortal && customerPortal.redirect) {
  window.location.href = customerPortal.url;
}
```

## Listing Customer Data

```typescript expandable theme={null}
// Get subscriptions
const { data: subscriptions, error } =
  await authClient.dodopayments.customer.subscriptions.list({
    query: {
      limit: 10,
      page: 1,
      status: "active",
    },
  });

// Get payment history
const { data: payments, error } =
  await authClient.dodopayments.customer.payments.list({
    query: {
      limit: 10,
      page: 1,
      status: "succeeded",
    },
  });
```

## Tracking Metered Usage

Enable the <code>usage()</code> plugin on the server to capture metered events and let customers inspect their usage-based billing.

* <code>authClient.dodopayments.usage.ingest</code> ingests events for the signed-in, email-verified user.
* <code>authClient.dodopayments.usage.meters.list</code> lists recent usage for the meters tied to that customer’s subscriptions.

```typescript expandable theme={null}
// Record a metered event (e.g., an API request)
const { error: ingestError } = await authClient.dodopayments.usage.ingest({
  event_id: crypto.randomUUID(),
  event_name: "api_request",
  metadata: {
    route: "/reports",
    method: "GET",
  },
  // Optional Date; defaults to now if omitted
  timestamp: new Date(),
});

if (ingestError) {
  console.error("Failed to record usage", ingestError);
}

// List recent usage for the current customer
const { data: usage, error: usageError } =
  await authClient.dodopayments.usage.meters.list({
    query: {
      page_size: 20,
      meter_id: "mtr_yourMeterId", // optional
    },
  });

if (usage?.items) {
  usage.items.forEach((event) => {
    console.log(event.event_name, event.timestamp, event.metadata);
  });
}
```

<Tip>
  Timestamps older than one hour or more than five minutes into the future are
  rejected when ingesting usage.
</Tip>

<Tip>
  If you omit <code>meter\_id</code> when listing usage meters, all meters
  tied to the customer’s subscriptions are returned.
</Tip>

# Webhooks

<Info>
  The webhooks plugin processes real-time payment events from Dodo Payments with
  secure signature verification. The default endpoint is
  <code>/api/auth/dodopayments/webhooks</code>.
</Info>

<Steps>
  <Step title="Generate and set webhook secret">
    Generate a webhook secret for your endpoint URL (e.g., <code>https\://\<your-domain>/api/auth/dodopayments/webhooks</code>) in the Dodo Payments Dashboard and set it in your <code>.env</code> file:

    ```env theme={null}
    DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
    ```
  </Step>

  <Step title="Handle webhook events">
    Example handler:

    ```typescript expandable theme={null}
    webhooks({
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET!,
      onPayload: async (payload) => {
        console.log("Received webhook:", payload.type);
      },
    });
    ```
  </Step>
</Steps>

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

# Configuration Reference

<AccordionGroup>
  <Accordion title="Plugin Options">
    * <b>client</b> (required): DodoPayments client instance
    * <b>createCustomerOnSignUp</b> (optional): Auto-create customers on user signup
    * <b>use</b> (required): Array of plugins to enable (checkout, portal, usage, webhooks)
    * <b>getCustomerParams</b> (optional): Function that receives the BetterAuth `User` and returns extra fields to attach to the DodoPayments customer on creation and update (e.g. `metadata`, `phone_number`)

    ```typescript theme={null}
    dodopayments({
      client: dodoPayments,
      createCustomerOnSignUp: true,
      use: [portal()],
      getCustomerParams: (user) => ({
        metadata: { userId: user.id },
        phone_number: user.phoneNumber ?? null,
      }),
    })
    ```
  </Accordion>

  <Accordion title="Checkout Plugin Options">
    * <b>products</b>: Array of products or async function returning products -
      <b>successUrl</b>: URL to redirect after successful payment -
      <b>authenticatedUsersOnly</b>: Require user authentication (default: false)
  </Accordion>
</AccordionGroup>

# Troubleshooting & Tips

<AccordionGroup>
  <Accordion title="Common Issues">
    * <b>Invalid API key</b>: Double-check your
      <code>DODO\_PAYMENTS\_API\_KEY</code> in <code>.env</code>. -
      <b>Webhook signature mismatch</b>: Ensure the webhook secret matches the one
      set in the Dodo Payments Dashboard. - <b>Customer not created</b>: Confirm
      <code>createCustomerOnSignUp</code> is set to <code>true</code>.
  </Accordion>

  <Accordion title="Best Practices">
    * Use environment variables for all secrets and keys. - Test in
      <code>test\_mode</code> before switching to <code>live\_mode</code>. - Log
      webhook events for debugging and auditing.
  </Accordion>
</AccordionGroup>

# Prompt for LLMs

```text expandable theme={null}
You are a skilled developer helping to integrate the @dodopayments/better-auth adapter into a typescript web application with better-auth. This adapter enables seamless payment processing through Dodo Payments with automatic customer management, checkout flows, and webhook handling.
STAGE 1: BASIC SETUP
This stage covers the foundational setup needed before implementing any plugins. Complete this stage first.
STEP 1: Installation
Install the required dependencies:
npm install @dodopayments/better-auth dodopayments better-auth zod
STEP 2: Environment Variables Setup
You will need to complete these external setup tasks. I will provide you with a TODO list for the actions you need to take outside of the code:
TODO LIST FOR USER:
1. Generate Dodo Payments API Key:
   - Go to your Dodo Payments Dashboard > Developer > API Keys
   - Create a new API key (or use existing)
   - Copy the API key value
   - Set environment variable: DODO_PAYMENTS_API_KEY=your_api_key_here
2. Generate Better Auth Secret:
   - Generate a random secret key (32+ characters)
   - Set environment variable: BETTER_AUTH_SECRET=your_better_auth_secret_here
3. Set Application URL:
   - For development: BETTER_AUTH_URL=http://localhost:3000
   - For production: BETTER_AUTH_URL=https://your-domain.com
4. Webhook Secret (only if implementing webhooks plugin):
   - This will be provided after you specify your domain name in Stage 2
   - Set environment variable: DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
Add these environment variables to your .env file:
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=your_better_auth_secret_here
STEP 3: Server Configuration
Create or update your better-auth setup file (src/lib/auth.ts):
import { BetterAuth } from "better-auth";
import { dodopayments } from "@dodopayments/better-auth";
import DodoPayments from "dodopayments";
// Create DodoPayments client
export const dodoPayments = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
  environment: "test_mode", // Change to "live_mode" for production
});
// Configure better-auth with dodopayments adapter
export const { auth, endpoints, client } = BetterAuth({
  plugins: [
    dodopayments({
      client: dodoPayments,
      createCustomerOnSignUp: true, // Auto-create customers on signup
      use: [], // We'll add plugins here in Stage 2
      // Optional: attach metadata or phone_number to DodoPayments customer records
      // getCustomerParams: (user) => ({
      //   metadata: { userId: user.id },
      //   phone_number: user.phoneNumber ?? null,
      // }),
    }),
  ],
});
STEP 4: Client Configuration
Create or update your auth client file (src/lib/auth-client.ts):
import { createAuthClient } from "better-auth/react";
import { dodopaymentsClient } from "@dodopayments/better-auth/client";
export const authClient = createAuthClient({
  baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
  plugins: [dodopaymentsClient()],
});
STAGE 2: PLUGIN IMPLEMENTATION
After completing Stage 1, you can selectively implement any of these plugins based on your needs. Each plugin is independent and can be added or removed as needed.
PLUGIN SELECTION:
Before implementing any plugins, ask the user which plugins they want to implement:
"Which plugins would you like to implement? You can choose any combination of:
1. CHECKOUT - Enables secure payment processing and checkout flows
2. PORTAL - Provides customer self-service portal for subscriptions and payments
3. USAGE - Tracks metered events and exposes usage history for billing beyond included allowances
4. WEBHOOKS - Handles real-time payment events from Dodo Payments
Please specify which plugins you want (e.g., 'checkout and usage', 'all four', 'just portal', etc.)"
If the user doesn't respond or you cannot prompt the user, implement all four plugins by default.
Based on the user's selection, implement only the requested plugins from the sections below:
CHECKOUT PLUGIN
Purpose: Enables secure payment processing using Checkout Sessions (preferred) with product slug mapping. A legacy checkout endpoint is also exposed for backward compatibility but is deprecated.
SETUP TODO LIST FOR USER:
1. Create products in Dodo Payments Dashboard:
   - Go to Dodo Payments Dashboard > Products
   - Create your products (e.g., subscription plans, one-time purchases)
   - Copy each product ID (starts with "pdt_")
   - Note down the product names for creating friendly slugs
2. Plan your checkout URLs:
   - Decide on your success URL (e.g., "/dashboard/success", "/thank-you")
   - Ensure this URL exists in your application
Configuration:
Add checkout to your imports in src/lib/auth.ts:
import { dodopayments, checkout } from "@dodopayments/better-auth";
Add checkout plugin to the use array in your dodopayments configuration:
use: [
  checkout({
    products: [
      {
        productId: "pdt_xxxxxxxxxxxxxxxxxxxxx", // Your actual product ID from Dodo Payments
        slug: "premium-plan", // Friendly slug for checkout
      },
      // Add more products as needed
    ],
    successUrl: "/dashboard/success", // Your success page URL
    authenticatedUsersOnly: true, // Require login for checkout
  }),
],
Usage Example (Preferred - Checkout Sessions):
const { data: session, error } = await authClient.dodopayments.checkoutSession({
  // Use the slug from your configuration OR provide product_cart directly
  slug: "premium-plan",
  // product_cart: [{ product_id: "pdt_xxxxxxxxxxxxxxxxxxxxx", quantity: 1 }],
  referenceId: "order_123", // Optional reference
});
if (session) {
  window.location.href = session.url;
}

Deprecated (Legacy Checkout):
const { data: checkout, error } = await authClient.dodopayments.checkout({
  slug: "premium-plan",
  customer: {
    email: "customer@example.com",
    name: "John Doe",
  },
  billing: {
    city: "San Francisco",
    country: "US",
    state: "CA",
    street: "123 Market St",
    zipcode: "94103",
  },
});
if (checkout) {
  window.location.href = checkout.url;
}
Options:
- products: Array of products or async function returning products
- successUrl: URL to redirect after successful payment
- authenticatedUsersOnly: Require user authentication (default: false)
PORTAL PLUGIN
Purpose: Provides customer self-service capabilities for managing subscriptions and viewing payment history.
Configuration:
Add portal to your imports in src/lib/auth.ts:
import { dodopayments, portal } from "@dodopayments/better-auth";
Add portal plugin to the use array in your dodopayments configuration:
use: [
  portal(),
],
Usage Examples:
// Access customer portal
const { data: customerPortal, error } = await authClient.dodopayments.customer.portal();
if (customerPortal && customerPortal.redirect) {
  window.location.href = customerPortal.url;
}
// List customer subscriptions
const { data: subscriptions, error } = await authClient.dodopayments.customer.subscriptions.list({
  query: {
    limit: 10,
    page: 1,
    active: true,
  },
});
// List customer payments
const { data: payments, error } = await authClient.dodopayments.customer.payments.list({
  query: {
    limit: 10,
    page: 1,
    status: "succeeded",
  },
});
Note: All portal methods require user authentication.

USAGE PLUGIN (METERED BILLING)
Purpose: Records metered events (like API requests) for usage-based plans and surfaces recent usage history per customer.

SETUP TODO LIST FOR USER:
1. Create or identify usage meters in the Dodo Payments Dashboard:
   - Dashboard > Usage > Meters
   - Copy the meter IDs (prefixed with <code>mtr_</code>) used by your usage-based plans
2. Decide which event names and metadata you will capture (e.g., <code>api_request</code>, route, method)
3. Ensure BetterAuth users verify their email addresses (the plugin enforces this before ingesting usage)

Configuration:
Add usage to your imports in <code>src/lib/auth.ts</code>:
    import { dodopayments, usage } from "@dodopayments/better-auth";

Add the plugin to the <code>use</code> array:
    use: [
      usage(),
    ],

Usage Examples:

    // Record a metered event for the signed-in customer
    const { error: ingestError } = await authClient.dodopayments.usage.ingest({
      event_id: crypto.randomUUID(),
      event_name: "api_request",
      metadata: {
        route: "/reports",
        method: "GET",
      },
      // Optional Date or ISO string; defaults to now
      timestamp: new Date(),
    });

    if (ingestError) {
      console.error("Failed to record usage", ingestError);
    }

    // List recent usage for the current customer
    const { data: usage, error: usageError } =
      await authClient.dodopayments.usage.meters.list({
        query: {
          page_size: 20,
          meter_id: "mtr_yourMeterId", // optional filter
        },
      });

    if (usage?.items) {
      usage.items.forEach((event) => {
        console.log(event.event_name, event.timestamp, event.metadata);
      });
    }

<Tip>
  The plugin exposes <code>authClient.dodopayments.usage.ingest</code> and
  <code>authClient.dodopayments.usage.meters.list</code>. Timestamps older
  than one hour or more than five minutes in the future are rejected.
</Tip>
<Tip>
  If you do
  not pass <code>meter_id</code> when listing usage meters, all meters tied to 
  the customer’s active subscriptions are returned.
</Tip>
WEBHOOKS PLUGIN
Purpose: Handles real-time payment events from Dodo Payments with secure signature verification.
BEFORE CONFIGURATION - Setup Webhook URL:
First, I need your domain name to generate the webhook URL and provide you with setup instructions.
STEP 1: Domain Name Input
What is your domain name? Please provide:
- For production: your domain name (e.g., "myapp.com", "api.mycompany.com")
- For staging: your staging domain (e.g., "staging.myapp.com")
- For development: use "localhost:3000" (or your local port)
STEP 2: After receiving your domain name, I will:
- Generate your webhook URL: https://[YOUR-DOMAIN]/api/auth/dodopayments/webhooks
- Provide you with a TODO list for webhook setup in Dodo Payments dashboard
- Give you the exact environment variable setup instructions
WEBHOOK SETUP TODO LIST (will be provided after domain input):
1. Configure webhook in Dodo Payments Dashboard:
   - Go to Dodo Payments Dashboard > Developer > Webhooks
   - Click "Add Webhook" or "Create Webhook"
   - Enter webhook URL: https://[YOUR-DOMAIN]/api/auth/dodopayments/webhooks
   - Select events you want to receive (or select all)
   - Copy the generated webhook secret
2. Set webhook secret in your environment:
   - For production: Set DODO_PAYMENTS_WEBHOOK_SECRET in your hosting provider environment
   - For staging: Set DODO_PAYMENTS_WEBHOOK_SECRET in your staging environment
   - For development: Add DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here to your .env file
3. Deploy your application with the webhook secret configured
STEP 3: Add webhooks to your imports in src/lib/auth.ts:
import { dodopayments, webhooks } from "@dodopayments/better-auth";
STEP 4: Add webhooks plugin to the use array in your dodopayments configuration:
use: [
  webhooks({
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET!,
    // Generic handler for all webhook events
    onPayload: async (payload) => {
      console.log("Received webhook:", payload.type);
    },
    // Payment event handlers
    onPaymentSucceeded: async (payload) => {
      console.log("Payment succeeded:", payload);
    },
    onPaymentFailed: async (payload) => {
      console.log("Payment failed:", payload);
    },
    onPaymentProcessing: async (payload) => {
      console.log("Payment processing:", payload);
    },
    onPaymentCancelled: async (payload) => {
      console.log("Payment cancelled:", payload);
    },
    // Refund event handlers
    onRefundSucceeded: async (payload) => {
      console.log("Refund succeeded:", payload);
    },
    onRefundFailed: async (payload) => {
      console.log("Refund failed:", payload);
    },
    // Dispute event handlers
    onDisputeOpened: async (payload) => {
      console.log("Dispute opened:", payload);
    },
    onDisputeExpired: async (payload) => {
      console.log("Dispute expired:", payload);
    },
    onDisputeAccepted: async (payload) => {
      console.log("Dispute accepted:", payload);
    },
    onDisputeCancelled: async (payload) => {
      console.log("Dispute cancelled:", payload);
    },
    onDisputeChallenged: async (payload) => {
      console.log("Dispute challenged:", payload);
    },
    onDisputeWon: async (payload) => {
      console.log("Dispute won:", payload);
    },
    onDisputeLost: async (payload) => {
      console.log("Dispute lost:", payload);
    },
    // Subscription event handlers
    onSubscriptionActive: async (payload) => {
      console.log("Subscription active:", payload);
    },
    onSubscriptionOnHold: async (payload) => {
      console.log("Subscription on hold:", payload);
    },
    onSubscriptionRenewed: async (payload) => {
      console.log("Subscription renewed:", payload);
    },
    onSubscriptionPlanChanged: async (payload) => {
      console.log("Subscription plan changed:", payload);
    },
    onSubscriptionCancelled: async (payload) => {
      console.log("Subscription cancelled:", payload);
    },
    onSubscriptionFailed: async (payload) => {
      console.log("Subscription failed:", payload);
    },
    onSubscriptionExpired: async (payload) => {
      console.log("Subscription expired:", payload);
    },
    onSubscriptionUpdated: async (payload) => {
      console.log("Subscription updated:", payload);
    },
    // License key event handlers
    onLicenseKeyCreated: async (payload) => {
      console.log("License key created:", payload);
    },
    // Abandoned checkout event handlers
    onAbandonedCheckoutDetected: async (payload) => {
      console.log("Abandoned checkout detected:", payload);
    },
    onAbandonedCheckoutRecovered: async (payload) => {
      console.log("Abandoned checkout recovered:", payload);
    },
    // Dunning event handlers
    onDunningStarted: async (payload) => {
      console.log("Dunning started:", payload);
    },
    onDunningRecovered: async (payload) => {
      console.log("Dunning recovered:", payload);
    },
    // Credit event handlers
    onCreditAdded: async (payload) => {
      console.log("Credit added:", payload);
    },
    onCreditDeducted: async (payload) => {
      console.log("Credit deducted:", payload);
    },
    onCreditExpired: async (payload) => {
      console.log("Credit expired:", payload);
    },
    onCreditRolledOver: async (payload) => {
      console.log("Credit rolled over:", payload);
    },
    onCreditRolloverForfeited: async (payload) => {
      console.log("Credit rollover forfeited:", payload);
    },
    onCreditOverageCharged: async (payload) => {
      console.log("Credit overage charged:", payload);
    },
    onCreditManualAdjustment: async (payload) => {
      console.log("Credit manual adjustment:", payload);
    },
    onCreditBalanceLow: async (payload) => {
      console.log("Credit balance low:", payload);
    },
  }),
],
Supported Webhook Event Handlers:
- onPayload: Generic handler for all webhook events
- onPaymentSucceeded: Payment completed successfully
- onPaymentFailed: Payment failed
- onPaymentProcessing: Payment is being processed
- onPaymentCancelled: Payment was cancelled
- onRefundSucceeded: Refund completed successfully
- onRefundFailed: Refund failed
- onDisputeOpened: Dispute was opened
- onDisputeExpired: Dispute expired
- onDisputeAccepted: Dispute was accepted
- onDisputeCancelled: Dispute was cancelled
- onDisputeChallenged: Dispute was challenged
- onDisputeWon: Dispute was won
- onDisputeLost: Dispute was lost
- onSubscriptionActive: Subscription became active
- onSubscriptionOnHold: Subscription was put on hold
- onSubscriptionRenewed: Subscription was renewed
- onSubscriptionPlanChanged: Subscription plan was changed
- onSubscriptionCancelled: Subscription was cancelled
- onSubscriptionFailed: Subscription failed
- onSubscriptionExpired: Subscription expired
- onSubscriptionUpdated: Subscription was updated
- onLicenseKeyCreated: License key was created
- onAbandonedCheckoutDetected: Abandoned checkout was detected
- onAbandonedCheckoutRecovered: Abandoned checkout was recovered
- onDunningStarted: Dunning process started
- onDunningRecovered: Dunning process recovered
- onCreditAdded: Credits were added
- onCreditDeducted: Credits were deducted
- onCreditExpired: Credits expired
- onCreditRolledOver: Credits were rolled over
- onCreditRolloverForfeited: Credit rollover was forfeited
- onCreditOverageCharged: Credit overage was charged
- onCreditManualAdjustment: Manual credit adjustment was made
- onCreditBalanceLow: Credit balance is low
COMBINING SELECTED PLUGINS:
After implementing the user's selected plugins, update your <code>src/lib/auth.ts</code> file to include all chosen plugins in the imports and <code>use</code> array:

Example for all four plugins:
    import {
      dodopayments,
      checkout,
      portal,
      usage,
      webhooks,
    } from "@dodopayments/better-auth";

    use: [
      checkout({
        // checkout configuration
      }),
      portal(),
      usage(),
      webhooks({
        // webhook configuration
      }),
    ];

Example for checkout + portal + usage:
    import { dodopayments, checkout, portal, usage } from "@dodopayments/better-auth";

    use: [
      checkout({
        // checkout configuration
      }),
      portal(),
      usage(),
    ];

Example for just webhooks:
    import { dodopayments, webhooks } from "@dodopayments/better-auth";

    use: [
      webhooks({
        // webhook configuration
      }),
    ];
IMPORTANT NOTES:
1. Complete Stage 1 before implementing any plugins
2. Ask the user which plugins they want to implement, or implement all four if no response
3. Only implement the plugins the user specifically requested
4. ALWAYS provide TODO lists for external actions the user needs to complete:
   - API key generation and environment variable setup
   - Product creation in Dodo Payments dashboard (for checkout plugin)
   - Usage meter configuration and API event definition (for usage plugin)
   - Webhook setup in Dodo Payments dashboard (for webhooks plugin)
   - Domain name collection for webhook URL generation
5. For webhook plugin: Ask for the user's domain name and generate the exact webhook URL: https://[domain]/api/auth/dodopayments/webhooks
6. The usage plugin requires the BetterAuth session user to exist and have a verified email before ingesting or listing usage
7. All client methods return <code>{ data, error }</code> objects for proper error handling
8. Use <code>test_mode</code> for development and <code>live_mode</code> for production
9. The webhook endpoint is automatically created and secured with signature verification (if webhooks plugin is selected)
10. Customer portal and subscription listing require user authentication (if portal plugin is selected)
11. Handle errors appropriately and test webhook functionality in development before going live
12. Present all external setup tasks as clear TODO lists with specific environment variable names
13. Use getCustomerParams to attach metadata or phone_number to DodoPayments customer records — the function receives the BetterAuth User object and runs on every customer creation and update

```


# Build with AI Coding Agents
Source: https://docs.dodopayments.com/developer-resources/build-with-ai-coding-agents

Use the Dodo Agent Plugin to build integrations with Claude Code, Codex CLI, Cursor, VS Code, Kiro, Gemini CLI, and OpenCode — MCP servers and skills in one install.

The Dodo Agent Plugin wires two MCP servers and seventeen integration skills into your AI coding agent in a single install. It works with **Claude Code**, **Codex CLI**, **Cursor**, **VS Code / GitHub Copilot**, **Kiro**, and **OpenCode**. **Gemini CLI** gets the two MCP servers only. The MCP servers and skills CLI work with any MCP-compatible client.

The plugin follows the [Agent Plugins 1.0.0](https://agent-plugins.org/specification) specification, so clients with native support load it directly from the root `plugin.json` and `mcp.json`. Clients that predate the spec load the same content through generated compatibility manifests.

<Info>
  **Three primitives, one plugin.** The Agent Plugin bundles everything you need:

  * **API MCP server** — live access to payments, subscriptions, customers, products, refunds, licenses, and usage. Authenticates via browser OAuth (no local keys required).
  * **Knowledge MCP server** — semantic search across all Dodo Payments documentation. No credentials needed.
  * **Seventeen agent skills** — cheat sheets your agent loads on demand for checkout, subscriptions, webhooks, usage-based and credit-based billing, license keys, product catalog, discounts, localized pricing, mobile checkout, refunds and disputes, customer management, framework adapters, BillingSDK, Better Auth, testing and go-live, and best practices.
</Info>

## Install the plugin

Choose your coding agent below. Every install adds both MCP servers; all of them except Gemini CLI also add the seventeen skills.

<AccordionGroup>
  <Accordion title="Claude Code">
    Install from the marketplace:

    ```bash theme={null}
    claude plugins marketplace add dodopayments/dodo-agent-plugin
    claude plugins install dodopayments@dodopayments
    ```

    The API MCP server uses browser OAuth by default — no keys required at install time. The first time your agent calls a Dodo tool, you'll be prompted to sign in.

    <Card title="Dodo Agent Plugin on GitHub" icon="github" href="https://github.com/dodopayments/dodo-agent-plugin">
      Source code, configuration options, and local development instructions
    </Card>
  </Accordion>

  <Accordion title="Codex CLI">
    Codex installs plugins in two steps: register the marketplace from your shell, then install the plugin from inside the Codex TUI.

    <Steps>
      <Step title="Register the marketplace">
        ```bash theme={null}
        codex plugin marketplace add dodopayments/dodo-agent-plugin
        ```
      </Step>

      <Step title="Install from the Codex TUI">
        Open Codex and run the `/plugins` slash command:

        ```bash theme={null}
        codex
        ```

        Then type `/plugins`, switch to the **Dodo Payments** marketplace, select the **dodopayments** plugin, and choose **Install plugin**.
      </Step>
    </Steps>

    Both MCP servers and all seventeen skills are registered automatically once the plugin is installed.

    <Note>
      Codex CLI does not have a `codex plugin install` subcommand — plugin installation always happens through the in-TUI `/plugins` flow. See the [official Codex plugins docs](https://developers.openai.com/codex/plugins).
    </Note>

    If you previously added the marketplace and the plugin doesn't appear under `/plugins`, refresh it:

    ```bash theme={null}
    codex plugin marketplace upgrade dodopayments
    ```
  </Accordion>

  <Accordion title="Cursor">
    Manual install — clone the repo into Cursor's local plugins directory:

    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-agent-plugin.git ~/.cursor/plugins/local/dodo-agent-plugin
    ```

    Restart Cursor. The plugin loads skills from `skills/` and MCP servers from `.mcp.json`, as declared in `.cursor-plugin/plugin.json`.

    <Info>
      Recent Cursor builds also recognize Agent Plugins 1.0.0 directly and accept either `.cursor-plugin/marketplace.json` or `.claude-plugin/marketplace.json` as a marketplace source. This plugin ships `.claude-plugin/marketplace.json` — use that path. The generated `.cursor-plugin/plugin.json` is kept for older builds.
    </Info>

    <Warning>
      Versions before 0.5.0 shipped `skills/` as symlinks into a git submodule, so this clone produced a plugin with **no working skills**. Skills now ship as real files. If you installed an earlier version, delete the directory and re-clone.
    </Warning>
  </Accordion>

  <Accordion title="OpenCode">
    OpenCode distributes via npm. Add the plugin to your `opencode.json`:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "plugin": ["@dodopayments/opencode-plugin"]
    }
    ```

    Restart OpenCode. Both MCP servers (`dodopayments-api`, `dodo-knowledge`) are registered automatically via the plugin's config hook. No manual `mcp` block required.

    **Skills need one extra line.** OpenCode does not scan installed packages for skills, so point it at the package's `skills/` directory yourself:

    ```bash theme={null}
    npm install --save-dev @dodopayments/opencode-plugin
    ```

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "plugin": ["@dodopayments/opencode-plugin"],
      "skills": {
        "paths": ["node_modules/@dodopayments/opencode-plugin/skills"]
      }
    }
    ```

    Relative `skills.paths` entries resolve against the **project directory**, so the package must exist in that project's `node_modules` — OpenCode's own plugin cache is a different location. An absolute path works too, and avoids the local-install requirement.

    <Warning>
      A skills path that does not exist is ignored **silently**. Verify rather than assume:

      ```bash theme={null}
      opencode run "List every skill available to you by name."
      ```

      You should see all seventeen. Versions before 0.5.0 documented these skills as auto-discovered — they were not, so OpenCode users had MCP servers but no skills.
    </Warning>
  </Accordion>

  <Accordion title="VS Code / GitHub Copilot">
    Clone the repo anywhere, then register it:

    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-agent-plugin.git
    ```

    Open the Chat view, go to **Plugins**, and add the cloned folder. You can also register it directly in `settings.json`:

    ```json theme={null}
    {
      "chat.pluginLocations": { "~/dodo-agent-plugin": true }
    }
    ```

    The key is a path, the value enables it. Absolute paths and `~/` both work; a relative path resolves against each workspace folder. The setting is read live, so a running window picks it up without a restart. Skills load from `skills/`, and both MCP servers load from `.mcp.json`.

    <Note>
      `chat.pluginLocations` is marked **experimental** and is a *restricted* setting, so the workspace must be trusted for it to apply. Agent-plugin support overall is a preview feature governed by `chat.plugins.enabled`, which is **on by default** — you only need to set it if your organization disables it by policy.
    </Note>

    <Info>
      VS Code does not key off the Agent Plugins `$schema`. Its loader probes `.plugin/plugin.json`, then `.claude-plugin/plugin.json`, then a root `plugin.json`, and defaults MCP to `.mcp.json` rather than `mcp.json`. Because this repo ships a generated `.claude-plugin/plugin.json`, VS Code loads it through that compatibility branch and gets the `mcp-remote` bridge rather than the native transports in `mcp.json`. Everything works — the path differs.
    </Info>
  </Accordion>

  <Accordion title="Kiro">
    Kiro reads the Agent Plugins manifest natively and loads this as a Power.

    <Steps>
      <Step title="Clone the repository">
        ```bash theme={null}
        git clone https://github.com/dodopayments/dodo-agent-plugin.git
        ```
      </Step>

      <Step title="Open the Powers panel">
        In Kiro, open the Powers panel — the Ghosty icon with the lightning bolt.
      </Step>

      <Step title="Import the folder">
        Choose **Add Custom Power → Import power from a folder**, select the cloned directory (the one containing `plugin.json`), and click **Install**.
      </Step>
    </Steps>

    Skills load from `skills/`, MCP servers from `mcp.json`, and Kiro-specific presentation comes from the `dev.kiro` extension namespace in `plugin.json`.

    <Note>
      For plugins in the Agent Plugins format, Kiro manages MCP servers internally — they are **not** written to your user-level `~/.kiro/settings/mcp.json`, so don't expect to find them there. Kiro can also install a Power directly from a GitHub URL; see [Kiro's install docs](https://kiro.dev/docs/powers/installation/).
    </Note>
  </Accordion>

  <Accordion title="Gemini CLI (MCP only)">
    Gemini CLI has no agent-skill primitive, so **only the two MCP servers are available** — the seventeen skills are not. `dodo-knowledge` still covers a good share of what the skills provide, and it stays current automatically.

    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-agent-plugin.git \
      ~/.gemini/extensions/dodopayments
    ```

    Restart Gemini CLI. `gemini-extension.json` at the repo root is the manifest.
  </Accordion>
</AccordionGroup>

<Info>
  Using a different agent? The [MCP Server](/developer-resources/mcp-server) and [Agent Skills](/developer-resources/agent-skills) guides cover Claude Desktop, Windsurf, Cline, Zed, and any MCP-compatible client.
</Info>

## What you get

Once the plugin is installed, your agent has access to two MCP servers and seventeen skills.

### MCP servers

| Server             | Purpose                                                                                  | Auth            |
| ------------------ | ---------------------------------------------------------------------------------------- | --------------- |
| `dodopayments-api` | Live API access — payments, subscriptions, customers, products, refunds, licenses, usage | OAuth (browser) |
| `dodo-knowledge`   | Semantic search across all Dodo Payments documentation                                   | None            |

Both servers speak Streamable HTTP. The canonical `mcp.json` declares them natively (`type: "streamable-http"`), which is what spec-native clients such as Codex CLI and Kiro use. The generated compatibility manifest `.mcp.json` wires the same two endpoints through `mcp-remote` instead, so they also run in clients that cannot dial Streamable HTTP directly — Claude Code, VS Code, and Cursor via the git-clone install documented above, whose `.cursor-plugin/plugin.json` points at `.mcp.json`.

### Agent skills

| Skill                        | Description                                                                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `dodo-best-practices`        | SDK setup, environments, API keys, and the canonical checkout-to-webhook architecture                                                   |
| `framework-adapters`         | Official `@dodopayments/*` route handlers for Next.js, Express, Hono, Astro, Remix, SvelteKit, Nuxt, Fastify, TanStack, Bun, and Convex |
| `testing-and-go-live`        | Test mode, test payment methods, webhook testing, and the production launch checklist                                                   |
| `checkout-integration`       | Checkout Sessions, payment links, and overlay or inline checkout                                                                        |
| `subscription-integration`   | Subscription lifecycle, trials, plan changes, proration, and on-demand charges                                                          |
| `mobile-checkout`            | In-app checkout for React Native, Flutter, iOS, and Android                                                                             |
| `webhook-integration`        | Receiving and verifying webhooks using the Standard Webhooks specification                                                              |
| `credit-based-billing`       | Credit entitlements, balances, ledger, rollover, overage, and meter-based deduction                                                     |
| `usage-based-billing`        | Meters, event ingestion, aggregation, and per-unit pricing                                                                              |
| `license-keys`               | License key activation, validation, and instance management                                                                             |
| `product-catalog-management` | Products, pricing, add-ons, collections, images, and digital product delivery                                                           |
| `discounts-and-promotions`   | Discount codes, eligibility rules, stacking, and subscription-cycle limits                                                              |
| `localized-pricing`          | Localized pricing, adaptive currency, and purchasing power parity                                                                       |
| `customer-management`        | Customers, the self-service portal, saved payment methods, and wallets                                                                  |
| `refunds-and-disputes`       | Issuing refunds, handling disputes and chargebacks, and reconciling access                                                              |
| `billing-sdk`                | BillingSDK React components for pricing tables and billing UI                                                                           |
| `better-auth-integration`    | The `@dodopayments/better-auth` plugin for customer sync, checkout, and portal access                                                   |

Skills load automatically — your agent picks the right one when it detects a relevant task. See the [Agent Skills documentation](/developer-resources/agent-skills) for the full list and individual installation.

### Try this prompt first

Once the plugin is active, try:

```
Set up Dodo Payments webhook handlers in my Next.js app for payment.succeeded and subscription.active events.
```

Your agent will load the `webhook-integration` skill, use the `dodo-knowledge` MCP to pull the latest payload shapes, and write a handler with signature verification following the Standard Webhooks spec.

## Client support

### Clients with an Agent Plugin install

One install wires both MCP servers, plus the skills on every client that has a skill primitive.

| Agent                        | Install             | Skills | MCP servers |
| ---------------------------- | ------------------- | -----: | ----------: |
| **Claude Code**              | marketplace command |     17 |           2 |
| **Codex CLI**                | marketplace command |     17 |           2 |
| **Cursor**                   | git clone           |     17 |           2 |
| **VS Code / GitHub Copilot** | git clone           |     17 |           2 |
| **Kiro**                     | git clone           |     17 |           2 |
| **OpenCode**                 | npm                 |     17 |           2 |
| **Gemini CLI**               | git clone           |      0 |           2 |

* **OpenCode** needs one extra `skills.paths` entry before its seventeen skills load — see the install section above.
* **Gemini CLI** has no agent-skill primitive, so skills are unavailable there by design.

### Other MCP-compatible clients

These have no Agent Plugin install. Configure the two MCP servers by hand, and add skills through the Skills CLI where supported.

| Agent                | MCP servers                                         | Skills                                          |
| -------------------- | --------------------------------------------------- | ----------------------------------------------- |
| Claude Desktop       | [MCP Server guide](/developer-resources/mcp-server) | not supported                                   |
| Windsurf             | [MCP Server guide](/developer-resources/mcp-server) | [Skills CLI](/developer-resources/agent-skills) |
| Cline / Zed / others | [MCP Server guide](/developer-resources/mcp-server) | [Skills CLI](/developer-resources/agent-skills) |

## Docs built for agents

Every Dodo Payments documentation page is available in a format optimized for AI consumption:

* **Full docs index**: [`docs.dodopayments.com/llms.txt`](https://docs.dodopayments.com/llms.txt) — serves the complete documentation index for context ingestion.
* **Plain markdown**: Append `.md` to any documentation URL to get the raw markdown version (e.g., `/api-reference/introduction.md`).
* **Source repository**: [`github.com/dodopayments/dodo-docs`](https://github.com/dodopayments/dodo-docs) — clone for offline indexing.

## What your agent can do

With the plugin installed, your coding agent can:

* **Create checkout sessions and payment links** — [One-time payments](/features/one-time-payment-products) and [subscriptions](/features/subscription)
* **Stand up subscription and usage-based billing end-to-end** — [Subscriptions](/features/subscription), [Usage-based billing](/features/usage-based-billing/introduction), [Credit-based billing](/features/credit-based-billing)
* **Generate Standard Webhooks–compliant handlers** with signature verification — [Webhooks](/developer-resources/webhooks)
* **Mount route handlers in your framework** using the official adapters — [Framework adaptors](/developer-resources/framework-adaptors)
* **Wire BillingSDK React components** for pricing tables and subscription management — [BillingSDK](/developer-resources/billingsdk)
* **Author license-key flows** for digital products — [License keys](/features/license-keys)
* **Implement credit-based billing** with entitlements, balances, rollover, and overage — [Credits](/features/credit-based-billing)
* **Build and manage your product catalog** with add-ons and collections — [Products](/features/products), [Add-ons](/features/addons), [Product collections](/features/product-collections)
* **Add discounts and localized pricing** — [Discount codes](/features/discount-codes), [Localized pricing](/features/localized-pricing), [Adaptive currency](/features/adaptive-currency)
* **Ship mobile in-app checkout** for React Native, Flutter, iOS, and Android — [Mobile integration](/developer-resources/mobile-integration)
* **Handle refunds, disputes, and customer self-service** — [Refunds](/features/transactions/refunds), [Disputes](/features/transactions/disputes), [Customer portal](/features/customer-portal)
* **Test the integration and go live safely** — [Test mode vs live mode](/miscellaneous/test-mode-vs-live-mode)

## Security and best practices

<Warning>
  **Never commit production API keys.** Use [test mode](/miscellaneous/test-mode-vs-live-mode) during development. The Agent Plugin uses browser OAuth by default — only switch to local API keys if your workflow requires it.
</Warning>

* **Use test mode first.** Sandbox your integration with `dodo_test_...` keys before going live. See [Test Mode vs Live Mode](/miscellaneous/test-mode-vs-live-mode).
* **OAuth is the default.** The Agent Plugin authenticates via browser OAuth (no local secrets). Only use API-key mode if you need it — see the Configure section below.
* **Review agent-generated code.** Always verify webhook handlers include signature verification following the [Standard Webhooks spec](https://standardwebhooks.com/).

## Configure with an API key

By default, the Agent Plugin uses the remote MCP server with browser OAuth — no local credentials needed. If your workflow requires a local API key (e.g., CI environments, headless servers), you can switch to stdio mode.

<AccordionGroup>
  <Accordion title="Local API key mode — Claude Code">
    Open `/plugins` in Claude Code, select **Dodo Payments**, and choose **Configure options**. Fill in:

    * `dodo_api_key` — your `dodo_test_...` or `dodo_live_...` key
    * `dodo_webhook_key` — your webhook signing secret
    * `dodo_environment` — `test_mode` or `live_mode`

    Then edit `.mcp.json` to point `dodopayments-api` at the local stdio server:

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments-api": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "dodopayments-mcp@latest"],
          "env": {
            "DODO_PAYMENTS_API_KEY": "${user_config.dodo_api_key}",
            "DODO_PAYMENTS_WEBHOOK_KEY": "${user_config.dodo_webhook_key}",
            "DODO_PAYMENTS_ENVIRONMENT": "${user_config.dodo_environment}"
          }
        }
      }
    }
    ```

    Run `/reload-plugins` to apply changes to your current session.
  </Accordion>

  <Accordion title="Local API key mode — OpenCode">
    Declare `dodopayments-api` yourself in `opencode.json` — your entry wins over the plugin's default remote server:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "plugin": ["@dodopayments/opencode-plugin"],
      "mcp": {
        "dodopayments-api": {
          "type": "local",
          "command": ["npx", "-y", "dodopayments-mcp@latest"],
          "environment": {
            "DODO_PAYMENTS_API_KEY": "dodo_test_...",
            "DODO_PAYMENTS_WEBHOOK_KEY": "whsec_...",
            "DODO_PAYMENTS_ENVIRONMENT": "test_mode"
          },
          "enabled": true
        }
      }
    }
    ```

    Restart OpenCode to apply.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="MCP Server" icon="terminal" href="/developer-resources/mcp-server">
    Full reference for both MCP servers — all supported clients, configuration, and available tools
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/developer-resources/agent-skills">
    Individual skill installation, skill reference, and per-agent setup instructions
  </Card>

  <Card title="Sentra IDE Assistant" icon="bolt" href="/developer-resources/sentra">
    AI-powered billing assistant for VS Code, Cursor, and Windsurf — ask, build, and plan in your editor
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete OpenAPI reference for all Dodo Payments endpoints
  </Card>
</CardGroup>


# Convex Component
Source: https://docs.dodopayments.com/developer-resources/convex-component

Learn how to integrate Dodo Payments with your Convex backend using our Convex Component. Covers checkout functions, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Function" icon="cart-shopping" href="#checkout-function">
    Integrate Dodo Payments checkout with session-based flow.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-function">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/convex
    ```
  </Step>

  <Step title="Add Component to Convex Config">
    Add the Dodo Payments component to your Convex configuration:

    ```typescript theme={null}
    // convex/convex.config.ts
    import { defineApp } from "convex/server";
    import dodopayments from "@dodopayments/convex/convex.config";

    const app = defineApp();
    app.use(dodopayments);
    export default app;
    ```

    After editing `convex.config.ts`, run `npx convex dev` once to generate the necessary types.
  </Step>

  <Step title="Set up environment variables">
    Set up environment variables in your Convex dashboard (**Settings** → **Environment Variables**). You can access the dashboard by running:

    ```bash theme={null}
    npx convex dashboard
    ```

    Add the following environment variables:

    * `DODO_PAYMENTS_API_KEY` - Your Dodo Payments API key
    * `DODO_PAYMENTS_ENVIRONMENT` - Set to `test_mode` or `live_mode`
    * `DODO_PAYMENTS_WEBHOOK_SECRET` - Your webhook secret (required for webhook handling)

    <Warning>
      Always use Convex environment variables for sensitive information. Never commit secrets to version control.
    </Warning>
  </Step>
</Steps>

## Component Setup Examples

<Steps>
  <Step title="Create Internal Query">
    First, create an internal query to fetch customers from your database. This will be used in the payment functions to identify customers.

    <Warning>
      Before using this query, make sure to define the appropriate schema in your `convex/schema.ts` file or change the query to match your existing schema.
    </Warning>

    ```typescript theme={null}
    // convex/customers.ts
    import { internalQuery } from "./_generated/server";
    import { v } from "convex/values";

    // Internal query to fetch customer by auth ID
    export const getByAuthId = internalQuery({
      args: { authId: v.string() },
      handler: async (ctx, { authId }) => {
        return await ctx.db
          .query("customers")
          .withIndex("by_auth_id", (q) => q.eq("authId", authId))
          .first();
      },
    });
    ```
  </Step>

  <Step title="Configure DodoPayments Component">
    <CodeGroup>
      ```typescript Convex Component Setup expandable theme={null}
      // convex/dodo.ts
      import { DodoPayments, DodoPaymentsClientConfig } from "@dodopayments/convex";
      import { components } from "./_generated/api";
      import { internal } from "./_generated/api";

      export const dodo = new DodoPayments(components.dodopayments, {
      // This function maps your Convex user to a Dodo Payments customer
      // Customize it based on your authentication provider and database
      identify: async (ctx) => {
        const identity = await ctx.auth.getUserIdentity();
        if (!identity) {
          return null; // User is not logged in
        }
        
        // Use ctx.runQuery() to lookup customer from your database
        const customer = await ctx.runQuery(internal.customers.getByAuthId, {
          authId: identity.subject,
        });
        
        if (!customer) {
          return null; // Customer not found in database
        }
        
        return {
          dodoCustomerId: customer.dodoCustomerId, // Replace customer.dodoCustomerId with your field storing Dodo Payments customer ID
        };
      },
      apiKey: process.env.DODO_PAYMENTS_API_KEY!,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
      } as DodoPaymentsClientConfig);

      // Export the API methods for use in your app
      export const { checkout, customerPortal } = dodo.api();
      ```
    </CodeGroup>
  </Step>
</Steps>

<Tabs>
  <Tab title="Checkout Function Setup">
    <Info>
      Use this function to integrate Dodo Payments checkout into your Convex app. Uses session-based checkout with full feature support.
    </Info>

    <CodeGroup>
      ```typescript Checkout Action expandable theme={null}
      // convex/payments.ts
      import { action } from "./_generated/server";
      import { v } from "convex/values";
      import { checkout } from "./dodo";

      export const createCheckout = action({
        args: { 
          product_cart: v.array(v.object({
            product_id: v.string(),
            quantity: v.number(),
          })),
          returnUrl: v.optional(v.string()),
        },
        handler: async (ctx, args) => {
          try {
            const session = await checkout(ctx, {
              payload: {
                product_cart: args.product_cart,
                return_url: args.returnUrl,
                billing_currency: "USD",
                feature_flags: {
                  allow_discount_code: true,
                },
              },
            });
            if (!session?.checkout_url) {
              throw new Error("Checkout session did not return a checkout_url");
            }
            return session;
          } catch (error) {
            console.error("Failed to create checkout session", error);
            throw new Error("Unable to create checkout session. Please try again.");
          }
        },
      });
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Setup">
    <Info>
      Use this function to allow customers to manage their subscriptions and details via the Dodo Payments customer portal. The customer is automatically identified via the `identify` function.
    </Info>

    <CodeGroup>
      ```typescript Customer Portal Action expandable theme={null}
      // convex/payments.ts (add to existing file)
      import { action } from "./_generated/server";
      import { v } from "convex/values";
      import { customerPortal } from "./dodo";

      export const getCustomerPortal = action({
        args: {
          send_email: v.optional(v.boolean()),
        },
          handler: async (ctx, args) => {
            try {
              const portal = await customerPortal(ctx, args);
              if (!portal?.portal_url) {
                throw new Error("Customer portal did not return a portal_url");
              }
              return portal;
            } catch (error) {
              console.error("Failed to generate customer portal link", error);
              throw new Error("Unable to generate customer portal link. Please try again.");
            }
          },
      });
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler Setup">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Convex app. All webhook handlers receive the Convex `ActionCtx` as the first parameter, allowing you to use `ctx.runQuery()` and `ctx.runMutation()` to interact with your database.
    </Info>

    <CodeGroup>
      ```typescript Convex HTTP Action expandable theme={null}
      // convex/http.ts
      import { createDodoWebhookHandler } from "@dodopayments/convex";
      import { httpRouter } from "convex/server";
      import { internal } from "./_generated/api";

      const http = httpRouter();

      http.route({
        path: "/dodopayments-webhook",
        method: "POST",
        handler: createDodoWebhookHandler({
          // Handle successful payments
          onPaymentSucceeded: async (ctx, payload) => {
            console.log("🎉 Payment Succeeded!");

            // Use Convex context to persist payment data
            await ctx.runMutation(internal.webhooks.createPayment, {
              paymentId: payload.data.payment_id,
              businessId: payload.business_id,
              customerEmail: payload.data.customer.email,
              amount: payload.data.total_amount,
              currency: payload.data.currency,
              status: payload.data.status,
              webhookPayload: JSON.stringify(payload),
            });
          },

          // Handle subscription activation
          onSubscriptionActive: async (ctx, payload) => {
            console.log("🎉 Subscription Activated!");
            // Use Convex context to persist subscription data
            await ctx.runMutation(internal.webhooks.createSubscription, {
              subscriptionId: payload.data.subscription_id,
              businessId: payload.business_id,
              customerEmail: payload.data.customer.email,
              status: payload.data.status,
              webhookPayload: JSON.stringify(payload),
            });
          },
          // Add other event handlers as needed
        }),
      });

      export default http;
      ```
    </CodeGroup>

    <Warning>
      Make sure to define the corresponding database mutations in your Convex backend for each webhook event you want to handle. For example, create a <code>createPayment</code> mutation to record successful payments or a <code>createSubscription</code> mutation to manage subscription state.
    </Warning>
  </Tab>
</Tabs>

## Checkout Function

<Info>
  The Dodo Payments Convex component uses session-based checkout, providing a secure, customizable checkout experience with pre-configured product carts and customer details. This is the recommended approach for all payment flows.
</Info>

### Usage

```typescript theme={null}
const result = await checkout(ctx, {
  payload: {
    product_cart: [{ product_id: "pdt_123", quantity: 1 }],
    customer: { email: "user@example.com" },
    return_url: "https://example.com/success"
  }
});
```

Refer [Checkout Sessions](/developer-resources/checkout-session) for more details and a complete list of supported fields.

### Response Format

The checkout function returns a JSON response with the checkout URL:

```json theme={null}
{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}
```

## Customer Portal Function

The Customer Portal Function enables you to seamlessly integrate the Dodo Payments customer portal into your Convex application.

### Usage

```typescript theme={null}
const result = await customerPortal(ctx, {
  send_email: false
});
```

### Parameters

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Info>
  The customer is automatically identified using the `identify` function configured in your DodoPayments setup. This function should return the customer's `dodoCustomerId`.
</Info>

## Webhook Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>DODO\_PAYMENTS\_WEBHOOK\_SECRET</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (ctx: GenericActionCtx, payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

## Frontend Usage

<Info>
  Use the checkout function from your React components with Convex hooks.
</Info>

<CodeGroup>
  ```tsx React Checkout Component expandable theme={null}
  import { useAction } from "convex/react";
  import { api } from "../convex/_generated/api";

  export function CheckoutButton() {
    const createCheckout = useAction(api.payments.createCheckout);

    const handleCheckout = async () => {
      try {
        const { checkout_url } = await createCheckout({
          product_cart: [{ product_id: "pdt_123", quantity: 1 }],
          returnUrl: "https://example.com/success"
        });
        if (!checkout_url) {
          throw new Error("Missing checkout_url in response");
        }
        window.location.href = checkout_url;
      } catch (error) {
        console.error("Failed to create checkout", error);
        throw new Error("Unable to create checkout. Please try again.");
      }
    };

    return <button onClick={handleCheckout}>Buy Now</button>;
  }
  ```
</CodeGroup>

<CodeGroup>
  ```tsx Customer Portal Component expandable theme={null}
  import { useAction } from "convex/react";
  import { api } from "../convex/_generated/api";

  export function CustomerPortalButton() {
    const getPortal = useAction(api.payments.getCustomerPortal);

    const handlePortal = async () => {
      try {
        const { portal_url } = await getPortal({ send_email: false });
        if (!portal_url) {
          throw new Error("Missing portal_url in response");
        }
        window.location.href = portal_url;
      } catch (error) {
        console.error("Unable to open customer portal", error);
        alert("We couldn't open the customer portal. Please try again.");
      }
    };

    return <button onClick={handlePortal}>Manage Subscription</button>;
  }
  ```
</CodeGroup>

***

## Prompt for LLM

```
You are an expert Convex developer assistant. Your task is to guide a user through integrating the @dodopayments/convex component into their existing Convex application.

The @dodopayments/convex adapter provides a Convex component for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, built using the official Convex component architecture pattern.

First, install the necessary package:

npm install @dodopayments/convex

Here's how you should structure your response:

1. Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/convex component would you like to integrate into your project? You can choose one or more of the following:

- Checkout Function (for handling product checkouts)
- Customer Portal Function (for managing customer subscriptions/details)
- Webhook Handler (for receiving Dodo Payments webhook events)
- All (integrate all three)"

2. Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Function is selected:

Purpose: This function handles session-based checkout flows and returns checkout URLs for programmatic handling.

Integration Steps:

Step 1: Add the component to your Convex configuration.

// convex/convex.config.ts
import { defineApp } from "convex/server";
import dodopayments from "@dodopayments/convex/convex.config";

const app = defineApp();
app.use(dodopayments);
export default app;

Step 2: Guide the user to set up environment variables in the Convex dashboard. Instruct them to open the dashboard by running:

npx convex dashboard

Then add the required environment variables (e.g., DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_ENVIRONMENT, DODO_PAYMENTS_WEBHOOK_SECRET) in **Settings → Environment Variables**. Do not use .env files for backend functions.

Step 3: Create an internal query to fetch customers from your database.
Note: Ensure the user has appropriate schema defined in their convex/schema.ts file or modify the query to match their existing schema.

// convex/customers.ts
import { internalQuery } from "./_generated/server";
import { v } from "convex/values";

// Internal query to fetch customer by auth ID
export const getByAuthId = internalQuery({
  args: { authId: v.string() },
  handler: async (ctx, { authId }) => {
    return await ctx.db
      .query("customers")
      .withIndex("by_auth_id", (q) => q.eq("authId", authId))
      .first();
  },
});

Step 4: Create your payment functions file.

// convex/dodo.ts
import { DodoPayments, DodoPaymentsClientConfig } from "@dodopayments/convex";
import { components } from "./_generated/api";
import { internal } from "./_generated/api";

export const dodo = new DodoPayments(components.dodopayments, {
  // This function maps your Convex user to a Dodo Payments customer
  // Customize it based on your authentication provider and user database
  identify: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      return null; // User is not logged in
    }
    
    // Use ctx.runQuery() to lookup customer from your database
    const customer = await ctx.runQuery(internal.customers.getByAuthId, {
      authId: identity.subject,
    });
    
    if (!customer) {
      return null; // Customer not found in database
    }
    
    return {
      dodoCustomerId: customer.dodoCustomerId, // Replace customer.dodoCustomerId with your field storing Dodo Payments customer ID
    };
  },
  apiKey: process.env.DODO_PAYMENTS_API_KEY!,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
} as DodoPaymentsClientConfig);

// Export the API methods for use in your app
export const { checkout, customerPortal } = dodo.api();

Step 5: Create actions that use the checkout function.

// convex/payments.ts
import { action } from "./_generated/server";
import { v } from "convex/values";
import { checkout } from "./dodo";

// Checkout session with full feature support
export const createCheckout = action({
  args: { 
    product_cart: v.array(v.object({
      product_id: v.string(),
      quantity: v.number(),
    })),
    returnUrl: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    return await checkout(ctx, {
      payload: {
        product_cart: args.product_cart,
        return_url: args.returnUrl,
        billing_currency: "USD",
        feature_flags: {
          allow_discount_code: true,
        },
      },
    });
  },
});

Step 6: Use in your frontend.

// Your frontend component
import { useAction } from "convex/react";
import { api } from "../convex/_generated/api";

export function CheckoutButton() {
  const createCheckout = useAction(api.payments.createCheckout);

  const handleCheckout = async () => {
    const { checkout_url } = await createCheckout({
      product_cart: [{ product_id: "pdt_123", quantity: 1 }],
    });
    window.location.href = checkout_url;
  };

  return <button onClick={handleCheckout}>Buy Now</button>;
}

Configuration Details:

- `checkout()`: Checkout session with full feature support using session checkout.
- Returns: `{"checkout_url": "https://checkout.dodopayments.com/..."}`

For complete API documentation, refer to:
- Checkout Sessions: https://docs.dodopayments.com/developer-resources/checkout-session
- One-time Payments: https://docs.dodopayments.com/api-reference/payments/post-payments
- Subscriptions: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

If Customer Portal Function is selected:

Purpose: This function allows customers to manage their subscriptions and payment methods. The customer is automatically identified via the `identify` function.

Integration Steps:

Follow Steps 1-4 from the Checkout Function section, then:

Step 5: Create a customer portal action.

// convex/payments.ts (add to existing file)
import { action } from "./_generated/server";
import { v } from "convex/values";
import { customerPortal } from "./dodo";

export const getCustomerPortal = action({
  args: {
    send_email: v.optional(v.boolean()),
  },
  handler: async (ctx, args) => {
    try {
      const portal = await customerPortal(ctx, args);
      if (!portal?.portal_url) {
        throw new Error("Customer portal did not return a portal_url");
      }
      return portal;
    } catch (error) {
      console.error("Failed to generate customer portal link", error);
      throw new Error("Unable to generate customer portal link. Please retry.");
    }
  },
});

Step 6: Use in your frontend.

// Your frontend component
import { useAction } from "convex/react";
import { api } from "../convex/_generated/api";

export function CustomerPortalButton() {
  const getPortal = useAction(api.payments.getCustomerPortal);

  const handlePortal = async () => {
    const { portal_url } = await getPortal({ send_email: false });
    window.location.href = portal_url;
  };

  return <button onClick={handlePortal}>Manage Subscription</button>;
}

Configuration Details:
- Requires authenticated user (via `identify` function).
- Customer identification is handled automatically by the `identify` function.
- `send_email`: Optional boolean to send portal link via email.

If Webhook Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments or subscription changes.

Integration Steps:

Step 1: Add the webhook secret to your environment variables in the Convex dashboard. You can open the dashboard by running:

Guide the user to open the Convex dashboard by running:

npx convex dashboard

In the dashboard, go to **Settings → Environment Variables** and add:

- `DODO_PAYMENTS_WEBHOOK_SECRET=whsec_...`

Do not use .env files for backend functions; always set secrets in the Convex dashboard.

Step 2: Create a file `convex/http.ts`:

// convex/http.ts
import { createDodoWebhookHandler } from "@dodopayments/convex";
import { httpRouter } from "convex/server";
import { internal } from "./_generated/api";

const http = httpRouter();

http.route({
  path: "/dodopayments-webhook",
  method: "POST",
  handler: createDodoWebhookHandler({
    // Handle successful payments
    onPaymentSucceeded: async (ctx, payload) => {
      console.log("🎉 Payment Succeeded!");

      // Use Convex context to persist payment data
      await ctx.runMutation(internal.webhooks.createPayment, {
        paymentId: payload.data.payment_id,
        businessId: payload.business_id,
        customerEmail: payload.data.customer.email,
        amount: payload.data.total_amount,
        currency: payload.data.currency,
        status: payload.data.status,
        webhookPayload: JSON.stringify(payload),
      });
    },

    // Handle subscription activation
    onSubscriptionActive: async (ctx, payload) => {
      console.log("🎉 Subscription Activated!");
      // Use Convex context to persist subscription data
      await ctx.runMutation(internal.webhooks.createSubscription, {
        subscriptionId: payload.data.subscription_id,
        businessId: payload.business_id,
        customerEmail: payload.data.customer.email,
        status: payload.data.status,
        webhookPayload: JSON.stringify(payload),
      });
    },
    // Add other event handlers as needed
  }),
});

export default http;

Note: Make sure to define the corresponding database mutations in your Convex backend for each webhook event you want to handle. For example, create a `createPayment` mutation to record successful payments or a `createSubscription` mutation to manage subscription state.

Now, you can set the webhook endpoint URL in your Dodo Payments dashboard to `https://<your-convex-deployment-url>/dodopayments-webhook`.

Environment Variable Setup:

Set up the following environment variables in your Convex dashboard if you haven't already (Settings → Environment Variables):

- `DODO_PAYMENTS_API_KEY` - Your Dodo Payments API key
- `DODO_PAYMENTS_ENVIRONMENT` - Set to `test_mode` or `live_mode`
- `DODO_PAYMENTS_WEBHOOK_SECRET` - Your webhook secret (required for webhook handling)

Usage in your component configuration:

apiKey: process.env.DODO_PAYMENTS_API_KEY
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode"

Important: Never commit sensitive environment variables directly into your code. Always use Convex environment variables for all sensitive information.

If the user needs assistance setting up environment variables or deployment, ask them about their specific setup and provide guidance accordingly.

Run `npx convex dev` after setting up the component to generate the necessary types.
```


# Official SDKs Overview
Source: https://docs.dodopayments.com/developer-resources/dodo-payments-sdks

Official SDKs for TypeScript, Python, PHP, Go, Ruby, Java, Kotlin, C#, and Rust to integrate Dodo Payments into your applications

Dodo Payments provides official SDKs for multiple programming languages, each designed with language-specific best practices and modern features for seamless payment integration.

<Tip>
  Always use the latest SDK version to access the newest features and improvements. Check your package manager for updates regularly to ensure you have access to all Dodo Payments capabilities.
</Tip>

## Available SDKs

Choose the SDK that matches your tech stack:

<CardGroup>
  <Card title="TypeScript SDK" icon="js" href="/developer-resources/sdks/typescript">
    Type-safe integration for TypeScript and Node.js with promise-based API and auto-pagination
  </Card>

  <Card title="Python SDK" icon="python" href="/developer-resources/sdks/python">
    Pythonic interface with async/await support for Python 3.7+ applications
  </Card>

  <Card title="PHP SDK" icon="php" href="/developer-resources/sdks/php">
    PSR-4 compliant SDK for modern PHP 8.1+ applications
  </Card>

  <Card title="Go SDK" icon="golang" href="/developer-resources/sdks/go">
    Idiomatic Go interface with context support and strong typing
  </Card>

  <Card title="Ruby SDK" icon="gem" href="/developer-resources/sdks/ruby">
    Elegant Ruby interface following Ruby conventions and best practices
  </Card>

  <Card title="Java SDK" icon="java" href="/developer-resources/sdks/java">
    Robust and thread-safe SDK for Java 8+ with Maven and Gradle support
  </Card>

  <Card title="Kotlin SDK" icon="code" href="/developer-resources/sdks/kotlin">
    Modern Kotlin SDK with coroutines, null safety, and extension functions
  </Card>

  <Card title="C# SDK" icon="c" href="/developer-resources/sdks/csharp">
    Type-safe SDK for .NET 8+ with async Task-based API (Beta)
  </Card>

  <Card title="Rust SDK" icon="rust" href="/developer-resources/sdks/rust">
    Async-first SDK built on Tokio and reqwest with strong typing for Rust 1.75+
  </Card>

  <Card title="CLI" icon="terminal" href="/developer-resources/sdks/cli">
    Command-line interface for interacting with the API from your terminal
  </Card>
</CardGroup>

Building a mobile app? See [Mobile Checkout SDKs](#mobile-checkout-sdks) below
for Android, iOS, React Native, and Flutter.

## Quick Start

Get started with any SDK in minutes:

<Steps>
  <Step title="Install the SDK">
    Use your language's package manager to install the SDK

    <Tabs>
      <Tab title="TypeScript/Node.js">
        ```bash theme={null}
        npm install dodopayments
        ```
      </Tab>

      <Tab title="Python">
        ```bash theme={null}
        pip install dodopayments
        ```
      </Tab>

      <Tab title="PHP">
        ```bash theme={null}
        composer require dodopayments/client
        ```
      </Tab>

      <Tab title="Go">
        ```bash theme={null}
        go get github.com/dodopayments/dodopayments-go
        ```
      </Tab>

      <Tab title="Rust">
        ```bash theme={null}
        cargo add dodopayments
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Initialize the Client">
    Configure the client with your API key

    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        import DodoPayments from 'dodopayments';
        const client = new DodoPayments({ bearerToken: 'your_api_key' });
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        from dodopayments import DodoPayments
        client = DodoPayments(bearer_token="your_api_key")
        ```
      </Tab>

      <Tab title="PHP">
        ```php theme={null}
        use Dodopayments\Client;
        $client = new Client(bearerToken: 'your_api_key');
        ```
      </Tab>

      <Tab title="Go">
        ```go theme={null}
        import "github.com/dodopayments/dodopayments-go"
        client := dodopayments.NewClient(option.WithBearerToken("your_api_key"))
        ```
      </Tab>

      <Tab title="Rust">
        ```rust theme={null}
        use dodopayments::Client;
        let client = Client::from_env()?; // reads DODO_PAYMENTS_API_KEY
        ```
      </Tab>
    </Tabs>

    <Warning>
      Always store your API keys securely using environment variables. Never commit them to version control.
    </Warning>
  </Step>

  <Step title="Make Your First API Call">
    Create a checkout session or payment

    <Check>
      You're now ready to process payments! Visit the individual SDK pages for detailed guides and examples.
    </Check>
  </Step>
</Steps>

## Key Features

All **backend** SDKs share these core capabilities. The mobile checkout SDKs
below are deliberately narrower — they hold no API key and never call the API:

* **Type Safety**: Strong typing for compile-time safety and better IDE support
* **Error Handling**: Comprehensive exception handling with detailed error messages
* **Authentication**: Simple API key authentication with environment variable support
* **Async Support**: Modern async/await patterns where applicable
* **Auto-Pagination**: Automatic pagination for list responses
* **Usage-Based Billing**: Built-in support for tracking and ingesting usage events
* **Testing**: Full Test Mode support for development and testing

## Mobile Checkout SDKs

If you'd rather open Dodo's **hosted checkout page** than build a native
payment sheet, use the mobile checkout SDK for your platform. All four share
the same one-call contract: `start(...)` returns a typed `CheckoutResult`,
none of them hold an API key, and Apple Pay/Google Pay work the same way they
do on the open web since checkout opens in the platform's real browser surface
(`SFSafariViewController` / Custom Tabs), not a `WebView`:

<CardGroup>
  <Card title="Android" icon="android" href="/developer-resources/sdks/android">
    Kotlin SDK that opens a Chrome Custom Tab. Requires `minSdk` 23
  </Card>

  <Card title="iOS" icon="apple" href="/developer-resources/sdks/ios">
    Swift SDK that opens `SFSafariViewController`. Requires iOS 16+
  </Card>

  <Card title="React Native" icon="react" href="/developer-resources/sdks/react-native">
    Turbo Module over both native cores. Requires React Native 0.76+
  </Card>

  <Card title="Flutter" icon="layer-group" href="/developer-resources/sdks/flutter">
    Pigeon channel over both native cores. Requires Flutter 3.44+
  </Card>
</CardGroup>

<Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
  The end-to-end mobile payment flow, from backend checkout session to callback scheme setup
</Card>

## Command-Line Interface

For terminal-based workflows and automation:

<Card title="CLI" icon="terminal" href="/developer-resources/sdks/cli">
  Auto-generated command-line interface with support for the Dodo Payments API
</Card>

**Features:**

* Resource-based command structure for intuitive usage
* Multiple output formats (JSON, YAML, pretty, interactive)
* Shell completion for bash, zsh, and fish
* Perfect for scripting and CI/CD automation

```bash theme={null}
# Quick example
dodopayments payments list --format json | jq '.items[] | {payment_id, total_amount}'
```

## Migration from Node.js SDK

<Info>
  We migrated from the Node.js SDK to the new TypeScript SDK. If you're using the legacy Node.js SDK, see the [migration guide](https://github.com/dodopayments/dodopayments-typescript/blob/main/MIGRATION.md) to update your integration.
</Info>

## Framework Adapters

Integrate in under 10 lines of code with our framework adapters. Choose from our recommended frameworks or explore all supported options.

### Recommended Frameworks

<CardGroup>
  <Card title="Next.js" icon="atom" href="/developer-resources/nextjs-adaptor">
    React-based full-stack framework with App Router support
  </Card>

  <Card title="Better Auth" icon="shield" href="/developer-resources/better-auth-adaptor">
    Authentication framework with built-in integrations
  </Card>

  <Card title="Supabase" icon="database" href="developer-resources/supabase-boilerplate">
    Open source Firebase alternative with Postgres and Auth
  </Card>

  <Card title="Convex" icon="database" href="/developer-resources/convex-component">
    Backend-as-a-Service with real-time capabilities
  </Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="Show other 8+ supported frameworks">
    <CardGroup>
      <Card title="SvelteKit" icon="js" href="/developer-resources/sveltekit-adaptor" />

      <Card title="Nuxt" icon="vuejs" href="/developer-resources/nuxt-adaptor" />

      <Card title="Remix" icon="react" href="/developer-resources/remix-adaptor" />

      <Card title="Express" icon="js" href="/developer-resources/express-adaptor" />

      <Card title="Fastify" icon="bolt" href="/developer-resources/fastify-adaptor" />

      <Card title="Hono" icon="cloud" href="/developer-resources/hono-adaptor" />

      <Card title="Astro" icon="star" href="/developer-resources/astro-adaptor" />

      <Card title="TanStack" icon="chart-line" href="/developer-resources/tanstack-adaptor" />
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Getting Help

Need assistance with any SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time help
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the respective SDK repository
* **Documentation**: Visit our [API reference](/api-reference/introduction)

## Contributing

We welcome contributions to all our SDKs! Each repository has a `CONTRIBUTING.md` file with guidelines for:

* Reporting bugs
* Requesting features
* Submitting pull requests
* Running tests locally
* Code style and conventions

Visit the individual SDK pages to access their GitHub repositories and contribution guidelines.


# Express Adaptor
Source: https://docs.dodopayments.com/developer-resources/express-adaptor

Learn how to integrate Dodo Payments with your Express App Router project using our Express Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your Express app.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/express
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    DODO_PAYMENTS_RETURN_URL=your-return-url
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Express app. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { checkoutHandler } from '@dodopayments/express';

      app.get('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "static"
      }))

      app.post('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "dynamic"
      }))

      app.post('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "session"
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { CustomerPortal } from "@dodopayments/express";

      app.get('/api/customer-portal', CustomerPortal({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Express app.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { Webhooks } from "@dodopayments/express";

      app.post('/api/webhook',Webhooks({
          webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
          onPayload: async (payload) => {
              // handle the payload
          },
          // ... other event handlers for granular control
      }))
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Express application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```
You are an expert Express.js developer assistant. Your task is to guide a user through integrating the @dodopayments/express adapter into their existing Express.js project.

The @dodopayments/express adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed to plug directly into an Express app.

First, install the necessary package. Use the package manager appropriate for the user's project (npm, yarn, or bun):

npm install @dodopayments/express

---

Here's how you should structure your response:

1. Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/express adapter would you like to integrate into your project? You can choose one or more of the following:

- Checkout Route Handler (for handling product checkouts)
- Customer Portal Route Handler (for managing customer subscriptions/details)
- Webhook Route Handler (for receiving Dodo Payments webhook events)
- All (integrate all three)"

---

2. Based on the user's selection, provide detailed integration steps for each chosen functionality.

---

**If Checkout Route Handler is selected:**

**Purpose**: This handler manages different types of checkout flows. All checkout types (static, dynamic, and sessions) return JSON responses with checkout URLs for programmatic handling.

**Integration**:
Create routes in your Express app for static (GET), dynamic (POST), and checkout sessions (POST).


import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// For checkout sessions
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

Config Options:

    bearerToken: Your Dodo Payments API key (recommended to be stored in DODO_PAYMENTS_API_KEY env variable).

    returnUrl (optional): URL to redirect the user after successful checkout.

    environment: "test_mode" or "live_mode"

    type: "static" (GET), "dynamic" (POST), or "session" (POST)

GET (static checkout) expects query parameters:

    productId (required)

    quantity, customer fields (fullName, email, etc.), and metadata (metadata_*) are optional.

    Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (dynamic checkout) expects a JSON body with payment details (one-time or subscription). Reference the docs for the full POST schema:

    One-time payments: https://docs.dodopayments.com/api-reference/payments/post-payments

    Subscriptions: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}


POST (checkout sessions) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

If Customer Portal Route Handler is selected:

Purpose: This route allows customers to manage their subscriptions via the Dodo Payments portal.

Integration:

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

Query Parameters:

    customer_id (required): e.g., ?customer_id=cus_123

    send_email (optional): if true, customer is emailed the portal link

Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: Processes incoming webhook events from Dodo Payments to trigger events in your app.

Integration:

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Handle generic payload
  },
  // You can also provide fine-grained handlers for each event type below
}));

Features:

    Only POST method is allowed — others return 405

    Signature verification is performed using webhookKey. Returns 401 if invalid.

    Zod-based payload validation. Returns 400 if invalid schema.

    All handlers are async functions.

Supported Webhook Event Handlers:

You may pass in any of the following handlers:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired, onSubscriptionUpdated

    onLicenseKeyCreated

    onAbandonedCheckoutDetected, onAbandonedCheckoutRecovered

    onDunningStarted, onDunningRecovered

    onCreditAdded, onCreditDeducted, onCreditExpired, onCreditRolledOver, onCreditRolloverForfeited, onCreditOverageCharged, onCreditManualAdjustment, onCreditBalanceLow

Environment Variable Setup:

Make sure to define these environment variables in your project:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Use these inside your code as:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Security Note: Do NOT commit secrets to version control. Use .env files locally and secrets managers in deployment environments (e.g., AWS, Vercel, Heroku, etc.).
```


# Framework Adaptors Overview
Source: https://docs.dodopayments.com/developer-resources/framework-adaptors

Pre-built adaptors for popular web frameworks to integrate Dodo Payments in minutes with minimal code

Dodo Payments provides official framework adaptors that simplify payment integration. Each adaptor is designed to work seamlessly with your framework's conventions, offering checkout, customer portal, and webhook handling out of the box.

<Tip>
  Framework adaptors let you integrate Dodo Payments in under 10 lines of code. They handle authentication, request parsing, and response formatting automatically.
</Tip>

## Available Framework Adaptors

Choose the adaptor that matches your framework:

<CardGroup>
  <Card title="Next.js" icon="react" href="/developer-resources/nextjs-adaptor">
    App Router support with route handlers for checkout, portal, and webhooks
  </Card>

  <Card title="Nuxt" icon="vuejs" href="/developer-resources/nuxt-adaptor">
    Vue-based full-stack framework with server routes integration
  </Card>

  <Card title="Express" icon="node-js" href="/developer-resources/express-adaptor">
    Middleware-based handlers for the popular Node.js framework
  </Card>

  <Card title="Fastify" icon="bolt" href="/developer-resources/fastify-adaptor">
    High-performance Node.js framework with plugin architecture
  </Card>

  <Card title="Hono" icon="cloud" href="/developer-resources/hono-adaptor">
    Ultrafast web framework for the edge, Cloudflare Workers, and more
  </Card>

  <Card title="Astro" icon="star" href="/developer-resources/astro-adaptor">
    Content-focused framework with server endpoints support
  </Card>

  <Card title="SvelteKit" icon="code" href="/developer-resources/sveltekit-adaptor">
    Full-stack Svelte framework with server hooks integration
  </Card>

  <Card title="Remix" icon="react" href="/developer-resources/remix-adaptor">
    Full-stack React framework with loader and action handlers
  </Card>

  <Card title="TanStack Start" icon="chart-line" href="/developer-resources/tanstack-adaptor">
    Type-safe full-stack React framework with server functions
  </Card>

  <Card title="Better Auth" icon="shield" href="/developer-resources/better-auth-adaptor">
    Authentication framework plugin for seamless auth + payments
  </Card>

  <Card title="Convex" icon="database" href="/developer-resources/convex-component">
    Backend-as-a-Service component for real-time payment sync
  </Card>

  <Card title="Bun" icon="bolt" href="/developer-resources/bun-adaptor">
    Native Bun.serve() handlers for checkout, portal, and webhooks
  </Card>
</CardGroup>

## Core Features

All framework adaptors provide these built-in capabilities:

| Feature                | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Checkout Handler**   | Support for static, dynamic, and session-based checkout flows |
| **Customer Portal**    | Pre-built handler for subscription and billing management     |
| **Webhook Handler**    | Secure signature verification with typed event handlers       |
| **Environment Config** | Simple setup via environment variables                        |
| **Type Safety**        | Full TypeScript support with typed payloads                   |

## Quick Start

Get started with any framework adaptor in three steps:

<Steps>
  <Step title="Install the Adaptor">
    Use your package manager to install the framework-specific adaptor:

    <Tabs>
      <Tab title="Next.js">
        ```bash theme={null}
        npm install @dodopayments/nextjs
        ```
      </Tab>

      <Tab title="Nuxt">
        ```bash theme={null}
        npm install @dodopayments/nuxt
        ```
      </Tab>

      <Tab title="Express">
        ```bash theme={null}
        npm install @dodopayments/express
        ```
      </Tab>

      <Tab title="Hono">
        ```bash theme={null}
        npm install @dodopayments/hono
        ```
      </Tab>

      <Tab title="Astro">
        ```bash theme={null}
        npm install @dodopayments/astro
        ```
      </Tab>

      <Tab title="SvelteKit">
        ```bash theme={null}
        npm install @dodopayments/sveltekit
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure Environment Variables">
    Add your Dodo Payments credentials to your environment:

    ```env theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
    DODO_PAYMENTS_ENVIRONMENT="test_mode" # or "live_mode"
    ```

    <Warning>
      Never commit your `.env` file or secrets to version control.
    </Warning>
  </Step>

  <Step title="Create Route Handlers">
    Set up your checkout, customer portal, and webhook routes:

    <Tabs>
      <Tab title="Next.js">
        ```typescript theme={null}
        // app/checkout/route.ts
        import { Checkout } from "@dodopayments/nextjs";

        export const GET = Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        });
        ```
      </Tab>

      <Tab title="Express">
        ```typescript theme={null}
        import { checkoutHandler } from '@dodopayments/express';

        app.get('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        }));
        ```
      </Tab>

      <Tab title="Hono">
        ```typescript theme={null}
        import { Checkout } from "@dodopayments/hono";

        app.get('/checkout', Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        }));
        ```
      </Tab>
    </Tabs>

    <Check>
      You're now ready to process payments! Visit the individual adaptor pages for detailed guides and all available options.
    </Check>
  </Step>
</Steps>

## Checkout Flow Types

All adaptors support three checkout flow types:

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    Use static checkout for simple, shareable payment links. Pass the product ID as a query parameter:

    ```
    /api/checkout?productId=pdt_xxx&quantity=1
    ```

    Supports optional customer prefill and customization via query parameters.
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    Use dynamic checkout to programmatically create payments with custom details:

    ```json theme={null}
    {
      "product_id": "pdt_xxx",
      "customer": {
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "quantity": 1
    }
    ```

    Supports both one-time payments and subscriptions.
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Use checkout sessions for the most flexible checkout experience with cart support:

    ```json theme={null}
    {
      "product_cart": [
        { "product_id": "pdt_xxx", "quantity": 1 },
        { "product_id": "pdt_yyy", "quantity": 2 }
      ],
      "customer": {
        "email": "customer@example.com"
      }
    }
    ```

    Learn more in the [Checkout Sessions Guide](/developer-resources/checkout-session).
  </Accordion>
</AccordionGroup>

## Webhook Event Handling

All adaptors provide type-safe webhook handling with granular event callbacks:

```typescript theme={null}
Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Handle any webhook event
  },
  onPaymentSucceeded: async (payload) => {
    // Handle successful payments
  },
  onSubscriptionActive: async (payload) => {
    // Handle new subscriptions
  },
  // ... 20+ event types supported
});
```

<Info>
  All webhook handlers automatically verify signatures and validate payloads using Zod schemas. Invalid requests are rejected with appropriate error codes.
</Info>

## Choosing the Right Adaptor

| Framework          | Best For                               | Runtime        |
| ------------------ | -------------------------------------- | -------------- |
| **Next.js**        | Full-stack React apps with App Router  | Node.js, Edge  |
| **Nuxt**           | Full-stack Vue.js applications         | Node.js        |
| **Express**        | REST APIs and traditional Node.js apps | Node.js        |
| **Fastify**        | High-performance APIs                  | Node.js        |
| **Hono**           | Edge deployments, Cloudflare Workers   | Edge, Node.js  |
| **Astro**          | Content sites with server endpoints    | Node.js, Edge  |
| **SvelteKit**      | Full-stack Svelte applications         | Node.js        |
| **Remix**          | Full-stack React with nested routing   | Node.js        |
| **TanStack Start** | Type-safe full-stack React             | Node.js        |
| **Better Auth**    | Apps already using Better Auth         | Various        |
| **Convex**         | Apps using Convex for backend          | Convex Runtime |
| **Bun**            | Native Bun server applications         | Bun            |

## Getting Help

Need assistance with framework adaptors?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time help
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the respective adaptor repository
* **Documentation**: Visit our [API reference](/api-reference/introduction)


# API Gateway Blueprint
Source: https://docs.dodopayments.com/developer-resources/ingestion-blueprints/api-gateway

Track API calls and gateway-level usage for billing. Perfect for API-as-a-service platforms with high-volume request tracking.

## Use Cases

Explore common scenarios supported by the API Gateway Blueprint:

<CardGroup>
  <Card title="API-as-a-Service" icon="server">
    Track usage per customer for API platforms and charge based on number of calls.
  </Card>

  <Card title="Rate Limiting" icon="gauge">
    Monitor API usage patterns and implement usage-based rate limiting.
  </Card>

  <Card title="Performance Monitoring" icon="chart-line">
    Track response times and error rates alongside billing data.
  </Card>

  <Card title="Multi-Tenant SaaS" icon="users">
    Bill customers based on their API consumption across different endpoints.
  </Card>
</CardGroup>

<Info>
  Ideal for tracking API endpoint usage, rate limiting, and implementing usage-based API billing.
</Info>

## Quick Start

Track API calls at the gateway level with automatic batching for high-volume scenarios:

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    * **Dodo Payments API Key**: Get it from [Dodo Payments Dashboard](https://app.dodopayments.com/developer/api-keys)
  </Step>

  <Step title="Create a Meter">
    Create a meter in your [Dodo Payments Dashboard](https://app.dodopayments.com/):

    * **Event Name**: `api_call` (or your preferred name)
    * **Aggregation Type**: `count` for tracking number of calls
    * Configure additional properties if tracking metadata like response times, status codes, etc.
  </Step>

  <Step title="Track API Calls">
    <CodeGroup>
      ```javascript Single API Call theme={null}
      import { Ingestion, trackAPICall } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'api_call'
      });

      // Track a single API call
      await trackAPICall(ingestion, {
        customerId: 'customer_123',
        metadata: {
          endpoint: '/api/v1/users',
          method: 'GET',
          status_code: 200,
          response_time_ms: 45
        }
      });
      ```

      ```javascript High-Volume with Batching theme={null}
      import { Ingestion, createBatch } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'live_mode',
        eventName: 'api_call'
      });

      // Create batch for high-volume tracking
      const batch = createBatch(ingestion, {
        maxSize: 100,      // Flush after 100 events
        flushInterval: 5000 // Or flush every 5 seconds
      });

      // Add API calls to batch
      batch.add({
        customerId: 'customer_123',
        metadata: {
          endpoint: '/api/v1/products',
          method: 'GET',
          status_code: 200
        }
      });

      // Clean up when done
      await batch.cleanup();
      ```

      ```javascript Express.js Middleware theme={null}
      import express from 'express';
      import { Ingestion, createBatch } from '@dodopayments/ingestion-blueprints';

      const app = express();

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'live_mode',
        eventName: 'api_call'
      });

      const batch = createBatch(ingestion, {
        maxSize: 50,
        flushInterval: 10000
      });

      // Middleware to track all API calls
      app.use((req, res, next) => {
        const startTime = Date.now();
        
        res.on('finish', () => {
          const responseTime = Date.now() - startTime;
          
          batch.add({
            customerId: req.user?.id || 'anonymous',
            metadata: {
              endpoint: req.path,
              method: req.method,
              status_code: res.statusCode,
              response_time_ms: responseTime
            }
          });
        });
        
        next();
      });

      // Cleanup on shutdown
      process.on('SIGTERM', async () => {
        await batch.cleanup();
        process.exit(0);
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## Configuration

### Ingestion Configuration

<ParamField type="string">
  Your Dodo Payments API key from the dashboard.
</ParamField>

<ParamField type="string">
  Environment mode: `test_mode` or `live_mode`.
</ParamField>

<ParamField type="string">
  Event name that matches your meter configuration.
</ParamField>

### Track API Call Options

<ParamField type="string">
  The customer ID for billing attribution.
</ParamField>

<ParamField type="object">
  Optional metadata about the API call like endpoint, method, status code, response time, etc.
</ParamField>

### Batch Configuration

<ParamField type="number">
  Maximum number of events before auto-flush. Default: `100`.
</ParamField>

<ParamField type="number">
  Auto-flush interval in milliseconds. Default: `5000` (5 seconds).
</ParamField>

## Best Practices

<Tip>
  **Use Batching for High Volume**: For applications handling more than 10 requests per second, use `createBatch()` to reduce overhead and improve performance.
</Tip>

<Warning>
  **Always Clean Up Batches**: Call `batch.cleanup()` on application shutdown to flush pending events and prevent data loss.
</Warning>


# LLM Blueprint
Source: https://docs.dodopayments.com/developer-resources/ingestion-blueprints/llm

Effortlessly track LLM token usage for usage-based billing with automatic ingestion to Dodo Payments. Works with AI SDK, OpenAI, Anthropic, OpenRouter, Groq, and Google Gemini.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="#quick-start">
    Get started in 2 minutes with automatic token tracking.
  </Card>

  <Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
    Complete API documentation for ingesting usage events.
  </Card>

  <Card title="API Reference - Meters" icon="gauge" href="/api-reference/meters/create-meter">
    Learn how to create and configure meters for billing.
  </Card>

  <Card title="Usage-Based Billing Guide" icon="arrow-trend-up" href="/developer-resources/usage-based-billing-guide">
    Comprehensive guide to usage-based billing with meters.
  </Card>
</CardGroup>

<Info>
  Perfect for SaaS apps, AI chatbots, content generation tools, and any LLM-powered application that needs usage-based billing.
</Info>

## Quick Start

Get started with automatic LLM token tracking in just 2 minutes:

<Steps>
  <Step title="Install the SDK">
    Install the Dodo Payments Ingestion Blueprints:

    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    You'll need two API keys:

    * **Dodo Payments API Key**: Get it from [Dodo Payments Dashboard](https://app.dodopayments.com/developer/api-keys)
    * **LLM Provider API Key**: From AI SDK, OpenAI, Anthropic, Groq, etc.

    <Tip>
      Store your API keys securely in environment variables. Never commit them to version control.
    </Tip>
  </Step>

  <Step title="Create a Meter in Dodo Payments">
    Before tracking usage, create a meter in your Dodo Payments dashboard:

    1. **Login** to [Dodo Payments Dashboard](https://app.dodopayments.com/)
    2. **Navigate to** Products → Meters
    3. **Click** "Create Meter"
    4. **Configure your meter**:
       * **Meter Name**: Choose a descriptive name (e.g., "LLM Token Usage")
       * **Event Name**: Set a unique event identifier (e.g., `llm.chat_completion`)
       * **Aggregation Type**: Select `sum` to add up token counts
       * **Over Property**: Choose what to track:
         * `inputTokens` - Track input/prompt tokens
         * `outputTokens` - Track output/completion tokens (includes reasoning tokens when applicable)
         * `totalTokens` - Track combined input + output tokens

    <Info>
      The **Event Name** you set here must match exactly what you pass to the SDK (case-sensitive).
    </Info>

    For detailed instructions, see the [Usage-Based Billing Guide](/developer-resources/usage-based-billing-guide).
  </Step>

  <Step title="Track Token Usage">
    Wrap your LLM client and start tracking automatically:

    <CodeGroup>
      ```javascript AI SDK theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import { generateText } from 'ai';
      import { google } from '@ai-sdk/google';

      const llmTracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'aisdk.usage',
      });

      const client = llmTracker.wrap({
        client: { generateText },
        customerId: 'customer_123'
      });

      const response = await client.generateText({
        model: google('gemini-2.0-flash'),
        prompt: 'Hello!',
        maxOutputTokens: 500
      });

      console.log('Usage:', response.usage);
      ```

      ```javascript OpenRouter theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import OpenAI from 'openai';

      const openrouter = new OpenAI({
        baseURL: 'https://openrouter.ai/api/v1',
        apiKey: process.env.OPENROUTER_API_KEY
      });

      const llmTracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'openrouter.usage'
      });

      const client = llmTracker.wrap({
        client: openrouter,
        customerId: 'customer_123'
      });

      const response = await client.chat.completions.create({
        model: 'qwen/qwen3-max',
        messages: [{ role: 'user', content: 'Hello!' }],
        max_tokens: 500
      });

      console.log('Response:', response.choices[0].message.content);
      console.log('Usage:', response.usage);
      ```

      ```javascript OpenAI theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import OpenAI from 'openai';

      // 1. Create your LLM client (normal way)
      const openai = new OpenAI({ 
        apiKey: process.env.OPENAI_API_KEY 
      });

      // 2. Create tracker ONCE at startup
      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode', // Use 'live_mode' for production
        eventName: 'llm.chat_completion' // Match your meter's event name
      });

      // 3. Wrap & use - automatic tracking!
      const client = tracker.wrap({ 
        client: openai, 
        customerId: 'customer_123' 
      });

      // Every API call is now automatically tracked
      const response = await client.chat.completions.create({
        model: 'gpt-4',
        messages: [{ role: 'user', content: 'Hello!' }]
      });

      // ✨ Usage automatically sent to Dodo Payments!
      console.log('Tokens used:', response.usage);
      ```

      ```javascript Anthropic theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import Anthropic from '@anthropic-ai/sdk';

      const anthropic = new Anthropic({ 
        apiKey: process.env.ANTHROPIC_API_KEY 
      });

      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'anthropic.usage'
      });

      const client = tracker.wrap({ 
        client: anthropic, 
        customerId: 'customer_123' 
      });

      const response = await client.messages.create({
        model: 'claude-sonnet-4-0',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Hello Claude!' }]
      });

      console.log('Tokens used:', response.usage);
      ```

      ```javascript Groq theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import Groq from 'groq-sdk';

      const groq = new Groq({ 
        apiKey: process.env.GROQ_API_KEY 
      });

      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'groq.usage'
      });

      const client = tracker.wrap({ 
        client: groq, 
        customerId: 'customer_123' 
      });

      const response = await client.chat.completions.create({
        model: 'llama-3.1-8b-instant',
        messages: [{ role: 'user', content: 'Hello!' }]
      });

      console.log('Tokens:', response.usage);
      ```

      ```javascript Google Gemini theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import { GoogleGenAI } from '@google/genai';

      const googleGenai = new GoogleGenAI({
        apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY
      });

      const llmTracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'gemini.usage'
      });

      const client = llmTracker.wrap({
        client: googleGenai,
        customerId: 'customer_123'
      });

      const response = await client.models.generateContent({
        model: 'gemini-2.5-flash',
        contents: 'Why is the sky blue?'
      });

      console.log('Response:', response.text);
      console.log('Usage:', response.usageMetadata);
      ```
    </CodeGroup>

    <Check>
      That's it! Every API call now automatically tracks token usage and sends events to Dodo Payments for billing.
    </Check>
  </Step>
</Steps>

***

## Configuration

### Tracker Configuration

Create a tracker once at application startup with these required parameters:

<ParamField type="string">
  Your Dodo Payments API key. Get it from the [API Keys page](https://app.dodopayments.com/developer/api-keys).

  ```javascript theme={null}
  apiKey: process.env.DODO_PAYMENTS_API_KEY
  ```
</ParamField>

<ParamField type="string">
  The environment mode for the tracker.

  * `test_mode` - Use for development and testing
  * `live_mode` - Use for production

  ```javascript theme={null}
  environment: 'test_mode' // or 'live_mode'
  ```

  <Warning>
    Always use `test_mode` during development to avoid affecting production metrics.
  </Warning>
</ParamField>

<ParamField type="string">
  The event name that triggers your meter. Must match exactly what you configured in your Dodo Payments meter (case-sensitive).

  ```javascript theme={null}
  eventName: 'llm.chat_completion'
  ```

  <Info>
    This event name links your tracked usage to the correct meter for billing calculations.
  </Info>
</ParamField>

### Wrapper Configuration

When wrapping your LLM client, provide these parameters:

<ParamField type="object">
  Your LLM client instance (OpenAI, Anthropic, Groq, etc.).

  ```javascript theme={null}
  client: openai
  ```
</ParamField>

<ParamField type="string">
  The unique customer identifier for billing. This should match your customer ID in Dodo Payments.

  ```javascript theme={null}
  customerId: 'customer_123'
  ```

  <Tip>
    Use your application's user ID or customer ID to ensure accurate billing per customer.
  </Tip>
</ParamField>

<ParamField type="object">
  Optional additional data to attach to the tracking event. Useful for filtering and analysis.

  ```javascript theme={null}
  metadata: {
    feature: 'chat',
    userTier: 'premium',
    sessionId: 'session_123',
    modelVersion: 'gpt-4'
  }
  ```
</ParamField>

### Complete Configuration Example

<CodeGroup>
  ```javascript Full Configuration theme={null}
  import { createLLMTracker } from "@dodopayments/ingestion-blueprints";
  import { generateText } from "ai";
  import { google } from "@ai-sdk/google";
  import "dotenv/config";

  async function aiSdkExample() {
    console.log("🤖 AI SDK Simple Usage Example\n");

    try {
      // 1. Create tracker
      const llmTracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY!,
        environment: "test_mode",
        eventName: "your_meter_event_name",
      });

      // 2. Wrap the ai-sdk methods
      const client = llmTracker.wrap({
        client: { generateText },
        customerId: "customer_123",
        metadata: {
          provider: "ai-sdk",
        },
      });

      // 3. Use the wrapped function
      const response = await client.generateText({
        model: google("gemini-2.5-flash"),
        prompt: "Hello, I am a cool guy! Tell me a fun fact.",
        maxOutputTokens: 500,
      });

      console.log(response);
      console.log(response.usage);
      console.log("✅ Automatically tracked for customer\n");
    } catch (error) {
      console.error(error);
    }
  }

  aiSdkExample().catch(console.error);
  ```
</CodeGroup>

<Info>
  **Automatic Tracking:** The SDK automatically tracks token usage in the background without modifying the response. Your code remains clean and identical to using the original provider SDKs.
</Info>

***

## Supported Providers

The LLM Blueprint works seamlessly with all major LLM providers and aggregators:

<AccordionGroup>
  <Accordion title="AI SDK (Vercel)" icon="code">
    Track usage with the Vercel AI SDK for universal LLM support.

    <CodeGroup>
      ```javascript AI SDK Integration theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import { generateText } from 'ai';
      import { google } from '@ai-sdk/google';

      const llmTracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'aisdk.usage',
      });

      const client = llmTracker.wrap({
        client: { generateText },
        customerId: 'customer_123',
        metadata: {
          model: 'gemini-2.0-flash',
          feature: 'chat'
        }
      });

      const response = await client.generateText({
        model: google('gemini-2.0-flash'),
        prompt: 'Explain neural networks',
        maxOutputTokens: 500
      });

      console.log('Usage:', response.usage);
      ```
    </CodeGroup>

    **Tracked Metrics:**

    * `inputTokens` → `inputTokens`
    * `outputTokens` + `reasoningTokens` → `outputTokens`
    * `totalTokens` → `totalTokens`
    * Model name

    <Note>
      When using reasoning-capable models through AI SDK (like Google's Gemini 2.5 Flash with thinking mode), reasoning tokens are automatically included in the `outputTokens` count for accurate billing.
    </Note>
  </Accordion>

  <Accordion title="OpenRouter" icon="route">
    Track token usage across 200+ models via OpenRouter's unified API.

    <CodeGroup>
      ```javascript OpenRouter Integration theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import OpenAI from 'openai';

      // OpenRouter uses OpenAI-compatible API
      const openrouter = new OpenAI({
        baseURL: 'https://openrouter.ai/api/v1',
        apiKey: process.env.OPENROUTER_API_KEY
      });

      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'openrouter.usage'
      });

      const client = tracker.wrap({ 
        client: openrouter, 
        customerId: 'user_123',
        metadata: { provider: 'openrouter' }
      });

      const response = await client.chat.completions.create({
        model: 'qwen/qwen3-max',
        messages: [{ role: 'user', content: 'What is machine learning?' }],
        max_tokens: 500
      });

      console.log('Response:', response.choices[0].message.content);
      console.log('Usage:', response.usage);
      ```
    </CodeGroup>

    **Tracked Metrics:**

    * `prompt_tokens` → `inputTokens`
    * `completion_tokens` → `outputTokens`
    * `total_tokens` → `totalTokens`
    * Model name

    <Tip>
      OpenRouter provides access to models from OpenAI, Anthropic, Google, Meta, and many more providers through a single API.
    </Tip>
  </Accordion>

  <Accordion title="OpenAI" icon="robot">
    Track token usage from OpenAI's GPT models automatically.

    <CodeGroup>
      ```javascript OpenAI Integration theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import OpenAI from 'openai';

      const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'openai.usage'
      });

      const client = tracker.wrap({ 
        client: openai, 
        customerId: 'user_123' 
      });

      // All OpenAI methods work automatically
      const response = await client.chat.completions.create({
        model: 'gpt-4',
        messages: [{ role: 'user', content: 'Explain quantum computing' }]
      });

      console.log('Total tokens:', response.usage.total_tokens);
      ```
    </CodeGroup>

    **Tracked Metrics:**

    * `prompt_tokens` → `inputTokens`
    * `completion_tokens` → `outputTokens`
    * `total_tokens` → `totalTokens`
    * Model name
  </Accordion>

  <Accordion title="Anthropic Claude" icon="robot">
    Track token usage from Anthropic's Claude models.

    <CodeGroup>
      ```javascript Anthropic Integration theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import Anthropic from '@anthropic-ai/sdk';

      const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'anthropic.usage'
      });

      const client = tracker.wrap({ 
        client: anthropic, 
        customerId: 'user_123' 
      });

      const response = await client.messages.create({
        model: 'claude-sonnet-4-0',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Explain machine learning' }]
      });

      console.log('Input tokens:', response.usage.input_tokens);
      console.log('Output tokens:', response.usage.output_tokens);
      ```
    </CodeGroup>

    **Tracked Metrics:**

    * `input_tokens` → `inputTokens`
    * `output_tokens` → `outputTokens`
    * Calculated `totalTokens`
    * Model name
  </Accordion>

  <Accordion title="Groq" icon="gauge-high">
    Track ultra-fast LLM inference with Groq.

    <CodeGroup>
      ```javascript Groq Integration theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import Groq from 'groq-sdk';

      const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });

      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'groq.usage'
      });

      const client = tracker.wrap({ 
        client: groq, 
        customerId: 'user_123' 
      });

      const response = await client.chat.completions.create({
        model: 'llama-3.1-8b-instant',
        messages: [{ role: 'user', content: 'What is AI?' }]
      });

      console.log('Tokens:', response.usage);
      ```
    </CodeGroup>

    **Tracked Metrics:**

    * `prompt_tokens` → `inputTokens`
    * `completion_tokens` → `outputTokens`
    * `total_tokens` → `totalTokens`
    * Model name
  </Accordion>

  <Accordion title="Google Gemini" icon="sparkles">
    Track token usage from Google's Gemini models via the Google GenAI SDK.

    <CodeGroup>
      ```javascript Google Gemini Integration theme={null}
      import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
      import { GoogleGenAI } from '@google/genai';

      const googleGenai = new GoogleGenAI({ 
        apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY 
      });

      const tracker = createLLMTracker({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'gemini.usage'
      });

      const client = tracker.wrap({ 
        client: googleGenai, 
        customerId: 'user_123' 
      });

      const response = await client.models.generateContent({
        model: 'gemini-2.5-flash',
        contents: 'Explain quantum computing'
      });

      console.log('Response:', response.text);
      console.log('Usage:', response.usageMetadata);
      ```
    </CodeGroup>

    **Tracked Metrics:**

    * `promptTokenCount` → `inputTokens`
    * `candidatesTokenCount` + `thoughtsTokenCount` → `outputTokens`
    * `totalTokenCount` → `totalTokens`
    * Model version

    <Note>
      **Gemini Thinking Mode:** When using Gemini models with thinking/reasoning capabilities (like Gemini 2.5 Pro), the SDK automatically includes `thoughtsTokenCount` (reasoning tokens) in `outputTokens` to accurately reflect the full computational cost.
    </Note>
  </Accordion>
</AccordionGroup>

***

## Advanced Usage

### Multiple Providers

Track usage across different LLM providers with separate trackers:

<CodeGroup>
  ```javascript Multiple Provider Setup theme={null}
  import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
  import OpenAI from 'openai';
  import Groq from 'groq-sdk';
  import Anthropic from '@anthropic-ai/sdk';
  import { GoogleGenAI } from '@google/genai';

  // Create separate trackers for different providers
  const openaiTracker = createLLMTracker({
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'live_mode',
    eventName: 'openai.usage'
  });

  const groqTracker = createLLMTracker({
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'live_mode',
    eventName: 'groq.usage'
  });

  const anthropicTracker = createLLMTracker({
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'live_mode',
    eventName: 'anthropic.usage'
  });

  const geminiTracker = createLLMTracker({
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'live_mode',
    eventName: 'gemini.usage'
  });

  const openrouterTracker = createLLMTracker({
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'live_mode',
    eventName: 'openrouter.usage'
  });

  // Initialize clients
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });
  const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
  const googleGenai = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY });
  const openrouter = new OpenAI({ 
    baseURL: 'https://openrouter.ai/api/v1',
    apiKey: process.env.OPENROUTER_API_KEY 
  });

  // Wrap clients
  const trackedOpenAI = openaiTracker.wrap({ client: openai, customerId: 'user_123' });
  const trackedGroq = groqTracker.wrap({ client: groq, customerId: 'user_123' });
  const trackedAnthropic = anthropicTracker.wrap({ client: anthropic, customerId: 'user_123' });
  const trackedGemini = geminiTracker.wrap({ client: googleGenai, customerId: 'user_123' });
  const trackedOpenRouter = openrouterTracker.wrap({ client: openrouter, customerId: 'user_123' });

  // Use whichever provider you need
  const response = await trackedOpenAI.chat.completions.create({...});
  // or
  const geminiResponse = await trackedGemini.models.generateContent({...});
  // or
  const openrouterResponse = await trackedOpenRouter.chat.completions.create({...});
  ```
</CodeGroup>

<Tip>
  Use different event names for different providers to track usage separately in your meters.
</Tip>

### Express.js API Integration

Complete example of integrating LLM tracking into an Express.js API:

<CodeGroup>
  ```javascript Express.js Server theme={null}
  import express from 'express';
  import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
  import OpenAI from 'openai';

  const app = express();
  app.use(express.json());

  // Initialize OpenAI client
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

  // Create tracker once at startup
  const tracker = createLLMTracker({
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode',
    eventName: 'api.chat_completion'
  });

  // Chat endpoint with automatic tracking
  app.post('/api/chat', async (req, res) => {
    try {
      const { message, userId } = req.body;
      
      // Validate input
      if (!message || !userId) {
        return res.status(400).json({ error: 'Missing message or userId' });
      }
      
      // Wrap client for this specific user
      const trackedClient = tracker.wrap({
        client: openai,
        customerId: userId,
        metadata: { 
          endpoint: '/api/chat',
          timestamp: new Date().toISOString()
        }
      });
      
      // Make LLM request - automatically tracked
      const response = await trackedClient.chat.completions.create({
        model: 'gpt-4',
        messages: [{ role: 'user', content: message }],
        temperature: 0.7
      });
      
      const completion = response.choices[0].message.content;
      
      res.json({ 
        message: completion,
        usage: response.usage
      });
    } catch (error) {
      console.error('Chat error:', error);
      res.status(500).json({ error: 'Internal server error' });
    }
  });

  app.listen(3000, () => {
    console.log('Server running on port 3000');
  });
  ```
</CodeGroup>

***

## What Gets Tracked

Every LLM API call automatically sends a usage event to Dodo Payments with the following structure:

<CodeGroup>
  ```json Event Structure theme={null}
  {
    "event_id": "llm_1673123456_abc123",
    "customer_id": "customer_123",
    "event_name": "llm.chat_completion",
    "timestamp": "2024-01-08T10:30:00Z",
    "metadata": {
      "inputTokens": 10,
      "outputTokens": 25,
      "totalTokens": 35,
      "model": "gpt-4",
    }
  }
  ```
</CodeGroup>

### Event Fields

<ParamField type="string">
  Unique identifier for this specific event. Automatically generated by the SDK.

  Format: `llm_[timestamp]_[random]`
</ParamField>

<ParamField type="string">
  The customer ID you provided when wrapping the client. Used for billing.
</ParamField>

<ParamField type="string">
  The event name that triggers your meter. Matches your tracker configuration.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp when the event occurred.
</ParamField>

<ParamField type="object">
  Token usage and additional tracking data:

  * `inputTokens` - Number of input/prompt tokens used
  * `outputTokens` - Number of output/completion tokens used (includes reasoning tokens when applicable)
  * `totalTokens` - Total tokens (input + output)
  * `model` - The LLM model used (e.g., "gpt-4")
  * `provider` - The LLM provider (if included in wrapper metadata)
  * Any custom metadata you provided when wrapping the client

  <Note>
    **Reasoning Tokens:** For models with reasoning capabilities, `outputTokens` automatically includes both the completion tokens and reasoning tokens.
  </Note>
</ParamField>

<Info>
  Your Dodo Payments meter uses the `metadata` fields (especially `inputTokens`, `outputTokens` or `totalTokens`) to calculate usage and billing.
</Info>

***


# Object Storage Blueprint
Source: https://docs.dodopayments.com/developer-resources/ingestion-blueprints/object-storage

Track file uploads and storage usage for S3, Google Cloud Storage, Azure Blob, and other object storage services.

## Use Cases

Explore common scenarios supported by the Object Storage Blueprint:

<CardGroup>
  <Card title="File Hosting" icon="folder">
    Bill customers based on total storage usage and upload volume.
  </Card>

  <Card title="Backup Services" icon="shield">
    Track backup data uploads and charge per GB stored.
  </Card>

  <Card title="Media CDN" icon="photo-film">
    Monitor media uploads and bill for storage and bandwidth.
  </Card>

  <Card title="Document Management" icon="file">
    Track document uploads per customer for usage-based pricing.
  </Card>
</CardGroup>

<Info>
  Perfect for billing based on storage uploads, file hosting, CDN usage, or backup services.
</Info>

## Quick Start

Track object storage uploads with bytes consumed:

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    * **Dodo Payments API Key**: Get it from [Dodo Payments Dashboard](https://app.dodopayments.com/developer/api-keys)
    * **Storage Provider API Key**: From AWS S3, Google Cloud Storage, Azure, etc.
  </Step>

  <Step title="Create a Meter">
    Create a meter in your [Dodo Payments Dashboard](https://app.dodopayments.com/):

    * **Event Name**: `object_storage_upload` (or your preferred name)
    * **Aggregation Type**: `sum` to track total bytes uploaded
    * **Over Property**: `bytes` to bill based on storage size
  </Step>

  <Step title="Track Storage Usage">
    <CodeGroup>
      ```javascript AWS S3 Upload theme={null}
      import { Ingestion, trackObjectStorage } from '@dodopayments/ingestion-blueprints';
      import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
      import fs from 'fs';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'object_storage_upload'
      });

      const s3 = new S3Client({ region: 'us-east-1' });

      // Read the file (example: from disk or request)
      const fileBuffer = fs.readFileSync('./document.pdf');

      // Upload to S3
      const command = new PutObjectCommand({
        Bucket: 'my-bucket',
        Key: 'uploads/document.pdf',
        Body: fileBuffer
      });

      await s3.send(command);

      // Track the upload
      await trackObjectStorage(ingestion, {
        customerId: 'customer_123',
        bytes: fileBuffer.length
      });
      ```

      ```javascript Google Cloud Storage theme={null}
      import { Ingestion, trackObjectStorage } from '@dodopayments/ingestion-blueprints';
      import { Storage } from '@google-cloud/storage';
      import fs from 'fs';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'object_storage_upload'
      });

      const storage = new Storage();
      const bucket = storage.bucket('my-bucket');

      // Read the file
      const fileBuffer = fs.readFileSync('./image.png');

      // Upload to GCS
      await bucket.file('uploads/image.png').save(fileBuffer);

      // Track the upload
      await trackObjectStorage(ingestion, {
        customerId: 'customer_456',
        bytes: fileBuffer.length,
        metadata: {
          bucket: 'my-bucket',
          key: 'uploads/image.png'
        }
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## Configuration

### Ingestion Configuration

<ParamField type="string">
  Your Dodo Payments API key from the dashboard.
</ParamField>

<ParamField type="string">
  Environment mode: `test_mode` or `live_mode`.
</ParamField>

<ParamField type="string">
  Event name that matches your meter configuration.
</ParamField>

### Track Object Storage Options

<ParamField type="string">
  The customer ID for billing attribution.
</ParamField>

<ParamField type="number">
  Number of bytes uploaded. Required for byte-based billing.
</ParamField>

<ParamField type="object">
  Optional metadata about the upload like bucket name, content type, etc.
</ParamField>

## Best Practices

<Tip>
  **Track Before or After Upload**: You can track the event before or after the actual upload depending on your error handling strategy.
</Tip>

<Warning>
  **Handle Upload Failures**: Only track successful uploads to avoid billing for failed operations.
</Warning>


# Stream Blueprint
Source: https://docs.dodopayments.com/developer-resources/ingestion-blueprints/stream

Track streaming data consumption for video, audio, live streams, and real-time data transfer billing.

## Use Cases

Explore common scenarios supported by the Stream Blueprint:

<CardGroup>
  <Card title="Video Platforms" icon="video">
    Bill customers based on video bandwidth consumption and streaming quality.
  </Card>

  <Card title="Music Streaming" icon="music">
    Track audio streaming usage per user for subscription tiers.
  </Card>

  <Card title="Live Events" icon="signal-stream">
    Monitor live stream consumption and charge for bandwidth usage.
  </Card>

  <Card title="Real-Time Data" icon="wave-pulse">
    Track real-time data transfer for IoT and telemetry applications.
  </Card>
</CardGroup>

<Info>
  Perfect for video/audio streaming platforms, live streaming services, and real-time data applications.
</Info>

## Quick Start

Track streaming bytes consumed by your customers:

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    * **Dodo Payments API Key**: Get it from [Dodo Payments Dashboard](https://app.dodopayments.com/developer/api-keys)
  </Step>

  <Step title="Create a Meter">
    Create a meter in your [Dodo Payments Dashboard](https://app.dodopayments.com/):

    * **Event Name**: `stream_consumption` (or your preferred name)
    * **Aggregation Type**: `sum` to track total bytes streamed
    * **Over Property**: `bytes` to bill based on bandwidth usage
  </Step>

  <Step title="Track Stream Usage">
    <CodeGroup>
      ```javascript Video Streaming theme={null}
      import { Ingestion, trackStreamBytes } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'stream_consumption'
      });

      // Track video stream consumption
      await trackStreamBytes(ingestion, {
        customerId: 'customer_123',
        bytes: 10485760, // 10MB
        metadata: {
          stream_type: 'video',
        }
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## Configuration

### Ingestion Configuration

<ParamField type="string">
  Your Dodo Payments API key from the dashboard.
</ParamField>

<ParamField type="string">
  Environment mode: `test_mode` or `live_mode`.
</ParamField>

<ParamField type="string">
  Event name that matches your meter configuration.
</ParamField>

### Track Stream Bytes Options

<ParamField type="string">
  The customer ID for billing attribution.
</ParamField>

<ParamField type="number">
  Number of bytes consumed in the stream. Required for bandwidth-based billing.
</ParamField>

<ParamField type="object">
  Optional metadata about the stream like stream type, quality, sessionId, etc.
</ParamField>

## Best Practices

<Tip>
  **Track by Chunk**: For long streams, track consumption in chunks rather than waiting for the entire stream to complete.
</Tip>

<Warning>
  **Accurate Byte Counting**: Ensure byte counts include all overhead (headers, protocol overhead) if billing for total bandwidth.
</Warning>


# Time Range Blueprint
Source: https://docs.dodopayments.com/developer-resources/ingestion-blueprints/time-range

Track resource consumption based on elapsed time for compute, serverless functions, containers, and runtime billing.

## Use Cases

Explore common scenarios supported by the Time Range Blueprint:

<CardGroup>
  <Card title="Serverless Functions" icon="function">
    Bill based on function execution time and memory usage.
  </Card>

  <Card title="Container Runtime" icon="container-storage">
    Track container running time for usage-based billing.
  </Card>

  <Card title="Compute Instances" icon="server">
    Monitor VM runtime and charge by the minute or hour.
  </Card>

  <Card title="Background Jobs" icon="briefcase">
    Track processing time for data exports, reports, and batch jobs.
  </Card>
</CardGroup>

<Info>
  Perfect for billing based on compute time, function execution duration, container runtime, or any time-based usage.
</Info>

## Quick Start

Track resource usage by time duration:

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    * **Dodo Payments API Key**: Get it from [Dodo Payments Dashboard](https://app.dodopayments.com/developer/api-keys)
  </Step>

  <Step title="Create a Meter">
    Create a meter in your [Dodo Payments Dashboard](https://app.dodopayments.com/):

    * **Event Name**: `time_range_usage` (or your preferred name)
    * **Aggregation Type**: `sum` to track total duration
    * **Over Property**: `durationSeconds`, `durationMinutes`, or `durationMs`
  </Step>

  <Step title="Track Time Usage">
    <CodeGroup>
      ```javascript Serverless Functions theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'function_execution'
      });

      // Track function execution time
      const startTime = Date.now();

      // Execute your function (example: image processing)
      const result = await yourImageProcessingLogic();

      const durationMs = Date.now() - startTime;

      await trackTimeRange(ingestion, {
        customerId: 'customer_123',
        durationMs: durationMs
      });
      ```

      ```javascript Container Runtime theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'container_runtime'
      });

      // Track container runtime in seconds
      await trackTimeRange(ingestion, {
        customerId: 'customer_456',
        durationSeconds: 120
      });
      ```

      ```javascript VM Instance Runtime theme={null}
      import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'vm_runtime'
      });

      // Track VM runtime in minutes
      await trackTimeRange(ingestion, {
        customerId: 'customer_789',
        durationMinutes: 60
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## Configuration

### Ingestion Configuration

<ParamField type="string">
  Your Dodo Payments API key from the dashboard.
</ParamField>

<ParamField type="string">
  Environment mode: `test_mode` or `live_mode`.
</ParamField>

<ParamField type="string">
  Event name that matches your meter configuration.
</ParamField>

### Track Time Range Options

<ParamField type="string">
  The customer ID for billing attribution.
</ParamField>

<ParamField type="number">
  Duration in milliseconds. Use for sub-second precision.
</ParamField>

<ParamField type="number">
  Duration in seconds. Most common for function execution and short tasks.
</ParamField>

<ParamField type="number">
  Duration in minutes. Useful for longer-running resources like VMs.
</ParamField>

<ParamField type="object">
  Optional metadata about the resource like CPU, memory, region, etc.
</ParamField>

## Best Practices

<Tip>
  **Choose the Right Unit**: Use milliseconds for short operations, seconds for functions, and minutes for longer-running resources.
</Tip>

<Warning>
  **Accurate Timing**: Use `Date.now()` or `performance.now()` for accurate time tracking, especially for serverless functions.
</Warning>


# Mobile Integration Guide
Source: https://docs.dodopayments.com/developer-resources/mobile-integration

Unified guide for integrating Dodo Payments into Android, iOS, React Native and Flutter mobile applications.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="#integration-workflow">
    Get your mobile payment integration running in 4 simple steps
  </Card>

  <Card title="Platform Examples" icon="code" href="#choose-your-sdk">
    Complete code examples for Android, iOS, React Native, and Flutter
  </Card>
</CardGroup>

<Info>
  Dodo Payments ships an official checkout SDK for **Android, iOS, React Native,
  and Flutter**. Each one wraps the pattern documented below (open the checkout
  URL, capture the return, parse the result) behind a single typed `start(...)`
  call, with abandoned-session recovery built in. Reach for a manual WebView only
  if none of them fits your stack.
</Info>

## Prerequisites

Before integrating Dodo Payments into your mobile app, ensure you have:

* **Dodo Payments Account**: Active merchant account with API access
* **API Credentials**: API key and webhook secret key from your dashboard
* **Mobile App Project**: Android, iOS, React Native, or Flutter application
* **Backend Server**: To securely handle checkout session creation

## Integration Workflow

The mobile integration follows a secure 4-step process where your backend handles API calls and your mobile app manages the user experience.

<Steps>
  <Step title="Backend: Create Checkout Session">
    <Card title="Checkout Session API Docs" icon="book" href="/developer-resources/checkout-session">
      Learn how to create a checkout session in your backend using Node.js, Python, and more. See complete examples and parameter references in the dedicated <strong>Checkout Sessions API</strong> documentation.
    </Card>

    <Note>
      **Security**: Checkout sessions must be created on your backend server, never in the mobile app. This protects your API keys and ensures proper validation.
    </Note>
  </Step>

  <Step title="Mobile: Get Checkout URL">
    Your mobile app calls your backend to get the checkout URL. Authenticate
    this request with the signed-in user's own session token.

    <Tabs>
      <Tab title="iOS (Swift)">
        ```swift theme={null}
        func getCheckoutURL(productId: String, customerEmail: String, customerName: String) async throws -> String {
            let url = URL(string: "https://your-backend.com/api/create-checkout-session")!
            var request = URLRequest(url: url)
            request.httpMethod = "POST"
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
            request.setValue("Bearer \(userSessionToken)", forHTTPHeaderField: "Authorization")
            
            let requestData: [String: Any] = [
                "productId": productId,
                "customerEmail": customerEmail,
                "customerName": customerName
            ]
            request.httpBody = try JSONSerialization.data(withJSONObject: requestData)
            
            let (data, _) = try await URLSession.shared.data(for: request)
            let response = try JSONDecoder().decode(CheckoutResponse.self, from: data)
            return response.checkout_url
        }
        ```
      </Tab>

      <Tab title="Android (Kotlin)">
        ```kotlin theme={null}
        suspend fun getCheckoutURL(productId: String, customerEmail: String, customerName: String): String {
            val client = OkHttpClient()
            val requestBody = JSONObject().apply {
                put("productId", productId)
                put("customerEmail", customerEmail)
                put("customerName", customerName)
            }.toString().toRequestBody("application/json".toMediaType())
            
            val request = Request.Builder()
                .url("https://your-backend.com/api/create-checkout-session")
                .header("Authorization", "Bearer $userSessionToken")
                .post(requestBody)
                .build()
            
            val response = client.newCall(request).execute()
            val responseBody = response.body?.string()
            val jsonResponse = JSONObject(responseBody ?: "")
            return jsonResponse.getString("checkout_url")
        }
        ```
      </Tab>

      <Tab title="React Native (JavaScript)">
        ```javascript theme={null}
        const getCheckoutURL = async (productId, customerEmail, customerName) => {
          try {
            const response = await fetch('https://your-backend.com/api/create-checkout-session', {
              method: 'POST',
              headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${userSessionToken}`,
              },
              body: JSON.stringify({
                productId,
                customerEmail,
                customerName
              })
            });
            
            const data = await response.json();
            return data.checkout_url;
          } catch (error) {
            console.error('Failed to get checkout URL:', error);
            throw error;
          }
        };
        ```
      </Tab>

      <Tab title="Flutter (Dart)">
        ```dart theme={null}
        import 'dart:convert';
        import 'package:http/http.dart' as http;

        Future<String> getCheckoutUrl({
          required String productId,
          required String customerEmail,
          required String customerName,
        }) async {
          final response = await http.post(
            Uri.parse('https://your-backend.com/api/create-checkout-session'),
            headers: {
              'Content-Type': 'application/json',
              'Authorization': 'Bearer $userSessionToken',
            },
            body: jsonEncode({
              'productId': productId,
              'customerEmail': customerEmail,
              'customerName': customerName,
            }),
          );

          if (response.statusCode != 200) {
            throw Exception('Failed to get checkout URL: ${response.statusCode}');
          }
          return jsonDecode(response.body)['checkout_url'] as String;
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      **Security**: Mobile apps only communicate with your backend, never directly with Dodo Payments API.
    </Note>
  </Step>

  <Step title="Mobile: Open Checkout in Browser">
    Open the checkout URL in a secure in-app browser for payment processing.
    Or skip the manual setup entirely with the official checkout SDK for your
    platform.

    <Card title="Pick your mobile SDK" icon="box" href="#choose-your-sdk">
      Install steps and setup instructions for Android, iOS, React Native, and Flutter.
    </Card>
  </Step>

  <Step title="Backend: Handle Payment Completion">
    Process payment completion via webhooks and redirect URLs to confirm payment status.
  </Step>
</Steps>

## Choose Your SDK

Every mobile SDK exposes the same contract: one `start(...)` call opens Dodo's
hosted checkout in the platform's native browser surface and returns a typed
`CheckoutResult` whose `status` is `succeeded`, `failed`, `cancelled`,
`pending`, or `expired`. None of them holds an API key or calls the Dodo
Payments API, and all four support abandoned-session recovery.

<CardGroup>
  <Card title="Android" icon="android" href="/developer-resources/sdks/android">
    `com.dodopayments.api:checkout-android` opens a Chrome Custom Tab. Requires `minSdk` 23.
  </Card>

  <Card title="iOS" icon="apple" href="/developer-resources/sdks/ios">
    `dodopayments-mobile-sdk-ios` opens `SFSafariViewController`. Requires iOS 16+.
  </Card>

  <Card title="React Native" icon="react" href="/developer-resources/sdks/react-native">
    `@dodopayments/react-native-checkout`, a Turbo Module over both native cores. Requires React Native 0.76+.
  </Card>

  <Card title="Flutter" icon="layer-group" href="/developer-resources/sdks/flutter">
    `dodopayments_checkout`, a Pigeon channel over both native cores. Requires Flutter 3.44+.
  </Card>
</CardGroup>

<Warning>
  The `status` you get back is a UI hint, not proof of payment. Confirm every
  payment from your backend via the `payment.succeeded` / `subscription.active`
  webhook, or by retrieving the payment with your secret key.
</Warning>

### Registering a Callback URL Scheme

All four SDKs hand control back to your app through a custom URL scheme that
you choose, for example `myapp://checkout/return`. Register it once per
platform:

<Tabs>
  <Tab title="Android">
    ```kotlin android/app/build.gradle theme={null}
    android {
        defaultConfig {
            manifestPlaceholders["dodoCallbackScheme"] = "myapp"
        }
    }
    ```

    The SDK's own manifest already declares the redirect activity, so there is no
    manifest XML to add.
  </Tab>

  <Tab title="iOS">
    ```xml Info.plist theme={null}
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLName</key>
        <string>myapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>myapp</string>
        </array>
      </dict>
    </array>
    ```

    On iOS you must also forward incoming URLs into the SDK, because
    `SFSafariViewController` cannot catch its own return URL. See the
    [iOS](/developer-resources/sdks/ios) or
    [React Native](/developer-resources/sdks/react-native) page for the exact
    handler.
  </Tab>

  <Tab title="Expo">
    `@dodopayments/react-native-checkout` ships a config plugin that registers the
    scheme for both platforms at `prebuild`. Pass it a `scheme` option:

    ```json app.json theme={null}
    {
      "expo": {
        "scheme": "myapp",
        "plugins": [
          [
            "@dodopayments/react-native-checkout",
            { "scheme": "myappcheckout" }
          ]
        ]
      }
    }
    ```

    `scheme` must match `returnUrl` and must differ from `expo.scheme`, which Expo
    already registers on `MainActivity`. See the
    [React Native SDK](/developer-resources/sdks/react-native) page for details.

    If `android/app/build.gradle` is hand-maintained without a standard
    `defaultConfig { }` block, set the placeholder manually instead (see the
    Android tab).

    Works with development builds only, not Expo Go. Run
    `npx expo prebuild --clean` after editing `app.json`.
  </Tab>
</Tabs>

<Note>
  Prefer to build it yourself? Open the `checkout_url` in a WebView and intercept
  the navigation to your `return_url`, then read the `status` and `payment_id`
  query parameters. The SDKs above do this for you in the platform's real browser
  surface, which is why Apple Pay and Google Pay keep working.
</Note>

## Appearance Customization

Every SDK accepts an optional `customization` parameter on `start(...)` /
`CheckoutParams` that controls the native browser surface's appearance and
behavior — the toolbar, buttons, and presentation. This is separate from the
checkout page's own theme, which you configure server-side via
[`customization.theme_config`](/developer-resources/checkout-session) on the
checkout session.

Options are grouped by platform because Android's Custom Tab and iOS's
`SFSafariViewController` expose different native controls. All fields are
optional; omitting `customization` entirely uses each platform's default
appearance.

<AccordionGroup>
  <Accordion title="Android — Custom Tab">
    <ParamField type="Color">
      Toolbar background color.
    </ParamField>

    <ParamField type="Color">
      Navigation bar color.
    </ParamField>

    <ParamField type="Color">
      Divider color above the navigation bar.
    </ParamField>

    <ParamField type="'default' | 'back'">
      `default` shows the system "X" icon; `back` draws a back arrow instead.
    </ParamField>

    <ParamField type="'start' | 'end'">
      Which side of the toolbar the close button appears on.
    </ParamField>

    <ParamField type="boolean">
      Shows the toolbar's share icon.
    </ParamField>

    <ParamField type="boolean">
      Shows the page title under the URL in the toolbar.
    </ParamField>

    <ParamField type="boolean">
      Lets the toolbar auto-hide as the page scrolls.
    </ParamField>

    <ParamField type="boolean">
      Shows "Bookmark this page" in the overflow menu.
    </ParamField>

    <ParamField type="boolean">
      Shows "Download page" in the overflow menu.
    </ParamField>

    <ParamField type="'system' | 'light' | 'dark'">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>

  <Accordion title="iOS — SFSafariViewController">
    <ParamField type="'done' | 'close' | 'cancel'">
      Label or icon for the dismiss button.
    </ParamField>

    <ParamField type="'pageSheet' | 'fullScreen'">
      `pageSheet` presents as a card with swipe-to-dismiss; `fullScreen` covers the whole screen.
    </ParamField>

    <ParamField type="boolean">
      Lets the toolbar collapse on scroll. Only visible when `presentationStyle` is `fullScreen` — `pageSheet` keeps the bars pinned regardless of this setting.
    </ParamField>

    <ParamField type="'system' | 'light' | 'dark'">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>
</AccordionGroup>

<Tabs>
  <Tab title="React Native">
    ```typescript theme={null}
    const result = await DodoCheckout.start({
      checkoutUrl,
      returnUrl: 'myapp://checkout/return',
      customization: {
        android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
        ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
      },
    });
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    final result = await DodoCheckout.instance.start(
      CheckoutParams(
        checkoutUrl: Uri.parse(checkoutUrl),
        returnUrl: Uri.parse('myapp://checkout/return'),
        customization: BrowserCustomization(
          android: AndroidBrowserOptions(
            toolbarColor: Color(0xFF6366F1),
            closeButtonStyle: CloseButtonStyle.back,
          ),
          ios: IosBrowserOptions(
            presentationStyle: PresentationStyle.fullScreen,
            colorScheme: BrowserColorScheme.dark,
          ),
        ),
      ),
    );
    ```
  </Tab>

  <Tab title="Android (Kotlin)">
    ```kotlin theme={null}
    val result = DodoCheckout.start(
        activity,
        CheckoutParams(
            checkoutUrl = checkoutUrl,
            returnUrl = "myapp://checkout/return",
            customization = BrowserCustomization(
                toolbarColor = Color.parseColor("#6366F1"),
                closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
            )
        )
    ) { event -> }
    ```
  </Tab>

  <Tab title="iOS (Swift)">
    ```swift theme={null}
    let result = try await DodoCheckout.start(
        checkoutUrl: checkoutUrl,
        returnUrl: URL(string: "myapp://checkout/return")!,
        customization: BrowserCustomization(
            presentationStyle: .fullScreen,
            colorScheme: .dark
        )
    )
    ```
  </Tab>
</Tabs>

## Best Practices

* **Security**: Never ship an API key in your app. Create checkout sessions on your backend and pass only the resulting `checkout_url` to the client.
* **Authority**: Treat `CheckoutResult.status` as a UI hint. Grant access only after your backend confirms the payment.
* **User Experience**: Show a loading state while your backend creates the session, and handle `cancelled` as a normal outcome rather than an error.
* **Testing**: Use test mode and test cards, and verify the return-URL round trip on a real device as well as a simulator.

## Troubleshooting

### Common Issues

* **Callback never arrives**: The scheme in `returnUrl` must match the one you registered. On Android that is the `dodoCallbackScheme` manifest placeholder; on iOS and React Native it is the `Info.plist` URL type.
* **Checkout returns to the browser instead of your app (iOS)**: You haven't forwarded the incoming URL. Call `DodoCheckout.handleOpenURL(url)` from `.onOpenURL`, `scene(_:openURLContexts:)`, or a React Native `Linking` listener.
* **`PLATFORM_ERROR` on Android**: Most often a scheme mismatch. It can also appear if your `MainActivity` sets `android:taskAffinity=""` (the stock `flutter create` default), which lets some OEM builds lose the in-flight checkout.
* **`ALREADY_IN_PROGRESS`**: A checkout is still open. Await or dismiss the previous one before starting another.
* **Build fails with an unresolved placeholder**: You added the Android SDK but never set `manifestPlaceholders["dodoCallbackScheme"]`.
* **Payment succeeded but access wasn't granted**: Expected if you're keying off the mobile result. Grant access from the `payment.succeeded` / `subscription.active` webhook instead.

## Additional Resources

* [Payment Integration Guide](/developer-resources/integration-guide)
* [Webhook Documentation](/developer-resources/webhooks/intents/webhook-events-guide)
* [Testing Process](/miscellaneous/testing-process)
* [Technical FAQs](/miscellaneous/faq)

<Check>
  For questions or support, contact <a href="mailto:support@dodopayments.com">[support@dodopayments.com](mailto:support@dodopayments.com)</a>.
</Check>


# Next.js Adaptor
Source: https://docs.dodopayments.com/developer-resources/nextjs-adaptor

Learn how to integrate Dodo Payments with your Next.js App Router project using our NextJS Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout with static, dynamic, and session flows.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/nextjs
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
    DODO_PAYMENTS_ENVIRONMENT="test_mode"or"live_mode"
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using the Next.js App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Next.js app. Supports static (GET), dynamic (POST), and checkout session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript Next.js Route Handler expandable theme={null}
      // app/checkout/route.ts
      import { Checkout } from "@dodopayments/nextjs";

      export const GET = Checkout({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        type: "static", // optional, defaults to 'static'
      });

      export const POST = Checkout({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        type: "dynamic", // for dynamic checkout
      });

      export const POST = Checkout({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        type: "session", // for checkout sessions
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Next.js Route Handler expandable theme={null}
      // app/customer-portal/route.ts
      import { CustomerPortal } from "@dodopayments/nextjs";

      export const GET = CustomerPortal({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Next.js app.
    </Info>

    <CodeGroup>
      ```typescript Next.js Route Handler expandable theme={null}
      // app/api/webhook/dodo-payments/route.ts
      import { Webhooks } from "@dodopayments/nextjs";

      export const POST = Webhooks({
        webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
        onPayload: async (payload) => {
          // handle the payload
        },
        // ... other event handlers for granular control
      });
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Next.js application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```

You are an expert Next.js developer assistant. Your task is to guide a user through integrating the @dodopayments/nextjs adapter into their existing Next.js project.

The @dodopayments/nextjs adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for the Next.js App Router.

First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):

npm install @dodopayments/nextjs

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/nextjs adapter would you like to integrate into your project? You can choose one or more of the following:

    Checkout Route Handler (for handling product checkouts)

    Customer Portal Route Handler (for managing customer subscriptions/details)

    Webhook Route Handler (for receiving Dodo Payments webhook events)

    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Route Handler is selected:

Purpose: This handler manages different types of checkout flows. All checkout types (static, dynamic, and sessions) return JSON responses with checkout URLs for programmatic handling.
File Creation: Create a new file at app/checkout/route.ts in your Next.js project.

Code Snippet:

// app/checkout/route.ts
import { Checkout } from '@dodopayments/nextjs'

export const GET = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
type: "static",
});

export const POST = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
type: "session", // or "dynamic" for dynamic link
});

Configuration & Usage:

    bearerToken: Your Dodo Payments API key. It's recommended to set this via the DODO_PAYMENTS_API_KEY environment variable.

    returnUrl: (Optional) The URL to redirect the user to after a successful checkout.

    environment: (Optional) Set to "test_mode" for testing, or omit/set to "live_mode" for production.

    type: (Optional) Set to "static" for GET/static checkout, "dynamic" for POST/dynamic checkout, or "session" for POST/checkout sessions.

Static Checkout (GET) Query Parameters:

    productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)

    quantity (optional): Quantity of the product

    Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode

    Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode

    Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts

    Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)

    Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}

Dynamic Checkout (POST) - Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}. For a complete list of supported POST body fields, refer to:

    Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments

    Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions


Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

Error Handling: If productId is missing or other parameters are invalid, the handler will return a 400 response.

If Customer Portal Route Handler is selected:

Purpose: This handler redirects authenticated users to their Dodo Payments customer portal.
File Creation: Create a new file at app/customer-portal/route.ts in your Next.js project.

Code Snippet:

// app/customer-portal/route.ts
import { CustomerPortal } from '@dodopayments/nextjs'

export const GET = CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
environment: "test_mode",
});

Query Parameters:

    customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)

    send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.

    Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at app/api/webhook/dodo-payments/route.ts in your Next.js project.

Code Snippet:

// app/api/webhook/dodo-payments/route.ts
import { Webhooks } from '@dodopayments/nextjs'

export const POST = Webhooks({
webhookKey: process.env.DODO_WEBHOOK_SECRET!,
onPayload: async (payload) => {
// handle the payload
},
// ... other event handlers for granular control
});

Handler Details:

    Method: Only POST requests are supported. Other methods return 405.

    Signature Verification: The handler verifies the webhook signature using the webhookKey and returns 401 if verification fails.

    Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:

    401: Invalid signature

    400: Invalid payload

    500: Internal error during verification

Event Routing: Calls the appropriate event handler based on the payload type.

Supported Webhook Event Handlers:

    onPayload?: (payload: WebhookPayload) => Promise<void>

    onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>

    onPaymentFailed?: (payload: WebhookPayload) => Promise<void>

    onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>

    onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>

    onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>

    onRefundFailed?: (payload: WebhookPayload) => Promise<void>

    onDisputeOpened?: (payload: WebhookPayload) => Promise<void>

    onDisputeExpired?: (payload: WebhookPayload) => Promise<void>

    onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>

    onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>

    onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>

    onDisputeWon?: (payload: WebhookPayload) => Promise<void>

    onDisputeLost?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>


    onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>

    onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>

    onDunningStarted?: (payload: WebhookPayload) => Promise<void>

    onDunningRecovered?: (payload: WebhookPayload) => Promise<void>

    onCreditAdded?: (payload: WebhookPayload) => Promise<void>

    onCreditDeducted?: (payload: WebhookPayload) => Promise<void>

    onCreditExpired?: (payload: WebhookPayload) => Promise<void>

    onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>

    onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>

    onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>

    onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>

    onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

    Environment Variable Setup:

To ensure the adapter functions correctly, you will need to manually set up the following environment variables in your Next.js project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):

    DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).

    RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

    DODO_WEBHOOK_SECRET: Your Dodo Payments Webhook Secret (required for Webhook handler).

Example .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Usage in your code:

bearerToken: process.env.DODO_PAYMENTS_API_KEY!
webhookKey: process.env.DODO_WEBHOOK_SECRET!

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance. You can also add comments to their PR or chat depending on the context

```


# Nuxt Adaptor
Source: https://docs.dodopayments.com/developer-resources/nuxt-adaptor

Integrate Dodo Payments with your Nuxt project using the official Nuxt module. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout API Route" icon="cart-shopping" href="#checkout-api-route">
    Integrate Dodo Payments checkout into your Nuxt app using a server route.
  </Card>

  <Card title="Customer Portal API Route" icon="user" href="#customer-portal-api-route">
    Allow customers to manage subscriptions and details via a Nuxt server route.
  </Card>

  <Card title="Webhooks API Route" icon="bell" href="#webhook-api-route">
    Receive and process Dodo Payments webhook events securely in Nuxt.
  </Card>
</CardGroup>

## Overview

<Info>
  This guide explains how to integrate Dodo Payments into your Nuxt application using the official Nuxt module. You'll learn how to set up checkout, customer portal, and webhook API routes, and how to securely manage environment variables.
</Info>

## Installation

<Steps>
  <Step title="Install the Nuxt module">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/nuxt
    ```
  </Step>

  <Step title="Register the module in nuxt.config.ts">
    Add <code>@dodopayments/nuxt</code> to your <code>modules</code> array and configure it:

    ```typescript nuxt.config.ts expandable theme={null}
    export default defineNuxtConfig({
      modules: ["@dodopayments/nuxt"],
      devtools: { enabled: true },
      compatibilityDate: "2025-02-25",
      runtimeConfig: {
        private: {
          bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
          webhookKey: process.env.NUXT_PRIVATE_WEBHOOK_KEY,
          environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
          returnUrl: process.env.NUXT_PRIVATE_RETURNURL
        },
      }
    });
    ```
  </Step>
</Steps>

<Warning>
  Never commit your <code>.env</code> file or secrets to version control.
</Warning>

## API Route Handler Examples

<Info>
  All Dodo Payments integrations in Nuxt are handled via server routes in the <code>server/routes/api/</code> directory.
</Info>

<Tabs>
  <Tab title="Checkout API Route">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Nuxt app. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript server/routes/api/checkout.get.ts expandable theme={null}

      export default defineEventHandler((event) => {
        const {
          private: { bearerToken, environment, returnUrl },
        } = useRuntimeConfig();

        const handler = checkoutHandler({
          bearerToken: bearerToken,
          environment: environment,
          returnUrl: returnUrl,
        });

        return handler(event);
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```typescript server/routes/api/checkout.post.ts expandable theme={null}

      export default defineEventHandler((event) => {
        const {
          private: { bearerToken, environment, returnUrl },
        } = useRuntimeConfig();

        const handler = checkoutHandler({
          bearerToken: bearerToken,
          environment: environment,
          returnUrl: returnUrl,
          type: "dynamic"
        });

        return handler(event);
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```typescript server/routes/api/checkout.post.ts (Checkout Sessions) expandable theme={null}

      export default defineEventHandler((event) => {
        const {
          private: { bearerToken, environment, returnUrl },
        } = useRuntimeConfig();

        const handler = checkoutHandler({
          bearerToken: bearerToken,
          environment: environment,
          returnUrl: returnUrl,
          type: "session"
        });

        return handler(event);
      });
      ```
    </CodeGroup>

    <Warning>
      If <code>productId</code> is missing or invalid, the handler returns a 400 response.
    </Warning>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal API Route">
    <Info>
      Create a GET route to allow customers to access their portal. Accepts <code>customer\_id</code> as a query parameter.
    </Info>

    <CodeGroup>
      ```typescript server/routes/api/customer-portal.get.ts expandable theme={null}

      export default defineEventHandler((event) => {
        const {
          private: { bearerToken, environment },
        } = useRuntimeConfig();

        const handler = customerPortalHandler({
          bearerToken,
          environment: environment,
        });

        return handler(event);
      });
      ```
    </CodeGroup>

    **Query Parameters:**

    * <code>customer\_id</code> (required): The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>)
    * <code>send\_email</code> (optional, boolean): If <code>true</code>, sends an email to the customer with the portal link.

    <Warning>
      Returns 400 if <code>customer\_id</code> is missing.
    </Warning>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook API Route">
    <Info>
      Create a POST route to securely receive and process webhook events from Dodo Payments.
    </Info>

    <CodeGroup>
      ```typescript server/routes/api/webhook.post.ts expandable theme={null}

      export default defineEventHandler((event) => {
        const {
          private: { webhookKey },
        } = useRuntimeConfig();

        const handler = Webhooks({
          webhookKey: webhookKey,
          onPayload: async (payload: any) => {
            // Handle webhook payload here
          },
          // ...add other event handlers as needed
        });

        return handler(event);
      });
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Nuxt application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```
You are an expert Nuxt developer assistant. Your task is to guide a user through integrating the @dodopayments/nuxt module into their existing Nuxt project.

The @dodopayments/nuxt module provides API route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Nuxt 3 server routes.

First, install the necessary package:

npm install @dodopayments/nuxt

Second, add the configuration to nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@dodopayments/nuxt"],
  devtools: { enabled: true },
  compatibilityDate: "2025-02-25",
  runtimeConfig: {
    private: {
      bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
      webhookKey: process.env.NUXT_PRIVATE_BEARER_TOKEN,
      environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
      returnUrl: process.env.NUXT_PRIVATE_RETURNURL
    },
  }
});


Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/nuxt module would you like to integrate into your project? You can choose one or more of the following:

    Checkout API Route (for handling product checkouts)
    Customer Portal API Route (for managing customer subscriptions/details)
    Webhook API Route (for receiving Dodo Payments webhook events)
    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout API Route is selected:

Purpose: This route redirects users to the Dodo Payments checkout page.
File Creation: Create a new file at server/routes/api/checkout.get.ts in your Nuxt project.

Code Snippet:

// server/routes/api/checkout.get.ts

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment, returnUrl },
  } = useRuntimeConfig();

  const handler = checkoutHandler({
    bearerToken: bearerToken,
    environment: environment,
    returnUrl: returnUrl,
  });

  return handler(event);
});

Configuration & Usage:
- bearerToken: Your Dodo Payments API key. Set via the NUXT_PRIVATE_BEARER_TOKEN environment variable.
- returnUrl: (Optional) The URL to redirect the user to after a successful checkout.
- environment: (Optional) Set to your environment (e.g., "test_mode" or "live_mode").

Static Checkout (GET) Query Parameters:
- productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)
- quantity (optional): Quantity of the product
- Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode
- Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode
- Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts
- Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)

Dynamic Checkout (POST): Parameters are sent as a JSON body. Supports both one-time and recurring payments. For a complete list of supported POST body fields, refer to:
- Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments
- Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

Error Handling: If productId is missing or other query parameters are invalid, the handler will return a 400 response.

If Customer Portal API Route is selected:

Purpose: This route allows customers to access their Dodo Payments customer portal.
File Creation: Create a new file at server/routes/api/customer-portal.get.ts in your Nuxt project.

Code Snippet:

// server/routes/api/customer-portal.get.ts

export default defineEventHandler((event) => {
  const {
    private: { bearerToken, environment },
  } = useRuntimeConfig();

  const handler = customerPortalHandler({
    bearerToken,
    environment: environment,
  });

  return handler(event);
});

Query Parameters:
- customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)
- send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.
- Returns 400 if customer_id is missing.

If Webhook API Route is selected:

Purpose: This route processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at server/routes/api/webhook.post.ts in your Nuxt project.

Code Snippet:

// server/routes/api/webhook.post.ts

export default defineEventHandler((event) => {
  const {
    private: { webhookKey },
  } = useRuntimeConfig();

  const handler = Webhooks({
    webhookKey: webhookKey,
    onPayload: async (payload) => {
      // handle the payload
    },
    // ... other event handlers for granular control
  });

  return handler(event);
});

Handler Details:
- Method: Only POST requests are supported. Other methods return 405.
- Signature Verification: The handler verifies the webhook signature using webhookKey and returns 401 if verification fails.
- Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:
- 401: Invalid signature
- 400: Invalid payload
- 500: Internal error during verification

Event Routing: Calls the appropriate event handler based on the payload type. Supported event handlers include:
- onPayload?: (payload: WebhookPayload) => Promise<void>
- onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>
- onPaymentFailed?: (payload: WebhookPayload) => Promise<void>
- onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>
- onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>
- onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>
- onRefundFailed?: (payload: WebhookPayload) => Promise<void>
- onDisputeOpened?: (payload: WebhookPayload) => Promise<void>
- onDisputeExpired?: (payload: WebhookPayload) => Promise<void>
- onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>
- onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>
- onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>
- onDisputeWon?: (payload: WebhookPayload) => Promise<void>
- onDisputeLost?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>
- onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>
- onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>
- onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>
- onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>
- onDunningStarted?: (payload: WebhookPayload) => Promise<void>
- onDunningRecovered?: (payload: WebhookPayload) => Promise<void>
- onCreditAdded?: (payload: WebhookPayload) => Promise<void>
- onCreditDeducted?: (payload: WebhookPayload) => Promise<void>
- onCreditExpired?: (payload: WebhookPayload) => Promise<void>
- onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>
- onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>
- onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>
- onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>
- onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

Environment Variable Setup:
To ensure the module functions correctly, set up the following environment variables in your Nuxt project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):
- NUXT_PRIVATE_BEARER_TOKEN: Your Dodo Payments API Key (required for Checkout and Customer Portal).
- NUXT_PRIVATE_WEBHOOK_KEY: Your Dodo Payments Webhook Secret (required for Webhook handler).
- NUXT_PRIVATE_ENVIRONMENT: (Optional) Set to your environment (e.g., "test_mode" or "live_mode").
- NUXT_PRIVATE_RETURNURL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

Usage in your code:
bearerToken: useRuntimeConfig().private.bearerToken
webhookKey: useRuntimeConfig().private.webhookKey

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance.
```


# On-Demand Subscriptions
Source: https://docs.dodopayments.com/developer-resources/ondemand-subscriptions

Integrate on-demand subscriptions by authorizing mandates, creating variable charges, handling webhooks, and implementing safe retry policies.

## Overview

On-demand subscriptions let you authorize a customer's payment method once and then charge variable amounts whenever you need, instead of on a fixed schedule. This feature is available for all accounts—no approval required.

Use this guide to:

* Create an on-demand subscription (authorize a mandate with optional initial price)
* Trigger subsequent charges with custom amounts
* Track outcomes using webhooks

For a general subscription setup, see the [Subscription Integration Guide](/developer-resources/subscription-integration-guide).

## Prerequisites

* Dodo Payments merchant account and API key
* Webhook secret configured and an endpoint to receive events
* A subscription product in your catalog

<Tip>
  This guide creates the on-demand subscription through a checkout session (`POST /checkouts`), which always returns a hosted `checkout_url`. Redirect the customer there to approve the mandate, and set `return_url` to where they should land afterward.
</Tip>

## How on-demand works

1. You create a subscription with the `on_demand` object to authorize a payment method and optionally collect an initial charge.
2. Later, you create charges against that subscription with custom amounts using the dedicated charge endpoint.
3. You listen to webhooks (e.g., `payment.succeeded`, `payment.failed`) to update your system.

## Create an on-demand subscription

Endpoint: [POST /checkouts](/api-reference/checkout-sessions/create)

Key request fields (body):\
Please find them in [Create Checkout Session](/api-reference/checkout-sessions/create)

### Create an on-demand subscription

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: 'test_mode', // defaults to 'live_mode'
    });

    async function main() {
      const subscription = await client.checkoutSessions.create({
        product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
        billing_address:  { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
        customer: { customer_id: 'cus_123' },
        return_url: 'https://example.com/billing/success',
        subscription_data: {
            on_demand: {
                mandate_only: true // set false to collect an initial charge
                // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
                // product_currency: 'USD',
                // product_description: 'Custom initial charge',
                // adaptive_currency_fees_inclusive: false,
            }
        }
      });

      console.log(subscription.checkout_url);
    }

    main().catch(console.error);
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from dodopayments import DodoPayments

    client = DodoPayments(
        bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'),
        environment="test_mode",  # defaults to "live_mode"
    )

    checkout = client.checkout_sessions.create(
        product_cart=[
            {"product_id": "pdt_123", "quantity": 1}
        ],
        billing_address={
            "city": "SF",
            "country": "US",
            "state": "CA",
            "street": "1 Market St",
            "zipcode": "94105",
        },
        customer={
            "customer_id": "cus_123",
        },
        return_url="https://example.com/billing/success",
        subscription_data={
          "on_demand":{
          "mandate_only": True,  # set False to collect an initial charge
          # "product_price": 1000,  # optional: charge $10.00 now if mandate_only is false
          # "product_currency": "USD",
          # "product_description": "Custom initial charge",
          # "adaptive_currency_fees_inclusive": False,
          }
        },
    )

    print(checkout.checkout_url)
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    package main

    import (
        "context"
        "fmt"
        "os"

        "github.com/dodopayments/dodopayments-go"
        "github.com/dodopayments/dodopayments-go/option"
    )

    func main() {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
            option.WithEnvironmentTestMode(), // defaults to live mode
        )

        checkout, err := client.CheckoutSessions.New(context.TODO(), dodopayments.CheckoutSessionNewParams{
            CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
                ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{
                    {
                        ProductID: dodopayments.F("pdt_123"),
                        Quantity:  dodopayments.F(int64(1)),
                    },
                }),
                BillingAddress: dodopayments.F(dodopayments.CheckoutSessionBillingAddressParam{
                    City:    dodopayments.F("SF"),
                    Country: dodopayments.F(dodopayments.CountryCodeUs),
                    State:   dodopayments.F("CA"),
                    Street:  dodopayments.F("1 Market St"),
                    Zipcode: dodopayments.F("94105"),
                }),
                Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
                    dodopayments.AttachExistingCustomerParam{
                        CustomerID: dodopayments.F("cus_123"),
                    },
                ),
                ReturnURL: dodopayments.F("https://example.com/billing/success"),
                SubscriptionData: dodopayments.F(dodopayments.SubscriptionDataParam{
                    OnDemand: dodopayments.F(dodopayments.OnDemandSubscriptionParam{
                        MandateOnly: dodopayments.F(true), // set false to collect an initial charge
                        // ProductPrice:    dodopayments.F(int64(1000)), // optional: charge $10.00 now if mandate_only is false
                        // ProductCurrency: dodopayments.F(dodopayments.CurrencyUsd),
                        // ProductDescription: dodopayments.F("Custom initial charge"),
                    }),
                }),
            },
        })
        if err != nil {
            panic(err)
        }

        fmt.Println(checkout.CheckoutURL)
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "$DODO_API/checkouts" \
      -H "Authorization: Bearer $DODO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "product_cart": [
          {
            "product_id": "pdt_123",
            "quantity": 1
          }
        ],
        "customer": {
          "customer_id": "cus_123"
        },
        "billing_address": {
          "street": "1 Market St",
          "city": "SF",
          "state": "CA",
          "country": "US",
          "zipcode": "94105"
        },
        "subscription_data": {
          "on_demand": {
            "mandate_only": true
          }
        },
        "return_url": "https://example.com/billing/success"
      }'
    ```
  </Tab>
</Tabs>

```json Success theme={null}
{
  "session_id": "cks_123",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks123"
}
```

## Charge an on-demand subscription

After the mandate is authorized, create charges as needed.

Endpoint: [POST /subscriptions/\{subscription\_id}/charge](/api-reference/subscriptions/create-charge)

Key request fields (body):

<AccordionGroup>
  <Accordion title="Charge request body parameters">
    <ParamField type="integer">
      Amount to charge (in the smallest currency unit). Example: to charge \$25.00, pass <code>2500</code>.
    </ParamField>

    <ParamField type="string">
      Optional currency override for the charge.
    </ParamField>

    <ParamField type="string">
      Optional description override for this charge.
    </ParamField>

    <ParamField type="boolean">
      If true, includes adaptive currency fees within <code>product\_price</code>. If false, fees are added on top.
    </ParamField>

    <ParamField type="object">
      Specify how the customer's wallet balance is used to settle this charge.
    </ParamField>

    <ParamField type="object">
      Additional metadata for the payment. If omitted, the subscription metadata is used.
    </ParamField>
  </Accordion>
</AccordionGroup>

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

    async function chargeNow(subscriptionId) {
      const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
      console.log(res.payment_id);
    }

    chargeNow('sub_123').catch(console.error);
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from dodopayments import DodoPayments

    client = DodoPayments(bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'))

    response = client.subscriptions.charge(
        subscription_id="sub_123",
        product_price=2500,
    )

    print(response.payment_id)
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    package main

    import (
      "context"
      "fmt"
      "github.com/dodopayments/dodopayments-go"
      "github.com/dodopayments/dodopayments-go/option"
    )

    func main() {
      client := dodopayments.NewClient(option.WithBearerToken("YOUR_API_KEY"))
      res, err := client.Subscriptions.Charge(context.TODO(), "sub_123", dodopayments.SubscriptionChargeParams{
        ProductPrice: dodopayments.F(int64(2500)),
      })
      if err != nil { panic(err) }
      fmt.Println(res.PaymentID)
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "$DODO_API/subscriptions/sub_123/charge" \
      -H "Authorization: Bearer $DODO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "product_price": 2500,
        "product_description": "Extra usage for March"
      }'
    ```
  </Tab>
</Tabs>

```json Success theme={null}
{ "payment_id": "pay_abc123" }
```

<Warning>
  Charging a subscription that is not on-demand may fail. Ensure the subscription has `on_demand: true` in its details before charging.
</Warning>

## Handling failed charges

When a charge against an on-demand subscription fails, you decide what happens next. Unlike scheduled subscriptions — where a failed renewal stops further automatic billing — **on-demand subscriptions remain chargeable after a failure**. You can call the charge endpoint again as part of your own retry logic.

### What happens on failure

<Steps>
  <Step title="Charge attempt fails">
    The `POST /subscriptions/{subscription_id}/charge` request either returns an error response or completes asynchronously and emits a `payment.failed` webhook with the decline reason.
  </Step>

  <Step title="Subscription may transition to on_hold">
    The subscription may move to the `on_hold` state and emit a `subscription.on_hold` webhook (see [Subscription States → On Hold](/features/subscription#on-hold-state)). This is a signal — not a lock. For on-demand subscriptions, `on_hold` does **not** prevent you from charging again.
  </Step>

  <Step title="Retry the charge (your call)">
    For on-demand flows, Dodo does **not** auto-retry. You can call `POST /subscriptions/{subscription_id}/charge` again at any time to retry. Apply the [safe retry policy](#payment-retries) below — use exponential backoff, skip hard declines, and avoid burst patterns — so retries are not flagged by our fraud and risk systems.
  </Step>

  <Step title="Optionally, ask the customer for a new payment method">
    If retries keep failing because the payment method itself is broken (expired card, closed account, etc.), use [`POST /subscriptions/{subscription_id}/update-payment-method`](/api-reference/subscriptions/update-payment-method) to collect a new one from the customer. On success, the subscription returns to `active` and `payment.succeeded` followed by `subscription.active` webhooks are emitted.
  </Step>
</Steps>

<Info>
  **On-demand vs scheduled**: For scheduled subscriptions, Dodo runs its own renewal retries and dunning. For on-demand subscriptions, you own the retry policy because only you know when the next charge should occur (it's driven by your usage events, not a calendar).
</Info>

### Webhook sequence on a failed on-demand charge

| Order | Event                  | Meaning                                                                              |
| ----- | ---------------------- | ------------------------------------------------------------------------------------ |
| 1     | `payment.failed`       | The on-demand charge attempt did not succeed (includes the decline reason)           |
| 2     | `subscription.on_hold` | The subscription was placed on hold (informational; does not block further charges)  |
| 3\*   | `payment.succeeded`    | A subsequent charge — either your retry or after a payment method update — succeeded |
| 4\*   | `subscription.active`  | The subscription returned to `active` after a successful charge                      |

<Info>
  Events 3 and 4 only fire after a follow-up charge succeeds.
</Info>

### Retry responsibility

<Warning>
  Dodo Payments **does not auto-retry failed on-demand charges**. You own the retry policy. Follow the safe retry guidelines below to avoid being flagged by our fraud detection systems as card testing.
</Warning>

[Subscription Dunning](/features/recovery/subscription-dunning) — the built-in email recovery sequence — is scoped to failed *renewal* payments on scheduled subscriptions and customer-initiated cancellations. It is not designed for on-demand charge failures. Communicate with the customer directly (e.g., transactional email or in-app prompt) when you decide the payment method needs to be updated.

## Payment retries

Our fraud detection system may block aggressive retry patterns (and can flag them as potential card testing). Follow a safe retry policy.

<Warning>
  Burst retry patterns can be flagged as fraudulent or suspected card testing by our risk systems and processors. Avoid clustered retries; follow the backoff schedule and time alignment guidance below.
</Warning>

### Principles for safe retry policies

* **Backoff mechanism**: Use exponential backoff between retries.
* **Retry limits**: Cap total retries (3–4 attempts max).
* **Intelligent filtering**: Retry only on retryable failures (e.g., network/issuer errors, insufficient funds); never retry hard declines.
* **Card testing prevention**: Do not retry failures like `DO_NOT_HONOR`, `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `FRAUDULENT`, `AUTHENTICATION_FAILURE`.
* **Vary metadata (optional)**: If you maintain your own retry system, differentiate retries via metadata (e.g., `retry_attempt`).

### Suggested retry schedule (subscriptions)

* **1st attempt**: Immediate when you create the charge
* **2nd attempt**: After 3 days
* **3rd attempt**: After 7 more days (10 days total)
* **4th attempt (final)**: After another 7 days (17 days total)

Final step: if still unpaid, mark the subscription as unpaid or cancel it, based on your policy. Notify the customer during the window to update their payment method.

### Avoid burst retries; align to authorization time

* Anchor retries to the original authorization timestamp to avoid "burst" behavior across your portfolio.
* Example: If the customer starts a trial or mandate at 1:10 pm today, schedule follow-up retries at 1:10 pm on subsequent days per your backoff (e.g., +3 days → 1:10 pm, +7 days → 1:10 pm).
* Alternatively, if you store the last successful payment time `T`, schedule the next attempt at `T + X days` to preserve time-of-day alignment.

<Note>
  Time-zone and DST: use a consistent time standard for scheduling and convert for display only to maintain intervals.
</Note>

### Decline codes you should not retry

* `STOLEN_CARD`
* `DO_NOT_HONOR`
* `FRAUDULENT`
* `PICKUP_CARD`
* `AUTHENTICATION_FAILURE`
* `LOST_CARD`

<Note>
  For a comprehensive list of decline reasons and whether they are user-correctable, see the
  [Transaction Failures](/api-reference/transaction-failures) documentation.
</Note>

<Tip>
  Only retry on soft/temporary issues (e.g., `insufficient_funds`, `issuer_unavailable`, `processing_error`, network timeouts). If the same decline repeats, pause further retries.
</Tip>

### Implementation guidelines (no code)

* Use a scheduler/queue that persists precise timestamps; compute next attempt at the exact time-of-day offset (e.g., `T + 3 days` at the same HH:MM).
* Maintain and reference the last successful payment timestamp `T` to compute the next attempt; do not bunch multiple subscriptions at the same instant.
* Always evaluate the last decline reason; stop retries for hard declines in the skip list above.
* Cap concurrent retries per customer and per account to prevent accidental surges.
* Communicate proactively: email/SMS the customer to update their payment method before the next scheduled attempt.
* Use metadata only for observability (e.g., `retry_attempt`); never try to "evade" fraud/risk systems by rotating inconsequential fields.

## Cancellation

On-demand subscriptions follow a different cancellation flow from scheduled subscriptions because there is no fixed billing cycle to anchor an immediate end date.

### Customer portal behavior

When a customer cancels an on-demand subscription from the [Customer Portal](/features/customer-portal), the cancellation is **scheduled for the next billing date** by default. The **Cancel Now** option is intentionally not shown for on-demand subscriptions.

The reason: on-demand subscriptions do not have predictable recurring renewal dates — the next charge time is driven entirely by your usage events. Scheduling cancellation at the next billing date keeps the mandate active until the period boundary so any in-flight usage can still be charged, then ends the subscription cleanly.

After the customer confirms cancellation:

* The subscription stays `active` and remains chargeable via `POST /subscriptions/{id}/charge` until the scheduled cancellation date.
* `cancel_at_next_billing_date` is set to `true` on the subscription.
* A `subscription.cancelled` webhook is emitted when the cancellation takes effect.

<Info>
  If you need to end the subscription immediately (for example, in response to a refund or a support request), cancel it programmatically via the API instead of relying on the customer portal flow.
</Info>

### Cancel programmatically

You can cancel an on-demand subscription via the API at any time. You control whether the cancellation is immediate or scheduled.

Endpoint: [PATCH /subscriptions/\{subscription\_id}](/api-reference/subscriptions/patch-subscriptions)

<Tabs>
  <Tab title="Cancel immediately">
    Set the subscription `status` to `cancelled` to end it right away. The mandate is revoked and no further charges can be created.

    ```javascript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

    await client.subscriptions.update('sub_123', {
      status: 'cancelled',
    });
    ```

    ```bash cURL theme={null}
    curl -X PATCH "$DODO_API/subscriptions/sub_123" \
      -H "Authorization: Bearer $DODO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "status": "cancelled" }'
    ```
  </Tab>

  <Tab title="Cancel at next billing date">
    Mirror the customer portal behavior — keep the subscription active until the scheduled cancellation date, then end it.

    ```javascript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

    await client.subscriptions.update('sub_123', {
      cancel_at_next_billing_date: true,
    });
    ```

    ```bash cURL theme={null}
    curl -X PATCH "$DODO_API/subscriptions/sub_123" \
      -H "Authorization: Bearer $DODO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "cancel_at_next_billing_date": true }'
    ```
  </Tab>
</Tabs>

### Webhooks on cancellation

| Event                       | When it fires                                                                    |
| --------------------------- | -------------------------------------------------------------------------------- |
| `subscription.cancelled`    | Subscription is fully cancelled and no longer chargeable                         |
| `subscription.plan_changed` | `cancel_at_next_billing_date` was toggled (scheduled cancellation set or undone) |

<Tip>
  To distinguish on-demand cancellations from scheduled-subscription cancellations in your handler, check the subscription's `on_demand` flag when processing the webhook.
</Tip>

## Track outcomes with webhooks

Implement webhook handling to track the customer journey. See [Implementing Webhooks](/developer-resources/integration-guide#implementing-webhooks).

* **subscription.active**: Mandate authorized and subscription activated
* **subscription.failed**: Creation failed (e.g., mandate failure)
* **subscription.on\_hold**: Subscription placed on hold (e.g., unpaid state)
* **subscription.cancelled**: Subscription fully cancelled (see [Cancellation](#cancellation))
* **payment.succeeded**: Charge succeeded
* **payment.failed**: Charge failed

<Tip>
  For on-demand flows, focus on `payment.succeeded` and `payment.failed` to reconcile usage-based charges. When `payment.failed` is followed by `subscription.on_hold`, see [Handling failed charges](#handling-failed-charges) to recover the subscription.
</Tip>

## Testing and next steps

<Steps>
  <Step title="Create in test mode">
    Use your test API key to create the subscription, then open the returned `checkout_url` and complete the mandate.
  </Step>

  <Step title="Trigger a charge">
    Call the charge endpoint with a small `product_price` (e.g., `100`) and verify you receive `payment.succeeded`.
  </Step>

  <Step title="Go live">
    Switch to your live API key once you have validated events and internal state updates.
  </Step>
</Steps>

## Troubleshooting

* **422 Invalid Request**: Ensure `on_demand.mandate_only` is provided on creation and `product_price` is provided for charges.
* **Currency errors**: If you override `product_currency`, confirm it's supported for your account and customer.
* **No webhooks received**: Verify your webhook URL and signature secret configuration.


# Android
Source: https://docs.dodopayments.com/developer-resources/sdks/android

Open Dodo Payments' hosted checkout from an Android app in a Chrome Custom Tab and get a typed result back in one call.

<Info>
  This is the official Android checkout SDK (`com.dodopayments.api:checkout-android`),
  for opening Dodo's hosted checkout. It is distinct from the
  [backend Kotlin SDK](/developer-resources/sdks/kotlin), which calls the Dodo
  Payments API from your server.
</Info>

<CardGroup>
  <Card title="Checkout Sessions API" icon="cart-shopping" href="/developer-resources/checkout-session">
    Create the `checkout_url` that this SDK opens
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    Best practices for mobile checkout flows
  </Card>
</CardGroup>

The Android SDK opens Dodo's hosted checkout in a Chrome Custom Tab using `androidx.browser.customtabs`. It contains zero networking code and holds no API key. You pass a `checkoutUrl` from your backend's checkout session, and the SDK returns a typed `CheckoutResult` when the user completes or abandons the flow.

**Requirements:** `minSdk` 23, Kotlin, Java 17.

## Installation

<Steps>
  <Step title="Add the Dependency">
    ```kotlin build.gradle.kts theme={null}
    dependencies {
        implementation("com.dodopayments.api:checkout-android:1.0.0")
    }
    ```
  </Step>

  <Step title="Register a Callback URL Scheme">
    Set your callback scheme as a Gradle manifest placeholder. The library's own
    manifest already declares the redirect activity's intent filter using the
    `${dodoCallbackScheme}` token, so this one property is the entire setup cost —
    you add no manifest XML:

    ```kotlin build.gradle.kts theme={null}
    android {
        defaultConfig {
            manifestPlaceholders["dodoCallbackScheme"] = "myapp"
        }
    }
    ```

    The value must match the scheme in `CheckoutParams.returnUrl` (e.g.
    `myapp://checkout/return`).

    <Note>
      If you omit the placeholder entirely, the build fails immediately with an
      unresolved-placeholder error rather than failing silently at checkout time. If
      you set it but it doesn't match `returnUrl`'s scheme, `DodoCheckout.start`
      throws `PLATFORM_ERROR` before presenting anything.
    </Note>
  </Step>
</Steps>

## Usage

The SDK supports two invocation styles.

<Tabs>
  <Tab title="Launcher (Recommended)">
    Register the contract with `registerForActivityResult`, then launch it:

    ```kotlin theme={null}
    import com.dodopayments.checkout.CheckoutParams
    import com.dodopayments.checkout.CheckoutStatus
    import com.dodopayments.checkout.DodoCheckout

    private val checkoutLauncher =
        registerForActivityResult(DodoCheckout.contract()) { result ->
            when (result.status) {
                CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
                CheckoutStatus.FAILED -> showFailure()
                CheckoutStatus.CANCELLED -> dismiss()
                CheckoutStatus.PENDING -> showPending()
                CheckoutStatus.EXPIRED -> showExpired()
            }
        }

    checkoutLauncher.launch(
        CheckoutParams(
            checkoutUrl = checkoutUrl, // from your backend's checkout session
            returnUrl = "myapp://checkout/return"
        )
    )
    ```

    <Tip>
      Prefer this style. The result is delivered through Android's OS-managed
      `ActivityResultRegistry`, so it survives process death.
    </Tip>
  </Tab>

  <Tab title="Suspend Function">
    Call `DodoCheckout.start` from a coroutine scope:

    ```kotlin theme={null}
    import com.dodopayments.checkout.CheckoutParams
    import com.dodopayments.checkout.CheckoutStatus
    import com.dodopayments.checkout.DodoCheckout

    lifecycleScope.launch {
        val result = DodoCheckout.start(
            activity = this@MyActivity,
            params = CheckoutParams(
                checkoutUrl = checkoutUrl, // from your backend's checkout session
                returnUrl = "myapp://checkout/return"
            ),
            onEvent = { event -> println(event.name) } // logging only
        )

        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> dismiss()
            CheckoutStatus.PENDING -> showPending()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }
    ```

    <Warning>
      This style resolves an in-memory `CompletableDeferred`, so it does **not**
      survive process death. `onEvent` is available only here, not on the contract.
    </Warning>
  </Tab>
</Tabs>

## What the Result Means

<Warning>
  The `status` field is a UI hint, not proof of payment. Always verify the payment on your backend using webhooks or the Get Payment Detail endpoint before granting access.
</Warning>

<ParamField type="CheckoutStatus">
  One of `SUCCEEDED`, `FAILED`, `CANCELLED`, `PENDING`, `EXPIRED`.
</ParamField>

<ParamField type="String?">
  Set when the return URL included one. Display it in the UI, don't use it to
  grant access. See Verify the Payment below.
</ParamField>

<ParamField type="String?">
  Set for subscription checkouts.
</ParamField>

<ParamField type="List<String>?">
  Set when the checkout includes license key products.
</ParamField>

<ParamField type="String?">
  Set when the checkout captures an email.
</ParamField>

<ParamField type="Map<String, String>">
  Every query parameter from the return URL, verbatim.
</ParamField>

## Verify the Payment

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Listen for payment events in real time
  </Card>

  <Card title="Get Payment Detail" icon="magnifying-glass" href="/api-reference/payments/get-payments-1">
    Query the payment status on demand
  </Card>
</CardGroup>

Grant access to the user only after one of these confirms the payment. Do not rely on the `CheckoutResult.status` alone.

## Appearance Customization

Customize the Custom Tab's toolbar, buttons, and color scheme via
`customization` on `CheckoutParams`. All fields are optional; omitting
`customization` uses Android's default Custom Tab appearance.

<ParamField type="Int?">
  Toolbar background color, as an ARGB `Color` int.
</ParamField>

<ParamField type="Int?">
  Navigation bar color.
</ParamField>

<ParamField type="Int?">
  Divider color above the navigation bar.
</ParamField>

<ParamField type="CloseButtonStyle">
  `DEFAULT` shows the system "X" icon; `BACK` draws a back arrow instead.
</ParamField>

<ParamField type="CloseButtonPosition">
  Which side of the toolbar the close button appears on: `START` or `END`.
</ParamField>

<ParamField type="Boolean">
  Shows the toolbar's share icon.
</ParamField>

<ParamField type="Boolean">
  Shows the page title under the URL in the toolbar.
</ParamField>

<ParamField type="Boolean">
  Lets the toolbar auto-hide as the page scrolls.
</ParamField>

<ParamField type="Boolean">
  Shows "Bookmark this page" in the overflow menu.
</ParamField>

<ParamField type="Boolean">
  Shows "Download page" in the overflow menu.
</ParamField>

<ParamField type="ColorScheme">
  Forces light or dark appearance regardless of the device's system setting: `SYSTEM`, `LIGHT`, or `DARK`.
</ParamField>

```kotlin theme={null}
import com.dodopayments.checkout.BrowserCustomization

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
            colorScheme = BrowserCustomization.ColorScheme.DARK,
        )
    )
)
```

## Errors

`DodoCheckout.start` throws `CheckoutError` only for misuse or a platform
failure. Read the code from `CheckoutError.code`:

* `INVALID_CHECKOUT_URL`: not a `checkout.dodopayments.com` session URL.
* `INVALID_RETURN_URL`: not a valid absolute URL.
* `ALREADY_IN_PROGRESS`: a checkout is already running.
* `PLATFORM_ERROR`: unexpected platform failure, including a `returnUrl` whose
  scheme doesn't match your `dodoCallbackScheme` placeholder.

A user cancelling or a declined payment is always a result (`CANCELLED` or
`FAILED`), never a thrown error. With the launcher style, validation errors
throw out of `launcher.launch(...)`.

## Abandoned Sessions

If the app is killed or the user force-stops it during checkout, the SDK stores the session locally. On the next app launch, check for an abandoned session and reconcile it with your backend:

```kotlin theme={null}
DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession(context)
}
```

The `abandoned.createdAt` is an epoch timestamp in milliseconds.

## Related

<CardGroup>
  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    Best practices for mobile checkout flows
  </Card>

  <Card title="Kotlin SDK" icon="code" href="/developer-resources/sdks/kotlin">
    Backend SDK for server-side operations
  </Card>
</CardGroup>


# C#
Source: https://docs.dodopayments.com/developer-resources/sdks/csharp

Integrate Dodo Payments into your .NET applications with modern async/await support

The C# SDK provides convenient access to the Dodo Payments REST API from applications written in C#. It features an async Task-based API with strong typing, automatic retries, and comprehensive error handling.

## Installation

Install the package from [NuGet](https://www.nuget.org/packages/DodoPayments.Client):

```bash theme={null}
dotnet add package DodoPayments.Client
```

<Info>
  The SDK requires .NET 8.0 or later. It works with ASP.NET Core, Console applications, and other .NET project types.
</Info>

## Quick Start

Initialize the client and create a checkout session:

```csharp theme={null}
using System;
using DodoPayments.Client;
using DodoPayments.Client.Models.CheckoutSessions;

// Configured using the DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_BASE_URL environment variables
DodoPaymentsClient client = new();

CheckoutSessionCreateParams parameters = new()
{
    ProductCart =
    [
        new()
        {
            ProductID = "product_id",
            Quantity = 1,
        },
    ],
};

var checkoutSessionResponse = await client.CheckoutSessions.Create(parameters);

Console.WriteLine(checkoutSessionResponse.SessionId);
```

<Warning>
  Always store your API keys securely using environment variables, user secrets, or Azure Key Vault. Never hardcode them in your source code or commit them to version control.
</Warning>

## Core Features

<CardGroup>
  <Card title="Async/Await" icon="bolt">
    Full async Task-based API for non-blocking operations
  </Card>

  <Card title="Strong Typing" icon="shield-check">
    Comprehensive type safety with nullable reference types
  </Card>

  <Card title="Smart Retries" icon="repeat">
    Automatic retries with exponential backoff for transient errors
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    Built-in exception hierarchy for precise error management
  </Card>
</CardGroup>

## Configuration

### Environment Variables

```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```

```csharp theme={null}
// Automatically reads from environment variables
DodoPaymentsClient client = new();
```

| Property      | Environment variable        | Required | Default value                     |
| ------------- | --------------------------- | -------- | --------------------------------- |
| `BearerToken` | `DODO_PAYMENTS_API_KEY`     | true     | -                                 |
| `WebhookKey`  | `DODO_PAYMENTS_WEBHOOK_KEY` | false    | -                                 |
| `BaseUrl`     | `DODO_PAYMENTS_BASE_URL`    | true     | `"https://live.dodopayments.com"` |

### Manual Configuration

```csharp theme={null}
DodoPaymentsClient client = new() { BearerToken = "My Bearer Token" };
```

### Environments

Switch between live and test mode:

```csharp theme={null}
using DodoPayments.Client.Core;

DodoPaymentsClient client = new() { BaseUrl = EnvironmentUrl.TestMode };
```

### Retries

The SDK automatically retries 2 times by default with exponential backoff. It retries on connection errors and status codes 408, 409, 429, and 5xx.

```csharp theme={null}
// Custom retry count
DodoPaymentsClient client = new() { MaxRetries = 3 };
```

### Timeouts

Requests time out after 1 minute by default.

```csharp theme={null}
DodoPaymentsClient client = new() { Timeout = TimeSpan.FromSeconds(30) };
```

### Per-Request Overrides

Temporarily modify configuration for a single request using `WithOptions`:

```csharp theme={null}
var response = await client
    .WithOptions(options => options with
    {
        Timeout = TimeSpan.FromSeconds(10),
        MaxRetries = 5,
    })
    .CheckoutSessions.Create(parameters);
```

## Common Operations

### Create a Checkout Session

```csharp theme={null}
var parameters = new CheckoutSessionCreateParams
{
    ProductCart =
    [
        new()
        {
            ProductID = "pdt_123",
            Quantity = 1
        }
    ],
    ReturnUrl = "https://yourdomain.com/return"
};

var session = await client.CheckoutSessions.Create(parameters);
Console.WriteLine($"Checkout URL: {session.CheckoutUrl}");
```

### Manage Customers

```csharp theme={null}
// Create a customer
var customer = await client.Customers.Create(new CustomerCreateParams
{
    Email = "customer@example.com",
    Name = "John Doe"
});

// Retrieve customer
var retrieved = await client.Customers.Retrieve(new CustomerRetrieveParams { CustomerID = "cus_123" });
Console.WriteLine($"Customer: {retrieved.Name} ({retrieved.Email})");
```

### Handle Subscriptions

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```csharp theme={null}
using DodoPayments.Client.Models.Payments;
using DodoPayments.Client.Models.Subscriptions;

// Create a subscription
var subscription = await client.Subscriptions.Create(new SubscriptionCreateParams
{
    Billing = new BillingAddress
    {
        Country = "US",
        City = "San Francisco",
        State = "CA",
        Street = "1 Market St",
        Zipcode = "94105",
    },
    Customer = new AttachExistingCustomer { CustomerID = "cus_123" },
    ProductID = "pdt_456",
    Quantity = 1,
});

// Charge an on-demand subscription
// ProductPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
var charge = await client.Subscriptions.Charge(new SubscriptionChargeParams
{
    SubscriptionID = subscription.SubscriptionId,
    ProductPrice = 2500,
});
```

<Info>
  `Billing` requires at minimum the two-letter ISO `Country` code. Use `AttachExistingCustomer` to attach an existing customer, or `NewCustomer` to create one. `ProductPrice` is in the lowest currency denomination.
</Info>

## Error Handling

The SDK throws specific exceptions based on the HTTP status code. All 4xx errors inherit from `DodoPayments4xxException`.

| Status | Exception                                   |
| ------ | ------------------------------------------- |
| 400    | `DodoPaymentsBadRequestException`           |
| 401    | `DodoPaymentsUnauthorizedException`         |
| 403    | `DodoPaymentsForbiddenException`            |
| 404    | `DodoPaymentsNotFoundException`             |
| 422    | `DodoPaymentsUnprocessableEntityException`  |
| 429    | `DodoPaymentsRateLimitException`            |
| 5xx    | `DodoPayments5xxException`                  |
| others | `DodoPaymentsUnexpectedStatusCodeException` |

Other exception types:

* `DodoPaymentsIOException`: I/O networking errors
* `DodoPaymentsInvalidDataException`: Failure to interpret parsed data
* `DodoPaymentsException`: Base class for all exceptions

## Pagination

### Auto-Pagination

Iterate through all results across all pages using the `Paginate` method, which returns an `IAsyncEnumerable`:

```csharp theme={null}
var page = await client.Payments.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

### Manual Pagination

```csharp theme={null}
var page = await client.Payments.List();
while (true)
{
    foreach (var item in page.Items)
    {
        Console.WriteLine(item);
    }
    if (!page.HasNext())
    {
        break;
    }
    page = await page.Next();
}
```

## ASP.NET Core Integration

Register the client in your DI container:

```csharp Program.cs theme={null}
using DodoPayments.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<DodoPaymentsClient>(sp =>
{
    var configuration = sp.GetRequiredService<IConfiguration>();
    return new DodoPaymentsClient
    {
        BearerToken = configuration["DodoPayments:ApiKey"]
    };
});

var app = builder.Build();
app.Run();
```

```json appsettings.json theme={null}
{
  "DodoPayments": {
    "ApiKey": "your_api_key_here"
  }
}
```

<Tip>
  For development, use [user secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) instead of storing keys in `appsettings.json`:

  ```bash theme={null}
  dotnet user-secrets init
  dotnet user-secrets set "DodoPayments:ApiKey" "your_api_key_here"
  ```
</Tip>

## Resources

<CardGroup>
  <Card title="NuGet Package" icon="box" href="https://www.nuget.org/packages/DodoPayments.Client">
    View package on NuGet Gallery
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-csharp">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>
</CardGroup>

## Support

Need help with the C# SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-csharp)


# Flutter
Source: https://docs.dodopayments.com/developer-resources/sdks/flutter

Open Dodo Payments' hosted checkout from Flutter in a system browser tab and get a typed result back in one call.

<Info>
  This is the official Dodo Payments Flutter package (`dodopayments_checkout`
  on pub.dev). A separate, community-built package also exists, see
  [Community Projects](/community/projects).
</Info>

<CardGroup>
  <Card title="Checkout Sessions API" icon="cart-shopping" href="/developer-resources/checkout-session">
    Create the checkout\_url this SDK opens, from your backend.
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    See how this fits into the full mobile payment flow.
  </Card>
</CardGroup>

`dodopayments_checkout` opens Dodo's hosted checkout in
`SFSafariViewController` on iOS and a Chrome Custom Tab on Android — the same
native cores used by the standalone [iOS](/developer-resources/sdks/ios) and
[Android](/developer-resources/sdks/android) SDKs. All checkout logic lives in
those native cores; the Dart layer passes the call through a typed
[Pigeon](https://pub.dev/packages/pigeon) channel. It holds no API key and
never calls the Dodo Payments API.

Requires Flutter 3.44+ / Dart 3.12+, iOS 16+, and Android `minSdk` 23.

## Installation

<Steps>
  <Step title="Add the Dependency">
    ```yaml pubspec.yaml theme={null}
    dependencies:
      dodopayments_checkout: ^1.0.0
    ```
  </Step>

  <Step title="Register a Callback URL Scheme">
    <Tabs>
      <Tab title="iOS">
        Add a URL type for your scheme in `ios/Runner/Info.plist`:

        ```xml ios/Runner/Info.plist theme={null}
        <key>CFBundleURLTypes</key>
        <array>
          <dict>
            <key>CFBundleURLName</key>
            <string>myapp</string>
            <key>CFBundleURLSchemes</key>
            <array>
              <string>myapp</string>
            </array>
          </dict>
        </array>
        ```

        Then forward incoming URLs (e.g. via
        [`app_links`](https://pub.dev/packages/app_links)) into the SDK, because
        `SFSafariViewController` cannot catch its own return URL:

        ```dart theme={null}
        import 'package:dodopayments_checkout/dodopayments_checkout.dart';

        DodoCheckout.instance.handleOpenURL(url);
        ```

        <Note>
          It's safe to forward every URL here. `handleOpenURL` only acts on URLs
          matching your registered `returnUrl` and resolves `false` for anything
          else.
        </Note>
      </Tab>

      <Tab title="Android">
        Set your callback scheme as a Gradle manifest placeholder:

        ```kotlin android/app/build.gradle theme={null}
        android {
            defaultConfig {
                manifestPlaceholders["dodoCallbackScheme"] = "myapp"
            }
        }
        ```

        <Warning>
          If `MainActivity` sets `android:taskAffinity=""` (the stock `flutter
                    create` default), remove it or give the SDK's activities the same
          affinity. Otherwise some OEM Android builds can lose the in-flight
          checkout and return `PLATFORM_ERROR`.
        </Warning>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Usage

```dart theme={null}
import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: dismiss();
  case CheckoutStatus.pending:   showPending();
  case CheckoutStatus.expired:   showExpired();
}
```

## What the Result Means

<Warning>
  `result.status` is a UI hint, not proof of payment. Confirm every payment
  from your backend, via the `payment.succeeded` / `subscription.active`
  webhook.
</Warning>

<ParamField type="CheckoutStatus">
  One of `succeeded`, `failed`, `cancelled`, `pending`, `expired`.
</ParamField>

<ParamField type="String?">
  Set when the return URL included one. Display it in the UI, don't use it
  to grant access. See Verify the Payment below.
</ParamField>

<ParamField type="String?">
  Set for subscription checkouts.
</ParamField>

<ParamField type="List<String>?">
  Set when the checkout includes license key products.
</ParamField>

<ParamField type="String?">
  Set when the checkout captures an email.
</ParamField>

<ParamField type="Map<String, String>">
  Every query parameter from the return URL, verbatim.
</ParamField>

## Verify the Payment

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Dodo Payments calls your backend when a payment succeeds or a subscription activates.
  </Card>

  <Card title="Get Payment Detail" icon="magnifying-glass" href="/api-reference/payments/get-payments-1">
    Look up `paymentId` with your secret key to check its status directly.
  </Card>
</CardGroup>

Grant access after one of these confirms the payment, never from
`result.status` alone.

## Appearance Customization

Customize the checkout browser's toolbar, buttons, and color scheme via
`customization` on `CheckoutParams`. Options are grouped by platform because
Android's Custom Tab and iOS's `SFSafariViewController` expose different
native controls. All fields are optional; omitting `customization` uses each
platform's default appearance.

<AccordionGroup>
  <Accordion title="Android — Custom Tab">
    <ParamField type="Color?">
      Toolbar background color.
    </ParamField>

    <ParamField type="Color?">
      Navigation bar color.
    </ParamField>

    <ParamField type="Color?">
      Divider color above the navigation bar.
    </ParamField>

    <ParamField type="CloseButtonStyle">
      `standard` shows the system "X" icon; `back` draws a back arrow instead.
    </ParamField>

    <ParamField type="CloseButtonPosition">
      Which side of the toolbar the close button appears on.
    </ParamField>

    <ParamField type="bool">
      Shows the toolbar's share icon.
    </ParamField>

    <ParamField type="bool">
      Shows the page title under the URL in the toolbar.
    </ParamField>

    <ParamField type="bool">
      Lets the toolbar auto-hide as the page scrolls.
    </ParamField>

    <ParamField type="bool">
      Shows "Bookmark this page" in the overflow menu.
    </ParamField>

    <ParamField type="bool">
      Shows "Download page" in the overflow menu.
    </ParamField>

    <ParamField type="BrowserColorScheme">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>

  <Accordion title="iOS — SFSafariViewController">
    <ParamField type="DismissButtonStyle">
      Label or icon for the dismiss button.
    </ParamField>

    <ParamField type="PresentationStyle">
      `pageSheet` presents as a card with swipe-to-dismiss; `fullScreen` covers the whole screen.
    </ParamField>

    <ParamField type="bool">
      Lets the toolbar collapse on scroll. Only visible when `presentationStyle` is `fullScreen` — `pageSheet` keeps the bars pinned regardless of this setting.
    </ParamField>

    <ParamField type="BrowserColorScheme">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>
</AccordionGroup>

```dart theme={null}
final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);
```

## Errors

`start` throws `CheckoutException` only for misuse or a platform failure.
A cancelled or declined payment is always a result, never an exception.

* `invalidCheckoutUrl` (`INVALID_CHECKOUT_URL`): not a `checkout.dodopayments.com` session URL.
* `invalidReturnUrl` (`INVALID_RETURN_URL`): not a valid absolute URL.
* `alreadyInProgress` (`ALREADY_IN_PROGRESS`): a checkout is already running.
* `platformError` (`PLATFORM_ERROR`): unexpected platform failure.

## Abandoned Sessions

<Info>
  If the app is killed mid-checkout, recover the session on next launch and
  reconcile it with your backend.
</Info>

```dart theme={null}
import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.instance.clearAbandonedSession();
}
```

## Related

<CardGroup>
  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    The same contract for Android, iOS, and React Native.
  </Card>

  <Card title="Community Projects" icon="users" href="/community/projects">
    A separate, community-built Flutter package also exists.
  </Card>
</CardGroup>


# Go
Source: https://docs.dodopayments.com/developer-resources/sdks/go

Integrate Dodo Payments into your Go applications with an idiomatic, performant SDK

The Go SDK provides a clean and idiomatic Go interface for integrating Dodo Payments into your applications. It offers context support, strongly typed responses, middleware capabilities, and is safe for concurrent use.

## Installation

Install the SDK using Go modules:

```bash theme={null}
go get github.com/dodopayments/dodopayments-go
```

Or to pin to a specific version:

```bash theme={null}
go get -u 'github.com/dodopayments/dodopayments-go@v1.97.3'
```

<Info>
  The SDK requires Go 1.22 or later versions, leveraging modern Go features for optimal performance.
</Info>

## Quick Start

Initialize the client and create your first checkout session:

```go theme={null}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/dodopayments/dodopayments-go"
	"github.com/dodopayments/dodopayments-go/option"
)

func main() {
	client := dodopayments.NewClient(
		option.WithBearerToken("My Bearer Token"), // defaults to os.LookupEnv("DODO_PAYMENTS_API_KEY")
		option.WithEnvironmentTestMode(),          // defaults to option.WithEnvironmentLiveMode()
	)
	
	checkoutSessionResponse, err := client.CheckoutSessions.New(context.TODO(), dodopayments.CheckoutSessionNewParams{
		CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
			ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{{
				ProductID: dodopayments.F("product_id"),
				Quantity:  dodopayments.F(int64(1)),
			}}),
		},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("Session ID: %s\n", checkoutSessionResponse.SessionID)
}
```

<Warning>
  Always store your API keys securely using environment variables. Never hardcode them in your source code.
</Warning>

## Core Features

<CardGroup>
  <Card title="Context Support" icon="clock">
    Full support for `context.Context` for cancellation and timeouts
  </Card>

  <Card title="Strong Typing" icon="shield-check">
    Strongly typed requests and responses for compile-time safety
  </Card>

  <Card title="Middleware" icon="layer-group">
    Extensible middleware support for logging, metrics, and custom logic
  </Card>

  <Card title="Goroutine Safe" icon="bolt">
    Thread-safe client designed for concurrent operations
  </Card>
</CardGroup>

## Configuration

### Context and Timeouts

Leverage Go's context for timeouts and cancellation:

```go theme={null}
import (
	"context"
	"time"
	
	"github.com/dodopayments/dodopayments-go"
	"github.com/dodopayments/dodopayments-go/option"
)

// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

payment, err := client.Payments.New(ctx, dodopayments.PaymentNewParams{
	Billing: dodopayments.F(dodopayments.BillingAddressParam{
		Country: dodopayments.F(dodopayments.CountryCodeUs),
		City:    dodopayments.F("San Francisco"),
		State:   dodopayments.F("CA"),
		Street:  dodopayments.F("1 Market St"),
		Zipcode: dodopayments.F("94105"),
	}),
	Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
		dodopayments.AttachExistingCustomerParam{
			CustomerID: dodopayments.F("cus_123"),
		},
	),
	ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
		ProductID: dodopayments.F("pdt_456"),
		Quantity:  dodopayments.F(int64(1)),
	}}),
})
if err != nil {
	if ctx.Err() == context.DeadlineExceeded {
		log.Println("Request timed out")
	} else {
		log.Fatal(err)
	}
}
```

### Retry Configuration

Configure automatic retry behavior:

```go theme={null}
// Configure default for all requests (default is 2)
client := dodopayments.NewClient(
	option.WithMaxRetries(0), // disable retries
)

// Override per-request
client.CheckoutSessions.New(
	context.TODO(),
	dodopayments.CheckoutSessionNewParams{
		CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
			ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{{
				ProductID: dodopayments.F("product_id"),
				Quantity:  dodopayments.F(int64(0)),
			}}),
		},
	},
	option.WithMaxRetries(5),
)
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```go theme={null}
session, err := client.CheckoutSessions.New(ctx, dodopayments.CheckoutSessionNewParams{
	CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
		ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{{
			ProductID: dodopayments.F("pdt_123"),
			Quantity:  dodopayments.F(int64(1)),
		}}),
		ReturnURL: dodopayments.F("https://yourdomain.com/return"),
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Checkout URL: %s\n", session.CheckoutURL)
```

### Manage Customers

Create and retrieve customer information:

```go theme={null}
// Create a customer
customer, err := client.Customers.New(ctx, dodopayments.CustomerNewParams{
	Email: dodopayments.F("customer@example.com"),
	Name:  dodopayments.F("John Doe"),
	Metadata: dodopayments.F(map[string]string{
		"user_id": "12345",
	}),
})
if err != nil {
	log.Fatal(err)
}

// Retrieve customer
customer, err = client.Customers.Get(ctx, "cus_123")
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Customer: %s (%s)\n", customer.Name, customer.Email)
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```go theme={null}
import "time"

// Create a subscription
subscription, err := client.Subscriptions.New(ctx, dodopayments.SubscriptionNewParams{
	Billing: dodopayments.F(dodopayments.BillingAddressParam{
		Country: dodopayments.F(dodopayments.CountryCodeUs),
		City:    dodopayments.F("San Francisco"),
		State:   dodopayments.F("CA"),
		Street:  dodopayments.F("1 Market St"),
		Zipcode: dodopayments.F("94105"),
	}),
	Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
		dodopayments.AttachExistingCustomerParam{
			CustomerID: dodopayments.F("cus_123"),
		},
	),
	ProductID: dodopayments.F("pdt_456"),
	Quantity:  dodopayments.F(int64(1)),
})
if err != nil {
	log.Fatal(err)
}

// Charge an on-demand subscription
// ProductPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
chargeResponse, err := client.Subscriptions.Charge(ctx, subscription.SubscriptionID,
	dodopayments.SubscriptionChargeParams{
		ProductPrice: dodopayments.F(int64(2500)),
	},
)
if err != nil {
	log.Fatal(err)
}

// Get usage history (for metered subscriptions)
usageHistory, err := client.Subscriptions.GetUsageHistory(
	ctx,
	subscription.SubscriptionID,
	dodopayments.SubscriptionGetUsageHistoryParams{
		StartDate: dodopayments.F(time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)),
		EndDate:   dodopayments.F(time.Date(2024, 3, 31, 23, 59, 59, 0, time.UTC)),
	},
)
if err != nil {
	log.Fatal(err)
}
```

<Info>
  `Billing` requires at minimum the two-letter ISO `Country` code. `Customer` is a `CustomerRequestUnionParam` — pass `AttachExistingCustomerParam{CustomerID: ...}` for an existing customer or `NewCustomerParam{Email: ..., Name: ...}` for a new one. `ProductPrice` is in the lowest currency denomination.
</Info>

## Usage-Based Billing

### Ingest Usage Events

Track custom events:

```go theme={null}
import "github.com/dodopayments/dodopayments-go"

response, err := client.UsageEvents.Ingest(ctx, dodopayments.UsageEventIngestParams{
	Events: dodopayments.F([]dodopayments.EventInputParam{{
		EventID:    dodopayments.F("api_call_12345"),
		CustomerID: dodopayments.F("cus_abc123"),
		EventName:  dodopayments.F("api_request"),
		Timestamp:  dodopayments.F(time.Date(2024, 1, 15, 10, 30, 0, 0, time.UTC)),
	}}),
})
if err != nil {
	log.Fatal(err)
}
```

### List Usage Events

```go theme={null}
// List events with filters
params := dodopayments.UsageEventListParams{
	CustomerID: dodopayments.F("cus_abc123"),
	EventName:  dodopayments.F("api_request"),
}

events, err := client.UsageEvents.List(ctx, params)
if err != nil {
	log.Fatal(err)
}

for _, event := range events.Items {
	fmt.Printf("Event %s: %s at %s\n", event.EventID, event.EventName, event.Timestamp)
}
```

## Error Handling

When the API returns a non-success status code, the SDK returns an error of type
`*dodopayments.Error`. It exposes the `StatusCode`, the underlying `*http.Request` and
`*http.Response`, and the JSON of the error body. Use the `errors.As` pattern to
inspect it, and branch on `StatusCode` to handle specific cases:

```go theme={null}
payment, err := client.Payments.New(ctx, dodopayments.PaymentNewParams{
	Billing: dodopayments.F(dodopayments.BillingAddressParam{
		Country: dodopayments.F(dodopayments.CountryCodeUs),
		City:    dodopayments.F("San Francisco"),
		State:   dodopayments.F("CA"),
		Street:  dodopayments.F("1 Market St"),
		Zipcode: dodopayments.F("94105"),
	}),
	Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
		dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F("cus_123")},
	),
	ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
		ProductID: dodopayments.F("pdt_456"),
		Quantity:  dodopayments.F(int64(1)),
	}}),
})
if err != nil {
	var apiErr *dodopayments.Error
	if errors.As(err, &apiErr) {
		fmt.Printf("Status Code: %d\n", apiErr.StatusCode)
		fmt.Println(string(apiErr.DumpResponse(true))) // Serialized HTTP response

		// Handle specific status codes
		switch apiErr.StatusCode {
		case 401:
			log.Println("Authentication failed")
		case 422:
			log.Println("Invalid request parameters")
		case 429:
			log.Println("Rate limit exceeded")
		default:
			log.Printf("API error: %s", apiErr.Error())
		}
	} else {
		log.Fatal(err)
	}
}
```

## Middleware

Add custom middleware for logging or metrics:

```go theme={null}
func Logger(req *http.Request, next option.MiddlewareNext) (res *http.Response, err error) {
	// Before the request
	start := time.Now()
	log.Printf("Request: %s %s\n", req.Method, req.URL)

	// Forward the request to the next handler
	res, err = next(req)

	// After the request
	end := time.Now()
	log.Printf("Response: %d in %v\n", res.StatusCode, end.Sub(start))

	return res, err
}

client := dodopayments.NewClient(
	option.WithMiddleware(Logger),
)
```

## Concurrency

The client is safe for concurrent use:

```go theme={null}
package main

import (
	"context"
	"sync"
	"log"

	"github.com/dodopayments/dodopayments-go"
)

func main() {
	client := dodopayments.NewClient()
	
	var wg sync.WaitGroup
	for i := 0; i < 10; i++ {
		wg.Add(1)
		go func(idx int) {
			defer wg.Done()
			
			payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
				Billing: dodopayments.F(dodopayments.BillingAddressParam{
					Country: dodopayments.F(dodopayments.CountryCodeUs),
					City:    dodopayments.F("San Francisco"),
					State:   dodopayments.F("CA"),
					Street:  dodopayments.F("1 Market St"),
					Zipcode: dodopayments.F("94105"),
				}),
				Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
					dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F("cus_123")},
				),
				ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
					ProductID: dodopayments.F("pdt_456"),
					Quantity:  dodopayments.F(int64(1)),
				}}),
			})
			if err != nil {
				log.Printf("Failed to create payment %d: %v", idx, err)
				return
			}
			
			log.Printf("Created payment %d: %s", idx, payment.PaymentID)
		}(i)
	}
	
	wg.Wait()
}
```

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-go">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-go/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the Go SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-go)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-go/blob/main/CONTRIBUTING.md) to get started.


# iOS
Source: https://docs.dodopayments.com/developer-resources/sdks/ios

Open Dodo Payments' hosted checkout from an iOS app in SFSafariViewController and get a typed result back in one call.

<Info>
  This is the official Dodo Payments iOS checkout SDK for Swift. It opens Dodo's hosted checkout in a native browser view and returns a typed result.
</Info>

<CardGroup>
  <Card title="Checkout Sessions API" icon="cart-shopping" href="/developer-resources/checkout-session">
    Create the checkout\_url this SDK opens, from your backend.
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    See how this fits into the full mobile payment flow.
  </Card>
</CardGroup>

The iOS SDK opens Dodo's hosted checkout in `SFSafariViewController`, holds no API key, and never calls the Dodo API directly. All checkout logic runs in the browser; the SDK simply manages the view lifecycle and captures the return URL.

Requires iOS 16+, Swift 6.

## Installation

<Steps>
  <Step title="Add the Package">
    In Xcode, go to **File → Add Package Dependencies** and enter:

    ```
    https://github.com/dodopayments/dodopayments-mobile-sdk-ios
    ```

    Select version 1.0.0 or later.

    Alternatively, add to your `Package.swift`:

    ```swift Package.swift theme={null}
    .package(url: "https://github.com/dodopayments/dodopayments-mobile-sdk-ios", from: "1.0.0")
    ```
  </Step>

  <Step title="Register a Callback URL Scheme">
    Your app must register a URL scheme to receive the return URL from the checkout. Add this to your `Info.plist`:

    ```xml Info.plist theme={null}
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLName</key>
        <string>myapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>myapp</string>
        </array>
      </dict>
    </array>
    ```

    You can also add this via Xcode's **Info → URL Types** UI.
  </Step>
</Steps>

## Usage

```swift theme={null}
import DodoCheckout

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,   // from your backend's checkout session
    returnUrl: URL(string: "myapp://checkout/return")!,
    onEvent: { event in print(event.name) }  // logging only
)

switch result.status {
case .succeeded: showSuccess(result.paymentId)
case .failed:    showFailure()
case .cancelled: dismiss()
case .pending:   showPending()
case .expired:   showExpired()
}
```

## Forwarding the Return URL

`SFSafariViewController` has no in-process way to catch its own return URL. Your app must forward incoming URLs into the SDK.

<Tabs>
  <Tab title="SwiftUI">
    ```swift theme={null}
    .onOpenURL { url in
        DodoCheckout.handleOpenURL(url)
    }
    ```
  </Tab>

  <Tab title="SceneDelegate">
    ```swift SceneDelegate.swift theme={null}
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let url = URLContexts.first?.url else { return }
        DodoCheckout.handleOpenURL(url)
    }
    ```
  </Tab>
</Tabs>

<Note>
  It's safe to forward every URL here. `handleOpenURL` only acts on URLs matching your registered `returnUrl` and returns `false` for anything else.
</Note>

## What the Result Means

<Warning>
  `result.status` is a UI hint, not proof of payment. Confirm every payment from your backend, via the `payment.succeeded` / `subscription.active` webhook.
</Warning>

<ParamField type="CheckoutStatus">
  One of `succeeded`, `failed`, `cancelled`, `pending`, `expired`.
</ParamField>

<ParamField type="String?">
  Set when the return URL included one. Display it in the UI, don't use it to grant access. See Verify the Payment below.
</ParamField>

<ParamField type="String?">
  Set for subscription checkouts.
</ParamField>

<ParamField type="[String]?">
  Set when the checkout includes license key products.
</ParamField>

<ParamField type="String?">
  Set when the checkout captures an email.
</ParamField>

<ParamField type="[String: String]">
  Every query parameter from the return URL, verbatim.
</ParamField>

## Verify the Payment

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Dodo Payments calls your backend when a payment succeeds or a subscription activates.
  </Card>

  <Card title="Get Payment Detail" icon="magnifying-glass" href="/api-reference/payments/get-payments-1">
    Look up `paymentId` with your secret key to check its status directly.
  </Card>
</CardGroup>

Grant access after one of these confirms the payment, never from `result.status` alone.

## Appearance Customization

Customize the sheet's dismiss button, presentation style, and color scheme
via `customization` on `start(...)`. All fields are optional; omitting
`customization` uses iOS's default `SFSafariViewController` appearance.

<ParamField type="DismissButtonStyle">
  Label or icon for the dismiss button: `done`, `close`, or `cancel`.
</ParamField>

<ParamField type="PresentationStyle">
  `pageSheet` presents as a card with swipe-to-dismiss; `fullScreen` covers the whole screen.
</ParamField>

<ParamField type="Bool">
  Lets the toolbar collapse on scroll. Only visible when `presentationStyle` is `fullScreen` — `pageSheet` keeps the bars pinned regardless of this setting.
</ParamField>

<ParamField type="ColorScheme">
  Forces light or dark appearance regardless of the device's system setting: `system`, `light`, or `dark`.
</ParamField>

```swift theme={null}
let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        dismissButtonStyle: .close,
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)
```

## Errors

`start` throws `CheckoutError` only for misuse or a platform failure. A cancelled or declined payment is always a result, never an exception.

* `invalidCheckoutUrl` (`INVALID_CHECKOUT_URL`): not a `checkout.dodopayments.com` session URL.
* `invalidReturnUrl` (`INVALID_RETURN_URL`): not a valid absolute URL.
* `alreadyInProgress` (`ALREADY_IN_PROGRESS`): a checkout is already running.
* `platformError` (`PLATFORM_ERROR`): unexpected platform failure.

## Abandoned Sessions

<Info>
  If the app is killed mid-checkout, recover the session on next launch and reconcile it with your backend.
</Info>

```swift theme={null}
import DodoCheckout

if let abandoned = DodoCheckout.getAbandonedSession() {
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession()
}
```

## Related

<CardGroup>
  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    The same contract for Android, React Native, and Flutter.
  </Card>

  <Card title="React Native SDK" icon="react" href="/developer-resources/sdks/react-native">
    Wraps this same Swift core on iOS.
  </Card>
</CardGroup>


# Java
Source: https://docs.dodopayments.com/developer-resources/sdks/java

Integrate Dodo Payments into your Java applications with a robust, type-safe SDK

The Java SDK provides convenient and ergonomic access to the Dodo Payments REST API for applications written in Java. It utilizes Java-specific features like Optional, Stream, and CompletableFuture for modern Java development.

## Installation

### Maven

Add the dependency to your `pom.xml`:

```xml pom.xml theme={null}
<dependency>
  <groupId>com.dodopayments.api</groupId>
  <artifactId>dodo-payments-java</artifactId>
  <version>1.97.1</version>
</dependency>
```

### Gradle

Add the dependency to your `build.gradle`:

```kotlin build.gradle.kts theme={null}
implementation("com.dodopayments.api:dodo-payments-java:1.97.1")
```

<Tip>
  Always use the latest SDK version to access the newest Dodo Payments features. Check [Maven Central](https://central.sonatype.com/artifact/com.dodopayments.api/dodo-payments-java) for the latest version.
</Tip>

<Info>
  The SDK supports Java 8 and all later versions, including Java 11, 17, and 21.
</Info>

## Quick Start

Initialize the client and create a checkout session:

```java theme={null}
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionCreateParams;
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest;
import com.dodopayments.api.models.checkoutsessions.ProductItemReq;

// Configure using environment variables (DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_BASE_URL)
// Or system properties (dodopayments.apiKey, dodopayments.baseUrl)
DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();

CheckoutSessionRequest params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("product_id")
        .quantity(1)
        .build())
    .build();
    
CheckoutSessionResponse checkoutSessionResponse = client.checkoutSessions().create(params);
System.out.println(checkoutSessionResponse.sessionId());
```

<Warning>
  Always store your API keys securely using environment variables, system properties, or a secure configuration management system. Never hardcode them in your source code.
</Warning>

## Core Features

<CardGroup>
  <Card title="Type Safety" icon="shield-check">
    Strongly typed API with compile-time safety
  </Card>

  <Card title="Thread-Safe" icon="bolt">
    Safe for concurrent use in multi-threaded applications
  </Card>

  <Card title="Builder Pattern" icon="layer-group">
    Intuitive builder pattern for constructing requests
  </Card>

  <Card title="Async Support" icon="arrows-rotate">
    CompletableFuture support for asynchronous operations
  </Card>
</CardGroup>

## Configuration

### Environment Variables

Configure using environment variables or system properties:

```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_BASE_URL=https://live.dodopayments.com
```

```java theme={null}
// Automatically reads from environment variables
DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv();
```

### Manual Configuration

Configure manually with all options:

```java theme={null}
import java.time.Duration;

DodoPaymentsClient client = DodoPaymentsOkHttpClient.builder()
    .bearerToken("your_api_key_here")
    .baseUrl("https://live.dodopayments.com")
    .maxRetries(4)
    .timeout(Duration.ofSeconds(30))
    .responseValidation(true)
    .build();
```

### Test Mode

Configure for the Test Mode environment:

```java theme={null}
DodoPaymentsClient testClient = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .testMode()
    .build();
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```java theme={null}
CheckoutSessionRequest params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("pdt_123")
        .quantity(1)
        .build())
    .returnUrl("https://yourdomain.com/return")
    .build();

CheckoutSessionResponse session = client.checkoutSessions().create(params);
System.out.println("Checkout URL: " + session.checkoutUrl());
```

### Manage Customers

Create and retrieve customer information:

```java theme={null}
import com.dodopayments.api.models.customers.Customer;
import com.dodopayments.api.models.customers.CustomerCreateParams;

// Create a customer
CustomerCreateParams createParams = CustomerCreateParams.builder()
    .email("customer@example.com")
    .name("John Doe")
    .putMetadata("user_id", "12345")
    .build();

Customer customer = client.customers().create(createParams);

// Retrieve customer
Customer retrieved = client.customers().retrieve("cus_123");
System.out.println("Customer: " + retrieved.name() + " (" + retrieved.email() + ")");
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```java theme={null}
import com.dodopayments.api.models.payments.AttachExistingCustomer;
import com.dodopayments.api.models.payments.BillingAddress;
import com.dodopayments.api.models.misc.CountryCode;
import com.dodopayments.api.models.subscriptions.SubscriptionChargeParams;
import com.dodopayments.api.models.subscriptions.SubscriptionChargeResponse;
import com.dodopayments.api.models.subscriptions.SubscriptionCreateParams;
import com.dodopayments.api.models.subscriptions.SubscriptionCreateResponse;

// Create a subscription
SubscriptionCreateParams subscriptionParams = SubscriptionCreateParams.builder()
    .billing(BillingAddress.builder()
        .city("San Francisco")
        .country(CountryCode.US)
        .state("CA")
        .street("1 Market St")
        .zipcode("94105")
        .build())
    .customer(AttachExistingCustomer.builder()
        .customerId("cus_123")
        .build())
    .productId("pdt_456")
    .quantity(1)
    .paymentLink(true)
    .returnUrl("https://yourdomain.com/return")
    .build();

SubscriptionCreateResponse subscription = client.subscriptions().create(subscriptionParams);
System.out.println("Subscription ID: " + subscription.subscriptionId());

// Charge an on-demand subscription
// product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
SubscriptionChargeParams chargeParams = SubscriptionChargeParams.builder()
    .subscriptionId(subscription.subscriptionId())
    .productPrice(2500)
    .build();

SubscriptionChargeResponse chargeResponse = client.subscriptions().charge(chargeParams);
System.out.println("Payment ID: " + chargeResponse.paymentId());
```

<Info>
  `productPrice` is expressed in the lowest currency denomination (e.g., cents for USD, paise for INR). To charge \$25.00, pass `2500`.
</Info>

<Tip>
  Charging via `subscriptions().charge(...)` is intended for [on-demand subscriptions](/developer-resources/ondemand-subscriptions). Standard scheduled subscriptions are billed automatically based on the product's pricing schedule.
</Tip>

## Usage-Based Billing

### Configure Meters

Create and manage meters for tracking usage:

```java theme={null}
import com.dodopayments.api.models.meters.*;

// Create API calls meter
MeterCreateParams apiMeterParams = MeterCreateParams.builder()
    .name("API Requests")
    .eventName("api_request")
    .aggregation(MeterAggregation.builder()
        .type(MeterAggregation.Type.COUNT)
        .build())
    .measurementUnit("calls")
    .build();

Meter apiMeter = client.meters().create(apiMeterParams);
System.out.println("Meter created: " + apiMeter.id());

// List all meters
client.meters().list()
    .autoPager()
    .forEach(m -> System.out.println("Meter: " + m.name() + " - " + m.aggregation()));
```

### Ingest Usage Events

Track custom events:

```java theme={null}
import com.dodopayments.api.models.usageevents.EventInput;
import com.dodopayments.api.models.usageevents.*;
import java.time.OffsetDateTime;

// Ingest single event
UsageEventIngestParams singleEventParams = UsageEventIngestParams.builder()
    .addEvent(EventInput.builder()
        .eventId("api_call_" + System.currentTimeMillis())
        .customerId("cus_abc123")
        .eventName("api_request")
        .timestamp(OffsetDateTime.now())
        .putMetadata("endpoint", "/api/v1/users")
        .putMetadata("method", "GET")
        .putMetadata("tokens_used", "150")
        .build())
    .build();

UsageEventIngestResponse response = client.usageEvents().ingest(singleEventParams);
System.out.println("Processed: " + response.ingestedCount());
```

### Batch Ingest Events

Ingest multiple events efficiently (max 1000 per request):

```java theme={null}
UsageEventIngestParams.Builder batchBuilder = UsageEventIngestParams.builder();

for (int i = 0; i < 100; i++) {
    batchBuilder.addEvent(EventInput.builder()
        .eventId("batch_event_" + i + "_" + System.currentTimeMillis())
        .customerId("cus_abc123")
        .eventName("video_transcode")
        .timestamp(OffsetDateTime.now().minusSeconds(i))
        .putMetadata("video_id", "video_" + i)
        .putMetadata("duration_seconds", String.valueOf(120 + i))
        .build());
}

UsageEventIngestResponse batchResponse = client.usageEvents().ingest(batchBuilder.build());
System.out.println("Batch processed: " + batchResponse.ingestedCount() + " events");
```

## Error Handling

Comprehensive error handling for different scenarios:

```java theme={null}
import com.dodopayments.api.errors.*;

try {
    Payment payment = client.payments().retrieve("pay_invalid");
} catch (NotFoundException e) {
    System.err.println("Payment not found: " + e.getMessage());
} catch (UnauthorizedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
} catch (PermissionDeniedException e) {
    System.err.println("Permission denied: " + e.getMessage());
} catch (BadRequestException e) {
    System.err.println("Invalid request: " + e.getMessage());
} catch (UnprocessableEntityException e) {
    System.err.println("Validation error: " + e.getMessage());
} catch (RateLimitException e) {
    System.err.println("Rate limit exceeded: " + e.getMessage());
    // SDK automatically retries with backoff
} catch (InternalServerException e) {
    System.err.println("Server error: " + e.getMessage());
} catch (DodoPaymentsServiceException e) {
    System.err.println("API error: " + e.statusCode() + " - " + e.getMessage());
}
```

<Tip>
  The SDK automatically retries requests on connection errors, 408, 409, 429, and 5xx errors with exponential backoff.
</Tip>

## Async Operations

Use CompletableFuture for asynchronous operations:

```java theme={null}
import java.util.concurrent.CompletableFuture;

CompletableFuture<CheckoutSessionResponse> future = client.async()
    .checkoutSessions()
    .create(params);

// Handle response asynchronously
future.thenAccept(response -> {
    System.out.println("Session created: " + response.sessionId());
}).exceptionally(ex -> {
    System.err.println("Error: " + ex.getMessage());
    return null;
});
```

## Spring Boot Integration

### Configuration Class

```java theme={null}
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class DodoPaymentsConfig {
    
    @Value("${dodo.api.key}")
    private String apiKey;
    
    @Value("${dodo.environment:test}")
    private String environment;
    
    @Bean
    public DodoPaymentsClient dodoPayments() {
        return DodoPaymentsOkHttpClient.builder()
            .bearerToken(apiKey)
            .baseUrl(environment.equals("live") 
                ? "https://live.dodopayments.com" 
                : "https://test.dodopayments.com")
            .build();
    }
}
```

### Service Layer

```java theme={null}
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.models.checkoutsessions.*;
import org.springframework.stereotype.Service;

@Service
public class PaymentService {
    
    private final DodoPaymentsClient client;
    
    public PaymentService(DodoPaymentsClient client) {
        this.client = client;
    }
    
    public CheckoutSessionResponse createCheckout(List<ProductItemReq> items) {
        CheckoutSessionRequest params = CheckoutSessionRequest.builder()
            .productCart(items)
            .returnUrl("https://yourdomain.com/return")
            .build();
            
        return client.checkoutSessions().create(params);
    }
}
```

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-java">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-java/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the Java SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-java)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-java/blob/main/CONTRIBUTING.md) to get started.


# Kotlin
Source: https://docs.dodopayments.com/developer-resources/sdks/kotlin

Integrate Dodo Payments into your Kotlin applications with modern coroutines and null-safety

The Kotlin SDK provides convenient access to the Dodo Payments REST API from applications written in Kotlin. It features nullable values, Sequence, suspend functions, and other Kotlin-specific features for ergonomic use.

## Installation

### Gradle (Kotlin DSL)

Add the dependency to your `build.gradle.kts`:

```kotlin build.gradle.kts theme={null}
implementation("com.dodopayments.api:dodo-payments-kotlin:1.97.1")
```

### Maven

Add the dependency to your `pom.xml`:

```xml pom.xml theme={null}
<dependency>
  <groupId>com.dodopayments.api</groupId>
  <artifactId>dodo-payments-kotlin</artifactId>
  <version>1.97.1</version>
</dependency>
```

<Tip>
  Always use the latest SDK version to access the newest Dodo Payments features. Check [Maven Central](https://central.sonatype.com/artifact/com.dodopayments.api/dodo-payments-kotlin) for the latest version.
</Tip>

<Info>
  The SDK requires Java 8 or later and is compatible with both JVM and Android platforms.
</Info>

## Quick Start

Initialize the client and create a checkout session:

```kotlin theme={null}
import com.dodopayments.api.client.DodoPaymentsClient
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionCreateParams
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest
import com.dodopayments.api.models.checkoutsessions.ProductItemReq

// Configure using environment variables (DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_BASE_URL)
// Or system properties (dodopayments.apiKey, dodopayments.baseUrl)
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()

val params: CheckoutSessionRequest = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("product_id")
        .quantity(1)
        .build())
    .build()
    
val checkoutSessionResponse: CheckoutSessionResponse = client.checkoutSessions().create(params)
println(checkoutSessionResponse.sessionId())
```

<Warning>
  Always store your API keys securely using environment variables or encrypted configuration. Never commit them to version control.
</Warning>

## Core Features

<CardGroup>
  <Card title="Coroutines" icon="bolt">
    Full support for Kotlin coroutines for asynchronous operations
  </Card>

  <Card title="Null Safety" icon="shield-check">
    Leverage Kotlin's null safety for robust error handling
  </Card>

  <Card title="Extension Functions" icon="code">
    Idiomatic Kotlin extensions for enhanced functionality
  </Card>

  <Card title="Data Classes" icon="layer-group">
    Type-safe data classes with copy and destructuring support
  </Card>
</CardGroup>

## Configuration

### From Environment Variables

Initialize from environment variables or system properties:

```kotlin theme={null}
val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv()
```

### Manual Configuration

Configure manually with all options:

```kotlin theme={null}
import java.time.Duration

val client = DodoPaymentsOkHttpClient.builder()
    .bearerToken("your_api_key_here")
    .baseUrl("https://live.dodopayments.com")
    .maxRetries(3)
    .timeout(Duration.ofSeconds(30))
    .build()
```

### Test Mode

Configure for the Test Mode environment:

```kotlin theme={null}
val testClient = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .testMode()
    .build()
```

### Timeouts and Retries

Configure globally or per-request:

```kotlin theme={null}
import com.dodopayments.api.core.RequestOptions

// Global configuration
val client = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .timeout(Duration.ofSeconds(45))
    .maxRetries(3)
    .build()

// Per-request timeout override
val product = client.products().retrieve(
    "pdt_123",
    RequestOptions.builder()
        .timeout(Duration.ofSeconds(10))
        .build()
)
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```kotlin theme={null}
val params = CheckoutSessionRequest.builder()
    .addProductCart(ProductItemReq.builder()
        .productId("pdt_123")
        .quantity(1)
        .build())
    .returnUrl("https://yourdomain.com/return")
    .build()

val session = client.checkoutSessions().create(params)
println("Checkout URL: ${session.checkoutUrl()}")
```

### Create a Product

Create products with detailed configuration:

```kotlin theme={null}
import com.dodopayments.api.models.products.Price
import com.dodopayments.api.models.products.Product
import com.dodopayments.api.models.products.ProductCreateParams
import com.dodopayments.api.models.misc.Currency
import com.dodopayments.api.models.misc.TaxCategory
import com.dodopayments.api.models.misc.TimeInterval

val createParams = ProductCreateParams.builder()
    .name("Premium Subscription")
    .description("Monthly subscription with all features")
    .price(
        Price.RecurringPrice.builder()
            .currency(Currency.USD)
            .price(2999) // $29.99 in cents
            .discount(0L)
            .purchasingPowerParity(false)
            .paymentFrequencyCount(1)
            .paymentFrequencyInterval(TimeInterval.MONTH)
            .subscriptionPeriodCount(1)
            .subscriptionPeriodInterval(TimeInterval.MONTH)
            .build()
    )
    .taxCategory(TaxCategory.DIGITAL_PRODUCTS)
    .build()

val product: Product = client.products().create(createParams)
println("Created product ID: ${product.productId()}")
```

### Activate License Key

Activate license keys for customers:

```kotlin theme={null}
import com.dodopayments.api.models.licenses.LicenseActivateParams
import com.dodopayments.api.models.licenses.LicenseActivateResponse

val activateParams = LicenseActivateParams.builder()
    .licenseKey("XXXX-XXXX-XXXX-XXXX")
    .name("user-laptop-01")
    .build()

try {
    val activationResult: LicenseActivateResponse = client.licenses()
        .activate(activateParams)

    println("License activated successfully")
    println("Instance ID: ${activationResult.id()}")
    println("License key ID: ${activationResult.licenseKeyId()}")
} catch (e: UnprocessableEntityException) {
    println("License activation failed: ${e.message}")
}
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```kotlin theme={null}
import com.dodopayments.api.models.payments.AttachExistingCustomer
import com.dodopayments.api.models.payments.BillingAddress
import com.dodopayments.api.models.misc.CountryCode
import com.dodopayments.api.models.subscriptions.SubscriptionChargeParams
import com.dodopayments.api.models.subscriptions.SubscriptionCreateParams

// Create a subscription
val subscriptionParams = SubscriptionCreateParams.builder()
    .billing(BillingAddress.builder()
        .city("San Francisco")
        .country(CountryCode.US)
        .state("CA")
        .street("1 Market St")
        .zipcode("94105")
        .build())
    .customer(AttachExistingCustomer.builder()
        .customerId("cus_123")
        .build())
    .productId("pdt_456")
    .quantity(1)
    .build()

val subscription = client.subscriptions().create(subscriptionParams)
println("Subscription ID: ${subscription.subscriptionId()}")

// Charge an on-demand subscription
// productPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
val chargeParams = SubscriptionChargeParams.builder()
    .subscriptionId(subscription.subscriptionId())
    .productPrice(2500)
    .build()

val chargeResponse = client.subscriptions().charge(chargeParams)
println("Payment ID: ${chargeResponse.paymentId()}")
```

<Info>
  `billing` requires at minimum a two-letter ISO `country` code. Use `AttachExistingCustomer` to attach an existing customer, or `NewCustomer` to create one. `productPrice` is expressed in the lowest currency denomination.
</Info>

## Usage-Based Billing

### Record Usage Events

Track usage for meters:

```kotlin theme={null}
import com.dodopayments.api.models.usageevents.EventInput
import com.dodopayments.api.models.usageevents.UsageEventIngestParams

val usageParams = UsageEventIngestParams.builder()
    .addEvent(EventInput.builder()
        .customerId("cust_456")
        .eventId("event_123")
        .eventName("api_call")
        .build())
    .build()

client.usageEvents().ingest(usageParams)
println("Usage event recorded")
```

## Async Operations

### Async Client

Use the async client for coroutine-based operations:

```kotlin theme={null}
import com.dodopayments.api.client.DodoPaymentsClientAsync
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClientAsync
import kotlinx.coroutines.runBlocking

val asyncClient: DodoPaymentsClientAsync = DodoPaymentsOkHttpClientAsync.fromEnv()

runBlocking {
    val customer = asyncClient.customers().retrieve("cust_123")
    println("Customer email: ${customer.email()}")
}
```

## Error Handling

Handle errors with Kotlin's exception handling:

```kotlin theme={null}
import com.dodopayments.api.errors.*

try {
    val payment = client.payments().create(params)
    println("Success: ${payment.paymentId()}")
} catch (e: AuthenticationException) {
    println("Authentication failed: ${e.message}")
} catch (e: InvalidRequestException) {
    println("Invalid request: ${e.message}")
    e.parameter?.let { println("Parameter: $it") }
} catch (e: RateLimitException) {
    println("Rate limit exceeded, retry after: ${e.retryAfter}")
} catch (e: DodoPaymentsServiceException) {
    println("API error: ${e.statusCode()} - ${e.message}")
}
```

### Functional Error Handling

Use `Result` for functional error handling:

```kotlin theme={null}
fun safeCreatePayment(client: DodoPaymentsClient): Result<Payment> = runCatching {
    client.payments().create(params)
}

// Usage
safeCreatePayment(client)
    .onSuccess { payment -> println("Created: ${payment.paymentId()}") }
    .onFailure { error -> println("Error: ${error.message}") }
```

<Tip>
  Use Kotlin's `runCatching` for a more functional approach to error handling with Result types.
</Tip>

## Android Integration

Use with Android applications:

```kotlin theme={null}
import android.app.Application
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.dodopayments.api.client.DodoPaymentsClient
import kotlinx.coroutines.launch

class PaymentViewModel(application: Application) : ViewModel() {
    private val client = DodoPaymentsOkHttpClient.builder()
        .bearerToken(BuildConfig.DODO_API_KEY)
        .build()
    
    fun createCheckout(productId: String) {
        viewModelScope.launch {
            try {
                val session = client.async().checkoutSessions().create(params)
                // Open checkout URL in browser or WebView
                openUrl(session.checkoutUrl())
            } catch (e: Exception) {
                handleError(e)
            }
        }
    }
}
```

## Response Validation

Enable response validation:

```kotlin theme={null}
import com.dodopayments.api.core.RequestOptions

// Per-request validation
val product = client.products().retrieve(
    "pdt_123",
    RequestOptions.builder()
        .responseValidation(true)
        .build()
)

// Or validate explicitly
val validatedProduct = product.validate()
```

## Advanced Features

### Proxy Configuration

Configure proxy settings:

```kotlin theme={null}
import java.net.InetSocketAddress
import java.net.Proxy

val client = DodoPaymentsOkHttpClient.builder()
    .fromEnv()
    .proxy(
        Proxy(
            Proxy.Type.HTTP,
            InetSocketAddress("proxy.example.com", 8080)
        )
    )
    .build()
```

### Temporary Configuration

Modify client configuration temporarily:

```kotlin theme={null}
val customClient = client.withOptions {
    it.baseUrl("https://example.com")
    it.maxRetries(5)
}
```

## Ktor Integration

Integrate with Ktor server applications:

```kotlin theme={null}
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.configureRouting() {
    val client = DodoPaymentsOkHttpClient.builder()
        .bearerToken(environment.config.property("dodo.apiKey").getString())
        .build()
    
    routing {
        post("/create-checkout") {
            try {
                val request = call.receive<CheckoutRequest>()
                val session = client.checkoutSessions().create(params)
                call.respond(mapOf("checkout_url" to session.checkoutUrl()))
            } catch (e: DodoPaymentsServiceException) {
                call.respond(HttpStatusCode.BadRequest, mapOf("error" to e.message))
            }
        }
    }
}
```

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-kotlin">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-kotlin/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the Kotlin SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-kotlin)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-kotlin/blob/main/CONTRIBUTING.md) to get started.


# PHP
Source: https://docs.dodopayments.com/developer-resources/sdks/php

Integrate Dodo Payments into your PHP applications with a modern, PSR-4 compliant SDK

The PHP SDK provides a robust and flexible way to integrate Dodo Payments into your PHP applications. Built following modern PHP standards with PSR-4 autoloading, it offers extensive test coverage and detailed documentation.

## Installation

Install the SDK using Composer:

```bash theme={null}
composer require "dodopayments/client 6.7.1"
```

<Info>
  The SDK requires PHP 8.1.0 or higher and Composer for dependency management.
</Info>

## Quick Start

Initialize the client and create a checkout session:

```php theme={null}
<?php

use Dodopayments\Client;

$client = new Client(
  bearerToken: getenv('DODO_PAYMENTS_API_KEY') ?: 'My Bearer Token',
  environment: 'test_mode',
);

$checkoutSessionResponse = $client->checkoutSessions->create(
  productCart: [["productID" => "product_id", "quantity" => 1]]
);

var_dump($checkoutSessionResponse->session_id);
```

<Warning>
  Store your API keys securely using environment variables. Never expose them in
  your codebase or commit them to version control.
</Warning>

## Core Features

<CardGroup>
  <Card title="PSR-4 Compliant" icon="check">
    Follows PHP Standards Recommendations for modern PHP development
  </Card>

  <Card title="Modern PHP" icon="php">
    Built for PHP 8.1+ with type declarations and strict types
  </Card>

  <Card title="Extensive Testing" icon="vial">
    Comprehensive test coverage for reliability and stability
  </Card>

  <Card title="Exception Handling" icon="shield-check">
    Clear exception types for different error scenarios
  </Card>
</CardGroup>

## Value Objects

The SDK uses named parameters to specify optional arguments. You can initialize value objects using the static `with` constructor:

```php theme={null}
<?php

use Dodopayments\Customers\AttachExistingCustomer;

// Recommended: Use static 'with' constructor with named parameters
$customer = AttachExistingCustomer::with(customerID: "customer_id");
```

Builders are also available as an alternative pattern:

```php theme={null}
<?php

use Dodopayments\Customers\AttachExistingCustomer;

// Alternative: Use builder pattern
$customer = (new AttachExistingCustomer)->withCustomerID("customer_id");
```

## Configuration

### Retry Configuration

Certain errors are automatically retried 2 times by default with a short exponential backoff. The following errors trigger automatic retries:

* Connection errors (network connectivity problems)
* 408 Request Timeout
* 409 Conflict
* 429 Rate Limit
* 500+ Internal errors
* Timeouts

Configure retry behavior globally or per-request:

```php theme={null}
<?php

use Dodopayments\Client;


// Configure default for all requests (disable retries)
$client = new Client(requestOptions: ['maxRetries' => 0]);

// Or, configure per-request
$result = $client->checkoutSessions->create(
  productCart: [["productID" => "product_id", "quantity" => 1]],
  requestOptions: ['maxRetries' => 5],
);
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```php theme={null}
$session = $client->checkoutSessions->create(
  productCart: [
    ["productID" => "pdt_123", "quantity" => 1]
  ],
  returnURL: "https://yourdomain.com/return"
);

header('Location: ' . $session->checkout_url);
```

### Manage Customers

Create and retrieve customer information:

```php theme={null}
// Create a customer
$customer = $client->customers->create(
  email: "customer@example.com",
  name: "John Doe",
  metadata: [
    "user_id" => "12345"
  ]
);

// Retrieve customer
$customer = $client->customers->retrieve("cus_123");
echo "Customer: {$customer->name} ({$customer->email})";
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```php theme={null}
use Dodopayments\Customers\AttachExistingCustomer;
use Dodopayments\Payments\BillingAddress;

// Create a subscription
$subscription = $client->subscriptions->create(
  billing: BillingAddress::with(
    country: 'US',
    city: 'San Francisco',
    state: 'CA',
    street: '1 Market St',
    zipcode: '94105',
  ),
  customer: AttachExistingCustomer::with(customerID: 'cus_123'),
  productID: 'pdt_456',
  quantity: 1,
);

// Charge an on-demand subscription
// productPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
$charge = $client->subscriptions->charge(
  $subscription->subscription_id,
  productPrice: 2500,
);
```

<Info>
  `billing` requires at minimum the two-letter ISO `country` code. Pass `AttachExistingCustomer::with(customerID: '...')` to attach an existing customer, or `NewCustomer::with(email: '...', name: '...')` to create one. `productPrice` is in the lowest currency denomination.
</Info>

## Pagination

Work with paginated list responses:

```php theme={null}
$page = $client->payments->list();

var_dump($page);

// Fetch items from the current page
foreach ($page->getItems() as $item) {
  var_dump($item->brand_id);
}

// Auto-paginate: fetch items from all pages
foreach ($page->pagingEachItem() as $item) {
  var_dump($item->brand_id);
}
```

## Error Handling

When the library cannot connect to the API or receives a non-success status code (4xx or 5xx), a subclass of `APIException` is thrown:

```php theme={null}
<?php

use Dodopayments\Core\Exceptions\APIConnectionException;
use Dodopayments\Core\Exceptions\RateLimitException;
use Dodopayments\Core\Exceptions\APIStatusException;

try {
  $checkoutSessionResponse = $client->checkoutSessions->create(
    productCart: [["productID" => "product_id", "quantity" => 1]]
  );
} catch (APIConnectionException $e) {
  echo "The server could not be reached", PHP_EOL;
  var_dump($e->getPrevious());
} catch (RateLimitException $_) {
  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusException $e) {
  echo "Another non-200-range status code was received", PHP_EOL;
  echo $e->getMessage();
}
```

### Error Types

| Cause            | Error Type                     |
| ---------------- | ------------------------------ |
| HTTP 400         | `BadRequestException`          |
| HTTP 401         | `AuthenticationException`      |
| HTTP 403         | `PermissionDeniedException`    |
| HTTP 404         | `NotFoundException`            |
| HTTP 409         | `ConflictException`            |
| HTTP 422         | `UnprocessableEntityException` |
| HTTP 429         | `RateLimitException`           |
| HTTP >= 500      | `InternalServerException`      |
| Other HTTP error | `APIStatusException`           |
| Timeout          | `APITimeoutException`          |
| Network error    | `APIConnectionException`       |

<Tip>
  Always wrap API calls in try-catch blocks to handle potential errors
  gracefully and provide meaningful feedback to users.
</Tip>

## Advanced Usage

### Undocumented Endpoints

Make requests to undocumented endpoints:

```php theme={null}
<?php

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);
```

### Undocumented Parameters

Send undocumented parameters to any endpoint or read undocumented response properties:

```php theme={null}
<?php

use Dodopayments\RequestOptions;

$checkoutSessionResponse = $client->checkoutSessions->create(
  productCart: [["productID" => "product_id", "quantity" => 1]],
  requestOptions: [
    'extraQueryParams' => ["my_query_parameter" => "value"],
    'extraBodyParams' => ["my_body_parameter" => "value"],
    'extraHeaders' => ["my-header" => "value"],
  ],
);
```

<Note>
  The `extra*` parameters with the same name override documented parameters.
</Note>

## Framework Integration

### Laravel

Create a service for Laravel applications:

```php theme={null}
<?php

namespace App\Services;

use Dodopayments\Client;

class PaymentService
{
    protected $client;

    public function __construct()
    {
        $this->client = new Client(
            bearerToken: config('services.dodo.api_key')
        );
    }

    public function createCheckout(array $items)
    {
        return $this->client->checkoutSessions->create(
            productCart: $items,
            returnURL: route('checkout.return')
        );
    }
}
```

Add configuration in `config/services.php`:

```php theme={null}
'dodo' => [
    'api_key' => env('DODO_API_KEY'),
    'environment' => env('DODO_ENVIRONMENT', 'test_mode')
],
```

### Symfony

Create a service in Symfony:

```php theme={null}
<?php

namespace App\Service;

use Dodopayments\Client;

class DodoPaymentService
{
    private Client $client;

    public function __construct(string $apiKey)
    {
        $this->client = new Client(bearerToken: $apiKey);
    }

    public function createPayment(string $productId, string $customerId, array $billing): object
    {
        return $this->client->payments->create(
            billing: $billing,
            customer: ['customerID' => $customerId],
            productCart: [['productID' => $productId, 'quantity' => 1]],
        );
    }
}
```

Register in `config/services.yaml`:

```yaml theme={null}
services:
  App\Service\DodoPaymentService:
    arguments:
      $apiKey: "%env(DODO_API_KEY)%"
```

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-php">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-php/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the PHP SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-php)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-php/blob/main/CONTRIBUTING.md) to get started.


# Python
Source: https://docs.dodopayments.com/developer-resources/sdks/python

Integrate Dodo Payments into your Python applications with a Pythonic interface and modern async/await support

The Python SDK offers a Pythonic interface to the Dodo Payments API, providing both synchronous and asynchronous clients with type definitions for requests and responses. It supports Python 3.9+ and includes comprehensive test coverage.

## Installation

Install the SDK using pip:

```bash theme={null}
pip install dodopayments
```

For enhanced async performance with aiohttp:

```bash theme={null}
pip install dodopayments[aiohttp]
```

<Info>
  The SDK requires Python 3.9 or higher. We recommend using the latest stable version of Python for the best experience and security updates.
</Info>

## Quick Start

### Synchronous Client

```python theme={null}
import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

checkout_session_response = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1
        }
    ],
)
print(checkout_session_response.session_id)
```

### Asynchronous Client

```python theme={null}
import os
import asyncio
from dodopayments import AsyncDodoPayments

client = AsyncDodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)


async def main() -> None:
    checkout_session_response = await client.checkout_sessions.create(
        product_cart=[
            {
                "product_id": "product_id",
                "quantity": 1,
            }
        ],
    )
    print(checkout_session_response.session_id)


asyncio.run(main())
```

<Warning>
  Always store your API keys securely using environment variables. Never commit them to version control.
</Warning>

## Core Features

<CardGroup>
  <Card title="Pythonic Interface" icon="code">
    Clean, idiomatic Python code that follows PEP 8 guidelines and Python conventions
  </Card>

  <Card title="Async/Await" icon="bolt">
    Full support for asynchronous operations with asyncio and optional aiohttp integration
  </Card>

  <Card title="Type Hints" icon="check">
    Complete type hints for better IDE support and type checking with mypy
  </Card>

  <Card title="Auto-Pagination" icon="arrows-rotate">
    Automatic pagination for list responses with simple iteration
  </Card>
</CardGroup>

## Configuration

### Environment Variables

Configure using environment variables:

```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```

### Timeouts

Configure request timeouts globally or per-request:

```python theme={null}
import httpx
from dodopayments import DodoPayments

# Configure default for all requests (default is 1 minute)
client = DodoPayments(
    timeout=20.0,  # 20 seconds
)

# More granular control
client = DodoPayments(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Override per-request
client.with_options(timeout=5.0).checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1,
        }
    ],
)
```

### Retries

Configure automatic retry behavior:

```python theme={null}
from dodopayments import DodoPayments

# Configure default for all requests (default is 2)
client = DodoPayments(
    max_retries=0,  # disable retries
)

# Override per-request
client.with_options(max_retries=5).checkout_sessions.create(
    product_cart=[
        {
            "product_id": "product_id",
            "quantity": 1,
        }
    ],
)
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```python theme={null}
session = client.checkout_sessions.create(
    product_cart=[
        {
            "product_id": "pdt_123",
            "quantity": 1
        }
    ],
    return_url="https://yourdomain.com/return"
)

print(f"Checkout URL: {session.checkout_url}")
```

### Manage Customers

Create and retrieve customer information:

```python theme={null}
# Create a customer
customer = client.customers.create(
    email="customer@example.com",
    name="John Doe",
    metadata={
        "user_id": "12345"
    }
)

# Retrieve customer
customer = client.customers.retrieve("cus_123")
print(f"Customer: {customer.name} ({customer.email})")
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```python theme={null}
# Create a subscription
subscription = client.subscriptions.create(
    billing={
        "country": "US",
        "city": "San Francisco",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={"customer_id": "cus_123"},  # or {"email": "...", "name": "..."} for a new customer
    product_id="pdt_456",
    quantity=1,
)

# Charge an on-demand subscription
# product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
charge_response = client.subscriptions.charge(
    subscription_id=subscription.subscription_id,
    product_price=2500,
)

# Retrieve usage history (for metered subscriptions)
usage_history = client.subscriptions.retrieve_usage_history(
    subscription_id=subscription.subscription_id,
    start_date="2024-01-01T00:00:00Z",
)
```

<Info>
  `billing` requires at minimum the two-letter ISO country code. `customer` accepts either `{"customer_id": ...}` to attach an existing customer or `{"email": ..., "name": ...}` to create a new one. `product_price` is in the lowest currency denomination.
</Info>

## Usage-Based Billing

### Ingest Usage Events

Track custom events for usage-based billing:

```python theme={null}
response = client.usage_events.ingest(
    events=[
        {
            "event_id": "api_call_12345",
            "customer_id": "cus_abc123",
            "event_name": "api_request",
            "timestamp": "2024-01-15T10:30:00Z",
            "metadata": {
                "endpoint": "/api/v1/users",
                "method": "GET",
                "tokens_used": "150"
            }
        }
    ]
)
```

### List and Retrieve Events

```python theme={null}
# Get a specific event
event = client.usage_events.retrieve("api_call_12345")

# List events with filtering
events = client.usage_events.list(
    customer_id="cus_abc123",
    event_name="api_request",
    page_size=20
)

for event in events.items:
    print(f"Event: {event.event_id} at {event.timestamp}")
```

## Pagination

### Auto-Pagination

Iterate through all items automatically:

```python theme={null}
from dodopayments import DodoPayments

client = DodoPayments()
all_payments = []

# Automatically fetches more pages as needed
for payment in client.payments.list():
    all_payments.append(payment)
print(all_payments)
```

### Async Pagination

```python theme={null}
import asyncio
from dodopayments import AsyncDodoPayments

client = AsyncDodoPayments()


async def main() -> None:
    all_payments = []
    # Iterate through items across all pages
    async for payment in client.payments.list():
        all_payments.append(payment)
    print(all_payments)


asyncio.run(main())
```

### Manual Pagination

For more control over pagination:

```python theme={null}
# Access items from current page
first_page = client.payments.list()
for payment in first_page.items:
    print(payment.brand_id)

# Check for more pages
if first_page.has_next_page():
    next_page = first_page.get_next_page()
    print(f"Fetched {len(next_page.items)} more items")
```

## HTTP Client Configuration

Customize the underlying `httpx` client:

```python theme={null}
import httpx
from dodopayments import DodoPayments, DefaultHttpxClient

client = DodoPayments(
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)
```

## Async with aiohttp

Use aiohttp for enhanced async performance:

```python theme={null}
import asyncio
from dodopayments import DefaultAioHttpClient
from dodopayments import AsyncDodoPayments


async def main() -> None:
    async with AsyncDodoPayments(
        bearer_token="My Bearer Token",
        http_client=DefaultAioHttpClient(),
    ) as client:
        checkout_session_response = await client.checkout_sessions.create(
            product_cart=[
                {
                    "product_id": "product_id",
                    "quantity": 1,
                }
            ],
        )
        print(checkout_session_response.session_id)


asyncio.run(main())
```

## Logging

Enable logging by setting the environment variable:

```bash theme={null}
export DODO_PAYMENTS_LOG=info
```

Or for debug-level logging:

```bash theme={null}
export DODO_PAYMENTS_LOG=debug
```

## Framework Integration

### FastAPI

```python theme={null}
from fastapi import FastAPI, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
import os

app = FastAPI()
dodo = AsyncDodoPayments(bearer_token=os.getenv("DODO_API_KEY"))

class CheckoutRequest(BaseModel):
    product_id: str
    quantity: int

@app.post("/create-checkout")
async def create_checkout(request: CheckoutRequest):
    try:
        session = await dodo.checkout_sessions.create(
            product_cart=[{
                "product_id": request.product_id,
                "quantity": request.quantity
            }],
            return_url="https://yourdomain.com/return"
        )
        return {"checkout_url": session.checkout_url}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))
```

### Django

```python theme={null}
from django.http import JsonResponse
from django.views.decorators.http import require_POST
from django.views.decorators.csrf import csrf_exempt
from dodopayments import DodoPayments
import os
import json

client = DodoPayments(bearer_token=os.getenv("DODO_PAYMENTS_API_KEY"))

@csrf_exempt
@require_POST
def create_checkout(request):
    try:
        data = json.loads(request.body)
        session = client.checkout_sessions.create(
            product_cart=[{
                "product_id": data.get("product_id"),
                "quantity": data.get("quantity", 1)
            }],
            return_url="https://yourdomain.com/return"
        )
        return JsonResponse({
            "status": "success",
            "checkout_url": session.checkout_url,
            "session_id": session.session_id
        })
    except Exception as e:
        return JsonResponse({
            "status": "error",
            "message": str(e)
        }, status=400)
```

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-python">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-python/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the Python SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-python)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-python/blob/main/CONTRIBUTING.md) to get started.


# React Native
Source: https://docs.dodopayments.com/developer-resources/sdks/react-native

Open Dodo Payments' hosted checkout from a React Native app in a system browser tab and get a typed result back in one call.

<Info>
  This is the official Dodo Payments React Native checkout SDK, `@dodopayments/react-native-checkout`. It opens Dodo's hosted checkout in a native browser view and returns a typed result. Note: an older, unrelated package named `dodopayments-react-native-sdk` (unscoped) exists with a completely different API. This page documents the current official scoped package only.
</Info>

<CardGroup>
  <Card title="Checkout Sessions API" icon="cart-shopping" href="/developer-resources/checkout-session">
    Create the checkout\_url this SDK opens, from your backend.
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    See how this fits into the full mobile payment flow.
  </Card>
</CardGroup>

The React Native SDK is a thin Turbo Module wrapper over the same native Swift and Kotlin cores. It opens `SFSafariViewController` on iOS and a Chrome Custom Tab on Android, holds no API key, and never calls the Dodo API directly. All checkout logic runs in the browser; the SDK simply manages the view lifecycle and captures the return URL.

<Warning>
  This SDK requires **New Architecture only**, React Native 0.76+, iOS 16+, and Android `minSdk` 24.
</Warning>

## Installation

<Steps>
  <Step title="Install the Package">
    <Tabs>
      <Tab title="Android">
        The package is autolinked and pulls `com.dodopayments.api:checkout-android` from Maven.

        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        ```

        No additional setup needed; the native dependency is resolved automatically.
      </Tab>

      <Tab title="iOS">
        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        cd ios && pod install
        ```

        The Swift core is bundled in the package and installed via CocoaPods.
      </Tab>

      <Tab title="Expo">
        Development builds only (not Expo Go).

        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        ```

        Then configure your `app.json` (see Register a Callback URL Scheme below).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Register a Callback URL Scheme">
    Your app must register a URL scheme to receive the return URL from the checkout.

    <Tabs>
      <Tab title="Android (Gradle)">
        In `android/app/build.gradle`:

        ```kotlin android/app/build.gradle theme={null}
        android {
            defaultConfig {
                manifestPlaceholders["dodoCallbackScheme"] = "myapp"
            }
        }
        ```

        Replace `"myapp"` with your app's scheme.
      </Tab>

      <Tab title="iOS (Info.plist)">
        In `ios/YourApp/Info.plist`:

        ```xml Info.plist theme={null}
        <key>CFBundleURLTypes</key>
        <array>
          <dict>
            <key>CFBundleURLName</key>
            <string>myapp</string>
            <key>CFBundleURLSchemes</key>
            <array>
              <string>myapp</string>
            </array>
          </dict>
        </array>
        ```

        You can also add this via Xcode's **Info → URL Types** UI.
      </Tab>

      <Tab title="Expo (both platforms)">
        The package's own config plugin registers the scheme for both platforms at
        `prebuild`. Pass it a `scheme` option in `app.json`:

        ```json app.json theme={null}
        {
          "expo": {
            "scheme": "myapp",
            "plugins": [
              [
                "@dodopayments/react-native-checkout",
                { "scheme": "myappcheckout" }
              ]
            ]
          }
        }
        ```

        `scheme` must match what you pass as `returnUrl` (e.g.
        `myappcheckout://return`), and must differ from `expo.scheme`. Expo already
        registers that one on `MainActivity`, and reusing it can route the checkout
        return to the wrong screen.

        Rebuild the native project after editing `app.json`:

        ```sh theme={null}
        npx expo prebuild --clean
        ```

        This works with development builds only, not Expo Go.

        If `android/app/build.gradle` is hand-maintained and has no standard
        `defaultConfig { }` block for the plugin to find, add the placeholder
        yourself instead. See the Android tab above.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Usage

```typescript theme={null}
import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}
```

## Forwarding the Return URL

The `Linking` listener is required for iOS's return-URL handling. On Android, `handleOpenURL` is a no-op that resolves `false` because the Android core handles its redirect natively. It's safe to register the listener unconditionally on both platforms.

```typescript theme={null}
import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});
```

## What the Result Means

<Warning>
  `result.status` is a UI hint, not proof of payment. Confirm every payment from your backend, via the `payment.succeeded` / `subscription.active` webhook.
</Warning>

<ParamField type="CheckoutStatus">
  One of `succeeded`, `failed`, `cancelled`, `pending`, `expired`.
</ParamField>

<ParamField type="string">
  Set when the return URL included one. Display it in the UI, don't use it to grant access. See Verify the Payment below.
</ParamField>

<ParamField type="string">
  Set for subscription checkouts.
</ParamField>

<ParamField type="string[]">
  Set when the checkout includes license key products.
</ParamField>

<ParamField type="string">
  Set when the checkout captures an email.
</ParamField>

<ParamField type="Record<string, string>">
  Every query parameter from the return URL, verbatim.
</ParamField>

## Verify the Payment

<CardGroup>
  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Dodo Payments calls your backend when a payment succeeds or a subscription activates.
  </Card>

  <Card title="Get Payment Detail" icon="magnifying-glass" href="/api-reference/payments/get-payments-1">
    Look up `paymentId` with your secret key to check its status directly.
  </Card>
</CardGroup>

Grant access after one of these confirms the payment, never from `result.status` alone.

## Appearance Customization

Customize the checkout browser's toolbar, buttons, and color scheme via
`customization` on `start(...)`. Options are grouped by platform because
Android's Custom Tab and iOS's `SFSafariViewController` expose different
native controls. All fields are optional; omitting `customization` uses each
platform's default appearance.

<AccordionGroup>
  <Accordion title="Android — Custom Tab">
    <ParamField type="Color">
      Toolbar background color.
    </ParamField>

    <ParamField type="Color">
      Navigation bar color.
    </ParamField>

    <ParamField type="Color">
      Divider color above the navigation bar.
    </ParamField>

    <ParamField type="'default' | 'back'">
      `default` shows the system "X" icon; `back` draws a back arrow instead.
    </ParamField>

    <ParamField type="'start' | 'end'">
      Which side of the toolbar the close button appears on.
    </ParamField>

    <ParamField type="boolean">
      Shows the toolbar's share icon.
    </ParamField>

    <ParamField type="boolean">
      Shows the page title under the URL in the toolbar.
    </ParamField>

    <ParamField type="boolean">
      Lets the toolbar auto-hide as the page scrolls.
    </ParamField>

    <ParamField type="boolean">
      Shows "Bookmark this page" in the overflow menu.
    </ParamField>

    <ParamField type="boolean">
      Shows "Download page" in the overflow menu.
    </ParamField>

    <ParamField type="'system' | 'light' | 'dark'">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>

  <Accordion title="iOS — SFSafariViewController">
    <ParamField type="'done' | 'close' | 'cancel'">
      Label or icon for the dismiss button.
    </ParamField>

    <ParamField type="'pageSheet' | 'fullScreen'">
      `pageSheet` presents as a card with swipe-to-dismiss; `fullScreen` covers the whole screen.
    </ParamField>

    <ParamField type="boolean">
      Lets the toolbar collapse on scroll. Only visible when `presentationStyle` is `fullScreen` — `pageSheet` keeps the bars pinned regardless of this setting.
    </ParamField>

    <ParamField type="'system' | 'light' | 'dark'">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>
</AccordionGroup>

```typescript theme={null}
const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});
```

## Errors

`start` rejects with a `CheckoutError` only for misuse or a platform failure. A cancelled or declined payment is always a result, never an exception.

* `INVALID_CHECKOUT_URL`: not a `checkout.dodopayments.com` session URL.
* `INVALID_RETURN_URL`: not a valid absolute URL.
* `ALREADY_IN_PROGRESS`: a checkout is already running.
* `PLATFORM_ERROR`: unexpected platform failure.

## Abandoned Sessions

If the app or the JS bundle is killed mid-checkout, the promise is lost but the native layer keeps the session. Recover it on next mount and reconcile it with your backend.

```typescript theme={null}
import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}
```

## Related

<CardGroup>
  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    The same contract for Android, iOS, and Flutter.
  </Card>

  <Card title="Expo Boilerplate" icon="layer-group" href="/developer-resources/expo-boilerplate">
    A complete Expo example with checkout integration.
  </Card>
</CardGroup>


# Ruby
Source: https://docs.dodopayments.com/developer-resources/sdks/ruby

Integrate Dodo Payments into your Ruby applications with an elegant, Ruby-native SDK

The Ruby SDK provides a simple and intuitive way to integrate Dodo Payments into your Ruby applications. It follows Ruby conventions and best practices, offering comprehensive error handling, pagination, and middleware support.

## Installation

Add the gem to your Gemfile:

```ruby Gemfile theme={null}
gem "dodopayments", "~> 2.9"
```

<Tip>
  Always use the latest SDK version to access the newest Dodo Payments features. Run `bundle update dodopayments` regularly to stay up to date.
</Tip>

Then run:

```bash theme={null}
bundle install
```

<Info>
  The SDK supports Ruby 3.2.0 and later versions, with comprehensive types, error handling, and retry mechanisms.
</Info>

## Quick Start

Initialize the client and create a checkout session:

```ruby theme={null}
require "bundler/setup"
require "dodopayments"

dodo_payments = Dodopayments::Client.new(
  bearer_token: ENV["DODO_PAYMENTS_API_KEY"], # This is the default and can be omitted
  environment: "test_mode" # defaults to "live_mode"
)

checkout_session_response = dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}]
)

puts(checkout_session_response.session_id)
```

<Warning>
  Store your API keys securely using environment variables. Never commit them to version control or expose them in your code.
</Warning>

## Core Features

<CardGroup>
  <Card title="Ruby Conventions" icon="gem">
    Follows Ruby naming conventions and idiomatic patterns
  </Card>

  <Card title="Elegant Syntax" icon="code">
    Clean, readable API that feels natural to Ruby developers
  </Card>

  <Card title="Auto-Pagination" icon="arrows-rotate">
    Built-in auto-paging iterators for list responses
  </Card>

  <Card title="Type Safety" icon="shield-check">
    Optional Sorbet types for enhanced type safety
  </Card>
</CardGroup>

## Configuration

### Timeout Configuration

Configure request timeouts:

```ruby theme={null}
# Configure default for all requests (default is 60 seconds)
dodo_payments = Dodopayments::Client.new(
  timeout: nil # disable timeout
)

# Or, configure per-request
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {timeout: 5}
)
```

### Retry Configuration

Configure automatic retry behavior:

```ruby theme={null}
# Configure default for all requests (default is 2)
dodo_payments = Dodopayments::Client.new(
  max_retries: 0 # disable retries
)

# Or, configure per-request
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {max_retries: 5}
)
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```ruby theme={null}
session = dodo_payments.checkout_sessions.create(
  product_cart: [
    {
      product_id: "pdt_123",
      quantity: 1
    }
  ],
  return_url: "https://yourdomain.com/return"
)

# Redirect to checkout
redirect_to session.checkout_url
```

### Manage Customers

Create and retrieve customer information:

```ruby theme={null}
# Create a customer
customer = dodo_payments.customers.create(
  email: "customer@example.com",
  name: "John Doe",
  metadata: {
    user_id: "12345"
  }
)

# Retrieve customer
customer = dodo_payments.customers.retrieve("cus_123")
puts "Customer: #{customer.name} (#{customer.email})"
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```ruby theme={null}
# Create a subscription
subscription = dodo_payments.subscriptions.create(
  billing: {
    country: "US",
    city: "San Francisco",
    state: "CA",
    street: "1 Market St",
    zipcode: "94105"
  },
  customer: { customer_id: "cus_123" }, # or { email: "...", name: "..." } for a new customer
  product_id: "pdt_456",
  quantity: 1
)

# Charge an on-demand subscription
# product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
charge = dodo_payments.subscriptions.charge(
  subscription.subscription_id,
  product_price: 2500
)

# Update subscription metadata
updated = dodo_payments.subscriptions.update(
  subscription.subscription_id,
  metadata: { plan_type: "premium" }
)
```

<Info>
  `billing` requires at minimum the two-letter ISO `country` code. `customer` accepts either `{ customer_id: "..." }` to attach an existing customer or `{ email: "...", name: "..." }` to create a new one. `product_price` is in the lowest currency denomination.
</Info>

## Pagination

### Auto-Pagination

Automatically iterate through all pages:

```ruby theme={null}
page = dodo_payments.payments.list

# Fetch single item from page
payment = page.items[0]
puts(payment.brand_id)

# Automatically fetches more pages as needed
page.auto_paging_each do |payment|
  puts(payment.brand_id)
end
```

### Manual Pagination

For more control over pagination:

```ruby theme={null}
page = dodo_payments.payments.list

if page.next_page?
  new_page = page.next_page
  puts(new_page.items[0].brand_id)
end
```

## Error Handling

Handle various Dodo Payments API errors:

```ruby theme={null}
begin
  checkout_session = dodo_payments.checkout_sessions.create(
product_cart: [{product_id: "product_id", quantity: 1}]
  )
rescue Dodopayments::Errors::APIConnectionError => e
  puts("The server could not be reached")
  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
rescue Dodopayments::Errors::RateLimitError => e
  puts("A 429 status code was received; we should back off a bit.")
rescue Dodopayments::Errors::APIStatusError => e
  puts("Another non-200-range status code was received")
  puts(e.status)
end
```

<Tip>
  Implement retry logic with exponential backoff for rate limit errors to ensure your application handles high-volume scenarios gracefully.
</Tip>

## Type Safety with Sorbet

Use Sorbet for type-safe request parameters:

```ruby theme={null}
# Type-safe using Sorbet RBI definitions
dodo_payments.checkout_sessions.create(
  product_cart: [
    Dodopayments::ProductItemReq.new(
      product_id: "product_id",
      quantity: 1
    )
  ]
)

# Hashes work, but are not typesafe
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}]
)

# You can also splat a full Params class
params = Dodopayments::CheckoutSessionCreateParams.new(
  product_cart: [
    Dodopayments::ProductItemReq.new(
      product_id: "product_id",
      quantity: 1
    )
  ]
)
dodo_payments.checkout_sessions.create(**params)
```

## Advanced Usage

### Undocumented Endpoints

Make requests to undocumented endpoints:

```ruby theme={null}
response = dodo_payments.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)
```

### Undocumented Parameters

Send undocumented parameters:

```ruby theme={null}
checkout_session_response = dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {
    extra_query: {my_query_parameter: value},
    extra_body: {my_body_parameter: value},
    extra_headers: {"my-header": value}
  }
)

# Access undocumented response properties
puts(checkout_session_response[:my_undocumented_property])
```

## Rails Integration

### Create an Initializer

Create `config/initializers/dodo_payments.rb`:

```ruby theme={null}
require "dodopayments"

DODO_CLIENT = Dodopayments::Client.new(
  bearer_token: Rails.application.credentials.dodo_api_key,
  environment: Rails.env.production? ? "live_mode" : "test_mode"
)
```

### Service Object Pattern

Create a payment service:

```ruby theme={null}
# app/services/payment_service.rb
class PaymentService
  def initialize
    @client = DODO_CLIENT
  end

  def create_checkout(items)
    @client.checkout_sessions.create(
      product_cart: items,
      return_url: Rails.application.routes.url_helpers.checkout_return_url
    )
  end

  def process_payment(product_id:, customer_id:, billing:)
    @client.payments.create(
      billing: billing,
      customer: { customer_id: customer_id },
      product_cart: [{ product_id: product_id, quantity: 1 }]
    )
  end
end
```

### Controller Integration

Use in your Rails controllers:

```ruby theme={null}
# app/controllers/checkouts_controller.rb
class CheckoutsController < ApplicationController
  def create
    service = PaymentService.new
    session = service.create_checkout(checkout_params[:items])
    
    redirect_to session.checkout_url, allow_other_host: true
  rescue Dodopayments::Errors::APIError => e
    flash[:error] = "Payment error: #{e.message}"
    redirect_to cart_path
  end

  private

  def checkout_params
    params.require(:checkout).permit(items: [:product_id, :quantity])
  end
end
```

## Sinatra Integration

Use with Sinatra applications:

```ruby theme={null}
require "sinatra"
require "dodopayments"

configure do
  set :dodo_client, Dodopayments::Client.new(
    bearer_token: ENV["DODO_API_KEY"]
  )
end

post "/create-checkout" do
  content_type :json
  
  begin
    session = settings.dodo_client.checkout_sessions.create(
      product_cart: JSON.parse(request.body.read)["items"],
      return_url: "#{request.base_url}/return"
    )
    
    { checkout_url: session.checkout_url }.to_json
  rescue Dodopayments::Errors::APIError => e
    status 400
    { error: e.message }.to_json
  end
end
```

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-ruby">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-ruby/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the Ruby SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-ruby)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-ruby/blob/main/CONTRIBUTING.md) to get started.


# Rust
Source: https://docs.dodopayments.com/developer-resources/sdks/rust

Integrate Dodo Payments into your Rust applications with an async-first, strongly typed SDK built on Tokio and reqwest

The Rust SDK provides convenient, async-first access to the Dodo Payments REST API from applications written in Rust. It offers strongly typed requests and responses, built-in pagination helpers, and configurable timeouts and environments.

## Installation

Add the SDK to your project with Cargo:

```bash theme={null}
cargo add dodopayments
```

Or add it to your `Cargo.toml` manually:

```toml theme={null}
[dependencies]
dodopayments = "1.106.0"
tokio = { version = "1", features = ["full"] }
serde_json = "1"
futures = "0.3" # required for streaming paginated results
```

<Info>
  The SDK requires Rust 1.75 or later, leveraging modern async features for optimal performance.
</Info>

## Quick Start

The client reads your API key from the `DODO_PAYMENTS_API_KEY` environment variable by default. Initialize the client and create your first checkout session:

```rust theme={null}
use dodopayments::Client;

#[tokio::main]
async fn main() -> dodopayments::Result<()> {
    let client = Client::from_env()?;

    let result = client
        .checkout_sessions()
        .create()
        .body(dodopayments::models::CheckoutSessionsCreateParams {
            product_cart: Some(vec![dodopayments::models::ProductItemReq {
                product_id: "product_id".to_string(),
                quantity: 1,
                addons: None,
                amount: None,
                credit_entitlements: None,
            }]),
            ..Default::default()
        })
        .await?;

    println!("{result:?}");
    Ok(())
}
```

<Warning>
  Always store your API keys securely using environment variables. Never hardcode them in your source code.
</Warning>

## Core Features

<CardGroup>
  <Card title="Async First" icon="bolt">
    Built on Tokio and reqwest with `async`/`await` support throughout
  </Card>

  <Card title="Strong Typing" icon="shield-check">
    Strongly typed requests and responses for compile-time safety
  </Card>

  <Card title="Auto-Pagination" icon="layer-group">
    Stream every item across pages or advance one page at a time
  </Card>

  <Card title="Configurable" icon="sliders">
    Configure environments, timeouts, and base URLs per client
  </Card>
</CardGroup>

## Configuration

### Environment Variables

By default, `Client::from_env()` reads your API key from the `DODO_PAYMENTS_API_KEY` environment variable and uses the default base URL unless you set `DODO_PAYMENTS_BASE_URL`:

```bash theme={null}
export DODO_PAYMENTS_API_KEY="your_api_key"
export DODO_PAYMENTS_BASE_URL="https://test.dodopayments.com" # optional
```

You can also configure the client explicitly. `Client::new` returns a `Result`, so unwrap it with `?` inside a function that returns `dodopayments::Result`:

```rust theme={null}
use dodopayments::{Client, ClientConfig};

#[tokio::main]
async fn main() -> dodopayments::Result<()> {
    let client = Client::new(
        ClientConfig::new("https://live.dodopayments.com").with_api_key("My API Key"),
    )?;
    println!("{}", client.base_url());
    Ok(())
}
```

### Environments

| Name        | Base URL                        |
| ----------- | ------------------------------- |
| `live_mode` | `https://live.dodopayments.com` |
| `test_mode` | `https://test.dodopayments.com` |

The default base URL is `https://live.dodopayments.com`. Select another environment with the `Environment` enum instead of hard-coding URLs:

```rust theme={null}
use dodopayments::{Client, ClientConfig, Environment};

let client = Client::new(
    ClientConfig::from_environment(Environment::TestMode).with_api_key("My API Key"),
)?;
```

To keep reading the API key from `DODO_PAYMENTS_API_KEY` via `from_env()` while targeting a non-default environment, override it on the config:

```rust theme={null}
use dodopayments::{Client, ClientConfig, Environment};

let client = Client::new(ClientConfig::from_env()?.with_environment(Environment::TestMode))?;
```

### Timeouts

The default request timeout is 30 seconds. Override it per client:

```rust theme={null}
use std::time::Duration;
use dodopayments::{Client, ClientConfig};

let client = Client::new(
    ClientConfig::new("https://live.dodopayments.com")
        .with_api_key("My API Key")
        .with_timeout(Duration::from_secs(60)),
)?;
```

## Common Operations

### Create a Checkout Session

Generate a checkout session:

```rust theme={null}
let session = client
    .checkout_sessions()
    .create()
    .body(dodopayments::models::CheckoutSessionsCreateParams {
        product_cart: Some(vec![dodopayments::models::ProductItemReq {
            product_id: "pdt_123".to_string(),
            quantity: 1,
            addons: None,
            amount: None,
            credit_entitlements: None,
        }]),
        return_url: Some("https://yourdomain.com/return".to_string()),
        ..Default::default()
    })
    .await?;

println!("{session:?}");
```

### Manage Customers

Create and retrieve customer information:

```rust theme={null}
// Create a customer
let customer = client
    .customers()
    .create()
    .body(dodopayments::models::CustomerCreateParams {
        email: "customer@example.com".to_string(),
        name: "John Doe".to_string(),
        ..Default::default()
    })
    .await?;

// Retrieve a customer
let customer = client
    .customers()
    .retrieve()
    .customer_id("cus_123")
    .await?;

println!("{customer:?}");
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```rust theme={null}
let subscription = client
    .subscriptions()
    .create()
    .body(dodopayments::models::SubscriptionCreateParams {
        billing: dodopayments::models::BillingAddress {
            country: "US".to_string(),
            city: "San Francisco".to_string(),
            state: "CA".to_string(),
            street: "1 Market St".to_string(),
            zipcode: "94105".to_string(),
        },
        customer: dodopayments::models::CustomerRequest::AttachExisting(
            dodopayments::models::AttachExistingCustomer {
                customer_id: "cus_123".to_string(),
            },
        ),
        product_id: "pdt_456".to_string(),
        quantity: 1,
        ..Default::default()
    })
    .await?;

println!("{subscription:?}");
```

<Info>
  `billing` requires at minimum the two-letter ISO `country` code. `customer` is a `CustomerRequest` enum — pass `AttachExisting` for an existing customer or `New` for a new one. Amount fields such as `product_price` are in the lowest currency denomination (e.g., `2500` = \$25.00 USD).
</Info>

## Usage-Based Billing

### Ingest Usage Events

Track custom events:

```rust theme={null}
let response = client
    .usage_events()
    .ingest()
    .body(dodopayments::models::UsageEventsIngestParams {
        events: Some(vec![dodopayments::models::EventInput {
            customer_id: "cus_abc123".to_string(),
            event_id: "api_call_12345".to_string(),
            event_name: "api_request".to_string(),
            metadata: None,
            timestamp: None,
        }]),
        ..Default::default()
    })
    .await?;

println!("{response:?}");
```

### List Usage Events

```rust theme={null}
let events = client
    .usage_events()
    .list()
    .query(serde_json::json!({
        "customer_id": "cus_abc123",
        "event_name": "api_request",
    }))
    .await?;

for event in &events.items {
    println!("{event:?}");
}
```

## Pagination

List endpoints return a typed page whose `items` field holds the current page of results. Stream every item across all pages with `into_stream`:

```rust theme={null}
use futures::StreamExt;

let mut items = Box::pin(
    client
        .payments()
        .list()
        .query(serde_json::json!({}))
        .await?
        .into_stream(),
);

while let Some(item) = items.next().await {
    let item = item?;
    println!("{item:?}");
}
```

Or advance one page at a time with `get_next_page`:

```rust theme={null}
let mut page = client
    .payments()
    .list()
    .query(serde_json::json!({}))
    .await?;

loop {
    for item in &page.items {
        println!("{item:?}");
    }
    match page.get_next_page().await? {
        Some(next) => page = next,
        None => break,
    }
}
```

## Error Handling

Every method returns a `dodopayments::Result<T>`. Failures are represented by the `dodopayments::Error` enum. Match on it to handle API errors distinctly from transport errors:

```rust theme={null}
let result = client
    .checkout_sessions()
    .create()
    .body(dodopayments::models::CheckoutSessionsCreateParams {
        product_cart: Some(vec![dodopayments::models::ProductItemReq {
            product_id: "product_id".to_string(),
            quantity: 1,
            addons: None,
            amount: None,
            credit_entitlements: None,
        }]),
        ..Default::default()
    })
    .await;

match result {
    Ok(value) => println!("{value:?}"),
    Err(dodopayments::Error::Api { status, message }) => {
        eprintln!("API returned {status}: {message}");
    }
    Err(err) => eprintln!("request failed: {err}"),
}
```

## Undocumented Endpoints

To call an endpoint not yet exposed as a typed method, use the low-level `request` builder, which applies authentication and the base URL:

```rust theme={null}
let response = client
    .request(reqwest::Method::GET, "/some/path")
    .send()
    .await?;
```

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-rust">
    View source code and contribute
  </Card>

  <Card title="Crates.io" icon="cube" href="https://crates.io/crates/dodopayments">
    View the published crate and versions
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>
</CardGroup>

## Support

Need help with the Rust SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-rust/issues)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-rust/blob/main/CONTRIBUTING.md) to get started.


# TypeScript
Source: https://docs.dodopayments.com/developer-resources/sdks/typescript

Integrate Dodo Payments into your TypeScript and Node.js applications with type safety and modern async/await support

The TypeScript SDK provides convenient server-side access to the Dodo Payments REST API for TypeScript and JavaScript applications. It features comprehensive type definitions, error handling, retries, timeouts, and auto-pagination for seamless payment processing.

## Installation

Install the SDK using your package manager of choice:

<CodeGroup>
  ```bash npm theme={null}
  npm install dodopayments
  ```

  ```bash yarn theme={null}
  yarn add dodopayments
  ```

  ```bash pnpm theme={null}
  pnpm add dodopayments
  ```
</CodeGroup>

## Quick Start

Initialize the client with your API key and start processing payments:

```javascript theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
  environment: 'test_mode', // defaults to 'live_mode'
});

const checkoutSessionResponse = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'product_id', quantity: 1 }],
});

console.log(checkoutSessionResponse.session_id);
```

<Warning>
  Always store your API keys securely using environment variables. Never commit them to version control or expose them in client-side code.
</Warning>

## Core Features

<CardGroup>
  <Card title="TypeScript First" icon="shield-check">
    Full TypeScript support with comprehensive type definitions for all API endpoints
  </Card>

  <Card title="Auto-Pagination" icon="arrows-rotate">
    Automatic pagination for list responses makes working with large datasets effortless
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    Built-in error types with detailed messages for different failure scenarios
  </Card>

  <Card title="Smart Retries" icon="repeat">
    Configurable automatic retries with exponential backoff for transient errors
  </Card>
</CardGroup>

## Configuration

### Environment Variables

Set environment variables for secure configuration:

```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```

### Timeout Configuration

Configure request timeouts globally or per-request:

```typescript theme={null}
// Configure default timeout for all requests (default is 1 minute)
const client = new DodoPayments({
  timeout: 20 * 1000, // 20 seconds
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 1 }] },
  { timeout: 5 * 1000 },
);
```

### Retry Configuration

Configure automatic retry behavior:

```javascript theme={null}
// Configure default for all requests (default is 2 retries)
const client = new DodoPayments({
  maxRetries: 0, // disable retries
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 1 }] },
  { maxRetries: 5 },
);
```

<Tip>
  The SDK automatically retries requests that fail due to network errors or server issues (5xx responses) with exponential backoff.
</Tip>

## Common Operations

### Create a Checkout Session

Generate a checkout session for collecting payment information:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  return_url: 'https://yourdomain.com/return'
});

console.log('Redirect to:', session.checkout_url);
```

### Manage Customers

Create and retrieve customer information:

```typescript theme={null}
// Create a customer
const customer = await client.customers.create({
  email: 'customer@example.com',
  name: 'John Doe',
  metadata: {
    user_id: '12345'
  }
});

// Retrieve customer
const retrieved = await client.customers.retrieve('cus_123');
console.log(`Customer: ${retrieved.name} (${retrieved.email})`);
```

### Handle Subscriptions

Create and manage recurring subscriptions:

<Warning>
  `POST /subscriptions` (the SDK's `subscriptions.create` method) is **deprecated**. It still works for existing integrations, but new integrations should create subscriptions through a [Checkout Session](/developer-resources/checkout-session).
</Warning>

```typescript theme={null}
// Create a subscription
const subscription = await client.subscriptions.create({
  billing: {
    country: 'US',
    city: 'San Francisco',
    state: 'CA',
    street: '1 Market St',
    zipcode: '94105',
  },
  customer: {
    customer_id: 'cus_123', // or pass { email, name } to create a new customer
  },
  product_id: 'pdt_456',
  quantity: 1,
});

// Charge an on-demand subscription
// product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
const chargeResponse = await client.subscriptions.charge(subscription.subscription_id, {
  product_price: 2500,
});

// Retrieve subscription usage history (for metered subscriptions)
const usageHistory = await client.subscriptions.retrieveUsageHistory(subscription.subscription_id, {
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-03-31T23:59:59Z',
});
```

<Info>
  `billing` requires at minimum the two-letter ISO country code. `customer` is a union of `{ customer_id }` (to attach an existing customer) or `{ email, name? }` (to create a new one). `product_price` is expressed in the lowest currency denomination.
</Info>

## Usage-Based Billing

### Ingest Usage Events

Track custom events for usage-based billing:

```typescript theme={null}
await client.usageEvents.ingest({
  events: [
    {
      event_id: 'api_call_12345',
      customer_id: 'cus_abc123',
      event_name: 'api_request',
      timestamp: '2024-01-15T10:30:00Z',
      metadata: {
        endpoint: '/api/v1/users',
        method: 'GET',
        tokens_used: '150'
      }
    }
  ]
});
```

<Info>
  Events must have unique `event_id` values for idempotency. Duplicate IDs within the same request are rejected, and subsequent requests with existing IDs are ignored.
</Info>

### Retrieve Usage Events

Fetch detailed information about usage events:

```typescript theme={null}
// Get a specific event
const event = await client.usageEvents.retrieve('api_call_12345');

// List events with filtering
const events = await client.usageEvents.list({
  customer_id: 'cus_abc123',
  event_name: 'api_request',
  start: '2024-01-14T10:30:00Z',
  end: '2024-01-15T10:30:00Z'
});
```

## Proxy Configuration

Configure proxy settings for different runtimes:

### Node.js (using undici)

```typescript theme={null}
import DodoPayments from 'dodopayments';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new DodoPayments({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});
```

### Bun

```typescript theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});
```

### Deno

```typescript theme={null}
import DodoPayments from 'npm:dodopayments';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new DodoPayments({
  fetchOptions: {
    client: httpClient,
  },
});
```

## Logging

Control log verbosity using environment variables or client options:

```typescript theme={null}
// Via client option
const client = new DodoPayments({
  logLevel: 'debug', // Show all log messages
});
```

```bash theme={null}
# Via environment variable
export DODO_PAYMENTS_LOG=debug
```

**Available log levels:**

* `'debug'` - Show debug messages, info, warnings, and errors
* `'info'` - Show info messages, warnings, and errors
* `'warn'` - Show warnings and errors (default)
* `'error'` - Show only errors
* `'off'` - Disable all logging

<Warning>
  At the debug level, all HTTP requests and responses are logged, including headers and bodies. Some authentication headers are redacted, but sensitive data in bodies may still be visible.
</Warning>

## Migration from Node.js SDK

If you're upgrading from the legacy Node.js SDK, the TypeScript SDK offers improved type safety and features:

<Card title="View Migration Guide" icon="arrow-right" href="https://github.com/dodopayments/dodopayments-typescript/blob/main/MIGRATION.md">
  Learn how to migrate from the Node.js SDK to the TypeScript SDK
</Card>

## Auto-Pagination

List methods in the DodoPayments API are paginated. You can use the `for await … of` syntax to iterate through items across all pages:

```typescript theme={null}
async function fetchAllPayments() {
  const allPayments = [];
  // Automatically fetches more pages as needed.
  for await (const paymentListResponse of client.payments.list()) {
    allPayments.push(paymentListResponse);
  }
  return allPayments;
}
```

Alternatively, you can request a single page at a time:

```typescript theme={null}
let page = await client.payments.list();
for (const paymentListResponse of page.items) {
  console.log(paymentListResponse);
}

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}
```

## Requirements

The following runtimes are supported:

* Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
* Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions
* Deno v1.28.0 or higher
* Bun 1.0 or later
* Cloudflare Workers
* Vercel Edge Runtime
* Jest 28 or greater with the `"node"` environment
* Nitro v2.6 or greater

TypeScript >= 4.9 is supported.

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-typescript">
    View source code and contribute
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and connect with developers
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-typescript/issues">
    Report bugs or request features
  </Card>
</CardGroup>

## Support

Need help with the TypeScript SDK?

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-typescript)

## Contributing

We welcome contributions! Check the [contributing guidelines](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md) to get started.


# Tanstack Adaptor
Source: https://docs.dodopayments.com/developer-resources/tanstack-adaptor

Learn how to integrate Dodo Payments with your Tanstack App Router project using our Tanstack Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your Tanstack app.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/tanstack
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_RETURN_URL=your-return-url
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using the Tanstack App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Tanstack app. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript Tanstack Route Handler expandable theme={null}
      // src/routes/api/checkout.ts
      import { Checkout } from "@dodopayments/tanstack";
      import { createServerFileRoute } from "@tanstack/react-start/server";

      export const ServerRoute = createServerFileRoute("/api/checkout")
      .methods({
          GET: async ({ request }) => {
          return Checkout({
              bearerToken: process.env.DODO_PAYMENTS_API_KEY,
              returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
              environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
              type: "static", // optional, defaults to 'static'
          })(request)
          },
          POST: async ({ request }) => {
          return Checkout({
              bearerToken: process.env.DODO_PAYMENTS_API_KEY,
              returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
              environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
              type: "session", // or "dynamic" for dynamic link
          })(request)
          }
      })

      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Tanstack Route Handler expandable theme={null}
      // src/routes/api/customer-portal.ts
      import { CustomerPortal } from "@dodopayments/tanstack";
      import { createServerFileRoute } from "@tanstack/react-start/server";

      export const ServerRoute = createServerFileRoute('/api/customer-portal')
      .methods({
          GET: async ({ request }) => {
          return CustomerPortal({
              bearerToken: process.env.DODO_PAYMENTS_API_KEY,
              environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          })(request)
          }
      })
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Tanstack app.
    </Info>

    <CodeGroup>
      ```typescript Tanstack Route Handler expandable theme={null}
      // src/routes/api/webhook.ts
      import { Webhooks } from "@dodopayments/tanstack";
      import { createServerFileRoute } from "@tanstack/react-start/server";

      export const ServerRoute = createServerFileRoute('/api/webhook')
      .methods({
          POST: async ({ request }) => {
          return Webhooks({
              webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
              onPayload: async (payload) => {
              console.log(payload)
              }
          })(request)
          }
      })
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Tanstack application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```

You are an expert Tanstack developer assistant. Your task is to guide a user through integrating the @dodopayments/tanstack adapter into their existing Tanstack project.

The @dodopayments/tanstack adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for the Tanstack App Router.

First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):

npm install @dodopayments/tanstack

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/tanstack adapter would you like to integrate into your project? You can choose one or more of the following:

    Checkout Route Handler (for handling product checkouts)

    Customer Portal Route Handler (for managing customer subscriptions/details)

    Webhook Route Handler (for receiving Dodo Payments webhook events)

    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Route Handler is selected:

Purpose: This handler redirects users to the Dodo Payments checkout page.
File Creation: Create a new file at app/checkout/route.ts in your Tanstack project.

Code Snippet:

// src/routes/api/checkout.ts
import { Checkout } from "@dodopayments/tanstack";
import { createServerFileRoute } from "@tanstack/react-start/server";

export const ServerRoute = createServerFileRoute("/api/checkout")
  .methods({
    GET: async ({ request }) => {
      return Checkout({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        type: "static", // optional, defaults to 'static'
      })(request)
    },
    POST: async ({ request }) => {
      return Checkout({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
        type: "session", // or "dynamic" for dynamic link
      })(request)
    }
  })


Configuration & Usage:

    bearerToken: Your Dodo Payments API key. It's recommended to set this via the DODO_PAYMENTS_API_KEY environment variable.

    returnUrl: (Optional) The URL to redirect the user to after a successful checkout.

    environment: (Optional) Set to "test_mode" for testing, or omit/set to "live_mode" for production.

    type: (Optional) Set to "static" for GET/static checkout, "dynamic" for POST/dynamic checkout, or "session" for POST/checkout sessions.

Static Checkout (GET) Query Parameters:

    productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)

    quantity (optional): Quantity of the product

    Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode

    Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode

    Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts

    Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)

    Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}

Dynamic Checkout (POST) - Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}. For a complete list of supported POST body fields, refer to:

    Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments

    Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions


Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

Error Handling: If productId is missing or other query parameters are invalid, the handler will return a 400 response.

If Customer Portal Route Handler is selected:

Purpose: This handler redirects authenticated users to their Dodo Payments customer portal.
File Creation: Create a new file at app/customer-portal/route.ts in your Tanstack project.

Code Snippet:

// src/routes/api/customer-portal.ts
import { CustomerPortal } from "@dodopayments/tanstack";
import { createServerFileRoute } from "@tanstack/react-start/server";

export const ServerRoute = createServerFileRoute('/api/customer-portal')
  .methods({
    GET: async ({ request }) => {
      return CustomerPortal({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      })(request)
    }
  })

Query Parameters:

    customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)

    send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.

    Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at app/api/webhook/dodo-payments/route.ts in your Tanstack project.

Code Snippet:

// src/routes/api/webhook.ts
import { Webhooks } from "@dodopayments/tanstack";
import { createServerFileRoute } from "@tanstack/react-start/server";

export const ServerRoute = createServerFileRoute('/api/webhook')
  .methods({
    POST: async ({ request }) => {
      return Webhooks({
        webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
        onPayload: async (payload) => {
          console.log(payload)
        }
      })(request)
    }
  })

Handler Details:

    Method: Only POST requests are supported. Other methods return 405.

    Signature Verification: The handler verifies the webhook signature using the webhookKey and returns 401 if verification fails.

    Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:

    401: Invalid signature

    400: Invalid payload

    500: Internal error during verification

Event Routing: Calls the appropriate event handler based on the payload type.

Supported Webhook Event Handlers:

    onPayload?: (payload: WebhookPayload) => Promise<void>

    onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>

    onPaymentFailed?: (payload: WebhookPayload) => Promise<void>

    onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>

    onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>

    onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>

    onRefundFailed?: (payload: WebhookPayload) => Promise<void>

    onDisputeOpened?: (payload: WebhookPayload) => Promise<void>

    onDisputeExpired?: (payload: WebhookPayload) => Promise<void>

    onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>

    onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>

    onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>

    onDisputeWon?: (payload: WebhookPayload) => Promise<void>

    onDisputeLost?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>

    onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>

    onDunningStarted?: (payload: WebhookPayload) => Promise<void>

    onDunningRecovered?: (payload: WebhookPayload) => Promise<void>

    onCreditAdded?: (payload: WebhookPayload) => Promise<void>

    onCreditDeducted?: (payload: WebhookPayload) => Promise<void>

    onCreditExpired?: (payload: WebhookPayload) => Promise<void>

    onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>

    onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>

    onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>

    onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>

    onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

    Environment Variable Setup:

To ensure the adapter functions correctly, you will need to manually set up the following environment variables in your Tanstack project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):

    DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).

    RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

    DODO_PAYMENTS_WEBHOOK_SECRET: Your Dodo Payments Webhook Secret (required for Webhook handler).

Example .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=your-return-url
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"

Usage in your code:

bearerToken: process.env.DODO_PAYMENTS_API_KEY
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance. You can also add comments to their PR or chat depending on the context

```


# Balances
Source: https://docs.dodopayments.com/features/account-summary-payout-wallet

Track your financial activity across multi-currency wallets with comprehensive transaction ledgers, including payments, refunds, fees, and payouts in USD, GBP, and EUR.

## Introduction

The **Balances** section provides merchants with a comprehensive overview of their financial activity across all currencies. It includes every transaction type - payments, refunds, fees, taxes, and payouts - ensuring full visibility into both earnings and deductions.

## Key Details

<Frame>
  <img alt="Balances dashboard showing wallet overview and transaction ledger" />
</Frame>

## Wallet Structure

Each business account maintains **three native wallets** based on supported payout currencies:

| Wallet     | Currency Code |
| ---------- | ------------- |
| USD Wallet | USD           |
| GBP Wallet | GBP           |
| EUR Wallet | EUR           |

### Wallet Logic

* Merchant sales are **credited to the appropriate wallet** based on the **customer's payment currency** and **geographic location**.
* This system optimizes for **payment processor efficiency**, **reduced transaction fees** and **lower currency conversion charges**.

## Balance Ledger

Each wallet has an **independent ledger** recording all related financial activity - payments, refunds, fees, and payouts - in that specific wallet's currency.

A **Consolidated Ledger** combines all wallet data, offering a unified view of the merchant's entire financial history.

### Filters and Navigation

* **Currency Filter:** Allows merchants to view transactions by specific wallet (USD, GBP, EUR).
* **All Transactions View:** Provides an aggregated view across all wallets with unified sorting, filtering, and search capabilities.

### Transaction Types

The following transaction types are recorded in the Balance ledger:

| Transaction Type     | Symbol     | Description                                       |
| -------------------- | ---------- | ------------------------------------------------- |
| **Payment**          | Credit (+) | Successful customer payment                       |
| **Refund**           | Debit (-)  | Returned amount to the customer                   |
| **Transaction Fees** | Debit (-)  | Processing fees applied to payments               |
| **Refund Fees**      | Debit (-)  | Fees deducted for processing refunds              |
| **Sales Tax**        | Debit (-)  | Tax amount charged on payments                    |
| **Sales Tax Refund** | Credit (+) | Refunded portion of sales tax on refunds          |
| **Payout**           | Debit (-)  | Amount transferred to the merchant's bank account |
| **Payout Fees**      | Debit (-)  | Transaction fees deducted from payouts            |

#### Additional Fields

* **Transaction Amount:** Total value associated with the transaction.
* **Transaction Timestamp:** Date and time of transaction completion.
* **Transaction ID:** Unique identifier for tracking and support purposes.

## Total Balance

The **Total Balance** section shows a **consolidated indicative amount** of all wallet balances - **USD, GBP, and EUR** - after conversion to USD.

<Note>
  **Indicative Display:** The displayed amount is **for reference only**. Final payout amounts may vary based on the actual exchange rate at the time of transfer.
</Note>

## Conclusion

The **Balances** aims to deliver **transparency, accuracy, and flexibility** in managing multi-currency funds.

By maintaining separate native wallets, providing currency-based filters, and enabling indicative consolidated views, Dodo Payments ensures merchants always have a clear understanding of their earnings and payout readiness.

<Tip>
  For any discrepancies or clarifications, please reach out to **[support@dodopayments.com](mailto:support@dodopayments.com)** with your **Transaction ID** and issue details.
</Tip>


# Adaptive Currency
Source: https://docs.dodopayments.com/features/adaptive-currency

Display prices in each customer's local currency to reduce friction and improve conversion. Automatic detection, conversion, and same‑currency refunds.

<Info>
  Adaptive Currency lets you show localized prices and accept payments in customers' local currencies. This reduces friction at checkout and builds trust.
</Info>

## What Is Adaptive Currency?

Adaptive Currency displays product prices in the customer's local currency instead of only your base currency. When enabled, checkout defaults to the detected local currency for supported countries, with the option to switch back to your base currency.

Your base currency is whatever you priced the product or add-on in — it can be any currency Dodo Payments can charge, not just USD. Adaptive Currency converts that base price at live exchange rates. To set your own fixed price per currency or country instead, see [Localized Pricing](/features/localized-pricing).

## Key Benefits

* **Localized payment experience**: Prices appear in local currency by default.
* **More payment methods**: Unlocks payment methods available for the local currency.
* **Same‑currency refunds**: Refund the customer in the currency they paid with.

## Enable Adaptive Currency

<Steps>
  <Step title="Open Settings">
    Log in to your Merchant Dashboard and go to Settings → Business.
  </Step>

  <Step title="Toggle Adaptive Pricing">
    Enable the Adaptive Pricing toggle. You can disable it at any time.

    <Warning>
      Changes apply only to future transactions.
    </Warning>
  </Step>

  <Step title="Confirm and Save">
    Save your settings.

    <Check>
      Verify a test checkout shows prices in your local currency when supported.
    </Check>
  </Step>
</Steps>

<Frame>
  <img alt="Adaptive Currency" />
</Frame>

## Customer Experience

1. **Detection**: The system detects the customer's country based on the billing address.
2. **Currency selection**: If the country is supported, prices show in the local currency by default. Customers can switch back to your base currency.
3. **Payment methods**: Localized payment methods appear where applicable.
4. **Checkout**: Payment is completed in the selected currency.

## Conversion and Fees

Adaptive Currency charges the customer in their local currency using the latest exchange rates.

* **You pay**: 0% (default) or 2–4% (when fees inclusive is enabled)
* **Your customers pay**: 2–4% based on order value (default) or 0% (when fees inclusive is enabled)

Tiered fees applied at checkout:

* 4% for orders under \$500
* 3% for 500 to \$1,500
* 2% for over \$1,500

### Choose who bears the fee

By default, adaptive currency fees are added on top of your displayed price and borne by the customer. With the **Fees Inclusive** setting, you can absorb the fee yourself: the customer sees the same local-currency price they always would, and the fee is deducted from your settlement.

<Steps>
  <Step title="Enable Adaptive Pricing">
    Go to **Settings → Business** and enable the Adaptive Pricing toggle if you haven't already.
  </Step>

  <Step title="Toggle Fees Inclusive">
    Once Adaptive Pricing is on, enable the **Fees Inclusive** sub-toggle in the same section.
  </Step>
</Steps>

| Mode                | Customer sees                 | Merchant settles              |
| ------------------- | ----------------------------- | ----------------------------- |
| Exclusive (default) | Local price + 2–4% fee on top | Full base price               |
| Inclusive           | Local price (unchanged)       | Base price minus the 2–4% fee |

You can also override the merchant default per request by passing `adaptive_currency_fees_inclusive` (boolean) on a one-time payment, an on-demand subscription (`on_demand.adaptive_currency_fees_inclusive`), a subscription charge, or a plan change. It is not accepted on checkout sessions:

```typescript theme={null}
const payment = await client.payments.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  adaptive_currency_fees_inclusive: true, // override the business setting for this payment
  return_url: 'https://yoursite.com/return'
});
```

<Info>
  INR → INR transactions are always treated as inclusive regardless of the business setting or per-request override.
</Info>

<Info>
  When a [Localized Pricing](/features/localized-pricing) rule matches, the transaction is always treated as inclusive, regardless of your **Fees Inclusive** setting or any per-request override. The customer pays exactly the localized amount you set, and the conversion fee is deducted from your settlement.
</Info>

## Supported Currencies

| Currency Code | Currency Name                       | Countries                                                                                                                                                                                                                     | Minimum Amount |
| ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| AED           | UAE Dirham                          | United Arab Emirates                                                                                                                                                                                                          | 2.00 AED       |
| ALL           | Albanian Lek                        | Albania                                                                                                                                                                                                                       | 50.00 ALL      |
| AMD           | Armenian Dram                       | Armenia                                                                                                                                                                                                                       | 500.00 AMD     |
| AUD           | Australian Dollar                   | Australia, Nauru                                                                                                                                                                                                              | 0.50 AUD       |
| AWG           | Aruban Florin                       | Aruba                                                                                                                                                                                                                         | 2.00 AWG       |
| AZN           | Azerbaijani Manat                   | Azerbaijan                                                                                                                                                                                                                    | 2.00 AZN       |
| BAM           | Bosnia-Herzegovina Convertible Mark | Bosnia and Herzegovina                                                                                                                                                                                                        | 2.00 BAM       |
| BDT           | Bangladeshi Taka                    | Bangladesh                                                                                                                                                                                                                    | 100.00 BDT     |
| BMD           | Bermudian Dollar                    | Bermuda                                                                                                                                                                                                                       | 1.00 BMD       |
| BND           | Brunei Dollar                       | Brunei                                                                                                                                                                                                                        | 1.00 BND       |
| BOB           | Bolivian Boliviano                  | Bolivia                                                                                                                                                                                                                       | 5.00 BOB       |
| BRL           | Brazilian Real                      | Brazil                                                                                                                                                                                                                        | 0.50 BRL       |
| BSD           | Bahamian Dollar                     | Bahamas                                                                                                                                                                                                                       | 1.00 BSD       |
| BWP           | Botswanan Pula                      | Botswana                                                                                                                                                                                                                      | 15.00 BWP      |
| BZD           | Belize Dollar                       | Belize                                                                                                                                                                                                                        | 2.00 BZD       |
| CAD           | Canadian Dollar                     | Canada                                                                                                                                                                                                                        | 0.50 CAD       |
| CHF           | Swiss Franc                         | Switzerland, Liechtenstein                                                                                                                                                                                                    | 0.50 CHF       |
| CLP           | Chilean Peso                        | Chile                                                                                                                                                                                                                         | 1000.00 CLP    |
| CNY           | Chinese Yuan                        | China                                                                                                                                                                                                                         | 4.00 CNY       |
| CRC           | Costa Rican Colón                   | Costa Rica                                                                                                                                                                                                                    | 500.00 CRC     |
| CZK           | Czech Koruna                        | Czech Republic                                                                                                                                                                                                                | 15.00 CZK      |
| DKK           | Danish Krone                        | Denmark, Greenland                                                                                                                                                                                                            | 2.50 DKK       |
| DOP           | Dominican Peso                      | Dominican Republic                                                                                                                                                                                                            | 100.00 DOP     |
| EGP           | Egyptian Pound                      | Egypt                                                                                                                                                                                                                         | 50.00 EGP      |
| ETB           | Ethiopian Birr                      | Ethiopia                                                                                                                                                                                                                      | 100.00 ETB     |
| EUR           | Euro                                | Austria, Belgium, Cyprus, Estonia, Finland, France, Germany, Greece, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Portugal, Slovakia, Slovenia, Spain, Andorra, Monaco, Croatia, San Marino, Montenegro | 0.50 EUR       |
| FJD           | Fijian Dollar                       | Fiji                                                                                                                                                                                                                          | 2.00 FJD       |
| GBP           | British Pound                       | United Kingdom                                                                                                                                                                                                                | 0.30 GBP       |
| GEL           | Georgian Lari                       | Georgia                                                                                                                                                                                                                       | 3.00 GEL       |
| GMD           | Gambian Dalasi                      | Gambia                                                                                                                                                                                                                        | 100.00 GMD     |
| GTQ           | Guatemalan Quetzal                  | Guatemala                                                                                                                                                                                                                     | 10.00 GTQ      |
| GYD           | Guyanese Dollar                     | Guyana                                                                                                                                                                                                                        | 200.00 GYD     |
| HKD           | Hong Kong Dollar                    | Hong Kong                                                                                                                                                                                                                     | 4.00 HKD       |
| HNL           | Honduran Lempira                    | Honduras                                                                                                                                                                                                                      | 25.00 HNL      |
| HUF           | Hungarian Forint                    | Hungary                                                                                                                                                                                                                       | 175.00 HUF     |
| IDR           | Indonesian Rupiah                   | Indonesia                                                                                                                                                                                                                     | 8500.00 IDR    |
| ILS           | Israeli New Shekel                  | Israel                                                                                                                                                                                                                        | 3.00 ILS       |
| INR           | Indian Rupee                        | India                                                                                                                                                                                                                         | 5.00 INR       |
| JPY           | Japanese Yen                        | Japan                                                                                                                                                                                                                         | 50 JPY         |
| KRW           | South Korean Won                    | South Korea                                                                                                                                                                                                                   | 50 KRW         |
| KZT           | Kazakhstani Tenge                   | Kazakhstan                                                                                                                                                                                                                    | 500.00 KZT     |
| LKR           | Sri Lankan Rupee                    | Sri Lanka                                                                                                                                                                                                                     | 300.00 LKR     |
| LRD           | Liberian Dollar                     | Liberia                                                                                                                                                                                                                       | 200.00 LRD     |
| LSL           | Lesotho Loti                        | Lesotho                                                                                                                                                                                                                       | 20.00 LSL      |
| MAD           | Moroccan Dirham                     | Morocco                                                                                                                                                                                                                       | 10.00 MAD      |
| MKD           | Macedonian Denar                    | North Macedonia                                                                                                                                                                                                               | 50.00 MKD      |
| MOP           | Macanese Pataca                     | Macau                                                                                                                                                                                                                         | 10.00 MOP      |
| MUR           | Mauritian Rupee                     | Mauritius                                                                                                                                                                                                                     | 50.00 MUR      |
| MVR           | Maldivian Rufiyaa                   | Maldives                                                                                                                                                                                                                      | 15.00 MVR      |
| MWK           | Malawian Kwacha                     | Malawi                                                                                                                                                                                                                        | 2000.00 MWK    |
| MXN           | Mexican Peso                        | Mexico                                                                                                                                                                                                                        | 10.00 MXN      |
| MYR           | Malaysian Ringgit                   | Malaysia                                                                                                                                                                                                                      | 4.00 MYR       |
| NGN           | Nigerian Naira                      | Nigeria                                                                                                                                                                                                                       | 2000.00 NGN    |
| NOK           | Norwegian Krone                     | Norway                                                                                                                                                                                                                        | 3.00 NOK       |
| NPR           | Nepalese Rupee                      | Nepal                                                                                                                                                                                                                         | 150.00 NPR     |
| NZD           | New Zealand Dollar                  | New Zealand                                                                                                                                                                                                                   | 1.00 NZD       |
| PEN           | Peruvian Sol                        | Peru                                                                                                                                                                                                                          | 3.00 PEN       |
| PGK           | Papua New Guinean Kina              | Papua New Guinea                                                                                                                                                                                                              | 4.00 PGK       |
| PHP           | Philippine Peso                     | Philippines                                                                                                                                                                                                                   | 50.00 PHP      |
| PLN           | Polish Zloty                        | Poland                                                                                                                                                                                                                        | 2.00 PLN       |
| PYG           | Paraguayan Guaraní                  | Paraguay                                                                                                                                                                                                                      | 4000 PYG       |
| QAR           | Qatari Rial                         | Qatar                                                                                                                                                                                                                         | 3.00 QAR       |
| RON           | Romanian Leu                        | Romania                                                                                                                                                                                                                       | 2.00 RON       |
| RSD           | Serbian Dinar                       | Serbia                                                                                                                                                                                                                        | 60.00 RSD      |
| SAR           | Saudi Riyal                         | Saudi Arabia                                                                                                                                                                                                                  | 2.00 SAR       |
| SBD           | Solomon Islands Dollar              | Solomon Islands                                                                                                                                                                                                               | 10.00 SBD      |
| SCR           | Seychellois Rupee                   | Seychelles                                                                                                                                                                                                                    | 15.00 SCR      |
| SEK           | Swedish Krona                       | Sweden                                                                                                                                                                                                                        | 3.00 SEK       |
| SGD           | Singapore Dollar                    | Singapore                                                                                                                                                                                                                     | 0.50 SGD       |
| SZL           | Swazi Lilangeni                     | Eswatini                                                                                                                                                                                                                      | 20.00 SZL      |
| THB           | Thai Baht                           | Thailand                                                                                                                                                                                                                      | 25.00 THB      |
| TOP           | Tongan Paʻanga                      | Tonga                                                                                                                                                                                                                         | 2.00 TOP       |
| TRY           | Turkish Lira                        | Turkey                                                                                                                                                                                                                        | 20.00 TRY      |
| TWD           | New Taiwan Dollar                   | Taiwan                                                                                                                                                                                                                        | 20.00 TWD      |
| TZS           | Tanzanian Shilling                  | Tanzania                                                                                                                                                                                                                      | 3000.00 TZS    |
| UYU           | Uruguayan Peso                      | Uruguay                                                                                                                                                                                                                       | 50.00 UYU      |
| VND           | Vietnamese Dong                     | Vietnam                                                                                                                                                                                                                       | 12000 VND      |
| WST           | Samoan Tala                         | Samoa                                                                                                                                                                                                                         | 2.00 WST       |
| XAF           | Central African CFA Franc           | Cameroon, Central African Republic, Chad, Republic of the Congo, Equatorial Guinea, Gabon                                                                                                                                     | 300 XAF        |
| XOF           | West African CFA Franc              | Benin, Burkina Faso, Côte d'Ivoire, Guinea-Bissau, Mali, Niger, Senegal, Togo                                                                                                                                                 | 300 XOF        |
| ZAR           | South African Rand                  | South Africa                                                                                                                                                                                                                  | 20.00 ZAR      |
| ZMW           | Zambian Kwacha                      | Zambia                                                                                                                                                                                                                        | 30.00 ZMW      |

## Refunds and Adjustments

Dodo Payments issues refunds in the currency the customer originally paid, using the latest exchange rate. The amount in your base currency remains fixed on your dashboard, invoices, and in the refund. This means the customer may receive more or less than the original local‑currency amount depending on FX changes.

<Info>
  Adaptive Currency fees which are generally the FX fees are not refunded.
</Info>

**Example refund**

1. You sell a product for 100 USD with Adaptive Currency enabled.
2. A Canadian customer sees 137 CAD at an exchange rate of 1.37 CAD per 1 USD and completes the purchase.
3. We process the payment, converting 137 CAD to 100 USD for your settlement.
4. Later, the exchange rate changes to 1.40 CAD per 1 USD and you issue a full refund.
5. We deduct 100 USD and refund the customer 140 CAD.

## Invoices and Taxation

* Invoices show only the settlement currency amount.
* Taxes and platform fees are calculated on the settlement currency amount.
* Example: a \$10 sale converted to 36 AED still reflects as \$10 in the Dashboard and invoices.

<Info>
  All amounts are rounded according to Dodo Payments' internal rounding logic.
</Info>

## Integration Examples

**Checkout Sessions with billing currency**

Pass `billing_currency` to explicitly set the billing currency for the session.

<Info>
  When Adaptive Pricing is disabled, `billing_currency` is ignored.
</Info>

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_one_time_or_subscription',
      quantity: 1
    }
  ],
  billing_currency: 'AED',
  return_url: 'https://example.com/return'
});
```

<Card title="Checkout Session" icon="code" href="/api-reference/checkout-sessions/create">
  Configure Billing Currency using our Checkout Session API.
</Card>


# Add-ons for Subscriptions
Source: https://docs.dodopayments.com/features/addons

Enhance your subscription products with flexible add-ons for seat-based billing, feature upgrades, and creative pricing models

<Info>
  Add-ons are additional products that can be attached to your main subscription products, enabling flexible pricing models and enhanced customer experiences. Whether you need seat-based billing, feature upgrades, or custom pricing structures, add-ons give you the power to create sophisticated subscription offerings.
</Info>

<CardGroup>
  <Card title="Seat-Based Billing" icon="users" href="/developer-resources/seat-based-pricing">
    Create add-ons for additional team seats, user licenses, or capacity upgrades with per-seat pricing.
  </Card>

  <Card title="Usage Extensions" icon="bolt" href="/features/usage-based-billing/introduction">
    Extend usage limits, API calls, or data allowances with flexible add-on pricing.
  </Card>
</CardGroup>

## What Are Add-ons?

Add-ons are supplementary products that customers can purchase alongside their main subscription. They're perfect for:

* **Seat-based billing**: Additional team members, user licenses, or concurrent users
* **Feature upgrades**: Premium features, advanced analytics, or priority support
* **Usage extensions**: Extra storage, API calls, or bandwidth allowances
* **Service add-ons**: Professional services, training, or consultation hours

<Frame>
  <img alt="Add-ons attached to subscription products in the dashboard" />
</Frame>

## Key Benefits

* **Flexible Pricing Models**: Offer base plans with optional add-ons to create sophisticated pricing structures. You can address diverse customer segments with upgrades that grow as your customers' needs change.
* **Revenue Optimization**: Boost your average revenue per user (ARPU) by presenting relevant add-ons. This enables natural upsell opportunities as customers add features over time.
* **Simplified Management**: Manage all pricing components from one dashboard. Add-ons are automatically included in both checkout sessions and subscription management.
* **Customer Choice**: Allow customers to customize their subscriptions by selecting only the add-ons they need, which enhances satisfaction and reduces churn.

## Creating Add-ons

Add-ons are created as separate products in your Dodo Payments dashboard and then attached to your main subscription products. This separation allows you to:

* Reuse add-ons across multiple subscription products
* Manage pricing independently
* Track add-on performance separately
* Update add-ons without affecting base subscriptions

<Frame>
  <img alt="Creating add-ons in the dashboard interface" />
</Frame>

### Add-on Configuration

When creating add-ons, you can configure:

* **Pricing**: Set the add-on amount (`price`) in the smallest currency unit. The add-on is billed on the parent subscription's cycle
* **Currency**: Set the base price in any currency Dodo Payments can charge. The searchable currency selector pins **USD, GBP, EUR, and INR** to the top; customers outside your base currency are billed through [Adaptive Currency](/features/adaptive-currency)
* **Quantity**: Customers choose a quantity when the add-on is attached to a subscription
* **Availability**: Control which subscription products can use the add-on
* **Tax settings**: Configure the appropriate `tax_category`

### Getting Started

Ready to implement add-ons in your subscription business? Here's how to get started:

<Steps>
  <Step title="Plan Your Add-ons">
    Identify the additional features, services, or capacity that would benefit your customers as add-ons.

    Consider:

    * What do customers frequently request?
    * What features could be monetized separately?
    * What would create natural upgrade paths?
  </Step>

  <Step title="Create Your First Add-on">
    Use the Dodo Payments dashboard or API to create your first add-on product.

    <Card title="Dashboard Guide" icon="box" href="/developer-resources/seat-based-pricing">
      Follow our step-by-step guide to create add-ons in the dashboard.
    </Card>
  </Step>

  <Step title="Attach to Subscriptions">
    Connect your add-ons to the appropriate subscription products where they should be available.
  </Step>

  <Step title="Test Integration">
    Create test checkout sessions with different add-on combinations to ensure everything works correctly.
  </Step>

  <Step title="Monitor Performance">
    Track add-on adoption rates and revenue impact to optimize your pricing strategy.
  </Step>
</Steps>

## API Management

Dodo Payments provides a comprehensive API for managing add-ons programmatically:

<AccordionGroup>
  <Accordion title="Create Add-ons">
    Use the `POST /addons` endpoint to create new add-ons with custom pricing, descriptions, and configuration options.

    <Card title="API Reference" icon="code" href="/api-reference/addons/create-addon">
      View the complete API documentation for creating add-ons.
    </Card>
  </Accordion>

  <Accordion title="Update Add-ons">
    Modify existing add-ons using the `PATCH /addons/{id}` endpoint to update pricing, descriptions, or availability.

    <Card title="API Reference" icon="code" href="/api-reference/addons/update-addon">
      Learn how to update add-on details programmatically.
    </Card>
  </Accordion>

  <Accordion title="List and Retrieve">
    Use `GET /addons` to list all add-ons or `GET /addons/{id}` to retrieve specific add-on details.

    <Card title="API Reference" icon="code" href="/api-reference/addons/list-addons">
      Access the complete listing and retrieval API documentation.
    </Card>
  </Accordion>

  <Accordion title="Image Management">
    Update add-on images using the `PUT /addons/{id}/images` endpoint for better product presentation.

    <Card title="API Reference" icon="code" href="/api-reference/addons/update-addon-images">
      Learn how to manage add-on images via API.
    </Card>
  </Accordion>
</AccordionGroup>

## Common Use Cases

* **Seat-Based Billing**: Additional team members, user licenses, or concurrent users
* **Feature Upgrades**: Premium features, advanced analytics, or priority support
* **Usage Extensions**: Extra storage, API calls, or bandwidth allowances
* **Service Add-ons**: Professional services, training, or consultation hours

## Integration Examples

### Checkout Sessions with Add-ons

When creating checkout sessions, you can include add-ons with custom quantities:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'your_subscription_id',
      quantity: 1,
      addons: [
        {
          addon_id: 'your_addon_id',
          quantity: 3 // 3 additional seats
        }
      ]
    }
  ],
  // ... other checkout options
});
```

<Tip>
  To let customers add or remove add-ons themselves on the checkout page, set the [`allow_editing_addons`](/developer-resources/checkout-session#optional-fields) feature flag to `true` when creating the session. It defaults to `false` and applies only to subscription products.

  ```typescript theme={null}
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: 'your_subscription_id', quantity: 1 }],
    feature_flags: {
      allow_editing_addons: true // customers can edit add-ons at checkout
    },
  });
  ```
</Tip>

### Plan Changes with Add-ons

Modify existing subscriptions to add, remove, or update add-ons:

```typescript theme={null}
// Add add-ons to existing subscription
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing add-ons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing add-ons
});
```

### Dynamic Pricing

Calculate total costs dynamically based on add-on selections:

```typescript theme={null}
function calculateTotalCost(basePrice: number, addons: AddonSelection[]) {
  const addonTotal = addons.reduce((sum, addon) => 
    sum + (addon.price * addon.quantity), 0
  );
  return basePrice + addonTotal;
}
```

## Best Practices

* **Start simple**: Launch with 2-3 core add-ons and expand options based on customer feedback and usage.
* **Maintain pricing clarity**: Clearly communicate add-on pricing and value, so customers understand what they're getting for the extra cost.
* **Test thoroughly**: Validate add-on combinations to ensure pricing calculations remain accurate and checkout flows function smoothly.

### Design Considerations

* **Clear Value Proposition**: Each add-on should have a clear benefit that customers can easily understand
* **Logical Grouping**: Group related add-ons together in your checkout flow
* **Flexible Quantities**: Allow customers to adjust quantities of add-ons as needed
* **Transparent Pricing**: Show total costs clearly throughout the checkout process

<Info>
  Add-ons are a powerful way to create flexible, scalable pricing models that grow with your customers. Start with simple use cases and expand as you learn what works best for your business and customers.
</Info>


# Affiliates
Source: https://docs.dodopayments.com/features/affiliates

Launch and manage your affiliate program while processing transactions through Dodo Payments.

## Introduction

This guide walks you through how to track affiliate referrals, handle commission events, and grow your revenue with trusted affiliate partnerships via Dodo Payments. We offer integrations with leading affiliate platforms including **Affonso**, **Dub Partners**, and **Rekomi** to help you manage and track your affiliate programs seamlessly.

## Key Features

<CardGroup>
  <Card title="Automated Commission Attribution" icon="robot">
    No spreadsheets or manual tracking. Referrals are automatically attributed and logged when a purchase is made.
  </Card>

  <Card title="Real-Time Reporting" icon="chart-line">
    Both you and your affiliates can monitor performance and leads from dedicated dashboards.
  </Card>

  <Card title="Flexible Tracking Options" icon="code">
    Use tracking scripts, metadata fields, and webhook events to capture referral data across signups and transactions.
  </Card>

  <Card title="Fully Encrypted & Secure" icon="shield">
    All sensitive credentials and webhook data are securely exchanged and stored using best-in-class encryption.
  </Card>

  <Card title="Quick Setup" icon="bolt">
    Launch your affiliate program in minutes—no code changes required beyond copy-pasting script snippets and API tokens.
  </Card>

  <Card title="Seamless Integration" icon="plug">
    Plug affiliate tracking directly into your checkout flows using our integrations with Affonso, Dub Partners, and Rekomi, leading affiliate marketing platforms.
  </Card>
</CardGroup>

## Integration Options

Dodo Payments integrates with leading affiliate management platforms:

* **[Affonso](https://affonso.io)**: A comprehensive affiliate management platform with automated commission tracking, real-time reporting, and dedicated affiliate dashboards.
* **[Dub Partners](https://dub.co)**: Use Dub's link management and conversion tracking to power your affiliate program with detailed attribution analytics.
* **[Rekomi](https://rekomi.com)**: An affiliate tracking and management platform with a one-paste Dodo Payments connection that also handles affiliate payouts and tax forms for you.

Choose the platform that best fits your needs, or use both for different use cases.

## Affonso Integration

We have partnered with Affonso, a leading affiliate management platform to power your sales. Follow the steps below to connect your Dodo Payments account with Affonso and begin tracking affiliate-driven sales.

<Frame>
  <iframe title="Affiliate Integration | Dodo Payments" />
</Frame>

<Steps>
  <Step title="Connect with Dodo Payments">
    To get started, connect your Dodo Payments account by adding your API key.

    ### How to Get Your Dodo Payments API Key

    * Log in to your **Dodo Payments Dashboard**
    * Go to the **Developer** section in the left menu
    * Click on **API Keys**
    * Select **Add API Key**
    * Give it a name (e.g. "Affonso Integration")
    * Click **Create** and **copy** your API key

    ### Add Your API Key to Affonso

    * Open your **Affonso Dashboard via** [affonso.io](https://affonso.io/)
    * Go to **Program Details > Connect**
    * Click the **Dodo Payments integration** card
    * Paste your Dodo Payments API key
    * Click **Connect**

    <Callout type="info">
      Your API key will be securely encrypted by Affonso.
    </Callout>
  </Step>

  <Step title="Add Webhook to Dodo Payments">
    Once connected, you'll receive a unique webhook URL from Affonso. This enables payment tracking and affiliate commission triggering.

    ### Add Webhook URL in Dodo Payments

    * In your Dodo Payments Dashboard, go to **Developer → Webhooks**
    * Click **Add Webhook**
    * Paste your **Affonso webhook URL** (from your program settings)
    * Save the webhook

    ### Add Webhook Secret in Affonso

    * After saving the webhook in Dodo Payments, **copy the signing key** provided
    * Paste it back into Affonso under the **Dodo Payments webhook settings**

    <Callout type="info">
      This allows Affonso to securely verify incoming events from Dodo Payments.
    </Callout>
  </Step>

  <Step title="Add the Tracking Script">
    Place the Affonso pixel on your site to start tracking affiliate visits and conversions.

    ```html theme={null}
    <!-- Place in <head> tag -->
    <script async defer
    src="https://affonso.io/js/pixel.min.js"
    data-affonso="YOUR_PUBLIC_PROGRAM_ID"
    data-cookie_duration="YOUR_COOKIE_DURATION">
    </script>
    ```

    This script:

    * Tracks affiliate visits
    * Sets a cookie with the referral ID (`affonso_referral`)
    * Enables signup and payment tracking

    <Callout type="info">
      Place this on all domains where users visit or convert (e.g. marketing site, app).
    </Callout>
  </Step>

  <Step title="Track User Signups">
    To gain funnel visibility and optimize affiliate performance, track user signups as leads.

    ```js theme={null}
    // After successful registration
    window.Affonso.signup(userEmail);
    ```

    This will:

    * Log a new referral as a **LEAD** if the user came via an affiliate link
    * Display it in your dashboard and the affiliate's stats

    <Callout type="info">
      Best practice: Trigger this after successful registration or double opt-in (DOI).
    </Callout>
  </Step>

  <Step title="Pass Referral Data to Dodo Payments">
    To attribute commissions correctly, pass the referral ID from Affonso to Dodo Payments during checkout.

    ### Payments Integration

    ```js theme={null}
    import DodoPayments from 'dodopayments';

    const referralId = window.affonso_referral;

    const client = new DodoPayments({
      bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
    });

    async function main() {
      const payment = await client.payments.create({
        payment_link: true,
        billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: '00000' },
        customer: { email: 'email@email.com', name: 'name' },
        product_cart: [{ product_id: 'product_id', quantity: 0 }],
        metadata: {
          affonso_referral: referralId,
        },
      });

      console.log(payment.payment_id);
    }

    main();
    ```

    ### Subscription Integration

    ```js theme={null}
    import DodoPayments from 'dodopayments';

    const referralId = window.affonso_referral;

    const client = new DodoPayments({
      bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
    });

    async function main() {
      const subscription = await client.subscriptions.create({
        billing: { city: 'city', country: 'IN', state: 'state', street: 'street', zipcode: '89789' },
        customer: { customer_id: 'customer_id' },
        product_id: 'product_id',
        payment_link: true,
        return_url: 'https://example.com/success',
        quantity: 1,
        metadata: {
          affonso_referral: referralId,
        },
      });

      console.log(subscription.subscription_id);
    }

    main();
    ```

    ### Payment Links

    ```js theme={null}
    // Original Dodo Payments Link
    const originalLink = 'https://checkout.dodopayments.com/buy/<YOUR_PRODUCT_ID>';

    // Append referral ID as reference_id
    const linkWithReferral = `${originalLink}?metadata_affonso_referral=${window.affonso_referral}`;
    ```

    <Callout type="info">
      For more details, see the [Dodo Payments API documentation](https://docs.dodopayments.com/api-reference/introduction)
    </Callout>
  </Step>

  <Step title="Testing Your Integration">
    Before launching publicly, test your setup with live affiliate links and test transactions.

    **Testing Checklist:**

    * ✅ Create an affiliate and generate a tracking link
    * ✅ Visit your website via the affiliate link
    * ✅ Ensure the Affonso script loads and the `affonso_referral` cookie is set
    * ✅ Complete a signup (optional)
    * ✅ Complete a payment via Dodo Payments
    * ✅ Confirm tracking and attribution in your Affonso dashboard
  </Step>
</Steps>

## Dub Partners Integration

You can also use [Dub Partners](https://dub.co) to track affiliate referrals and conversions. Dub's conversion tracking feature allows you to attribute sales to your affiliate links, providing detailed analytics on which partners drive the most revenue.

<Info>
  For detailed setup instructions, see our [Dub integration guide](/integrations/dub) which covers how to track sale conversion events and attribute revenue to your affiliate links.
</Info>

### Quick Setup with Dub Partners

1. **Enable conversion tracking** in your Dub dashboard for affiliate links
2. **Capture the Dub click ID** (`dub_id` cookie) when creating checkout sessions
3. **Store the click ID** in payment metadata along with customer information
4. **Configure webhook integration** to send sale data to Dub when payments succeed

The integration automatically tracks:

* One-time payments
* Subscription activations
* Recurring subscription payments

<Card title="Learn More" icon="book" href="/integrations/dub">
  View the complete Dub integration guide with code examples and transformation templates.
</Card>

## Rekomi Integration

You can also use [Rekomi](https://rekomi.com) to run your affiliate program end to end. Rekomi tracks clicks and conversions, calculates commissions on the pre-tax sale amount, and pays your affiliates for you in 150+ countries, tax forms included.

<Info>
  For detailed setup instructions, see our [Rekomi integration guide](/integrations/rekomi). The connection is a single pasted API key: Rekomi creates the webhook endpoint in your Dodo Payments account itself, so there is no manual webhook setup.
</Info>

### Quick Setup with Rekomi

1. **Create an API key with write access enabled** in your Dodo Payments dashboard under **Developer → API Keys**
2. **Paste the key into Rekomi**, which validates it and creates the webhook endpoint automatically
3. **Install the Rekomi tracking script** on your site so affiliate clicks are captured
4. **Pass the referral** into checkout as `rekomi_ref` metadata (or the `metadata_rekomi_ref` payment-link parameter)

The integration automatically tracks:

* One-time payments
* Subscription activations and renewals
* Refunds and disputes, with automatic commission clawback

<Card title="Learn More" icon="book" href="/integrations/rekomi">
  View the complete Rekomi integration guide with code examples for checkout sessions and payment links.
</Card>

## Need Help?

If you face any issues or need support during integration:

<CardGroup>
  <Card title="Affonso Support" icon="headset">
    * Chat with us via **live chat** on [affonso.io](https://affonso.io/)
    * Email us at **[support@affonso.io](mailto:support@affonso.io)**
  </Card>

  <Card title="Dub Support" icon="headset">
    * Visit the [Dub documentation](https://dub.co/docs) for conversion tracking guides
    * Contact Dub support through their [dashboard](https://app.dub.co)
  </Card>

  <Card title="Rekomi Support" icon="headset">
    * Visit the [Rekomi documentation](https://rekomi.com/docs) for setup and troubleshooting guides
    * Email us at **[support@rekomi.com](mailto:support@rekomi.com)** or use the live chat in the [Rekomi dashboard](https://app.rekomi.com)
  </Card>

  <Card title="Dodo Payments Support" icon="headset">
    For Dodo Payments-specific API queries, refer to docs.dodopayments.com or contact our support team.
  </Card>

  <Card title="Integration Guides" icon="book">
    * [Affonso Integration](#affonso-integration) (above)
    * [Dub Partners Integration](/integrations/dub)
    * [Rekomi Integration](/integrations/rekomi)
  </Card>
</CardGroup>


# Third-party Analytics
Source: https://docs.dodopayments.com/features/analytics

Track page views and e-commerce events on your Dodo Payments-hosted pages with Google Analytics 4, Google Tag Manager, and Meta Pixel.

<Frame>
  <img alt="Analytics Integration" />
</Frame>

Track customer journeys from your storefront through checkout to purchase completion. Dodo Payments integrates with Google Analytics 4, Google Tag Manager, and Meta Pixel to provide comprehensive analytics across all your hosted pages.

<Info>
  Analytics tracking is automatically enabled on your Storefront, Checkout pages, and Customer Portal once you add your tracking IDs in the dashboard.
</Info>

<Warning>
  Ad blockers in customer browsers can prevent analytics tracking from working for some visitors to your store.
</Warning>

## Supported Platforms

<CardGroup>
  <Card title="Google Analytics 4" icon="chart-simple">
    Page views and e-commerce tracking with GA4.
  </Card>

  <Card title="Google Tag Manager" icon="tags">
    Add and manage marketing tags.
  </Card>

  <Card title="Meta Pixel" icon="meta">
    Track Facebook and Instagram ad conversions.
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Open Business Settings">
    In your Dodo Payments dashboard, navigate to **Settings → Business** and scroll to the **Analytics** section.
  </Step>

  <Step title="Enable Your Tracking Platform">
    Toggle on the analytics platform you want to use and enter your tracking ID:

    * **Google Analytics**: Enter your Measurement ID (format: `G-XXXXXXXXXX`)
    * **Google Tag Manager**: Enter your Container ID (format: `GTM-XXXXXXX`)
    * **Meta Pixel**: Enter your Pixel ID (numeric, 10-20 digits)
  </Step>

  <Step title="Save Your Settings">
    Click **Save** to apply your tracking configuration.
  </Step>

  <Step title="Verify Tracking">
    Visit your storefront or create a test checkout to verify events are being tracked in your analytics dashboard.
  </Step>
</Steps>

## Google Analytics 4

[Google Analytics 4](https://marketingplatform.google.com/about/analytics/) provides comprehensive web analytics with e-commerce tracking capabilities. With Dodo Payments integration, you can track the complete customer journey from browsing your store to completing a purchase.

### Add Your Google Analytics Measurement ID

1. In Google Analytics, go to **Admin** → **Data Streams** → select your web stream
2. Copy the **Measurement ID** (starts with `G-`)
3. In Dodo Payments dashboard, go to **Settings** → **Business** → **Analytics**
4. Toggle on **Google Analytics** and paste your Measurement ID
5. Click **Save**

<Tip>
  If you don't have a Google Analytics property yet, follow [Google's setup guide](https://support.google.com/analytics/answer/9304153) to create one.
</Tip>

### Events Tracked in Google Analytics

We track the following events on your hosted storefront and checkout pages. Event data including product information, transaction totals, and currency are sent with each event.

#### Storefront Events

| Event            | Description                                                 |
| ---------------- | ----------------------------------------------------------- |
| `view_item_list` | Fires when the storefront page loads with products          |
| `select_item`    | Fires when a customer clicks on a product to start checkout |

#### Checkout Events

| Event               | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `view_item`         | Fires when the checkout page loads                           |
| `view_cart`         | Fires when the checkout loads and when a variant is selected |
| `apply_discount`\*  | Fires when a valid discount code is successfully applied     |
| `remove_discount`\* | Fires when a discount code is removed                        |
| `add_payment_info`  | Fires when the customer submits the payment form             |
| `purchase`          | Fires when payment is successful                             |

<Note>
  `apply_discount` and `remove_discount` are custom events not included in the [standard Google Analytics e-commerce events](https://support.google.com/analytics/answer/9267735).
</Note>

### Using GA4 with Overlay/Inline Checkout

To track Google Analytics events in overlay or inline checkout embedded on your own website, you need to install the Google Analytics tracking code on your website where the checkout is embedded.

Once installed, all tracking events listed above will be sent to your Google Analytics account automatically - no additional configuration needed.

## Google Tag Manager

[Google Tag Manager](https://marketingplatform.google.com/about/tag-manager/) lets you manage marketing and analytics tags without modifying code. Tags deployed through GTM will fire on all Dodo Payments-hosted pages.

### Add Your GTM Container ID

1. In Google Tag Manager, copy your **Container ID** (starts with `GTM-`)
2. In Dodo Payments dashboard, go to **Settings** → **Business** → **Analytics**
3. Toggle on **Google Tag Manager** and paste your Container ID
4. Click **Save**

<Info>
  When using GTM, you can configure additional tracking (like Google Ads conversions) directly in your GTM container. The Dodo Payments integration injects both the GTM script and the noscript fallback for maximum compatibility.
</Info>

### Using GTM with Overlay/Inline Checkout

For overlay or inline checkout embedded on your website, install GTM on your own site. The checkout will inherit your GTM configuration and fire events within the embedded frame.

## Meta Pixel

[Meta Pixel](https://www.facebook.com/business/tools/meta-pixel/) tracks customer actions on your store to measure the effectiveness of your Facebook and Instagram ad campaigns. Track conversions from ad click to purchase completion.

### Add Your Meta Pixel ID

1. In [Meta Events Manager](https://www.facebook.com/events_manager2/), create or select your Pixel
2. Copy the **Pixel ID** (numeric, typically 15-16 digits)
3. In Dodo Payments dashboard, go to **Settings** → **Business** → **Analytics**
4. Toggle on **Meta Pixel** and paste your Pixel ID
5. Click **Save**

<Tip>
  Follow Meta's [Pixel setup guide](https://www.facebook.com/business/help/952192354843755) if you haven't created a Pixel yet.
</Tip>

### Events Tracked with Meta Pixel

We track the following events which appear in your [Meta Events Manager](https://www.facebook.com/events_manager2/). Event data including content IDs, values, and currency are sent with each event.

<Note>
  Events may not appear immediately in Meta Events Manager - there can be a delay of several minutes.
</Note>

#### Storefront Events

| Event              | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `PageView`         | Fires when the storefront page loads                        |
| `ViewContent`      | Fires when the storefront loads with products               |
| `InitiateCheckout` | Fires when a customer clicks on a product to start checkout |

#### Checkout Events

| Event              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `PageView`         | Fires when the checkout page loads                           |
| `AddToCart`        | Fires when the checkout loads and when a variant is selected |
| `ApplyDiscount`\*  | Fires when a valid discount code is successfully applied     |
| `RemoveDiscount`\* | Fires when a discount code is removed                        |
| `AddPaymentInfo`   | Fires when the customer submits the payment form             |
| `Purchase`         | Fires when payment is successful                             |

<Note>
  `ApplyDiscount` and `RemoveDiscount` are custom events not included in [Meta's standard events](https://developers.facebook.com/docs/meta-pixel/reference#standard-events).
</Note>

## Complete Events Reference

This table shows all events tracked across both Google Analytics 4 and Meta Pixel:

| Trigger                      | GA4 Event          | Meta Pixel Event   | Location   |
| ---------------------------- | ------------------ | ------------------ | ---------- |
| Storefront page loads        | `view_item_list`   | `ViewContent`      | Storefront |
| Customer clicks product      | `select_item`      | `InitiateCheckout` | Storefront |
| Checkout page loads          | `view_item`        | `AddToCart`        | Checkout   |
| Cart viewed/variant selected | `view_cart`        | -                  | Checkout   |
| Discount code applied        | `apply_discount`   | `ApplyDiscount`    | Checkout   |
| Discount code removed        | `remove_discount`  | `RemoveDiscount`   | Checkout   |
| Payment form submitted       | `add_payment_info` | `AddPaymentInfo`   | Checkout   |
| Payment successful           | `purchase`         | `Purchase`         | Checkout   |

## Platform Coverage

Analytics tracking is available across different Dodo Payments surfaces:

| Surface                     | Google Analytics 4 | Google Tag Manager | Meta Pixel |
| --------------------------- | ------------------ | ------------------ | ---------- |
| Storefront                  | Yes                | Yes                | Yes        |
| Checkout (Hosted)           | Yes                | Yes                | Yes        |
| Checkout (Overlay/Inline)\* | Yes                | Yes                | Yes        |
| Customer Portal             | Yes                | Yes                | No         |

<Info>
  \*For overlay and inline checkout, install the tracking code on your own website for full attribution. Events from the embedded checkout will be tracked automatically.
</Info>

## Event Data Included

Each tracking event includes relevant e-commerce data to help you analyze customer behavior:

### Product Data

* Product ID
* Product name
* Price
* Currency
* Quantity

### Transaction Data (Purchase Events)

* Transaction/Payment ID
* Total amount
* Tax amount
* Currency
* Discount applied

### Customer Data

* Customer ID (for returning customers)
* Email (hashed for privacy where applicable)

## Best Practices

<AccordionGroup>
  <Accordion title="Test Your Integration">
    After adding your tracking IDs, visit your storefront and complete a test checkout to verify events appear in your analytics dashboards. Use Google Analytics Realtime reports or Meta Events Manager's Test Events feature.
  </Accordion>

  <Accordion title="Use UTM Parameters">
    Add UTM parameters to your marketing links to track which campaigns drive conversions. Dodo Payments preserves UTM parameters throughout the checkout flow.
  </Accordion>

  <Accordion title="Set Up Conversion Goals">
    In Google Analytics, create conversion events for `purchase` to track your conversion rate. In Meta Ads Manager, use the `Purchase` event as your optimization goal for campaigns.
  </Accordion>

  <Accordion title="Enable Enhanced E-commerce">
    If using Google Tag Manager, consider setting up Enhanced E-commerce reports for detailed funnel analysis and product performance metrics.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not appearing in Google Analytics">
    * Verify your Measurement ID is correct (format: `G-XXXXXXXXXX`)
    * Check Google Analytics Realtime reports - events appear there first
    * Ensure the toggle is enabled in your Dodo Payments settings
    * Wait a few minutes as there can be processing delays
    * Test in an incognito window to rule out ad blockers
  </Accordion>

  <Accordion title="Events not appearing in Meta Events Manager">
    * Verify your Pixel ID is correct (numeric, 10-20 digits)
    * Use the Meta Pixel Helper browser extension to debug
    * Check the Test Events tab in Events Manager
    * Events can take several minutes to appear
    * Ensure ad blockers are disabled during testing
  </Accordion>

  <Accordion title="GTM tags not firing">
    * Confirm your Container ID is correct (format: `GTM-XXXXXXX`)
    * Use GTM Preview mode to debug tag firing
    * Check that triggers are configured correctly in your GTM container
    * Verify the container is published (not just in draft)
  </Accordion>

  <Accordion title="Overlay/Inline checkout not tracking">
    * Install the tracking code on your own website first
    * Ensure the tracking loads before the checkout overlay opens
    * Check browser console for any JavaScript errors
    * Verify cross-domain tracking is configured if using GA4
  </Accordion>

  <Accordion title="Purchase events showing wrong amounts">
    * Amounts are sent in the smallest currency unit (cents)
    * Verify your analytics tool is configured to display the correct currency
    * Check if tax is included/excluded as expected
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup>
  <Card title="Segment Integration" icon="chart-line" href="/integrations/segment">
    Send payment events to Segment for advanced analytics and CDP integration.
  </Card>

  <Card title="Dub Integration" icon="https://mintcdn.com/dodopayments/LYWHtNbGSpS1P01t/images/logos/dub.svg?fit=max&auto=format&n=LYWHtNbGSpS1P01t&q=85&s=c36ca87c0811f65b3d8a4a79e4a34242" href="/integrations/dub">
    Track sale conversions and affiliate attribution with Dub.
  </Card>

  <Card title="Customer.io Integration" icon="envelope" href="/integrations/customer-io">
    Trigger automated email campaigns based on payment events.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Build custom analytics integrations with webhook events.
  </Card>
</CardGroup>


# Dashboard Analytics
Source: https://docs.dodopayments.com/features/analytics-and-reporting

Gain actionable business insights with Dodo Payments' Analytics & Reporting dashboard. Track revenue, customers, retention, and transaction health at both the business and product level.

<Frame>
  <img alt="Analytics and Reporting dashboard overview" />
</Frame>

## Introduction

Dodo Payments' **Analytics & Reporting** helps you monitor business performance, understand customer behavior, and make data-driven decisions. **Home** is a curated, at-a-glance pulse; **Analytics** is where you go for deep, filterable analysis.

<CardGroup>
  <Card title="Home" icon="house" href="#home">
    A daily pulse (**Today**) plus a customizable overview.
  </Card>

  <Card title="Business Analytics" icon="chart-pie-simple" href="#analytics">
    Revenue, customers, subscriptions, retention, transaction health, and recovery across your business.
  </Card>

  <Card title="Product-Level Analytics" icon="chart-mixed" href="#product-level-analytics">
    Drill into individual product performance—revenue, customers, churn, subscribers, and MRR.
  </Card>

  <Card title="Page Highlight Tiles" icon="table-list" href="#page-highlight-tiles">
    At-a-glance summary metrics on your products, subscriptions, payments, and other list pages.
  </Card>

  <Card title="Exportable Reports" icon="file-csv" href="#reports">
    Download payments, refunds, payouts, disputes, and more as CSV for custom date ranges.
  </Card>
</CardGroup>

<Frame>
  <img alt="Dashboard Analytics Home page showing the Today pulse and a customizable overview of key business metrics" />
</Frame>

***

## Home

**Home** is your landing page in the sidebar, with two parts: **Today** and **Your overview**.

### Today

<Frame>
  <img alt="Home Today view with an hourly volume chart, cash position, and next payout tiles" />
</Frame>

The day's pulse, hour by hour.

* **Headline chart:** Toggle between **Net volume** and **Gross volume** (defaults to Net volume), plotted hourly against yesterday's same-time line.
* **Cash Position:** Your current wallet balance and next payout date.

<Note>
  Both cards show an info tooltip (ⓘ) and an "Updated Xs ago" timestamp, so you always know how fresh the data is.
</Note>

### Your Overview

<Frame>
  <img alt="Home Your overview view with customizable cards for revenue by country, payouts received, top customers by spend, and refunds" />
</Frame>

Fully customizable—use **Customize** to choose, reorder, and remove cards.

* **Default cards:** Net volume, Gross volume, Payments, Top customers by spend, New customers, Revenue by country, and Refunds—plus **Average order value** (one-time/usage merchants) or **MRR** and **Net New MRR** (subscription merchants).
* **Controls:**
  * **Period:** Daily/Weekly or a custom range.
  * **Compare:** Previous period or previous month (on by default).
  * **Product:** A single product or a group.

***

## Analytics

Access **Analytics** from the sidebar, directly below **Home**, for deep-dive analysis across your entire business. It's organized into six tabs, each with its own filters.

<CardGroup>
  <Card title="Revenue" icon="chart-line">
    Gross/net volume, payouts, refunds, disputes, and top markets.
  </Card>

  <Card title="Customers" icon="users">
    Active and new customers, ARPU, top customers, and modeled LTV.
  </Card>

  <Card title="Subscriptions" icon="rectangle-list">
    MRR, Projected ARR, active subscriptions, and the full MRR breakdown.
  </Card>

  <Card title="Retention" icon="arrows-rotate">
    Customer and revenue churn, NRR/GRR, cohorts, and trial conversion.
  </Card>

  <Card title="Success Rate" icon="circle-check">
    Payment and refund success rates with failure-reason analysis.
  </Card>

  <Card title="Recovery" icon="life-ring">
    Payment retries, dunning, and abandoned cart recovery performance.
  </Card>
</CardGroup>

### Filtering & Customization

Each tab has its own filter bar:

* **Time Period:** Preset ranges — **Today**, **Last 7 days**, **Last 30 days**, **Month to date**, **Quarter to date**, **Last 6 months**, **All time** — or a custom date range, plus **Daily/Weekly** grouping. New dashboards start on **Last 30 days**.
* **Compare:** Previous period or previous month (on by default). Comparison is unavailable on **All time**, since there is no earlier window to compare against.
* **Product:** Available on the Revenue, Subscriptions, and Retention tabs. Product is multi-select and defaults to **All**.

Your date range and compare selections are remembered per business and synced to your profile, so switching businesses, returning later, or signing in on another device keeps each business on the window you last used.

<Tip>
  Use filters to drill down into specific products, time periods, or payment methods for targeted insights.
</Tip>

### Revenue Tab

<Frame>
  <img alt="Revenue tab showing gross volume, net volume, payouts received, and refunds cards with trend charts" />
</Frame>

Track your income, payouts, and dispute activity to understand revenue trends and identify your top-performing markets. Use the **Gross/Net** dropdown to switch the headline figure, chart, and country ranking between gross and net values.

| Metric                  | Description                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gross volume**        | Total amount charged across all successful payments in the period, before fees, refunds, or disputes are removed.                                                                                                                                                                                                                 |
| **Net volume**          | Net volume = gross volume − fees − refunds − lost disputes.                                                                                                                                                                                                                                                                       |
| **Payouts received**    | Payout = eligible sales − taxes − fees − refunds − chargebacks.                                                                                                                                                                                                                                                                   |
| **Refund rate**         | Refund rate = refunded amount ÷ gross volume.                                                                                                                                                                                                                                                                                     |
| **Disputes**            | Headline is the chargeback rate, gross of outcome: every chargeback received counts, so ones you later win or that get withdrawn don't lower it (this is how card networks judge risk). Won / lost / pending are shown as counts for context, compared across the two periods. Chargeback rate = chargebacks received ÷ payments. |
| **Payments count**      | Count of payments with a Successful status. In-progress, failed, and not-initiated attempts are excluded.                                                                                                                                                                                                                         |
| **Average order value** | AOV = revenue ÷ number of orders, across one-time and usage-based products.                                                                                                                                                                                                                                                       |
| **Revenue by product**  | Gross revenue attributed to each product, ranked highest to lowest.                                                                                                                                                                                                                                                               |
| **Revenue by country**  | Revenue attributed to each country, based on the customer's billing country, shown as a full-width card pairing a world map with the ranked country list beside it. Darker countries earned more. The top 150 countries are listed individually, with any remainder grouped into a single "others" row.                           |

### Customers Tab

<Frame>
  <img alt="Customers tab showing active customers, new customers, ARPU, and top customers by spend" />
</Frame>

Analyze customer acquisition, retention, and spending patterns to optimize your customer strategy.

| Metric                | Description                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active customers**  | Customers who made a payment or held an active subscription at any point in the period.                                                               |
| **New customers**     | Customers whose first successful payment with you falls in this period.                                                                               |
| **ARPU**              | ARPU = revenue ÷ active customers.                                                                                                                    |
| **Top customers**     | Customers ranked by revenue in the period, highest first. Each entry is identified by customer name, falling back to email when no name is on record. |
| **New vs. returning** | New = first purchase in this period. Returning = purchased with you in an earlier period.                                                             |
| **Modeled LTV**       | Estimated revenue from a customer before they churn.                                                                                                  |

### Subscriptions Tab

Monitor your recurring revenue and understand how your Monthly Recurring Revenue (MRR) changes over time.

| Metric                   | Description                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **MRR**                  | Recurring revenue expected in a month, with every plan converted to monthly (a yearly plan counts as 1/12). One-time payments are excluded. |
| **Projected ARR**        | Projected ARR = current MRR × 12.                                                                                                           |
| **Net New MRR**          | Net New MRR = New + Expansion − Contraction − Churned.                                                                                      |
| **Active subscriptions** | Subscriptions actively billing, including those still in a trial.                                                                           |
| **New MRR**              | MRR added by brand-new subscriptions in the period.                                                                                         |
| **Expansion MRR**        | Extra MRR from existing customers upgrading or buying add-ons.                                                                              |
| **Contraction MRR**      | MRR lost when existing customers move to a cheaper plan but stay subscribed.                                                                |
| **Churned MRR**          | MRR lost when customers cancel their subscriptions in the period.                                                                           |

<Note>
  MRR accounts for **concurrent subscriptions** (summed per customer) and prorates by each subscription's paid-through period.
</Note>

### Retention Tab

<Frame>
  <img alt="Retention tab showing the user retention cohort matrix, customer churn rate, revenue churn rate, and net revenue retention" />
</Frame>

Monitor customer retention and churn patterns.

| Metric                            | Description                                                                                                                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User retention matrix**         | Groups customers by signup month (cohort), then shows the share of each cohort still active in every later month. Retention (month k) = cohort customers active in month k ÷ cohort size.   |
| **Customer churn rate**           | Share of starting subscribers who cancelled during the period, with the churned-customer count shown beside it. Customer churn rate = churned subscribers ÷ subscribers at start of period. |
| **Revenue churn rate**            | Revenue churn rate = churned MRR ÷ starting MRR, where starting MRR is the recurring revenue from existing customers at the start of the period (where the prior period ended).             |
| **Net Revenue Retention (NRR)**   | Includes upgrades, so it can exceed 100%. NRR = (starting MRR + Expansion − Contraction − Churned) ÷ starting MRR.                                                                          |
| **Gross Revenue Retention (GRR)** | Excludes upgrades, so it caps at 100%. GRR = (starting MRR − Contraction − Churned) ÷ starting MRR.                                                                                         |
| **Trial conversion**              | Trial conversion = trials converted ÷ trials that ended in the period. Only shown if you offer trials.                                                                                      |

### Success Rate Tab

<Frame>
  <img alt="Success Rate tab showing payment success rate, payments breakdown, payment failure reasons, and success by payment method" />
</Frame>

Monitor payment and refund success rates to identify and resolve transaction issues quickly.

| Metric                     | Description                                                                                                                                                                                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Payment success rate**   | Only processor/network failures count against it; customer-fixable ones (a wrong or expired card) are excluded from the denominator. Payment success rate = succeeded ÷ (attempts − customer-fixable failures). |
| **Payments breakdown**     | Splits attempts into total, success, failed (network), failed (customer), and not initiated.                                                                                                                    |
| **Payment failure reason** | Breakdown of payment failures by reason.                                                                                                                                                                        |
| **By payment method**      | Per method (card, wallet, UPI, BNPL): success rate = succeeded ÷ attempts; volume = succeeded amount.                                                                                                           |
| **Checkouts count**        | How many checkout sessions customers began, whether or not they completed.                                                                                                                                      |
| **Refund success rate**    | The share of initiated refunds that processed successfully.                                                                                                                                                     |

<Card title="Transaction Failure Reference" icon="circle-exclamation" href="/api-reference/transaction-failures">
  Get all possible transaction failure codes and their reasons.
</Card>

<Warning>
  If you notice a drop in success rates or a spike in failures, review the failure reasons and address them promptly to minimize revenue loss.
</Warning>

### Recovery Tab

<Frame>
  <img alt="Recovery tab showing recovery overview, recovery by flow, payment retries, and dunning metrics" />
</Frame>

Track how much revenue Dodo Payments recovers on your behalf through automated retries, dunning emails, and abandoned cart recovery.

| Metric                | Description                                                                                                                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Recovery overview** | Recovered revenue over the period, alongside the overall recovery rate. Recovery rate = recovered ÷ recoverable failed amount; hard declines (closed accounts) are excluded from recoverable. |
| **Recovery by flow**  | Recovered revenue broken down across retries, dunning, and abandoned cart.                                                                                                                    |
| **Payment retries**   | Retry attempts, successful retries, retry success rate, and subscriptions saved.                                                                                                              |
| **Dunning**           | Dunning entries, emails sent, recovered revenue, recovery rate, and average time to recover.                                                                                                  |
| **Abandoned cart**    | Abandoned checkouts, recovered revenue, recovery rate, and average time to recover.                                                                                                           |

<Card title="Recovery Features" icon="life-ring" href="/features/recovery/overview">
  Learn more about configuring payment retries, dunning, and abandoned cart recovery.
</Card>

***

## Product-Level Analytics

Beyond business-wide metrics, you can view detailed analytics for **each individual product**. Navigate to **Products > \[Select a Product]** to access a dedicated analytics dashboard for that product.

<Frame>
  <img alt="Product analytics overview tab with total revenue, successful payments, and revenue trend chart" />
</Frame>

The product analytics dashboard is organized into five tabs:

<CardGroup>
  <Card title="Overview" icon="chart-line">
    Revenue summary, trend chart, and transaction history.
  </Card>

  <Card title="Customers" icon="users">
    Top customers ranked by spend with a full breakdown table.
  </Card>

  <Card title="Retention" icon="arrows-rotate">
    Customer and revenue churn rates with trend analysis.
  </Card>

  <Card title="Subscribers" icon="rectangle-list">
    All subscriptions with status and billing details.
  </Card>

  <Card title="MRR" icon="chart-bar">
    Monthly Recurring Revenue breakdown — new, expansion, churned, and net.
  </Card>
</CardGroup>

All tabs support a **date filter** (defaults to All Time) so you can focus on any period.

### Overview Tab

The Overview tab provides a high-level snapshot of the product's financial performance.

* **Total Revenue**: Cumulative revenue generated by this product.
* **Number of Successful Payments**: Total count of successful transactions.
* **Revenue Trend Chart**: A 30-day line chart showing revenue over time. Toggle between cumulative and daily views using the **Show Daily** button.

Below the chart, a **Transactions** table lists every payment for this product:

| Column         | Description                           |
| -------------- | ------------------------------------- |
| Payment ID     | Unique identifier for the transaction |
| Status         | `Successful` or `Failed`              |
| Amount         | Transaction amount with currency      |
| Date (UTC)     | Timestamp of the transaction          |
| Payment Method | Card, UPI, or other method used       |
| Refund         | Option to initiate a refund           |

<Frame>
  <img alt="Product transactions table with payment IDs, statuses, amounts, and refund actions" />
</Frame>

Use the **Filter by status** button to narrow the list to successful or failed transactions.

### Customers Tab

See who is buying this product and how much they're spending.

<Frame>
  <img alt="Customers tab showing top 3 customers ranked by revenue with a detailed breakdown table" />
</Frame>

* **Top Customers of the Month**: A visual podium highlights your **top 3 customers** ranked by total spend, showing revenue amount, name, and email.
* **Customer Table**: A detailed breakdown of all customers with their Customer ID and total revenue for this product.

### Retention Tab

Understand how well this product retains its subscribers.

<Frame>
  <img alt="Retention tab showing customer churn rate, revenue churn rate, and churn rate trend chart" />
</Frame>

* **Customer Churn Rate**: Percentage of subscribers who have cancelled.
* **Revenue Churn Rate**: Percentage of revenue lost from cancellations and downgrades.
* **Churn Rate Trend**: A dual-line chart tracking both metrics over time to help you spot trends and take corrective action.

### Subscribers Tab

A complete list of all subscriptions associated with this product.

<Frame>
  <img alt="Subscribers tab with subscription IDs, customer emails, statuses, start dates, and next billing information" />
</Frame>

| Column              | Description                                    |
| ------------------- | ---------------------------------------------- |
| Subscription ID     | Unique identifier for the subscription         |
| Customer Email      | The subscriber's email address                 |
| Status              | `Active`, `Failed`, `On hold`, or `Pending`    |
| Product Name        | The product this subscription belongs to       |
| Start Date          | When the subscription began                    |
| Next Billing Date   | The upcoming renewal date                      |
| Next Billing Amount | The amount due at next renewal (excluding tax) |

### MRR Tab

A detailed breakdown of your product's Monthly Recurring Revenue.

<Frame>
  <img alt="MRR tab with stacked bar chart showing new, expansion, and churned MRR by month" />
</Frame>

The **MRR chart** visualizes your recurring revenue composition month by month as a stacked bar chart.

Below the chart, metric cards provide detailed insights:

<Frame>
  <img alt="MRR breakdown showing New MRR, Expansion MRR, Churned MRR, and Net New MRR with trend charts" />
</Frame>

| Metric              | Description                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| **New MRR**         | Revenue from new subscriptions acquired this month, with month-over-month change |
| **Expansion MRR**   | Additional revenue from existing subscribers upgrading or adding to their plans  |
| **Contraction MRR** | Revenue lost from existing subscribers downgrading without fully cancelling      |
| **Churned MRR**     | Revenue lost from cancelled subscriptions                                        |
| **Net New MRR**     | The net result: New MRR + Expansion MRR − Contraction MRR − Churned MRR          |

Each card includes a trend mini-chart and a percentage change indicator compared to the previous month.

***

## Page Highlight Tiles

Many list pages in your dashboard now display **highlight tiles** at the top, giving you key summary metrics at a glance—without opening the full Analytics dashboard. The tiles respect the page's active filters.

| Page              | Highlight Tiles                                           |
| ----------------- | --------------------------------------------------------- |
| **Products**      | All Products, Active Products, Archived Products          |
| **Add-ons**       | All Add-Ons, Active Add-Ons, Linked to Products           |
| **Collections**   | All Collections, Active Collections, Archived Collections |
| **Subscriptions** | Active Subscriptions, On Hold, Cancelled                  |
| **Payments**      | Successful Payments, Payment Volume, Failed Payments      |
| **Refunds**       | Successful Refunds, Refund Volume, Failed Refunds         |
| **Disputes**      | Disputes Created, Won, Accepted, Lost                     |

<Note>
  "Active" products, add-ons, collections, and meters are those that have participated in at least one successful payment.
</Note>

***

## Reports

Each report has a **Build Report** button on its respective page. Navigate to the relevant section to access and download the report you need.

Each report can be filtered (by payment method, status, product type, failure type, dispute status, or currency where applicable) and downloaded as a CSV.

| Report Type                | Description                                                                                                                                              | Where to find it            |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **Payment Report**         | Detailed record of all processed payments, including billing address, card details, USD-equivalent amounts, settlement details, fees, and failure codes. | **Transactions → Payments** |
| **Refund Report**          | Comprehensive log of all refund activities with detailed refund information.                                                                             | **Transactions → Refunds**  |
| **Disputes Report**        | Payment disputes summary with resolution status and evidence details.                                                                                    | **Transactions → Disputes** |
| **Customer Report**        | Payment, refund, and dispute summary organized by customer.                                                                                              | **Sales → Customers**       |
| **Payout Report**          | Summary of payouts made to your account, with a breakdown of fees by ledger event.                                                                       | **Payouts**                 |
| **Account Summary Report** | Detailed balance-ledger entries with event type, amount, and references.                                                                                 | **Payouts → Balances**      |

<Frame>
  <img alt="Create a Payment Report modal showing time period selection and payment method filters" />
</Frame>

## Downloading Reports

<Steps>
  <Step title="Navigate to the relevant page">
    Go to the page for the report you need using the table above.
  </Step>

  <Step title="Select a time period">
    Click <strong>Build Report</strong> and choose a preset range (Today, Last 7 days, Last 30 days, This month, etc.) or pick a custom date range using the calendar.
  </Step>

  <Step title="Download">
    Click <strong>Download Report</strong>. The report will be exported as a CSV and saved to your device.
  </Step>
</Steps>

<Note>
  Fee data is not available as a standalone report. A breakdown of fees (payment fees, refund fees, and payout fees) is accessible as filter options within the **Account Summary Report** under **Payouts → Balances**.
</Note>

***

## Best Practices

<Tip>
  * Regularly review your analytics to spot trends and anomalies early.
  * Use filters to compare performance across products, time periods, or geographies.
  * Drill into product-level analytics to understand which products drive the most revenue and which have the highest churn.
  * If data appears incorrect or missing, check your filters and date range settings first.
</Tip>

<Warning>
  If you notice persistent discrepancies or missing data, contact <a href="mailto:support@dodopayments.com">[support@dodopayments.com](mailto:support@dodopayments.com)</a> for assistance.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Account Summary & Payout Wallet" icon="wallet" href="/features/account-summary-payout-wallet">
    Understand your earnings, deductions, and payout cycles.
  </Card>

  <Card title="Products" icon="box" href="/features/products">
    Create and manage your products.
  </Card>

  <Card title="Payments" icon="money-bill-transfer" href="/features/transactions/payments">
    Track and manage all payment transactions.
  </Card>

  <Card title="Refunds" icon="rotate-left" href="/features/transactions/refunds">
    Initiate and monitor refunds, and export refund reports.
  </Card>
</CardGroup>


# Selling Digital Goods on iOS
Source: https://docs.dodopayments.com/features/appstore-digital-goods

A comprehensive guide to selling digital goods and services on iOS apps using Dodo Payments

## Introduction

Dodo Payments empowers developers to sell digital goods and services in iOS apps, handling complex aspects like tax compliance, currency conversion, and payouts. This comprehensive guide details how to integrate Dodo Payments into your iOS app, specifically for SaaS tools, content subscriptions, and digital utilities.

## Overview

Dodo Payments serves as your **Merchant of Record (MoR)**, managing critical aspects of your digital business:

<Tabs>
  <Tab title="What We Handle">
    * Tax collection and remittance (VAT, GST, and other regional taxes)
    * Global payments as per policies and local payment methods
    * Currency conversion and foreign exchange
    * Chargebacks and fraud prevention
    * End-customer invoicing and receipts
    * Compliance with regional regulations
  </Tab>

  <Tab title="What You Get">
    * A unified API for web and mobile platforms
    * Support for in-app checkouts (UPI, cards, wallets, BNPL)
    * Global payout support (Payoneer, Wise, local bank transfers)
    * Analytics and reporting dashboard
    * Secure payment processing
  </Tab>
</Tabs>

## Use Cases

<CardGroup>
  <Card title="Subscriptions" icon="repeat">
    * Premium content or feature access
    * Recurring billing with flexible options, Free trials, Proration, or Upgrades and downgrades
  </Card>

  <Card title="Courses and Learning" icon="graduation-cap">
    * Pay-per-course access
    * Bundled content packages
    * Lifetime or renewable licenses
    * Progress tracking integration
  </Card>

  <Card title="Digital Downloads" icon="download">
    * One-time purchases (PDFs, music, tools)
    * Digital asset delivery
    * License key management
  </Card>

  <Card title="SaaS Tools" icon="screwdriver-wrench">
    * Software-as-a-Service subscriptions
    * Usage-based billing
    * Team and enterprise plans
  </Card>
</CardGroup>

## Integration Flow

Your app opens Dodo's hosted checkout with the
[iOS checkout SDK](/developer-resources/sdks/ios), which presents it in
`SFSafariViewController` and hands back a typed result.

<Warning>
  Use the SDK rather than embedding checkout in a `WebView`. Apple Pay is only
  available in a real browser surface, so a `WebView` silently costs you wallet
  conversions — and payment flows inside a `WebView` are a common cause of App
  Store review rejections.
</Warning>

```mermaid theme={null}
flowchart LR
  A[Mobile App] -->|Request checkout| B(Your Server)
  B -->|Create checkout session| C(Dodo API)
  C -->|checkout_url| B
  B -->|checkout_url| A
  A -->|SDK opens SFSafariViewController| D[Hosted Checkout]
  D -->|Webhook| B
  B -->|Grant access| A
```

### Integration Steps

<Steps>
  <Step title="Mobile App to Your Server">
    Your app asks your own backend for a checkout URL, authenticated with the
    signed-in user's session token.
  </Step>

  <Step title="Your Server to Dodo API">
    Your backend creates a [checkout session](/developer-resources/checkout-session)
    with your API key and returns the `checkout_url` to the app.

    <Warning>
      Create checkout sessions on your server, never in the app. An API key shipped
      inside an app binary can be extracted from the bundle.
    </Warning>
  </Step>

  <Step title="Mobile App Opens Checkout">
    Pass the `checkout_url` to `DodoCheckout.start(...)`. The SDK presents it in
    `SFSafariViewController` and resolves with a typed result when the customer
    completes or dismisses checkout.
  </Step>

  <Step title="Dodo Payments to Your Server">
    Dodo Payments calls your webhook endpoint when the payment succeeds or the
    subscription activates.
  </Step>

  <Step title="Your Server Grants Access">
    Unlock the purchased content from that webhook, not from the result the app
    received. The SDK result is a UI hint, not proof of payment.
  </Step>
</Steps>

<CardGroup>
  <Card title="iOS Checkout SDK" icon="apple" href="/developer-resources/sdks/ios">
    Install steps and the full `start(...)` contract for Swift.
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    The end-to-end flow, plus the same contract for Android, React Native, and Flutter.
  </Card>
</CardGroup>

## Regional Availability

Dodo Payments enables alternative in-app purchase flows only in App Store regions where Apple explicitly allows external payments, or where a regulator or court order mandates it.

### Supported Regions

<AccordionGroup>
  <Accordion title="United States">
    Supported to the extent permitted by current court orders and Apple's updated guidelines.

    * Available under specific court-mandated provisions
    * Subject to Apple's compliance with legal requirements
    * Must follow Apple's implementation guidelines
  </Accordion>

  <Accordion title="European Union (EU) App Store">
    Supported via Apple's EU Alternative Terms and External Purchase Entitlement.

    * Enabled through Apple's EU Alternative Terms
    * Requires External Purchase Entitlement approval
    * Must comply with EU Digital Markets Act requirements
  </Accordion>

  <Accordion title="South Korea">
    Supported through the StoreKit External Purchase Entitlement for Korea-only binaries.

    * Available via StoreKit External Purchase Entitlement
    * Requires Korea-specific app binary
    * Must comply with Korean telecommunications law
  </Accordion>
</AccordionGroup>

<Warning>
  Always review and comply with Apple's region-specific entitlements and App Store Connect requirements before enabling Dodo Payments for any storefront. Using alternative payment flows in unsupported regions may result in app rejection or removal.
</Warning>

<Note>
  For some business models - such as services or certain categories of content - Apple may not require the use of in-app purchase (IAP) at all. Dodo Payments supports these models as well. Always verify your app's classification and Apple's latest guidelines to determine if IAP is mandatory for your use case.
</Note>

### Learn More

For a detailed breakdown of global policies, legal precedents, and strategic approaches to bypassing App Store fees, see our comprehensive guide:

<Card title="Bypassing App Store & Play Store Fees: A Strategic and Legal Playbook" icon="shield-check" href="/features/bypassing-app-store-fees">
  Learn where and how you can legally implement alternative payment flows, with up-to-date regional guidance and compliance tips.
</Card>


# B2B Payments
Source: https://docs.dodopayments.com/features/b2b-payments

The B2B Payments feature ensures that merchants processing B2B transactions have their customer’s Tax IDs verified during checkout, ensuring accurate tax application based on the customer's country and applicable regulations. This validation helps determine whether input tax collection applies or if the transaction falls under a reverse charge mechanism.

## **Tax ID Validation for B2B Transactions**

* If a **valid Tax ID** is provided during checkout, the invoice will include:
  * The **customer’s Tax ID**.
* Tax deductions will be determined based on the applicable regulations for the customer’s country.
* The invoice will include **Dodo Payments’ tax details**, along with the tax applied to the transaction.

## Collecting a Business Name for B2B Invoices

For B2B purchases, you can have the customer's **legal business name** rendered on the invoice instead of the buyer's personal name. This is collected alongside the Tax ID via the `customer_business_name` field.

When the customer selects **Purchasing as a business** at checkout, they're prompted for both a **Business Name** and a **Tax ID Number**.

The Tax ID is validated live as the customer types. For EU member states, Great Britain, and Australia, checkout performs both format/checksum validation **and** a live registry lookup (VIES, HMRC, and ABR respectively) and autofills the registered legal business name when a match is found. For all other countries, only format/checksum validation is performed.

<Frame>
  <img alt="Checkout page with the 'Purchasing as a business' toggle enabled, showing Business Name and Tax ID Number fields" />
</Frame>

The business name appears on the invoice only when **all three** conditions are met:

1. The transaction is B2B (`b2b = true`)
2. A `tax_id` is present
3. A non-empty `customer_business_name` is supplied

If any condition is not met, the customer's personal name is used instead.

### Setting it at checkout

Pass `customer_business_name` directly, and/or enable `allow_customer_editing_business_name` to let the customer enter or edit it on the checkout page next to their Tax ID:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: { email: 'buyer@acme.com' },
  tax_id: 'GB123456789',
  customer_business_name: 'Acme Corp Ltd',
  feature_flags: {
    allow_tax_id: true,
    allow_customer_editing_business_name: true // optional: let the customer edit it
  },
  return_url: 'https://yoursite.com/return'
});
```

| Surface           | Field                                                                          | Notes                                                     |
| ----------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Checkout Sessions | `customer_business_name`, `feature_flags.allow_customer_editing_business_name` | Max 250 chars; flag defaults to `false`                   |
| Payments          | `customer_business_name`                                                       | Max 250 chars                                             |
| Subscriptions     | `customer_business_name`                                                       | Set or clear via `PATCH /subscriptions/{subscription_id}` |

<Warning>
  `customer_business_name` cannot be set without a `tax_id` — the request is rejected. Clearing the `tax_id` also clears the business name, since the two are coupled on the invoice. Surrounding whitespace is trimmed, and whitespace-only values are treated as an explicit clear.
</Warning>

## **Tax Treatment for B2C Transactions**

* Transactions where a valid Tax ID is **not provided** will be treated as **B2C transactions**, and tax will be deducted as per the applicable tax regulations in the customer’s country.
* The invoice will include **Dodo Payments’ tax details**, along with the tax applied to the transaction.

## Reverse Charge Mechanism

Generally, the supplier of goods or services is liable to pay VAT/Service Tax/GST.
However, in specified cases like imports and other notified supplies, the liability is on the recipient (customer) under the reverse charge mechanism. Reverse Charge means the liability to pay tax is on the recipient of supply of goods or services instead of the supplier of such goods or services in respect of notified categories of supply.

## **Reverse Charge Applicability**

* In certain cases, where applicable by law, tax will **not be deducted** at checkout and the transaction will be subject to a **reverse charge mechanism**.
* The invoice will clearly indicate when a reverse charge applies, as per regulatory requirements.


# Bring Your Own Processor (BYOP)
Source: https://docs.dodopayments.com/features/byop

Keep your own Stripe or Adyen account and route payments through it, while Dodo Payments powers subscriptions, invoicing, and analytics on top.

**Bring Your Own Processor (BYOP)** lets you connect your own payment processor — currently **Stripe** or **Adyen**, with support for more processors coming soon — and keep using Dodo Payments for everything that sits on top of the transaction: products, subscriptions, license keys and the entitlement engine, invoicing, the customer portal, and analytics.

You decide, per customer country, whether a payment is processed by **your processor** (you remain the merchant of record for that route) or by **Dodo Payments** as your full-service Merchant of Record. Countries you don't explicitly route fall back to Dodo automatically.

<CardGroup>
  <Card title="Route by geography" icon="globe">
    Send payments from specific countries to your own processor, and everything else to Dodo.
  </Card>

  <Card title="Keep your processor accounts" icon="plug">
    Continue using your existing Stripe or Adyen accounts and relationships.
  </Card>

  <Card title="Stay the merchant of record" icon="building">
    On your own routes, you remain the legal seller and control tax, disputes, and payouts.
  </Card>

  <Card title="One billing layer" icon="layer-group">
    Dodo powers products, subscriptions, invoices, and analytics across both routes.
  </Card>
</CardGroup>

## BYOP vs. Dodo as Merchant of Record

When you enable BYOP you choose how each payment is handled. The two models can run side by side, routed by customer country.

| Feature                    | Dodo as Merchant of Record               | Bring Your Own Processor                   |
| -------------------------- | ---------------------------------------- | ------------------------------------------ |
| Legal seller of record     | Dodo Payments                            | Your company                               |
| Tax (VAT, GST & sales tax) | Calculated, collected & remitted for you | You register, collect & file               |
| Chargebacks & fraud        | Liability & protection handled by Dodo   | You manage with your processor's own tools |
| PCI compliance             | Handled by Dodo                          | You manage                                 |
| Payment methods            | 30+ global & local, multi-currency       | Cards only (credit/debit)                  |
| Payouts                    | Aggregated global payouts                | Direct from your processor                 |
| Setup                      | Simple, go live in minutes               | Moderate, add keys & routing               |
| Best for                   | Selling globally, hands-off compliance   | Existing processor & regional control      |

<Tip>
  A common setup is **hybrid**: route a country where you already have a registered entity and processor (for example, your home market) to your own processor, and let Dodo handle the rest of the world as Merchant of Record.
</Tip>

## Supported processors

Today you can connect **Stripe** or **Adyen**. Support for more processors is on the way.

<CardGroup>
  <Card title="Stripe" icon="stripe" />

  <Card title="Adyen" icon="https://mintcdn.com/dodopayments/4tpr59mZcbRBC9sk/images/logos/adyen.svg?fit=max&auto=format&n=4tpr59mZcbRBC9sk&q=85&s=0acd6437cfd0362c95fc8acecb7dd32f" />
</CardGroup>

<Note>
  Payments routed through your own processor currently support **credit and debit cards only**. We're adding more payment methods soon.
</Note>

<Warning>
  Both **Stripe** and **Adyen** require **raw card API access** enabled on your account so that Dodo can power billing on top of your processor. Each processor grants this on request — you arrange it by contacting the processor's support before you connect. See the [Stripe](/features/byop/stripe) and [Adyen](/features/byop/adyen) guides for details.
</Warning>

<Info>
  Connections are configured **per environment**. The processor you connect in **test mode** (Sandbox) is separate from the one in **live mode** (Production); set up both if you want to test before going live. The setup wizard follows your dashboard's global test/live toggle.
</Info>

## Set up BYOP

Open **Settings → BYOP** in the dashboard and select **Configure** on the *Bring Your Own Processor* card to launch the setup wizard.

<Frame>
  <img alt="BYOP settings showing the Merchant of Record and Bring Your Own Processor options with a feature comparison" />
</Frame>

<Steps>
  <Step title="Choose a payment processor">
    Select the processor you want to connect, **Stripe** or **Adyen**, and continue.

    <Frame>
      <img alt="Select Payment Processor dialog with Stripe and Adyen options" />
    </Frame>
  </Step>

  <Step title="Connect your account">
    Give the connection a **Provider Name** (useful when you have multiple accounts from the same processor, e.g. *Stripe US* and *Stripe UK*), then enter your processor's **Secret Key** (for Stripe, your `sk_...` key).

    For **Adyen**, also enter your **Merchant Account** identifier.

    <Frame>
      <img alt="Connect Your Stripe Account step showing processor name, secret key, webhook endpoint, and signing secret fields" />
    </Frame>

    Saving creates the connection and generates a **Webhook Endpoint** unique to it. Add that URL as a webhook destination in your processor's dashboard, then paste the **Webhook Signing Secret** back into Dodo to finish:

    * **Stripe**: paste the signing secret from the webhook endpoint you added.
    * **Adyen**: paste the **HMAC key** from *Customer Area → Webhooks*.

    <Note>
      Your secret key is stored securely and can't be viewed or changed after saving. You only ever configure the Dodo-generated webhook URL in your processor; you never interact with the underlying infrastructure directly.
    </Note>

    <Tip>
      Use **Verify connection** after saving to run a test call against your processor and confirm the keys and webhook secret are valid before you go live.
    </Tip>
  </Step>

  <Step title="Configure payment routing">
    Add **routing rules** that map customer countries to a processor. Each country can be routed to exactly one processor.

    * **Your processor** handles payments from the countries you assign to it.
    * **Dodo Payments** handles **Rest of the World** (every country you don't explicitly route) as Merchant of Record.

    <Frame>
      <img alt="Configure Payment Routing step showing Stripe US routed to United States and Dodo Payments as the Rest of the World default" />
    </Frame>

    Use **Add Route** to assign one or more countries to a processor.

    <Frame>
      <img alt="Add Route panel selecting a processor and countries" />
    </Frame>

    <Info>
      **Routing guidelines**

      * "Rest of World" covers all countries not listed above.
      * Dodo Payments MoR routes handle compliance and tax automatically.
      * Your own processor routes require separate tax configuration if needed.
    </Info>
  </Step>

  <Step title="Configure invoice information">
    For payments routed through your own processor, **you** are the seller on the invoice. Enter the business details that should appear on those invoices:

    * **Registered Business Name** (required)
    * **Tax ID** (EIN, SSN, etc.; optional, with format validation available for US EINs)
    * **Statement Descriptor** (required): what customers see on their bank statement (5 to 22 characters)
    * **Registered Business Address** (required): start typing to search and autofill your address
    * **Privacy Policy** and **Terms of Service** links (required)

    A live **Invoice Header Preview** shows how the details will appear. These details apply **only** to invoices for routes you handle through your own processor; Dodo-routed payments continue to use Dodo's Merchant of Record details.

    <Frame>
      <img alt="Configure Invoice Information step with business details and a live invoice header preview" />
    </Frame>
  </Step>

  <Step title="Review and finish">
    Review your processor connection, routing rules, and invoice details. Confirm that the routing and billing details are correct, then select **Finish setup**.

    <Frame>
      <img alt="Review Your Configuration step summarising the processor, routing, and invoice details" />
    </Frame>
  </Step>
</Steps>

Once configured, the BYOP card shows **Edit Configuration**, and you can return to MoR-only at any time with **Edit routing rules**.

<Frame>
  <img alt="BYOP settings after configuration showing Edit Configuration and routing options" />
</Frame>

## How routing works

Routing is determined by the **customer's country** at payment time. The same logic applies across one-time payments, checkout sessions, and subscription sign-ups. Renewals reuse the processor the subscription was created on (see [Subscriptions](#subscriptions)).

```mermaid theme={null}
flowchart TD
    A[👤 Customer pays] --> B{Customer country<br/>has a route?}
    B -->|Yes| C[🏦 Your processor<br/>You are merchant of record]
    B -->|No, Rest of World| D[🟢 Dodo Payments<br/>Dodo is Merchant of Record]
    C --> E[🧾 Dodo powers billing,<br/>invoicing & subscriptions]
    D --> E
```

On a route handled by **your processor**:

* The payment is processed on **your** processor account in the billing currency.
* **No tax is calculated or collected** by Dodo; you remain responsible for tax on that route.
* Invoices use the **business details and statement descriptor** you configured, with no Merchant of Record references.
* Payouts settle **directly to you** from your processor; nothing flows through Dodo's wallet.

On a route handled by **Dodo** (Rest of World), Dodo behaves exactly as your full-service Merchant of Record, handling tax, compliance, disputes, fraud, and aggregated payouts.

## Subscriptions

Subscriptions stay on the processor they were created on. At renewal, Dodo charges the same payment processor that was used to purchase the subscription, reusing the payment mandate stored against it. Routing rules are not re-evaluated on every renewal.

## Seeing which processor handled a payment

Once BYOP is configured, the **Payments** and **Disputes** tables show a processor icon (Stripe, Adyen, or Dodo) next to each row, and the payment and dispute detail pages include a **Payment Processor** field, so you can always tell which route handled a given transaction.

## Refunds, disputes & payouts

<Tabs>
  <Tab title="Refunds">
    You initiate refunds from the Dodo dashboard as usual. For payments routed through your own processor, the refund is executed on that processor; for Dodo-routed payments, Dodo processes the refund.
  </Tab>

  <Tab title="Disputes">
    The Dodo dashboard shows disputes for **Dodo-processed** payments only.

    > Only Dodo-processed disputes are shown here. Disputes on your own processor (e.g. Stripe) are managed in that processor's dashboard.

    Evidence upload, accept, and challenge actions are available only for Dodo-processed disputes. Disputes on your processor are handled with your processor's own tools.
  </Tab>

  <Tab title="Payouts">
    For routes on your own processor, your processor pays you **directly**; those payouts don't appear in Dodo.

    > Only Dodo payouts are visible here. Payouts on your own processor occur in that processor.

    Dodo payouts (for Rest-of-World MoR volume) follow the standard [payout structure](/features/payouts/payout-structure).
  </Tab>
</Tabs>

## Analytics

Revenue, tax, and subscription analytics include **both** routes so you see the full picture of your billing. Disputes and payouts widgets show **Dodo-processed** activity only, with a banner indicating that activity on your own processor lives in that processor's dashboard.

## Billing fee

Dodo applies a small **BYOP billing fee** on payments routed through your own processor, since Dodo still powers your products, subscriptions, invoicing, and analytics on those transactions. It appears as a `byop_fee` line in your balance ledger. The default rate is **0.5%**; the exact rate is confirmed as part of enabling BYOP for your account. [Reach out](mailto:founders@dodopayments.com) for details.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Which processors can I connect?">
    Stripe and Adyen are supported today, with support for more processors coming soon. Both require **raw card API access** enabled on your account, which you arrange by contacting the processor's support. See the [Stripe](/features/byop/stripe) and [Adyen](/features/byop/adyen) guides for details.
  </Accordion>

  <Accordion title="Can I route only some countries to my processor?">
    Yes. Assign specific countries to your processor and leave the rest as **Rest of the World**, which Dodo handles as Merchant of Record. Each country routes to exactly one processor.
  </Accordion>

  <Accordion title="Who is the merchant of record on BYOP routes?">
    You are. On routes handled by your own processor, you remain the legal seller and are responsible for tax, chargebacks, PCI compliance, and payouts on those transactions.
  </Accordion>

  <Accordion title="Does Dodo calculate tax on my processor's routes?">
    No. Tax is not calculated or collected on routes handled through your own processor; you manage tax for those transactions. Dodo continues to handle tax on Dodo-routed (MoR) payments.
  </Accordion>

  <Accordion title="What happens to active subscriptions if I disable a processor?">
    Renewals on that processor will fail and surface as failed payments in the dashboard. Re-enable the processor to restore renewals.
  </Accordion>
</AccordionGroup>

## Get started

<Card title="What is Merchant of Record?" icon="building-columns" href="/features/mor-introduction">
  Understand how Dodo's full-service MoR model works.
</Card>


# Adyen - Connect & Raw Card API Access
Source: https://docs.dodopayments.com/features/byop/adyen

Generate the API key, merchant account, and HMAC-signed webhook you need to connect Adyen as your own processor with Bring Your Own Processor (BYOP).

<Note>
  This guide applies when you connect **Adyen** as your own processor through [Bring Your Own Processor (BYOP)](/features/byop). [Talk to us](mailto:founders@dodopayments.com) if you need help.
</Note>

## Enable raw card data access

Before Dodo can route payments through Adyen, your Adyen account needs **raw card data access** enabled. Adyen gates this behind PCI DSS compliance. Because **Dodo Payments handles the raw card data on your behalf** and is **PCI DSS Level 1 compliant**, you provide **Dodo Payments' Attestation of Compliance (AOC)** to Adyen — you don't need your own certification.

<Card title="Dodo Payments PCI DSS Attestation of Compliance (AOC)" icon="file-shield" href="https://pub-2a89184e4c954b599464449d23f506bb.r2.dev/dodo-payments-pci-dss-aoc.pdf">
  Download Dodo Payments' current AOC and submit it to Adyen support to enable raw card data access.
</Card>

Contact Adyen support to request raw card access for your merchant account, attaching the AOC above.

## What you'll need

To connect Adyen in **Settings → BYOP**, gather three values from your Adyen Customer Area:

| Value                | Where it comes from                    |
| -------------------- | -------------------------------------- |
| **API key**          | Developers → API credentials           |
| **Merchant Account** | Your Adyen merchant account identifier |
| **HMAC key**         | Generated when you set up the webhook  |

<Info>
  Adyen keeps **test** (`ca-test.adyen.com`) and **live** (`ca-live.adyen.com`) credentials separate. Generate credentials in the environment that matches the mode you're configuring in Dodo.
</Info>

## Step 1: Generate an API key

<Steps>
  <Step title="Open API credentials">
    In the Adyen Customer Area, go to **Developers → API credentials**. You need the **Manage API credentials** or **Merchant admin** role.
  </Step>

  <Step title="Select your credential">
    Choose the **Payments** tab and select your credential username (it looks like `ws_123456@Company.YourCompanyAccount`).
  </Step>

  <Step title="Generate the key">
    Go to **Server settings → Authentication**, open the **API key** tab, and select **Generate API key**.
  </Step>

  <Step title="Copy it immediately">
    Copy and store the key securely; you can't copy it again after leaving the page. A newly generated key is active immediately, and the previous key keeps working for 24 hours.
  </Step>
</Steps>

## Step 2: Find your merchant account

Your **merchant account** is the account identifier Adyen uses to process your transactions. It's shown in the account selector at the top of the Customer Area (for example, `YourCompany_ECOM`). You'll paste this into the **Merchant Account** field in Dodo.

## Step 3: Set up the webhook and HMAC key

Dodo generates a **Webhook Endpoint** URL when you save the Adyen connection. Add it as a webhook in Adyen and generate an HMAC key. You need the **Merchant admin** or **Merchant technical integrator** role.

<Steps>
  <Step title="Create a webhook">
    In the Customer Area, go to **Developers → Webhooks** and select **Create new webhook**. From the list, select **Add** for the **Standard webhook** type.
  </Step>

  <Step title="Configure the webhook">
    * Enter a **Description**.
    * Toggle **Enabled** to activate it.
    * Under **Server configuration**, paste the **Webhook Endpoint** URL that Dodo generated into the **URL** field (it must be HTTPS and publicly accessible).
  </Step>

  <Step title="Generate the HMAC key">
    Under **Security**, in the **HMAC Key** section, select **Generate** to create a new HMAC key. Copy it and store it securely; you won't be able to copy it again later. Then select **Save configuration**.
  </Step>

  <Step title="Paste the HMAC key into Dodo">
    Back in **Settings → BYOP**, paste the HMAC key into the **Webhook Signing Secret** field to finish the connection.

    <Card title="Set up BYOP" icon="shuffle" href="/features/byop">
      Follow the full Bring Your Own Processor setup flow.
    </Card>
  </Step>
</Steps>

<Tip>
  After saving, use **Verify connection** in Dodo to run a test call against Adyen and confirm your API key, merchant account, and HMAC key are valid before you go live.
</Tip>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="What is the HMAC key for?">
    Adyen signs every webhook with an HMAC signature so the receiver can verify the notification's integrity and origin. Dodo uses the HMAC key you provide to validate webhooks from your Adyen account.
  </Accordion>

  <Accordion title="I lost my API key or HMAC key, what now?">
    Neither can be retrieved after creation. Generate a new API key under **Developers → API credentials**, or a new HMAC key in the webhook settings, then update the value in **Settings → BYOP**.
  </Accordion>

  <Accordion title="Do test and live use the same credentials?">
    No. Generate credentials in the matching environment, test (`ca-test.adyen.com`) or live (`ca-live.adyen.com`), and configure them in the corresponding mode in Dodo.
  </Accordion>
</AccordionGroup>

## References

* [Adyen: API credentials](https://docs.adyen.com/development-resources/api-credentials/)
* [Adyen: Configure and manage webhooks](https://docs.adyen.com/development-resources/webhooks/configure-and-manage)


# Stripe - Connect & Raw Card API Access
Source: https://docs.dodopayments.com/features/byop/stripe

Enable raw card data API access on Stripe with Dodo Payments' PCI DSS AOC, then connect your Stripe account to Bring Your Own Processor (BYOP).

<Note>
  This guide applies when you connect **Stripe** as your own processor through [Bring Your Own Processor (BYOP)](/features/byop). [Talk to us](mailto:founders@dodopayments.com) if you need help.
</Note>

## Enable raw card data access

To route payments through your Stripe account while Dodo Payments powers billing on top, Dodo needs to pass card details to Stripe on your behalf using Stripe's **raw card data APIs**.

By default, Stripe accounts can't send raw card numbers (PANs) directly to its APIs. Stripe gates this behind an approval that confirms the systems handling raw card data are **PCI DSS compliant**. With BYOP, the system that handles card data is **Dodo Payments**, which is PCI DSS Level 1 compliant — so you prove compliance using Dodo Payments' certification rather than your own. You request this access once, per account.

When you request access, Stripe asks for a short description of how card data is handled — state that **Dodo Payments**, your PCI DSS Level 1-compliant payment provider, processes the raw card data and that your own systems never store or touch raw card numbers (PANs). Because Dodo Payments handles the data, you don't need your own SAQ D; submit **Dodo Payments' Attestation of Compliance (AOC)** as your proof:

<Card title="Dodo Payments PCI DSS Attestation of Compliance (AOC)" icon="file-shield" href="https://pub-2a89184e4c954b599464449d23f506bb.r2.dev/dodo-payments-pci-dss-aoc.pdf">
  Download Dodo Payments' current AOC and submit it to Stripe when you request raw card data access.
</Card>

<Tip>
  **Test mode requires no documentation.** You can ask Stripe to enable raw card data APIs for **test mode** right away so you can build and verify your BYOP setup. Live mode still requires the Dodo Payments AOC above.
</Tip>

Request access directly through Stripe's official guide, and submit the Dodo Payments AOC when Stripe asks for PCI documentation:

<Card title="Enabling access to raw card data APIs" icon="stripe" href="https://support.stripe.com/questions/enabling-access-to-raw-card-data-apis">
  Stripe's guide to requesting raw card data API access on your account.
</Card>

## What you'll need

Once Stripe confirms raw card data access, connect Stripe in **Settings → BYOP**. Gather two values from your Stripe Dashboard:

| Value                      | Where it comes from                |
| -------------------------- | ---------------------------------- |
| **Secret key**             | Developers → API keys              |
| **Webhook signing secret** | Generated when you add the webhook |

<Info>
  Stripe keeps **test** and **live** credentials separate — switch with the **Test mode / Live mode** toggle in the Dashboard. Generate credentials in the environment that matches the mode you're configuring in Dodo.
</Info>

## Step 1: Get your secret key

<Steps>
  <Step title="Open API keys">
    In the Stripe Dashboard, go to **Developers → API keys**. Use the **Test mode / Live mode** toggle to match the environment you're configuring.
  </Step>

  <Step title="Copy your secret key">
    Copy the **Secret key** — it starts with `sk_test_` in test mode or `sk_live_` in live mode (a restricted key, `rk_...`, also works if you prefer to scope permissions). You'll paste this into the **Secret Key** field in Dodo.
  </Step>
</Steps>

## Step 2: Set up the webhook and signing secret

Dodo generates a **Webhook Endpoint** URL when you save the Stripe connection. Add it as a webhook in Stripe, then copy the signing secret.

<Steps>
  <Step title="Add an endpoint">
    In the Stripe Dashboard, go to **Developers → Webhooks** and select **Add endpoint**. Paste the **Webhook Endpoint** URL that Dodo generated (it must be HTTPS and publicly accessible) and select the events to listen for.
  </Step>

  <Step title="Reveal the signing secret">
    Open the endpoint's detail page and select **Reveal secret** to view the **Signing secret** — it starts with `whsec_`. The secret is unique to each endpoint, and test and live endpoints have different secrets.
  </Step>

  <Step title="Paste the signing secret into Dodo">
    Back in **Settings → BYOP**, paste the signing secret into the **Webhook Signing Secret** field to finish the connection.

    <Card title="Set up BYOP" icon="shuffle" href="/features/byop">
      Follow the full Bring Your Own Processor setup flow.
    </Card>
  </Step>
</Steps>

<Tip>
  After saving, use **Verify connection** in Dodo to run a test call against Stripe and confirm your secret key and webhook signing secret are valid before you go live.
</Tip>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Do I need my own PCI certification (SAQ D)?">
    No. Because **Dodo Payments handles the raw card data on your behalf** and is **PCI DSS Level 1 compliant**, you submit **Dodo Payments' Attestation of Compliance (AOC)** to Stripe instead of completing your own SAQ D or undergoing a separate audit.
  </Accordion>

  <Accordion title="Why can't Stripe just enable this by default?">
    Sending raw card numbers to an API brings the sending system into PCI DSS scope. Stripe requires proof of PCI compliance before enabling raw card data APIs so that cardholder data stays protected. Dodo Payments is **PCI DSS Level 1 compliant**, so you provide Dodo Payments' AOC as that proof.
  </Accordion>

  <Accordion title="Can I test BYOP before getting live approval?">
    Yes. Ask Stripe to enable raw card data APIs in **test mode**, which needs no PCI documentation, and connect Stripe in test mode in Dodo. You'll need the live-mode approval before processing real payments.
  </Accordion>

  <Accordion title="I lost my secret key or signing secret, what now?">
    Generate a new key under **Developers → API keys**, or open the webhook endpoint and select **Reveal secret** to view the signing secret again, then update the value in **Settings → BYOP**.
  </Accordion>
</AccordionGroup>

## References

* [Dodo Payments PCI DSS Attestation of Compliance (AOC)](https://pub-2a89184e4c954b599464449d23f506bb.r2.dev/dodo-payments-pci-dss-aoc.pdf)
* [Stripe Support: Enabling access to raw card data APIs](https://support.stripe.com/questions/enabling-access-to-raw-card-data-apis)
* [Stripe: API keys](https://docs.stripe.com/keys)
* [Stripe: Webhook signing secret](https://docs.stripe.com/webhooks/signature)


# Checkout Features
Source: https://docs.dodopayments.com/features/checkout

Conversion-optimized, globally compliant checkout with multi-currency, multi-language support, automatic tax calculation, discount codes, add-ons, and smart address collection.

<Frame>
  <img alt="Checkout page" />
</Frame>

<Info>
  Dodo Payments checkout is a conversion-optimized, globally compliant checkout designed for digital products and SaaS businesses. It supports multiple currencies, languages, taxes, discounts, add-ons, and business-friendly compliance workflows.
</Info>

<CardGroup>
  <Card title="Checkout Sessions API" icon="code" href="/api-reference/checkout-sessions/create">
    Create hosted checkout sessions programmatically.
  </Card>

  <Card title="Preview Checkout" icon="eye" href="/api-reference/checkout-sessions/preview">
    Calculate pricing and taxes before creating a session.
  </Card>

  <Card title="Payment Methods" icon="credit-card" href="/features/payment-methods">
    Supported payment methods and configuration options.
  </Card>
</CardGroup>

<Note>
  Checkout links generated through the [Checkout Sessions API](/api-reference/checkout-sessions/create) are not reusable and expire within 24 hours. Generate a fresh session for each customer and each payment attempt.
</Note>

## Adaptive Currency

Adaptive Currency allows customers to pay in their preferred local currency, improving trust and conversion rates.

### How It Works

1. **Enable**: Enable Adaptive Currency from **Settings → Business**
2. **Select**: Customers can switch currencies directly on checkout
3. **Convert**: Prices are dynamically converted using real-time FX rates
4. **Display**: Final payable amount is shown transparently before payment

<Frame>
  <img alt="Currency selector on checkout" />
</Frame>

<Card title="Adaptive Currency" icon="money-bill-transfer" href="/features/adaptive-currency">
  Learn more about supported currencies, conversion fees, and refund handling.
</Card>

## Multi-Language Checkout

Dodo Payments supports multiple languages on the checkout page, allowing customers to complete payments in a language they're comfortable with.

<Frame>
  <img alt="Language selector on checkout" />
</Frame>

### Key Highlights

* Language selector available directly on checkout
* UI text, labels, and system messages are localized
* Improves accessibility and international conversion

### Supported Languages

The checkout page supports 21 languages:

| Language   | Code |
| ---------- | ---- |
| Arabic     | `ar` |
| Catalan    | `ca` |
| Chinese    | `zh` |
| Dutch      | `nl` |
| English    | `en` |
| French     | `fr` |
| German     | `de` |
| Hebrew     | `he` |
| Indonesian | `id` |
| Italian    | `it` |
| Japanese   | `ja` |
| Korean     | `ko` |
| Malay      | `ms` |
| Polish     | `pl` |
| Portuguese | `pt` |
| Romanian   | `ro` |
| Russian    | `ru` |
| Spanish    | `es` |
| Swedish    | `sv` |
| Thai       | `th` |
| Turkish    | `tr` |

<Tip>
  You can force a specific language on the checkout by setting the `force_language` parameter when creating a checkout session. See the [Checkout Sessions API](/developer-resources/checkout-session#14-forcing-a-language) for details.
</Tip>

## Automatic Tax Calculation

Taxes are automatically calculated based on the customer's billing location, ensuring compliance with GST, VAT, and sales tax requirements without manual setup.

### How Tax Calculation Works

<Steps>
  <Step title="Location Detection">
    Tax rules are applied based on the customer's country (and region where applicable).
  </Step>

  <Step title="Dynamic Updates">
    Tax amount updates automatically when:

    * Country changes
    * Address is updated
  </Step>

  <Step title="Transparent Display">
    Final tax breakdown is shown clearly before payment.
  </Step>
</Steps>

<Tip>
  Tax calculation is fully automated. No manual configuration required for standard digital goods and SaaS products.
</Tip>

## Business Tax ID Support

For registered businesses, the checkout allows customers to enter their Business Tax ID (e.g., VAT/GST number).

### What Happens When a Tax ID Is Entered

* Tax eligibility is validated in real-time
* Applicable tax exemptions or reverse-charge rules are applied
* Tax amount updates instantly on checkout

<Frame>
  <img alt="Business Tax ID entry on checkout" />
</Frame>

<Info>
  This is especially useful for B2B SaaS and digital services where business customers may be eligible for tax exemptions.
</Info>

## Discount Codes

Customers can apply discount or promo codes you've created in the dashboard directly on the checkout page.

### Checkout Experience

1. Customer enters the discount code
2. Discount is validated instantly
3. Updated price and savings are shown clearly

<Frame>
  <img alt="Discount code entry on checkout" />
</Frame>

### API Integration

Pre-apply one or more stacked discount codes or enable the discount input field:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  discount_codes: ['WELCOME20'], // Pre-apply one or more codes (max 20, applied in order)
  feature_flags: {
    allow_discount_code: true // Shown by default; set to false to hide the field
  },
  return_url: 'https://yoursite.com/return'
});
```

<Info>
  `discount_codes` accepts an array of up to 20 codes that stack in order. The singular `discount_code` field is deprecated but still works — existing integrations don't need to change immediately. Migrate to `discount_codes` when convenient to use stacking and the richer response shape.
</Info>

<Card title="Discount Codes" icon="percent" href="/features/discount-codes">
  Learn how to create and manage discount codes.
</Card>

<Card title="Validate Discount by Code" icon="tag" href="/api-reference/discounts/get-discount-by-code">
  Look up and validate discounts using code names.
</Card>

## Smart Address Collection

The checkout supports flexible address entry for faster completion.

### Options Available

| Option                      | Description                                                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Google Address Autofill** | Quick selection with autocomplete                                                                         |
| **Manual Entry**            | Full control for complete addresses                                                                       |
| **Country Selection**       | Drives tax and compliance logic                                                                           |
| **Minimal Address**         | Collect only country (and ZIP where required for tax) — see [Minimal Address Mode](#minimal-address-mode) |

<Tip>
  Address collection balances speed, accuracy, and global coverage to maximize conversion while ensuring compliance.
</Tip>

### Minimal Address Mode

For maximum conversion, enable minimal address collection to reduce checkout friction. When `minimal_address` is set to `true`, the checkout only collects:

* **Country** — always required for tax determination
* **ZIP/Postal code** — only in regions where it's necessary for sales tax, VAT, or GST calculation

All other address fields (street, city, state) are skipped, significantly speeding up checkout completion.

<Frame>
  <img alt="Minimal address mode showing only country and ZIP/postal code fields on checkout" />
</Frame>

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  minimal_address: true,
  return_url: 'https://yoursite.com/return'
});
```

<Info>
  Full address collection remains the default. Enable `minimal_address` for digital products and SaaS flows where complete billing details aren't required.
</Info>

<Card title="Minimal Address Reference" icon="address-card" href="/developer-resources/checkout-session#request-body">
  See the full `minimal_address` parameter reference in the Checkout Sessions API guide.
</Card>

## Phone Number Collection

Control whether the phone number field appears on checkout — and whether it's required — using checkout session feature flags.

| Flag                            | Default | Behavior                                                                           |
| ------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `allow_phone_number_collection` | `true`  | Shows the phone number field on the checkout form                                  |
| `require_phone_number`          | `false` | Makes the phone number field required (form validation enforces a non-empty value) |

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_phone_number_collection: true,
    require_phone_number: true
  },
  return_url: 'https://yoursite.com/return'
});
```

<Warning>
  `require_phone_number: true` requires `allow_phone_number_collection: true`. The API rejects sessions where phone collection is disabled while phone number is required.
</Warning>

<Tip>
  Use `require_phone_number` for B2B SaaS, regulated industries, or any flow where you need a verified contact channel for support, fraud review, or compliance.
</Tip>

## Custom Fields

Collect additional information from customers during checkout by defining custom form fields. This is useful for gathering data like company name, team size, referral source, or any other business-specific information.

### Available Field Types

| Type       | Description                    |
| ---------- | ------------------------------ |
| `text`     | Single-line text input         |
| `number`   | Numeric input                  |
| `email`    | Email address with validation  |
| `url`      | URL with validation            |
| `date`     | Date picker                    |
| `dropdown` | Select from predefined options |
| `boolean`  | Yes/No toggle                  |

### Example

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '200+']
    }
  ],
  return_url: 'https://yoursite.com/return'
});
```

<Info>
  Customer responses are automatically included in webhook payloads (`payment.succeeded`, `subscription.active`) and API responses via the `custom_field_responses` array. You can define up to 5 custom fields per checkout session.
</Info>

<Card title="Custom Fields Guide" icon="input-text" href="/developer-resources/checkout-session#15-collecting-custom-fields">
  Learn more about custom field configuration and accessing responses.
</Card>

## Privacy Policy & Terms Acceptance

To ensure legal and compliance transparency:

* [Privacy Policy](https://dodopayments.com/privacy-policy) and [Buyer Terms](https://dodopayments.com/buyer-terms) links are clearly displayed on checkout
* Customers explicitly acknowledge these before completing payment

<Info>
  This helps meet global consumer protection and data privacy requirements including GDPR compliance.
</Info>

## Collection Checkout

Product Collections enable a unified checkout experience where customers can view and select from multiple related products (e.g., Starter, Pro, Enterprise plans) in a single checkout.

### How It Works

1. **All products displayed**: Customers see every active product in the collection
2. **First product pre-selected**: The first product in the collection is automatically selected
3. **Compare options**: Customers can compare pricing and features before choosing
4. **Single selection**: After selecting a product, checkout proceeds with standard payment flow

### Creating a Collection Checkout

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_collection_id: 'pdc_abc123',
  product_cart: [], // Required: pass an empty array for collection checkout
  return_url: 'https://yoursite.com/return'
});
```

<Warning>
  When using `product_collection_id`, pass an empty `product_cart` array. Discount codes cannot be pre-applied at session creation.
</Warning>

<Card title="Product Collections" icon="layer-group" href="/features/product-collections">
  Learn how to create and manage product collections for unified checkout experiences.
</Card>

## Checkout Session Configuration

Control checkout behavior using the Checkout Sessions API:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'Jane Doe'
  },
  billing_currency: 'EUR', // Set specific currency
  discount_codes: ['PROMO10'],
  feature_flags: {
    allow_discount_code: true
  },
  return_url: 'https://yoursite.com/return',
  cancel_url: 'https://yoursite.com/pricing', // Optional: where to redirect on cancel
  metadata: {
    order_ref: 'ORD-12345'
  }
});
```

<Info>
  After payment, customers are redirected to your `return_url` with query parameters appended automatically -- including `payment_id` or `subscription_id`, `status`, `email`, and `license_key` (if applicable). See the [Checkout Sessions guide](/developer-resources/checkout-session#request-body) for the full list.
</Info>

<CardGroup>
  <Card title="Checkout Sessions API" icon="code" href="/api-reference/checkout-sessions/create">
    Complete API reference for checkout sessions.
  </Card>

  <Card title="Checkout Integration Guide" icon="book" href="/developer-resources/checkout-session">
    Step-by-step guide to integrating checkout.
  </Card>
</CardGroup>

## Checkout Theme Customization

Customize the checkout page appearance to match your brand using the `customization.theme_config` parameter when creating a checkout session via the API. Configure colors, fonts, border radius, and button text for both light and dark modes.

<Frame>
  <img alt="Custom themed checkout page" />
</Frame>

<Card title="Design & Theme Customization" icon="palette" href="/features/design">
  Configure themes visually from the dashboard with pre-built themes, typography, colors, and live preview.
</Card>

<Info>
  This section covers the **server-side API** theme configuration using `customization.theme_config`. If you're using the **Checkout SDK** (overlay or inline checkout), see the theme customization section in [Overlay Checkout](/developer-resources/overlay-checkout#theme-customization) which uses camelCase properties (e.g., `bgPrimary` instead of `bg_primary`).
</Info>

### Theme Configuration Options

| Property             | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `light`              | Color configuration for light mode                                          |
| `dark`               | Color configuration for dark mode                                           |
| `font_primary_url`   | URL for the primary font                                                    |
| `font_secondary_url` | URL for the secondary font                                                  |
| `font_size`          | Font size: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`                              |
| `font_weight`        | Font weight: `normal`, `medium`, `bold`, `extraBold`                        |
| `radius`             | Border radius for UI elements (e.g., `4px`, `0.5rem`, `8px`)                |
| `pay_button_text`    | Custom text for the pay button (e.g., "Complete Purchase", "Subscribe Now") |

### Color Configuration (Light/Dark Mode)

Each mode (`light` and `dark`) supports the following color properties:

| Property                 | Description                       |
| ------------------------ | --------------------------------- |
| `bg_primary`             | Background primary color          |
| `bg_secondary`           | Background secondary color        |
| `text_primary`           | Text primary color                |
| `text_secondary`         | Text secondary color              |
| `text_placeholder`       | Text placeholder color            |
| `text_error`             | Text error color                  |
| `text_success`           | Text success color                |
| `border_primary`         | Border primary color              |
| `border_secondary`       | Border secondary color            |
| `button_primary`         | Primary button background color   |
| `button_primary_hover`   | Primary button hover color        |
| `button_secondary`       | Secondary button background color |
| `button_secondary_hover` | Secondary button hover color      |
| `button_text_primary`    | Primary button text color         |
| `button_text_secondary`  | Secondary button text color       |
| `input_focus_border`     | Input focus border color          |

<Info>
  All color fields accept standard CSS color formats:

  * Hex: `#fff`, `#ffffff`, `#ffffffff`
  * RGB/RGBA: `rgb(255, 255, 255)`, `rgba(255, 255, 255, 0.5)`
  * HSL/HSLA: `hsl(120, 100%, 50%)`, `hsla(120, 100%, 50%, 0.5)`
  * Named colors: `red`, `blue`, `transparent`
</Info>

### Example

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  customization: {
    theme_config: {
      // Custom fonts
      font_primary_url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap',
      font_size: 'md',
      font_weight: 'medium',
      radius: '8px',
      pay_button_text: 'Complete Purchase',
      
      // Light mode colors
      light: {
        bg_primary: '#ffffff',
        bg_secondary: '#f5f5f5',
        text_primary: '#1a1a1a',
        text_secondary: '#666666',
        button_primary: '#0066ff',
        button_primary_hover: '#0052cc',
        button_text_primary: '#ffffff',
        border_primary: '#e0e0e0'
      },
      
      // Dark mode colors
      dark: {
        bg_primary: '#1a1a1a',
        bg_secondary: '#2d2d2d',
        text_primary: '#ffffff',
        text_secondary: '#a0a0a0',
        button_primary: '#3385ff',
        button_primary_hover: '#4d99ff',
        button_text_primary: '#ffffff',
        border_primary: '#404040'
      }
    }
  },
  return_url: 'https://yoursite.com/return'
});
```

<Tip>
  You don't need to specify all color properties. Any unspecified properties will use the default theme values.
</Tip>


# Communication Preferences
Source: https://docs.dodopayments.com/features/communication-preferences

Configure how you and your team receive notifications about payments, payouts, refunds, subscriptions, and disputes across email, in-app, and push channels.

<Frame>
  <img alt="Communication Preferences Overview" />
</Frame>

<Info>
  Communication Preferences gives you complete control over how and when you're notified about important events in your Dodo Payments account. You can configure notifications for yourself, add multiple team email recipients with individual preferences, and choose between email, in-app, and push notification channels.
</Info>

## Accessing Communication Preferences

To configure your communication preferences:

1. Navigate to **Settings** in your Dodo Payments dashboard
2. Click on the **Communication** tab
3. Use the dropdown menu to switch between notification channels (Email, In-App, Push Notifications)

## Notification Channels

Dodo Payments supports three notification channels, each designed for different use cases. You can configure each channel independently to match your workflow.

<Frame>
  <img alt="Notification Channel Selector" />
</Frame>

| Channel                | Description                                                       | Best For                                        |
| ---------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
| **Email**              | Receive detailed notifications via email to one or more addresses | Comprehensive record-keeping, team distribution |
| **In-App**             | See notifications directly in the dashboard notification center   | Quick updates while working in the dashboard    |
| **Push Notifications** | Get instant mobile alerts on your registered devices              | Time-sensitive alerts when away from desktop    |

### Email Notifications

Email is the most flexible notification channel. You can add multiple recipient email addresses, and each recipient can have their own customized notification preferences. This is ideal for routing specific notifications to different team members (e.g., finance team receives payout notifications, support team receives dispute notifications).

<Frame>
  <img alt="Email Notifications Configuration" />
</Frame>

**Key features:**

* Add unlimited email recipients
* Configure per-recipient notification preferences
* Use "Enable All" or "Disable All" for quick bulk configuration
* Remove email addresses when team members change

### In-App Notifications

In-app notifications appear in the notification center within your Dodo Payments dashboard. These are perfect for staying informed while actively working in the dashboard without cluttering your email inbox.

<Frame>
  <img alt="In-App Notifications" />
</Frame>

In-app notifications are displayed in real-time and can be accessed by clicking the bell icon in the dashboard header. They provide a quick summary of recent events and link directly to the relevant transaction or record.

### Push Notifications

Push notifications deliver instant mobile alerts to your registered devices. This channel is ideal for critical events that require immediate attention, such as payment failures or new disputes.

<Frame>
  <img alt="Push Notifications" />
</Frame>

Push notifications are organized by device, allowing you to:

* Enable/disable notifications for specific devices
* Configure which events trigger push notifications per device
* Manage multiple devices (e.g., phone and tablet)

<Tip>
  Download the [Dodo Payments mobile or desktop app](/features/mobile-app) to receive push notifications on your iOS, Android, macOS, Windows, or Linux device.
</Tip>

## Managing Email Recipients

The email channel allows you to add multiple recipient addresses, making it easy to keep your entire team informed about relevant events.

### Adding a New Email Recipient

1. In the **Your Emails** section, click the **Add Email** button
2. Enter the email address in the modal that appears
3. Click **Add Email** to confirm

<Frame>
  <img alt="Add Email Address Modal" />
</Frame>

After adding an email, you can immediately configure which notifications that address should receive.

### Configuring Email Preferences

1. Click on an email address to expand its notification options
2. Use the toggle switches next to each event to enable or disable notifications
3. Changes are saved automatically

**Quick Actions:**

* **Enable All**: Turns on all notifications for this email address with one click
* **Disable All**: Turns off all notifications for this email address with one click

### Removing an Email Recipient

To remove an email address, expand the email entry and click the **Remove email** button. This immediately stops all notifications to that address.

## Your Notification Events

These notifications keep you and your team informed about business-critical events. Each category can be independently configured per notification channel.

### Payments

Stay informed about payment activity for your products.

| Event                | Description                                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Payment Failed**   | Notifies when a payment attempt fails. This could be due to insufficient funds, card decline, or other payment issues. Useful for identifying potential customer issues. |
| **Payment Received** | Notifies when a payment is successfully processed. Confirms that a customer has completed their purchase.                                                                |

### Payouts

Track the movement of funds from your Dodo Payments account to your bank account.

<Frame>
  <img alt="Payout and Refund Notifications" />
</Frame>

| Event                  | Description                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Payout Failed**      | Notifies when a payout attempt fails. This may indicate an issue with your bank account details that needs immediate attention. |
| **Payout In Progress** | Notifies when a payout is actively being processed. The funds are on their way to your bank account.                            |
| **Payout Initiated**   | Notifies when a payout is initiated to your bank account. This marks the beginning of the payout process.                       |
| **Payout On Hold**     | Notifies if a payout is paused or under review. This may require you to provide additional information or documentation.        |
| **Payout Processed**   | Notifies when a payout completes successfully. The funds should now be available in your bank account.                          |

### Refunds

Monitor refund activity across your transactions.

| Event                | Description                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| **Refund Completed** | Notifies when a refund is successfully processed and the funds have been returned to the customer. |
| **Refund Failed**    | Notifies when a refund fails to process. This may require manual intervention to resolve.          |

### Subscriptions

Track subscription lifecycle events.

| Event                    | Description                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| **Subscription Started** | Notifies when a new subscription is created and activated. This confirms a new recurring customer. |

### Disputes

Disputes require prompt attention to protect your business. These notifications ensure you never miss a dispute deadline.

<Frame>
  <img alt="Subscription and Dispute Notifications" />
</Frame>

| Event                  | Description                                                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Dispute Created**    | Notifies when a customer opens a dispute (chargeback) against a payment. Requires prompt attention to respond within the deadline. |
| **Dispute Challenged** | Notifies when a dispute you've responded to is being challenged or escalated. The dispute is still in progress.                    |
| **Dispute Won**        | Notifies when a dispute is resolved in your favor. The funds are retained in your account.                                         |
| **Dispute Lost**       | Notifies when a dispute is resolved in the customer's favor. The disputed amount has been deducted from your account.              |

<Warning>
  Disputes have strict response deadlines. We strongly recommend keeping dispute notifications enabled to ensure you can respond in time.
</Warning>

## Customer Emails

In addition to notifications for your team, you can configure which transactional emails are automatically sent to your customers. These emails are sent from Dodo Payments on your behalf and help keep your customers informed about their purchases.

<Frame>
  <img alt="Customer Email Configuration" />
</Frame>

| Email                                               | Default  | Description                                                                                                                                                                                                         |
| --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Payment Succeeded**                               | Enabled  | Automatically sends a confirmation email to customers when their payment is successfully processed. Includes receipt details and order information.                                                                 |
| **Subscription Plan Changed**                       | Enabled  | Sends an email to customers when their subscription plan changes, whether through an upgrade, downgrade, or modification. Confirms the new plan details and pricing.                                                |
| **License Key Created**                             | Enabled  | Sends an email to customers when a license key is generated for their purchase. Includes the license key and activation instructions.                                                                               |
| **Refund Successful**                               | Enabled  | Notifies customers when a refund has been successfully processed and funds are on their way back to them.                                                                                                           |
| **Subscription Trial Ending**                       | Enabled  | Reminds customers that their free trial is ending soon (sent approximately 2 days before the trial period expires and the first billing charge occurs).                                                             |
| **Subscription Cancelled Immediately**              | Enabled  | Notifies customers when their subscription has been cancelled with immediate effect.                                                                                                                                |
| **Subscription Set to Cancel at Next Billing Date** | Enabled  | Informs customers when their subscription has been scheduled to cancel at the end of the current billing period, rather than immediately.                                                                           |
| **Payment Failed**                                  | Disabled | Notifies customers when a payment attempt on their account has failed. Disabled by default — enable if you want Dodo Payments to send these notifications directly to customers rather than handling them yourself. |
| **Subscription Renewal Failed**                     | Disabled | Notifies customers specifically when a subscription renewal payment fails. Fires for failed payments that are tied to a subscription renewal; complements the general Payment Failed email. Disabled by default.    |
| **Upcoming Renewal Reminder**                       | Disabled | Sends customers a reminder approximately 2 days before their subscription renews. Disabled by default — useful if you want proactive renewal notice sent to customers.                                              |

<Tip>
  Customer emails that are **enabled by default** are sent automatically unless you turn them off. Emails that are **disabled by default** will only be sent if you explicitly enable them — these are typically events where you may prefer to handle customer communication through your own systems.
</Tip>

<Note>
  Customer emails are separate from the notification emails sent to your team. Disabling a customer email does not affect your team's notifications about the same event.
</Note>

## Best Practices

Here are some recommendations for configuring your communication preferences effectively:

1. **Set up role-based email routing**: Add different team email addresses for different notification types. For example:
   * `finance@yourcompany.com` for payout notifications
   * `support@yourcompany.com` for dispute notifications
   * `sales@yourcompany.com` for payment notifications

2. **Enable critical notifications across channels**: For time-sensitive events like disputes, consider enabling notifications on multiple channels (email + push) to ensure you never miss them.

3. **Review preferences periodically**: As your team grows or changes, review your notification settings to ensure the right people are receiving the right notifications.

4. **Keep customer emails enabled**: Unless you have a specific reason to disable them, keeping customer emails enabled provides a better customer experience and reduces support inquiries.


# Credit-Based Billing
Source: https://docs.dodopayments.com/features/credit-based-billing

Issue, manage, and track credit entitlements across subscriptions, one-time products, and usage-based billing with rollover, overage, and expiration controls.

<Frame>
  <iframe title="Credit-Based Billing Tutorial" />
</Frame>

<Info>
  Credit-Based Billing lets you grant customers a balance of credits - API calls, tokens, compute units, or any custom metric - and deduct from that balance as they consume your service. Credits work across all product types: subscriptions, one-time purchases, and usage-based billing.
</Info>

## What is Credit-Based Billing?

Credit-Based Billing gives you a flexible system to issue credit entitlements to customers as part of your products. Instead of charging per-use or limiting access through feature flags, you allocate a pool of credits that customers draw from as they use your service.

Credits are ideal for:

* **AI and LLM platforms**: Grant tokens or generation credits per plan tier
* **API services**: Allocate API call credits with overage pricing
* **Infrastructure platforms**: Issue compute hours or storage credits
* **Communication services**: Provide message or minute credits per subscription
* **SaaS with consumption tiers**: Bundle included usage into credit pools

<Frame>
  <img alt="Checkout showing included credits with the product purchase" />
</Frame>

## Core Concepts

### Credit Types

When creating a credit, you choose between two types:

<Tabs>
  <Tab title="Custom Unit">
    Define credits in your own unit - tokens, API calls, compute hours, or any metric meaningful to your product. Custom units use the precision you set (0 to 10 decimal places).

    **Best for**: API calls, AI tokens, compute hours, storage units, messages
  </Tab>

  <Tab title="Fiat Credits">
    Credits represent actual currency value (e.g., USD, EUR). Customers receive a monetary credit balance that depletes as they use your service at your defined pricing.

    **Best for**: Prepaid balances, promotional credits, service compensation
  </Tab>
</Tabs>

### Credit Lifecycle

Credits follow a clear lifecycle from issuance through consumption:

<Steps>
  <Step title="Credits Issued">
    Credits are granted when a customer purchases a product (subscription or one-time) with attached credit entitlements. For subscriptions, credits are re-issued each billing cycle.
  </Step>

  <Step title="Credits Consumed">
    As customers use your service, credits are deducted. For usage-based products, meters automatically deduct credits based on real-time events. You can also deduct credits manually via the dashboard or API.
  </Step>

  <Step title="Credits Expire or Roll Over">
    At the end of the billing cycle (or after the configured expiry period), unused credits either expire or roll over to the next period based on your settings.
  </Step>

  <Step title="Overage Handling">
    If credits run out mid-cycle, you can allow overage (continued usage beyond the balance) and choose how overage is handled - forgive it, bill it, or carry the deficit forward.
  </Step>
</Steps>

### Grant Sources

Credits can be granted from multiple sources:

| Source           | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| **Subscription** | Credits issued with subscription purchase, re-issued each billing cycle |
| **One-Time**     | Credits issued with a one-time payment product                          |
| **Add-on**       | Credits issued with an add-on attached to a subscription                |
| **API**          | Credits granted manually via API or dashboard                           |
| **Rollover**     | Credits carried over from a previous billing cycle                      |

***

## Creating Credits

Create credit entitlements in the **Products → Credits** section of your dashboard. Each credit defines the unit, precision, expiry rules, and lifecycle behavior.

<Frame>
  <img alt="Credits listing page showing created credit entitlements" />
</Frame>

<Steps>
  <Step title="Navigate to Credits">
    Go to **Products** in your dashboard and select the **Credits** tab. Click **Create Credit** to start.
  </Step>

  <Step title="Configure Basic Information">
    Enter a **Credit Name** - this is your internal identifier for the credit.

    <Frame>
      <img alt="Credit creation form showing basic info, general settings, and subscription settings" />
    </Frame>
  </Step>

  <Step title="Set General Settings">
    Configure the credit type and display properties:

    <ParamField type="string">
      Choose **Custom Unit** or **Fiat Credits**.

      * **Custom Unit** - Define your own metric (tokens, API calls, compute hours). Requires a **Unit Name** (e.g., "Platform tokens") and a **Precision** setting.
      * **Fiat Credits** - Credits represent real currency value. Requires a **Unit Currency** selection (USD, EUR, GBP, INR, etc.).
    </ParamField>

    <ParamField type="string">
      Only for Custom Unit credits. The label customers see for this credit (e.g., "AI Tokens", "API Calls"). Shown in checkout and the customer portal.
    </ParamField>

    <ParamField type="number">
      Only for Custom Unit credits. Number of decimal places allowed, from `0` to `10`:

      * `0` - Whole numbers (best for countable items like API calls)
      * `1` - One decimal (0.0)
      * `2` - Two decimals (0.00) - **default**
      * `3` - Three decimals (0.000)
      * Up to `10` - For high-precision units (e.g. fractional tokens or micro-usage)

      <Warning>
        Precision cannot be changed after the credit is created.
      </Warning>
    </ParamField>

    <ParamField type="string">
      How long credits remain valid after issuance:

      * **7 days**, **30 days** (default), **60 days**, **90 days**, **Custom**, or **Never**

      Select **Custom** to specify a custom number of days (minimum 1).
    </ParamField>
  </Step>

  <Step title="Configure Subscription Settings (Optional)">
    These settings control credit behavior within recurring subscriptions:

    <ParamField type="boolean">
      Allow unused credits to carry forward to the next billing cycle. When enabled, configure:

      * **Max Rollover Percentage** (0–100%) - Limit how much carries over
      * **Rollover Timeframe** - How long rolled-over credits remain valid (e.g., 1 Month)
      * **Max Rollover Count** - Maximum consecutive rollovers before credits are forfeited
    </ParamField>

    **When Credits Run Out or Subscription Expires:**

    <ParamField type="boolean">
      Let customers continue using your service after their credit balance reaches zero. When enabled, configure:

      * **Overage Limit** - Maximum credits customers can consume beyond their balance
      * **Price Per Unit** - Cost per additional credit when overage is enabled (with currency selector)
    </ParamField>

    <ParamField type="string">
      Controls how overage is handled at the end of the billing cycle:

      * **Forgive overage at reset** (default) - Usage beyond the credit limit is tracked but not billed. Balance resets each cycle.
      * **Bill overage at billing** - Usage beyond the credit limit is charged on the next invoice, then the balance resets.
      * **Carry over deficit** - Usage beyond the credit limit carries forward as a negative balance into the next cycle.
      * **Carry over deficit (auto-repay)** - Deficit carries forward and is automatically repaid from new credits in the next cycle.
    </ParamField>
  </Step>

  <Step title="Create Credit">
    Click **Create Credit** to save. The credit is now available to attach to any product.

    <Check>
      Your credit entitlement is ready. Attach it to products to start issuing credits to customers.
    </Check>
  </Step>
</Steps>

<Tip>
  Start with simple settings - no rollover, no overage - and add complexity as you learn how customers use credits. Most settings can be updated at any time without affecting existing grants. Note that **precision cannot be changed** after a credit is created.
</Tip>

***

## Attaching Credits to Products

Credits are attached to products as **entitlements** in the product creation or editing flow. You can attach up to **5 credits per product**. Credits work with all three pricing types.

### Subscription Products

For subscriptions, credits are issued **per billing cycle** and can be configured with proration, trial credits, and cycle-specific settings.

<Steps>
  <Step title="Create or Edit a Subscription Product">
    Go to **Products → Create Product** or edit an existing product. Select **Subscription** as the pricing type and configure your recurring price.
  </Step>

  <Step title="Open Entitlements Section">
    Expand the **Entitlements** section and click the **Attach** button next to **Credits**.

    <Frame>
      <img alt="Product entitlements section showing Credits attach button" />
    </Frame>
  </Step>

  <Step title="Select Credits to Attach">
    An **Add Credits** panel opens. You can select an existing credit from the dropdown or click **Create new credit** to define one on the spot.

    <Frame>
      <img alt="Add Credits panel with credit selection dropdown" />
    </Frame>

    <Info>
      You can attach up to 5 credits per product. Each credit can have its own configuration.
    </Info>
  </Step>

  <Step title="Configure Credit Settings">
    For each attached credit, configure:

    <ParamField type="number">
      The number of credits granted to the customer each billing period.
    </ParamField>

    <ParamField type="number">
      Notify when credits fall below this amount. Useful for alerting customers before they run out.
    </ParamField>

    <ParamField type="number">
      Set a different credit amount for trial periods. Enable **Expire trial credits after trial ends** to revoke unused trial credits when the trial converts to a paid subscription.
    </ParamField>

    <ParamField type="boolean">
      Prorate remaining credits when a customer upgrades or downgrades their subscription plan.
    </ParamField>

    <ParamField type="boolean">
      Use the default rollover, overage, and expiry settings from the credit entitlement. Turn this off to customize settings specifically for this product.
    </ParamField>

    <Frame>
      <img alt="Credit configuration form with billing cycle, trial, and proration settings" />
    </Frame>
  </Step>

  <Step title="Review and Add">
    Review the attached credit showing name, amount, and expiration. Click **Add to Subscription** to confirm.

    <Frame>
      <img alt="Add Credits panel showing selected credit with details" />
    </Frame>
  </Step>
</Steps>

### One-Time Payment Products

For one-time payments, credits are issued **once** at the time of purchase.

<Steps>
  <Step title="Create a One-Time Product">
    Create a product with **Single Payment** pricing type.

    <Frame>
      <img alt="Product pricing section with Single Payment selected" />
    </Frame>
  </Step>

  <Step title="Attach Credits">
    Open the **Entitlements** section and attach credits. Configure the **number of credits issued** (total one-time grant) on purchase.
  </Step>
</Steps>

<Tip>
  One-time credit products are ideal for credit top-up packs, promotional bundles, or prepaid credit purchases.
</Tip>

### Usage-Based Billing Products

For usage-based products, credits are **linked to meters** and automatically deducted based on real-time consumption events.

<Steps>
  <Step title="Create a Usage-Based Product">
    Select **Usage Based Billing** as the pricing type. Configure the base price and billing frequency.

    <Frame>
      <img alt="Usage Based Billing pricing configuration" />
    </Frame>
  </Step>

  <Step title="Add a Meter">
    Click the **+** button in the **Select meter** section to add a meter. A subscription can have up to **3 meters**.

    <Frame>
      <img alt="Select Meter panel showing free threshold and credit toggle" />
    </Frame>
  </Step>

  <Step title="Enable Credit Billing on the Meter">
    Toggle **Bill usage in Credits** to attach a credit to the meter. Select the credit entitlement from the dropdown.

    <ParamField type="number">
      The number of units that are free before credit deduction begins.
    </ParamField>

    <ParamField type="boolean">
      When enabled, meter usage deducts from the customer's credit balance instead of charging per-unit.
    </ParamField>

    <ParamField type="number">
      The number of usage units required to deduct 1 credit. For example, if set to `1000`, then 1,000 API calls consume 1 credit.
    </ParamField>

    <Frame>
      <img alt="Meter configuration with credit selection and meter units per credit" />
    </Frame>
  </Step>

  <Step title="Configure Credit Issuance">
    Set the number of credits issued and optionally customize the credit settings for this product.

    <Frame>
      <img alt="Credit configuration for UBB product" />
    </Frame>
  </Step>

  <Step title="Verify Attachment">
    Once configured, the meter shows the attached credit name, unit price, and free threshold.

    <Frame>
      <img alt="Configured meter showing credit attachment details" />
    </Frame>
  </Step>
</Steps>

<Info>
  When credits are linked to meters, the system automatically deducts credits based on ingested usage events. A background worker processes events every minute, aggregates them according to the meter's configuration, and applies FIFO (first-in, first-out) deduction from the customer's oldest non-expired grants.
</Info>

***

## Credit Settings

### Rollover

Rollover lets unused credits carry forward to the next billing cycle instead of expiring.

| Setting                     | Description                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Rollover Enabled**        | Toggle to allow unused credits to carry forward                                                                     |
| **Max Rollover Percentage** | Limit how much carries over (0–100%). At 50%, only half of unused credits roll over                                 |
| **Rollover Timeframe**      | How long rolled-over credits remain valid (day, week, month, year)                                                  |
| **Max Rollover Count**      | Maximum number of times credits can be consecutively rolled over. After this limit, remaining credits are forfeited |

**Example**: A customer has 200 unused credits at cycle end. With 75% rollover, 150 credits carry forward and 50 are forfeited.

### Overage

Overage controls what happens when a customer's credit balance reaches zero mid-cycle.

| Setting              | Description                                                                    |
| -------------------- | ------------------------------------------------------------------------------ |
| **Allow Overage**    | Toggle to let customers continue using the service beyond their credit balance |
| **Overage Limit**    | Maximum credits customers can consume beyond their balance                     |
| **Price Per Unit**   | Cost per additional credit consumed as overage (with currency)                 |
| **Overage Behavior** | Controls what happens to overage at the end of the billing cycle (see below)   |

**Overage Behavior options:**

| Behavior                            | Description                                                                            |
| ----------------------------------- | -------------------------------------------------------------------------------------- |
| **Forgive overage at reset**        | Usage beyond the credit limit is tracked but not billed. Balance resets each cycle     |
| **Bill overage at billing**         | Usage beyond the credit limit is charged on the next invoice, then the balance resets  |
| **Carry over deficit**              | Overage carries forward as a negative balance into the next cycle                      |
| **Carry over deficit (auto-repay)** | Deficit carries forward and is automatically repaid from new credits in the next cycle |

<Info>
  When overage is disabled, customers cannot use the service once their credit balance reaches zero. Choose an overage behavior that matches your billing model - **Forgive at reset** is the default and simplest option.
</Info>

### Expiration

| Setting                              | Description                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------ |
| **Credit Expiry**                    | Duration after issuance before credits expire (7, 30, 60, 90, custom days, or never) |
| **Trial Credits Expire After Trial** | Whether trial-specific credits expire when the trial period ends                     |

<Info>
  Expired credits create a `CreditExpired` ledger entry. If rollover is enabled, the rollover percentage is applied before expiration, and only the remainder expires.
</Info>

***

## Usage Billing with Credits

When credits are linked to usage meters, the system creates a powerful consumption-based billing model. Customers receive a credit allocation, and usage events automatically deduct from their balance.

<Frame>
  <img alt="Usage Billing dashboard showing events table with credits consumed" />
</Frame>

### How Meter-Based Credit Deduction Works

1. **Your application sends usage events** - Each event includes a customer ID, event name, and metadata
2. **Meters aggregate events** - Using Count, Sum, Max, or Last aggregation
3. **Credits are deducted automatically** - A background worker processes events every minute, converts meter units to credits using your configured rate, and deducts from the customer's balance using FIFO ordering (oldest grants first)
4. **Overage is tracked** - If the credit balance reaches zero and overage is enabled, the system tracks overage usage for end-of-cycle billing

### Meters Panel

The Usage Billing dashboard includes a **Meters** panel listing all defined meters with their aggregation type:

| Aggregation | Description            | Example                 |
| ----------- | ---------------------- | ----------------------- |
| **Count**   | Total number of events | API calls               |
| **Sum**     | Sum of a value field   | Total bytes transferred |
| **Max**     | Highest value recorded | Peak concurrent users   |
| **Last**    | Most recent value      | Current storage used    |

***

## Customer Experience

### Checkout

When a customer purchases a product with attached credits, the checkout page displays the included credits as part of the product offering.

<Frame>
  <img alt="Checkout page showing product with included API call credits" />
</Frame>

Credits appear in an **Includes** section below the product description, showing the credit amount and type (e.g., "\$1000 API calls").

### Customer Portal

Customers can view and manage their credit balances in the Customer Portal under the **Credits** section.

<Frame>
  <img alt="Customer Portal credits view with balance and transaction history" />
</Frame>

The portal displays:

* **Available Balance** - Current credit balance displayed prominently
* **Credit Tabs** - Switch between different credit types (e.g., "OpenAI Credits", "Usage Tokens")
* **Recent Transactions** - Full history with date, transaction ID, type, amount, and running balance

Transaction types shown to customers include:

| Type                          | Description                                       | Amount    |
| ----------------------------- | ------------------------------------------------- | --------- |
| **Credits with Subscription** | Credits issued with subscription purchase/renewal | Green (+) |
| **One-Time Credits**          | Credits from one-time purchases or manual grants  | Green (+) |
| **Usage Deduction**           | Credits consumed through service usage            | Red (-)   |
| **Overage**                   | Usage beyond credit balance                       | Red (-)   |

### Subscription Details

The subscription detail page shows credit entitlements alongside other plan information.

<Frame>
  <img alt="Subscription details page showing entitlements and usage history" />
</Frame>

Key information displayed:

* **Credit allocation** per billing cycle (e.g., "1000 credits each cycle")
* **Remaining balance** (e.g., "7500 credits remaining")
* **Renewal date** for next credit issuance
* **Usage History** tab with meter-level breakdown showing units consumed, thresholds, unit prices, and total costs

### Transaction Details

Payment transaction pages include an **Entitlements** section showing all entitlements delivered with the payment, including credits.

<Frame>
  <img alt="Transaction details page showing credit entitlements" />
</Frame>

***

## Managing Credits

### Dashboard Views

#### Credit Entitlements List

View all your credit entitlements in **Products → Credits**. The table shows credit name, expiry settings, and provides quick actions for editing or archiving.

<Frame>
  <img alt="Credits listing page in the Products section" />
</Frame>

#### Customer Credit Details

View a specific customer's credit balances and transaction history from **Customers → \[Customer Name] → Credits**.

<Frame>
  <img alt="Customer details page with Credits tab showing balance and transactions" />
</Frame>

The customer credit view includes:

* **Credit Selector** - Switch between different credit entitlements
* **Available Balance** - Current balance in large, prominent display
* **Apply Credit/Debit** - Button to manually adjust the customer's balance
* **Recent Transactions** - Full ledger with date, transaction ID, type, amount, and running balance

### Manual Adjustments

You can manually credit or debit a customer's balance directly from the dashboard:

<Steps>
  <Step title="Navigate to Customer">
    Go to **Customers** and select the customer.
  </Step>

  <Step title="Open Credits Tab">
    Click the **Credits** tab and select the appropriate credit entitlement from the wallet selector.
  </Step>

  <Step title="Apply Credit or Debit">
    Click **Apply Credit/Debit** to open the adjustment interface.

    <ParamField type="string">
      Select **Credit** to add credits or **Debit** to remove credits from the customer's balance.
    </ParamField>

    <ParamField type="number">
      The number of credits to add or remove.
    </ParamField>

    <ParamField type="string">
      Optional explanation for the adjustment (e.g., "Service compensation", "Promotional bonus").
    </ParamField>
  </Step>

  <Step title="Confirm">
    Review and apply the adjustment. The change is reflected immediately in the customer's balance and recorded in the credit ledger.

    <Check>
      Manual adjustments create a `ManualAdjustment` ledger entry with full audit trail.
    </Check>
  </Step>
</Steps>

### Credit Ledger

Every credit operation is recorded in the credit ledger, providing a complete audit trail:

| Transaction Type       | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| **Credit Added**       | Credits granted (subscription, one-time, or API)          |
| **Credit Deducted**    | Credits consumed through usage or manual debit            |
| **Credit Expired**     | Credits expired without rollover                          |
| **Credit Rolled Over** | Credits carried forward to the next period                |
| **Rollover Forfeited** | Rolled credits forfeited after max rollover count reached |
| **Overage Charged**    | Usage beyond credit balance with overage enabled          |
| **Overage Reset**      | Tracked overage cleared at the billing-cycle reset        |
| **Auto Top-Up**        | Automatic credit replenishment at low balance             |
| **Manual Adjustment**  | Credit or debit applied manually by merchant              |
| **Refund**             | Credits refunded                                          |

Each ledger entry records the balance before and after the transaction, overage before and after, a description, and reference to the source (payment, subscription, etc.).

***

## Webhooks

Credit-Based Billing fires webhook events for every credit lifecycle change. Use these to keep your application in sync with credit balances, trigger notifications, or build custom billing workflows.

| Event                       | Description                                               |
| --------------------------- | --------------------------------------------------------- |
| `credit.added`              | Credits granted to a customer                             |
| `credit.deducted`           | Credits consumed through usage or manual debit            |
| `credit.expired`            | Unused credits expired                                    |
| `credit.rolled_over`        | Credits carried forward to a new grant                    |
| `credit.rollover_forfeited` | Credits forfeited at max rollover count                   |
| `credit.overage_charged`    | Overage charges applied                                   |
| `credit.overage_reset`      | Tracked overage was reset at the end of the billing cycle |
| `credit.manual_adjustment`  | Manual credit/debit adjustment made                       |
| `credit.balance_low`        | Balance dropped below configured threshold                |

All ledger events (every `credit.*` event except `credit.balance_low`) include the full `CreditLedgerEntry` payload with balance before/after, overage before/after, source reference, and the `metadata` of the grant's source subscription or payment (empty for grants created directly via the API). The `credit.balance_low` event includes the threshold configuration and current balance.

<Card title="Credit Webhook Payloads" icon="bell" href="/developer-resources/webhooks/intents/credit">
  View full payload schemas, field descriptions, and integration examples for all credit webhook events.
</Card>

***

## API Management

<AccordionGroup>
  <Accordion title="Create Credit Entitlements">
    Use the API to create credit entitlements programmatically with full control over rollover, overage, and expiration settings.

    <CardGroup>
      <Card title="Create Credit Entitlement" icon="plus" href="/api-reference/credit-entitlements/create-credit-entitlement">
        Create a new credit entitlement with rollover, overage, and expiry configuration.
      </Card>

      <Card title="List Credit Entitlements" icon="list" href="/api-reference/credit-entitlements/list-credit-entitlements">
        Retrieve all credit entitlements for your business.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Manage Credit Entitlements">
    Retrieve, update, or delete credit entitlements. Deleted entitlements can be restored.

    <CardGroup>
      <Card title="Get Credit Entitlement" icon="magnifying-glass" href="/api-reference/credit-entitlements/get-credit-entitlement">
        Retrieve a specific credit entitlement by ID.
      </Card>

      <Card title="Update Credit Entitlement" icon="pen" href="/api-reference/credit-entitlements/update-credit-entitlement">
        Update rollover, overage, expiry, or other settings.
      </Card>

      <Card title="Delete Credit Entitlement" icon="trash" href="/api-reference/credit-entitlements/delete-credit-entitlement">
        Soft-delete a credit entitlement.
      </Card>

      <Card title="Undelete Credit Entitlement" icon="rotate-left" href="/api-reference/credit-entitlements/undelete-credit-entitlement">
        Restore a previously deleted credit entitlement.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Grant and Adjust Credits">
    Grant credits directly to a customer's balance without requiring a purchase, or create manual debit entries for billing adjustments.

    <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
      Credit or debit a customer's balance with full audit trail and idempotency support.
    </Card>
  </Accordion>

  <Accordion title="Query Balances and Ledger">
    Retrieve a customer's current credit balance, grant history, and full ledger of transactions for any credit entitlement.

    <CardGroup>
      <Card title="List Balances" icon="wallet" href="/api-reference/credit-entitlements/list-balances">
        List all customer balances for a credit entitlement.
      </Card>

      <Card title="Get Customer Balance" icon="user" href="/api-reference/credit-entitlements/get-customer-balance">
        Get a specific customer's balance.
      </Card>

      <Card title="List Customer Grants" icon="gift" href="/api-reference/credit-entitlements/list-customer-grants">
        View all credit grants for a customer.
      </Card>

      <Card title="List Customer Ledger" icon="scroll" href="/api-reference/credit-entitlements/list-customer-ledger">
        Full transaction history for a customer.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

### Integration Example

Initialize the Dodo Payments client:

```typescript theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode', // defaults to 'live_mode'
});
```

Attach credits to a subscription product during checkout:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_ai_pro_plan',
      quantity: 1,
    }
  ],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yourapp.com/success'
});
```

Send usage events that deduct credits automatically:

```typescript theme={null}
await client.usageEvents.ingest({
  events: [{
    event_id: `gen_${Date.now()}`,
    customer_id: 'cus_abc123',
    event_name: 'ai.generation',
    timestamp: new Date().toISOString(),
    metadata: { model: 'gpt-4', tokens: 1500 }
  }]
});
```

***

## Real-World Examples

<AccordionGroup>
  <Accordion title="AI SaaS Platform">
    **Pricing Structure:**

    | Plan       | Price    | Credits/Month    | Overage       |
    | ---------- | -------- | ---------------- | ------------- |
    | Starter    | \$29/mo  | 10,000 tokens    | \$0.003/token |
    | Pro        | \$99/mo  | 100,000 tokens   | \$0.002/token |
    | Enterprise | \$499/mo | 1,000,000 tokens | \$0.001/token |

    **Configuration:**

    * Credit Type: Custom Unit ("AI Tokens")
    * Precision: 0 (whole tokens)
    * Rollover: 25% max, 1-month timeframe
    * Overage: Enabled, bill overage at billing
    * Meter: `ai.generation` with Sum aggregation on `tokens` field
  </Accordion>

  <Accordion title="API Gateway">
    **Pricing Structure:**

    | Plan      | Price   | Credits/Month | Overage       |
    | --------- | ------- | ------------- | ------------- |
    | Free      | \$0/mo  | 1,000 calls   | Blocked       |
    | Developer | \$19/mo | 50,000 calls  | \$0.001/call  |
    | Business  | \$99/mo | 500,000 calls | \$0.0005/call |

    **Configuration:**

    * Credit Type: Custom Unit ("API Calls")
    * Precision: 0 (whole calls)
    * Rollover: Disabled
    * Overage: Developer+ plans allow overage (forgive at reset), Free plan disables overage
    * Meter: `api.request` with Count aggregation
  </Accordion>

  <Accordion title="Cloud Storage Service">
    **Pricing Structure:**

    | Plan     | Price   | Credits/Month  | Overage        |
    | -------- | ------- | -------------- | -------------- |
    | Personal | \$9/mo  | 100 GB-hours   | \$0.05/GB-hour |
    | Team     | \$49/mo | 1,000 GB-hours | \$0.03/GB-hour |

    **Configuration:**

    * Credit Type: Custom Unit ("GB-hours")
    * Precision: 2 (two decimal places)
    * Rollover: 50% max, carries over once
    * Overage: Enabled with 200% limit
    * Meter: `storage.usage` with Sum aggregation
  </Accordion>
</AccordionGroup>

***

## Best Practices

* **Start simple**: Begin with a single credit type and no rollover. Add complexity based on customer feedback and usage patterns.
* **Set clear expectations**: Display credit allocations, remaining balances, and overage pricing prominently in your product pages and customer portal.
* **Use meaningful units**: Name credits after what they represent (e.g., "API Calls", "AI Tokens") rather than generic terms. This helps customers understand value.
* **Configure expiry thoughtfully**: Short expiry windows (7 days) drive urgency but may frustrate customers. Longer windows (30–90 days) are more customer-friendly for most SaaS products.
* **Monitor low balances**: Set low balance thresholds to alert customers before they run out, reducing surprise overage charges.
* **Test in test mode**: Create credits, attach them to test products, and simulate the full purchase → usage → deduction → expiration cycle before going live.

<Info>
  Credit-Based Billing works seamlessly with all other Dodo Payments features - subscriptions with trials, plan changes with proration, and the customer portal. Start with a basic setup and expand as your pricing model evolves.
</Info>


# Customer Portal
Source: https://docs.dodopayments.com/features/customer-portal

Empower customers to self-serve and manage their subscriptions, billing history, license keys, and profile securely.

<Info>
  The Customer Portal is a secure, hosted area where your customers can manage subscriptions, view invoices and access license keys details—without contacting support.
</Info>

<CardGroup>
  <Card title="Create Portal Session (API)" icon="code" href="/api-reference/customers/create-customer-portal-session">
    Programmatically create secure, time‑bound portal sessions.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Manage recurring plans, upgrades, downgrades, and add‑ons.
  </Card>
</CardGroup>

<br />

<Frame>
  <img alt="Revamped Customer Portal showing active subscriptions, payment methods, and billing history" />
</Frame>

## What Is the Customer Portal?

The portal provides a trusted, branded self‑service experience for customers to:

* **Access billing history**: View invoices and download receipts.
* **Manage subscriptions**: View subscription details, cancel subscriptions immediately or at the next billing date.
* **Update payment methods**: Change payment methods for active subscriptions or reactivate subscriptions on hold.
* **Retrieve license keys**: Access all keys tied to purchases.
* **Navigate with ease**: Use the back button to move between portal sections without losing context.

## Key Benefits

* **Lower support volume**: Customers resolve common billing requests on their own
* **Faster time‑to‑value**: Immediate access to invoices and keys
* **Reduced churn risk**: Clear visibility into renewals and plan details
* **Secure by design**: Tokenized access with expiring links
* **Localized experience**: Portal is available in 21 languages, with automatic detection based on the customer's browser preferences

## Access Methods

Customers can reach the portal using either a static link or a one‑time dynamic link.

### Static link (email‑based access)

Customers can request portal access by entering their email at a static link that never expires.

The static portal link format varies by environment:

**Test Mode** (for testing and development):

```bash theme={null}
https://test.customer.dodopayments.com/login/{business_id}
```

**Live Mode** (for production with real transactions):

```bash theme={null}
https://customer.dodopayments.com/login/{business_id}
```

Replace `{business_id}` with your actual business identifier, then share the appropriate link with customers so they can enter their email and receive secure access to the portal.

<Frame>
  <img alt="Email-based login screen" />
</Frame>

<Steps>
  <Step title="Merchant flow">
    1. Go to Sales → Customer.
    2. Click <i>Share invite</i>.
    3. Copy the <i>Static link</i> and share it with your customer.
  </Step>

  <Step title="Customer flow">
    1. Open the static link.
    2. Enter the email used at purchase.
    3. Receive a secure login link to access the portal.

    <Check>
      Existing customers are recognized automatically.
    </Check>
  </Step>
</Steps>

### Dynamic link (magic link)

A personalized, one‑time magic link that sends customers directly into the portal. The link expires in 24 hours.

<Warning>
  Dynamic links expire after 24 hours. If it expires, generate and send a new link.
</Warning>

<Frame>
  <img alt="Magic link direct access" />
</Frame>

<Steps>
  <Step title="Merchant flow">
    1. Go to Sales → Customer.
    2. Click <i>Share invite</i>.
    3. Copy the <i>Dynamic link</i> and share it with your customer.
  </Step>

  <Step title="Customer flow">
    1. Open the dynamic link.
    2. Access the Customer Portal directly without entering an email.
  </Step>
</Steps>

## Portal Features

The revamped Customer Portal provides a clean, unified interface with a left sidebar and organized sections for all account management needs.

<CardGroup>
  <Card title="Active Subscriptions" icon="repeat">
    View all active subscriptions with plan name, price, renewal date, and validity. Click "Manage subscription" to view details, edit billing info, or cancel.
  </Card>

  <Card title="Payment Methods" icon="credit-card">
    View all saved payment methods (cards, UPI, etc.) at a glance. Edit payment methods directly from subscription details.
  </Card>

  <Card title="Billing History" icon="file-invoice">
    View all transactions in a detailed table with date, status, pricing type, entitlements, and downloadable invoices.
  </Card>

  <Card title="Billing Information" icon="user">
    View and edit your name, email, phone number, and billing address from the subscription details page.
  </Card>
</CardGroup>

### Portal Overview

The main portal page displays all active subscriptions, saved payment methods, and billing history in a single scrollable view.

<Frame>
  <img alt="Customer Portal main page showing active subscriptions and payment methods" />
</Frame>

### Payment Methods & Billing History

Scroll down to view saved payment methods and a complete billing history with status indicators and downloadable invoices.

<Frame>
  <img alt="Payment methods and billing history with invoice downloads" />
</Frame>

## Language Support

The Customer Portal is available in **21 languages**, so your customers can manage their subscriptions, payment methods, and billing history in the language they're most comfortable with.

### How language selection works

* **Automatic detection**: On first visit, the portal detects the customer's preferred language from their browser settings and loads the matching translation if available. English is used as the fallback.
* **Manual override**: Customers can change the active language at any time from the language selector in the portal header (available on both desktop and mobile).
* **Persisted preference**: The selected language is stored in the `NEXT_LOCALE` cookie (valid for 1 year) so the portal remembers the choice across sessions.

### Supported languages

| Language          | Code | Language   | Code |
| ----------------- | ---- | ---------- | ---- |
| English (default) | `en` | Indonesian | `id` |
| Arabic            | `ar` | Italian    | `it` |
| Catalan           | `ca` | Japanese   | `ja` |
| Chinese           | `zh` | Korean     | `ko` |
| Dutch             | `nl` | Malay      | `ms` |
| French            | `fr` | Polish     | `pl` |
| German            | `de` | Portuguese | `pt` |
| Hebrew            | `he` | Romanian   | `ro` |
| Russian           | `ru` | Spanish    | `es` |
| Swedish           | `sv` | Thai       | `th` |
| Turkish           | `tr` |            |      |

## Plan Changes (Upgrade/Downgrade)

When products are organized into **Product Collections**, customers can upgrade or downgrade between plans directly from the Customer Portal.

<Tip>
  **Want to enable upgrade/downgrade for existing subscriptions?** Add your subscription products to a Product Collection. Once grouped, customers can switch between plans in the same collection via the Customer Portal.
</Tip>

### Available Actions

| Action        | Description                                       | When Available                            |
| ------------- | ------------------------------------------------- | ----------------------------------------- |
| **Upgrade**   | Move to a higher-tier plan in the same collection | Business has enabled subscription updates |
| **Downgrade** | Move to a lower-tier plan in the same collection  | Business has enabled subscription updates |

### How Plan Changes Work

1. Customer views their current subscription in the portal
2. Available upgrade/downgrade options are shown based on the product collection
3. Customer selects the new plan
4. Proration is calculated and payment is processed immediately (if applicable)
5. Subscription is updated to the new plan

<Info>
  Plan changes are only available between products within the same collection. Products must be subscription or usage-based billing types.
</Info>

### Business Controls

Businesses can configure portal subscription behavior in Subscription Settings:

* **Allow Subscription Updates**: Enable or disable the ability for customers to upgrade or downgrade their subscriptions
* **Allow Subscription Cancellation**: Enable or disable the ability for customers to cancel their own subscriptions

<Card title="Product Collections" icon="layer-group" href="/features/product-collections">
  Learn how to set up product collections and configure upgrade/downgrade paths.
</Card>

## Subscription Details

When customers click "Manage subscription" on any active subscription, they are taken to the subscription details page. This page shows:

* **Plan details**: Subscription name, price, renewal date, and validity period
* **Payment method**: The card or payment method linked to the subscription, with an "Edit" button
* **Billing information**: Name, email, phone number, and billing address with an "Edit" button
* **Billing history**: A detailed table of all payments for this subscription
* **Cancel Subscription**: A prominent button to cancel the subscription

<Frame>
  <img alt="Subscription details page showing plan info, payment method, billing information, and cancel option" />
</Frame>

## Cancelling a Subscription

Customers can cancel their subscription directly from the subscription details page. Clicking "Cancel Subscription" opens a confirmation dialog with two options:

* **Cancel at next billing date**: The subscription remains active until the current billing period ends, then cancels automatically.
* **Cancel now**: The subscription is cancelled immediately.

<Info>
  Self-service cancellation is controlled by the **Allow Subscription Cancellation** setting under **Settings → Subscriptions**, which is enabled by default. When you turn it off, the Cancel Subscription button is disabled with a tooltip asking the customer to contact you, and both portal cancellation paths — cancel now and cancel at next billing date — are rejected. Customers who already have a scheduled cancellation keep the option to revoke it, so they can choose to stay. Cancellations you perform yourself are never affected.
</Info>

<Frame>
  <img alt="Cancel subscription dialog with options to cancel at next billing date or cancel immediately" />
</Frame>

### Cancellation Reasons

Before confirming cancellation, customers are asked **"Why are you cancelling?"** and prompted to pick a reason from a curated list. The reason is stored on the subscription and surfaced in webhook payloads and the API, so you can analyze churn drivers and tailor your win-back flows.

<Frame>
  <img alt="Cancellation modal with the 'Why are you cancelling?' dropdown showing reasons like Too expensive, Missing features, and Other" />
</Frame>

| Value              | Customer-facing label       |
| ------------------ | --------------------------- |
| `too_expensive`    | Too expensive               |
| `missing_features` | Missing features            |
| `switched_service` | Switched to another service |
| `unused`           | Not using it enough         |
| `customer_service` | Poor customer service       |
| `low_quality`      | Low quality                 |
| `too_complex`      | Too complex                 |
| `other`            | Other                       |

The selected value is written to the subscription's `cancellation_feedback` field. An optional free-text `cancellation_comment` can also be captured.

```typescript theme={null}
// Read the captured feedback after a customer cancels
const subscription = await client.subscriptions.retrieve('sub_123');
console.log(subscription.cancellation_feedback); // e.g., "too_expensive"
console.log(subscription.cancellation_comment);  // e.g., "Switching to a competitor"
```

Both fields are also included in the `subscription.cancelled` webhook payload, and you can populate them programmatically on `PATCH /subscriptions/{subscription_id}` when scheduling or executing a cancellation through the API.

<Tip>
  Combine `cancellation_feedback` with [Subscription Dunning](/features/recovery/subscription-dunning) to tailor win-back emails — for example, send a discount code to `too_expensive` cancellers and a "what's missing?" survey to `missing_features` cancellers.
</Tip>

## Updating Payment Methods

Customers can update their payment methods directly from the subscription details page by clicking "Edit" next to the payment method. This feature is especially important for reactivating subscriptions that have been placed on hold due to failed payments.

### Reactivating Subscriptions on Hold

When a subscription is placed on `on_hold` state due to a failed payment, customers must update their payment method to reactivate it. The update process automatically:

1. **Creates a charge** for remaining dues
2. **Generates an invoice** for the charge
3. **Processes the payment** using the new payment method
4. **Reactivates the subscription** to `active` state upon successful payment

<Warning>
  Subscriptions in `on_hold` state will not renew automatically. Customers must update their payment method to clear dues and reactivate the subscription.
</Warning>

<Info>
  After successfully updating the payment method for an `on_hold` subscription, customers will see a confirmation page and receive email notifications about the successful payment and subscription reactivation.
</Info>

### Payment Method Update Flow

<Steps>
  <Step title="Access subscription details">
    Click "Manage subscription" on any active subscription from the portal home page.
  </Step>

  <Step title="Click Edit on payment method">
    Click the "Edit" button next to the payment method to open the payment method update interface.
  </Step>

  <Step title="Select or add payment method">
    Choose an existing saved payment method or add a new one by entering card details securely.
  </Step>

  <Step title="Confirm changes">
    Confirm the update. For `on_hold` subscriptions, this will automatically create a charge for remaining dues.
  </Step>

  <Step title="Complete payment (if on hold)">
    If the subscription is on hold, customers will be redirected to complete the payment for remaining dues. Upon successful payment, the subscription is automatically reactivated.
  </Step>

  <Step title="Confirmation">
    Customers receive confirmation that the payment method has been updated and, if applicable, that the subscription has been reactivated.
  </Step>
</Steps>

## Integration Examples

Create a time‑bound Customer Portal session for a specific customer via API, then redirect the user to the session URL.

<CodeGroup>
  ```typescript Node.js theme={null}
  const session = await client.customers.customerPortal.create('cus_123');

  // Redirect the user to the hosted Customer Portal
  window.location.href = session.link;
  ```
</CodeGroup>

## Unified Customer Portal

In addition to business-specific customer portals, Dodo Payments offers a **Unified Customer Portal** at [customer.dodopayments.com](https://customer.dodopayments.com) where customers can view and manage all their purchases and subscriptions across different businesses using Dodo Payments.

<Frame>
  <img alt="Unified Customer Portal" />
</Frame>

### Unified Portal Features

* **Cross-business visibility**: View all purchases and subscriptions from any Dodo Payments merchant in one place
* **Centralized management**: Manage subscriptions across different businesses from a single dashboard
* **Unified billing history**: Access invoices and payment history from all purchases
* **Single sign-on**: Log in once with email to access purchases from all Dodo Payments merchants

<Tip>
  The Unified Customer Portal complements business-specific portals. Customers can use either the branded merchant portal or the unified portal based on their preference.
</Tip>

## Troubleshooting

* **Link expired**: Generate and send a new dynamic link.
* **Email not recognized**: Ask the customer to use the email associated with their purchase
* **Subscription on hold**: If a subscription is on hold, customers must update their payment method through the portal to clear dues and reactivate the subscription. The update process will automatically charge for remaining dues.
* **Payment method update failed**: If payment fails during the update process for an `on_hold` subscription, the subscription will remain on hold. Customers can try again with a different payment method.

<Card title="Design & Theme Customization" icon="palette" href="/features/design">
  Customize your customer portal appearance with pre-built themes, typography, colors, and live preview from the Design page.
</Card>


# Customer Wallets
Source: https://docs.dodopayments.com/features/customer-wallet

Manage prepaid monetary balances for your customers. Fund wallets, apply balances to subscription invoices, handle refunds as wallet funds, and track transaction history.

<CardGroup>
  <Card title="Get Customer Wallets" icon="code" href="/api-reference/customers/get-customer-wallets">
    Check customer monetary balances across currencies.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/customers/post-customer-wallets-ledger-entries">
    Add or deduct funds from customer wallets.
  </Card>

  <Card title="List Ledger Entries" icon="list" href="/api-reference/customers/get-customer-wallets-ledger-entries">
    View complete transaction history with pagination.
  </Card>
</CardGroup>

## What are Customer Wallets?

Customer wallets are monetary balance accounts that hold real funds for your users. Every customer gets one automatically when you create their account. You can use these wallets to:

* **Store prepaid funds** for future subscription payments
* **Handle refunds** as wallet balance instead of card refunds
* **Issue promotional balances** like welcome bonuses or loyalty rewards
* **Apply wallet funds to invoices** automatically during billing
* **Track monetary transactions** with a detailed ledger history

<Info>
  Every customer automatically gets a wallet when you create their account. Wallets support USD, EUR, and GBP currencies with separate monetary balances for each.
</Info>

<Warning>
  **Customer Wallets ≠ Credit-Based Billing**

  Customer Wallets hold **real monetary balances** (USD, EUR, GBP) that can be applied to invoices and subscription payments.

  If you're looking to track virtual usage units (API calls, tokens, compute hours), see [Credit-Based Billing](/features/credit-based-billing) instead.
</Warning>

<Frame>
  <img alt="Customer Wallets" />
</Frame>

## How It Works

Customer wallets hold funds that customers can apply to their purchases. When a customer has an invoice or a recurring subscription charge, their wallet balance is checked first. Any available funds are automatically applied to the invoice before charging their primary payment method.

### Automatic Setup

When you create a new customer, Dodo Payments automatically creates a wallet with a zero balance. It's ready to receive funds immediately through our API.

### Multi-Currency Support

Each wallet can hold balances in different currencies:

<ResponseField name="USD Balance" type="integer">
  Balance in US Dollars (stored in cents)
</ResponseField>

<ResponseField name="EUR Balance" type="integer">
  Balance in Euros (stored in cents)
</ResponseField>

<ResponseField name="GBP Balance" type="integer">
  Balance in Pounds Sterling (stored in pence)
</ResponseField>

<Info>
  Currently, only **USD**, **EUR**, and **GBP** balances are available. The INR native wallet has been discontinued — see [Payout Structure](/features/payouts/payout-structure). INR remains supported as a transaction currency for UPI, RuPay, and Indian-card subscriptions.
</Info>

## Working with Wallets

### Check Customer Balances

See how much funds a customer has across all currencies. This is useful for verifying available balance before processing a purchase or showing the balance in your application UI.

<Card title="Get Customer Wallet Balances" icon="wallet" href="/api-reference/customers/get-customer-wallets">
  Check a customer’s wallet monetary balances in all supported currencies.
</Card>

### Add or Deduct Funds

Fund customer wallets (like welcome bonuses or refund balances) or deduct funds (like subscription charges). You can provide reasons for each transaction to maintain a clear audit trail.

<Note>
  The `entry_type` field uses `'credit'` to add funds to the wallet and `'debit'` to subtract funds from the wallet.
</Note>

<Card title="Create Customer Wallet Ledger Entry" icon="plus" href="/api-reference/customers/post-customer-wallets-ledger-entries">
  Add or deduct funds from a customer’s wallet.
</Card>

### View Transaction History

See every credit and debit transaction for a customer. This detailed ledger helps you reconcile accounts and provides transparency for your customers.

<Card title="List Customer Wallet Ledger Entries" icon="list" href="/api-reference/customers/get-customer-wallets-ledger-entries">
  View every monetary transaction for a customer.
</Card>

## Real-World Examples

### Refund to Wallet

When a customer requests a refund, you can add the amount to their wallet balance instead of performing a traditional card refund. This keeps the funds within your ecosystem for future purchases.

```javascript theme={null}
async function refundToWallet(customerId, refundAmount, originalPaymentId) {
  await client.customers.wallets.ledgerEntries.create(customerId, {
    amount: refundAmount, // Amount in cents
    currency: 'USD',
    entry_type: 'credit',
    reason: `Refund for payment ${originalPaymentId}`,
    idempotency_key: `refund_${originalPaymentId}`
  });
}
```

### Welcome Bonus / Promotional Balance

Give new customers a monetary welcome bonus to encourage their first purchase.

```javascript theme={null}
async function addWelcomeBonus(customerId) {
  await client.customers.wallets.ledgerEntries.create(customerId, {
    amount: 1000, // $10.00 promotional balance
    currency: 'USD',
    entry_type: 'credit',
    reason: 'Welcome bonus - $10 promotional balance',
    idempotency_key: `welcome_${customerId}`
  });
}
```

### Subscription Payment from Wallet

Deduct funds from a wallet to cover a subscription charge or a manual purchase.

```javascript theme={null}
async function deductForPurchase(customerId, purchaseAmount, purchaseId) {
  try {
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: purchaseAmount,
      currency: 'USD',
      entry_type: 'debit',
      reason: `Subscription charge - monthly billing`,
      idempotency_key: `charge_${purchaseId}`
    });
  } catch (error) {
    if (error.status === 400) {
      console.log('Insufficient wallet balance');
    }
  }
}
```

### Prepaid Billing System

Allow customers to fund their accounts upfront and draw down from that balance over time.

<Steps>
  <Step title="Add Initial Funds">
    Add funds to the customer's wallet when they make a deposit.

    ```javascript theme={null}
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: 5000, // $50.00 deposit
      currency: 'USD',
      entry_type: 'credit',
      reason: 'Account funding - prepaid deposit',
      idempotency_key: `deposit_${paymentId}`
    });
    ```
  </Step>

  <Step title="Apply Balance to Purchases">
    Deduct from the balance as the customer uses your services or renews subscriptions.

    ```javascript theme={null}
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: 1500, // $15.00 charge
      currency: 'USD', 
      entry_type: 'debit',
      reason: 'Service purchase - monthly subscription',
      idempotency_key: `purchase_${purchaseId}`
    });
    ```
  </Step>

  <Step title="Monitor Balances">
    Check if customers are running low on funds to prompt a top-up.

    ```javascript theme={null}
    const wallets = await client.customers.wallets.list(customerId);
    const usdWallet = wallets.items.find(w => w.currency === 'USD');
    const balance = usdWallet.balance;

    if (balance < 1000) { // Less than $10.00
      // Send low balance notification
      await sendLowBalanceNotification(customerId, balance);
    }
    ```
  </Step>
</Steps>

### Multi-Currency Support

Manage separate monetary balances for customers in different regions.

<AccordionGroup>
  <Accordion title="US Customers">
    Manage USD funds for US-based customers.

    ```javascript theme={null}
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: 20000, // $200.00 in cents
      currency: 'USD',
      entry_type: 'credit',
      reason: 'USD account funding',
      idempotency_key: `usd_deposit_${paymentId}`
    });
    ```
  </Accordion>

  <Accordion title="European Customers">
    Manage EUR funds for Europe-based customers.

    ```javascript theme={null}
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: 18000, // €180.00 in cents
      currency: 'EUR',
      entry_type: 'credit',
      reason: 'EUR account funding',
      idempotency_key: `eur_deposit_${paymentId}`
    });
    ```
  </Accordion>

  <Accordion title="UK Customers">
    Manage GBP funds for UK-based customers.

    ```javascript theme={null}
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: 15000, // £150.00 in pence
      currency: 'GBP',
      entry_type: 'credit',
      reason: 'GBP account funding',
      idempotency_key: `gbp_deposit_${paymentId}`
    });
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

### Prevent Duplicate Transactions

Use idempotency keys to ensure you don't accidentally add or deduct funds twice for the same event.

```javascript theme={null}
async function addFundsSafely(customerId, amount, reason) {
  const idempotencyKey = `${reason}_${customerId}_${Date.now()}`;
  
  try {
    const result = await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: amount,
      currency: 'USD',
      entry_type: 'credit',
      reason: reason,
      idempotency_key: idempotencyKey
    });
    
    // Replaying the same idempotency_key returns the original entry rather than
    // creating a duplicate, so no special duplicate handling is required.
    return { success: true, wallet: result };
  } catch (error) {
    if (error.status === 400) {
      // e.g. insufficient balance on a debit
      return { success: false, reason: 'insufficient_balance' };
    }

    throw error;
  }
}
```

### Check Balances Before Charging

Verify customers have sufficient funds before attempting to process large transactions from the wallet.

```javascript theme={null}
async function checkBalanceBeforeOperation(customerId, requiredAmount) {
  const wallets = await client.customers.wallets.list(customerId);
  const usdWallet = wallets.items.find(w => w.currency === 'USD');
  
  if (!usdWallet || usdWallet.balance < requiredAmount) {
    throw new Error('Insufficient funds for this operation');
  }
  
  return usdWallet.balance;
}
```

## What's Coming Next

<Warning>
  These features are planned for future releases:
</Warning>

* **Balance Expiration**: Set funds to expire after a certain period
* **Better Analytics**: Detailed spending reports and balance trends
* **More Webhooks**: Real-time notifications for balance changes and low balance alerts

<Tip>
  Start with basic funding and deduction operations, then integrate more complex automated billing workflows as your business grows.
</Tip>


# Customer Management
Source: https://docs.dodopayments.com/features/customers

Manage customer relationships, track purchase history, and provide self-service options through the Dodo Payments dashboard and API.

## Overview

The Customers feature in Dodo Payments provides a centralized hub for managing all your customer relationships. Track every customer interaction, view purchase history, manage subscriptions, access wallet transaction ledgers, and enable self-service options - all from a single dashboard.

<CardGroup>
  <Card title="Customer Dashboard" icon="table-columns">
    View and manage all customers in one place with search and filtering capabilities.
  </Card>

  <Card title="Customer Wallets" icon="wallet">
    Manage prepaid monetary balances, fund wallets, and track transaction history.
  </Card>

  <Card title="Customer Portal" icon="id-card">
    Empower customers to self-manage subscriptions, invoices, and license keys.
  </Card>

  <Card title="API Management" icon="code">
    Programmatically create, update, and retrieve customer data via API.
  </Card>
</CardGroup>

## Accessing the Customers Page

<Steps>
  <Step title="Navigate to Customers">
    From the dashboard, click on **Sales > Customers** in the navigation menu.
  </Step>

  <Step title="View Customer List">
    The Customers Page will display a list of all current and past customers who have interacted with your business.
  </Step>
</Steps>

<Frame>
  <img alt="Customers list page showing all customers with their details" />
</Frame>

## Customer Information

On the **Customers Page**, you can see a comprehensive overview of your entire customer base. The table displays all customers with the following information:

### Customer List Columns

* **Customer Name**: The full name of the customer with an avatar indicator.
* **Customer Id**: A unique identifier (e.g., `cus_5fpsWAa...`) for each customer.
* **Email**: The customer's email address for communication and portal access.
* **Phone Number**: The customer's phone number (if provided).
* **Created At (UTC)**: The date and time when the customer account was created.
* **Invite**: Quick action button to share Customer Portal invites.

### Page Features

* **Edit Columns**: Customize which columns are displayed in the customer table.
* **Build Report**: Generate custom reports based on your customer data.
* **Search**: Quickly find specific customers by name, email, or customer ID.
* **Pagination**: Navigate through your customer list with adjustable rows per page.

<Tip>
  Use the "Edit Columns" feature to customize your view and show only the information most relevant to your workflow.
</Tip>

## Customer Details Page

Click on any customer to view their detailed information page, which includes:

<Frame>
  <img alt="Customer details page showing customer information and transaction history" />
</Frame>

### About Section

The About section displays core customer information:

* **Name**: Customer's full name
* **Email**: Customer's email address
* **Customer ID**: Unique identifier for API and tracking purposes
* **Created At**: Timestamp of when the customer account was created

### Customer Activity Tabs

The customer details page includes three tabs for viewing different aspects of customer activity:

<Tabs>
  <Tab title="Transactions History">
    View all payment transactions for this customer including:

    * **Payment ID**: Unique transaction identifier
    * **Status**: Payment status (Successful, Failed, Pending, Refunded)
    * **Amount**: Transaction amount
    * **Date (UTC)**: When the transaction occurred
    * **Pricing Type**: Whether it's a one-time purchase or subscription
    * **Payment Method**: Payment method used (Card, UPI, etc.)
    * **Customer Email**: Email associated with the transaction
    * **Refund**: Quick action to initiate refunds
    * **Actions**: Additional options for managing the transaction
  </Tab>

  <Tab title="Active Subscriptions">
    View all active subscriptions for this customer:

    * Subscription plan details
    * Billing cycle and next renewal date
    * Subscription status
    * Options to manage or cancel subscriptions
  </Tab>

  <Tab title="Wallet Ledger">
    View the customer's wallet transaction ledger showing:

    * All fund additions and deductions

    * Current wallet balance in each currency (USD, EUR, GBP)

    * Transaction reasons and timestamps

    * Detailed transaction history for reconciliation
      View the customer's wallet credit ledger showing:

    * All credit and debit transactions

    * Current wallet balance in each currency

    * Transaction reasons and timestamps

    * Detailed transaction history for reconciliation
  </Tab>
</Tabs>

<Note>
  The Wallet Ledger tab provides complete transparency into customer wallet transactions, making it easy to track fund additions, deductions, and current monetary balances.
</Note>

## Customer Portal

The Customer Portal is a secure, hosted self-service area where your customers can manage their subscriptions, view billing history, access license keys, and update their profile—without contacting support.

### Portal Capabilities

Customers can access the portal to:

* **View Billing History**: See all past transactions and download invoices.
* **Manage Subscriptions**: Cancel or view subscription details.
* **Retrieve License Keys**: Access all license keys tied to their purchases.
* **Update Profile**: Change name, email, or phone number.

<Card title="Learn More About Customer Portal" icon="id-card" href="/features/customer-portal">
  Explore detailed documentation on portal features, access methods, and integration examples.
</Card>

## Customer Wallets

Customer Wallets are prepaid monetary balance accounts for your customers. Each customer automatically receives a wallet that can hold real funds in multiple currencies (USD, EUR, and GBP), which can be applied to subscription invoices, used for refund balances, or funded with promotional bonuses.

### Key Features

* **Multi-Currency Support**: Track monetary balances in USD, EUR, and GBP separately.
* **Prepaid Balances**: Customers can hold funds that get applied to future invoices and subscription payments.
* **Transaction History**: View complete ledger of all fund additions and deductions.
* **API-First Design**: Programmatically add, deduct, and check wallet balances.
* **Credit-Based Billing**: Allow customers to purchase credits upfront and spend them on your services.
* **Transaction History**: View complete ledger of all credits and debits.
* **API-First Design**: Programmatically add, remove, and check wallet balances.

<Card title="Learn More About Customer Wallets" icon="wallet" href="/features/customer-wallet">
  Explore detailed documentation, code examples, and best practices for managing customer wallet balances.
</Card>

## API Management

Dodo Payments provides a comprehensive REST API for programmatic customer management. You can create, retrieve, update, and manage customers entirely through the API.

### Available API Endpoints

<CardGroup>
  <Card title="Create Customer" icon="user-plus" href="/api-reference/customers/create-customer">
    Create a new customer in your Dodo Payments account with their details.
  </Card>

  <Card title="List Customers" icon="list" href="/api-reference/customers/get-customers">
    Retrieve a paginated list of all customers associated with your account.
  </Card>

  <Card title="Get Customer Details" icon="user" href="/api-reference/customers/get-customers-1">
    Get detailed information about a specific customer by their ID.
  </Card>

  <Card title="Update Customer" icon="pen" href="/api-reference/customers/patch-customer">
    Update a customer's information such as name, email, or metadata.
  </Card>

  <Card title="Delete Payment Method" icon="trash" href="/api-reference/customers/delete-payment-method">
    Remove a saved payment method from a customer's account.
  </Card>

  <Card title="Create Portal Session" icon="arrow-up-right-from-square" href="/api-reference/customers/create-customer-portal-session">
    Generate a secure Customer Portal session link for a specific customer.
  </Card>
</CardGroup>

<Note>
  All API endpoints require authentication using your API key. Always use your secret key on the server-side and never expose it in client-side code.
</Note>


# Design & Theme Customization
Source: https://docs.dodopayments.com/features/design

Customize the look and feel of your checkout, storefront, and customer portal from one place. Choose pre-built themes, configure typography and colors, and apply per-section overrides, all with live preview.

<Frame>
  <img alt="Design settings page with live preview of checkout, customer portal, and storefront" />
</Frame>

<Info>
  The Design page is your central hub for branding every customer-facing surface: checkout, storefront, and customer portal. Changes apply instantly across all three and are previewed in real time before you save. Test mode and live mode hold separate designs — see [Copy Design From Test to Live Mode](#copy-design-from-test-to-live-mode).
</Info>

## Key Highlights

1. **Unified Design Hub** - Configure checkout, storefront, and customer portal appearance from a single page.
2. **Pre-Built Themes** - Start with a curated theme and customize from there.
3. **Light & Dark Mode** - Define separate color palettes for each mode.
4. **Live Preview** - See how your changes look across checkout, customer portal, and storefront before saving.
5. **Per-Section Overrides** - Fine-tune individual sections (checkout, storefront, customer portal) without affecting the others.
6. **Programmatic Control** - Override themes at checkout time via the API or Checkout SDK.
7. **Copy Test Design to Live** - Move a design you perfected in test mode into live mode in one step.

## Getting Started

Navigate to **Settings → Design** in your Merchant Dashboard. The Design page has four tabs:

| Tab                 | Purpose                                                            |
| ------------------- | ------------------------------------------------------------------ |
| **General**         | Business name, logo, theme selection, and global advanced settings |
| **Checkout**        | Override theme settings specifically for the checkout page         |
| **Storefront**      | Override theme settings and configure storefront layout            |
| **Customer Portal** | Override theme settings for the customer portal                    |

## General Settings

The **General** tab controls your baseline brand identity and global theme.

<Frame>
  <img alt="General tab showing advanced settings with typography, colors, and border configuration" />
</Frame>

### Basic Configuration

| Setting           | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| **Business Name** | The name displayed on checkout, storefront, and customer portal |
| **Business Logo** | Your brand logo shown across all customer-facing pages          |
| **Theme**         | Select a pre-built theme as your starting point                 |

### Advanced Settings

Expand **Advanced Settings** to access granular controls:

<Frame>
  <img alt="Advanced settings expanded showing full color configuration for light and dark modes" />
</Frame>

#### Typography

| Setting            | Options                                 | Description                               |
| ------------------ | --------------------------------------- | ----------------------------------------- |
| **Primary Font**   | Any Google Font                         | Main font for headings and body text      |
| **Secondary Font** | Any Google Font                         | Accent font for labels and secondary text |
| **Font Size**      | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`     | Global base font size                     |
| **Font Weight**    | `normal`, `medium`, `bold`, `extraBold` | Default font weight                       |

#### Color Configuration

Define separate color palettes for **Light Mode** and **Dark Mode**. Each mode supports the following properties:

| Property                  | Description                        |
| ------------------------- | ---------------------------------- |
| **Background Primary**    | Main background color              |
| **Background Secondary**  | Secondary background (tabs, cards) |
| **Text Primary**          | Main text color                    |
| **Text Secondary**        | Muted text color                   |
| **Button Primary**        | Primary button background          |
| **Button Primary Text**   | Text color on primary buttons      |
| **Button Secondary**      | Secondary button background        |
| **Button Secondary Text** | Text color on secondary buttons    |
| **Border Primary**        | Main border color                  |
| **Border Secondary**      | Accent border color                |

#### Border

| Setting           | Description                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Border Radius** | Controls the roundness of inputs, buttons, tabs, and cards (e.g., `0` for sharp corners, `8px` for rounded, `16px` for pill-shaped) |

## Pre-Built Themes

Dodo Payments ships with four curated themes. Select one from the **Theme** dropdown on the General tab to instantly apply a cohesive design across checkout, storefront, and customer portal.

### Dodo Pulses

The default Dodo Payments theme. Lime green accents give it an energetic, fresh feel. Clean sans-serif typography with generous spacing.

<Tabs>
  <Tab title="Light Mode">
    <Frame>
      <img alt="Dodo Pulses theme in light mode showing checkout, customer portal, and storefront" />
    </Frame>
  </Tab>

  <Tab title="Dark Mode">
    <Frame>
      <img alt="Dodo Pulses theme in dark mode showing checkout, customer portal, and storefront" />
    </Frame>
  </Tab>
</Tabs>

### Terminal

A developer-oriented theme with monospaced typography and royal blue accents. Sharp corners and a technical aesthetic that pairs well with dev-tool and API-first products.

<Tabs>
  <Tab title="Light Mode">
    <Frame>
      <img alt="Terminal theme in light mode showing checkout with blue accents and monospaced font" />
    </Frame>
  </Tab>

  <Tab title="Dark Mode">
    <Frame>
      <img alt="Terminal theme in dark mode showing checkout with blue accents and monospaced font" />
    </Frame>
  </Tab>
</Tabs>

### Bumblebee

Warm amber and gold accents with rounded, modern styling. Bold and high-contrast, well-suited for consumer-facing products that want to feel premium.

<Tabs>
  <Tab title="Light Mode">
    <Frame>
      <img alt="Bumblebee theme in light mode showing checkout with amber accents" />
    </Frame>
  </Tab>

  <Tab title="Dark Mode">
    <Frame>
      <img alt="Bumblebee theme in dark mode showing checkout with gold accents" />
    </Frame>
  </Tab>
</Tabs>

### Bubblegum

Playful pink and magenta accents with fully rounded corners. A modern, approachable look that works great for creative tools, design products, and lifestyle brands.

<Tabs>
  <Tab title="Light Mode">
    <Frame>
      <img alt="Bubblegum theme in light mode showing checkout, customer portal, and storefront with pink accents" />
    </Frame>
  </Tab>

  <Tab title="Dark Mode">
    <Frame>
      <img alt="Bubblegum theme in dark mode showing checkout, customer portal, and storefront with pink accents" />
    </Frame>
  </Tab>
</Tabs>

<Tip>
  After selecting a pre-built theme, you can further customize individual properties in the Advanced Settings. Any unspecified properties fall back to the theme defaults.
</Tip>

## Per-Section Overrides

Each section tab (Checkout, Storefront, Customer Portal) includes an **Override Theme** toggle. When enabled, you can customize that section's appearance independently from the global theme.

### Checkout Tab

<Frame>
  <img alt="Checkout tab showing full checkout preview with product details and payment form" />
</Frame>

Override typography, colors, and border settings specifically for the checkout experience. The live preview shows:

* Product information and pricing
* Express checkout options (Apple Pay, Google Pay)
* Payment method selection and card form
* Discount code input and price breakdown

### Storefront Tab

<Frame>
  <img alt="Storefront tab showing store URL, branding controls, and storefront preview" />
</Frame>

Configure storefront-specific settings:

| Setting                 | Description                                                                 |
| ----------------------- | --------------------------------------------------------------------------- |
| **Store URL**           | Your storefront address (e.g., `store.dodopayments.com/your-store`)         |
| **Store Name**          | Toggle and set the name displayed on your storefront                        |
| **Store Logo**          | Toggle and upload a logo for the storefront header                          |
| **Store Banner**        | Toggle and upload a banner image                                            |
| **Product Description** | Toggle to show or hide product descriptions on cards                        |
| **Override Theme**      | Enable to customize typography, colors, and borders for the storefront only |

### Customer Portal Tab

<Frame>
  <img alt="Customer portal tab showing subscription management, billing history, and payment methods preview" />
</Frame>

Override the theme for the customer portal, which includes:

* Subscription management
* Billing history
* Payment methods
* Wallet and credits

## Copy Design From Test to Live Mode

Test mode and live mode keep separate design configurations, so a theme you build while testing does not automatically appear to real customers. Instead of re-creating it by hand, copy your design from test mode to live mode in one step.

The copy covers **all design surfaces** — general settings, checkout, customer portal, and storefront overrides — along with your storefront branding.

<Warning>
  Copying overwrites the existing live mode design. Review your live checkout and storefront after copying to confirm everything looks the way you expect.
</Warning>

## Related Resources

<CardGroup>
  <Card title="Checkout Features" icon="cart-shopping" href="/features/checkout">
    Checkout features including currency, language, tax, discounts, and more.
  </Card>

  <Card title="Overlay Checkout SDK" icon="layer-group" href="/developer-resources/overlay-checkout">
    Embed checkout as a modal overlay on your page.
  </Card>

  <Card title="Inline Checkout SDK" icon="credit-card" href="/developer-resources/inline-checkout">
    Embed checkout directly into your page layout.
  </Card>

  <Card title="Storefront" icon="store" href="/features/storefront">
    Set up and manage your branded storefront.
  </Card>

  <Card title="Customer Portal" icon="user" href="/features/customer-portal">
    Customer self-service portal for subscriptions and billing.
  </Card>

  <Card title="Multi-Brand Setup" icon="building-columns" href="/features/multi-brands">
    Run multiple brands under one account with separate branding.
  </Card>
</CardGroup>


# Digital Product Delivery
Source: https://docs.dodopayments.com/features/digital-product-delivery

Deliver downloadable files, external links, and download instructions automatically when customers purchase. Digital Product Delivery is the Digital Files entitlement type. Files are issued with presigned download URLs on every grant and revoked when access is withdrawn.

## Overview

Digital Product Delivery is the **Digital Files** entitlement type. You upload your files once to a Digital Files entitlement, attach the entitlement to a product, and Dodo Payments delivers presigned download links to every paying customer through email and the customer portal.

The entitlement supports:

* **Hosted file uploads**: store files on Dodo Payments and serve them via short-lived presigned URLs.
* **External download links**: link to files hosted on Dropbox, Google Drive, S3, or any URL.
* **Download instructions**: free-form text shown to the customer on their order page and in the delivery email.

You can mix all three on a single entitlement.

## Key Features

<CardGroup>
  <Card title="File Upload" icon="upload">
    Upload files (PDF, ZIP, images, videos, etc.) up to 500 MiB. Files are streamed and stored efficiently.
  </Card>

  <Card title="Multiple Files" icon="files">
    Attach as many files as you need to a single entitlement.
  </Card>

  <Card title="External Links" icon="link">
    Provide external download links (Dropbox, Google Drive, signed S3 URLs) as an alternative or addition.
  </Card>

  <Card title="Presigned URLs" icon="lock">
    Hosted files are served via short-lived presigned URLs. Each download URL expires automatically after roughly 15 minutes.
  </Card>
</CardGroup>

***

## Set up Digital Product Delivery

<Steps>
  <Step title="Open Entitlements">
    Go to **Entitlements** in your Dodo Payments dashboard and click **+** to create a new entitlement.
  </Step>

  <Step title="Choose Digital Files">
    Select **Digital Product Delivery** as the integration.
  </Step>

  <Step title="Add files, links, and instructions">
    Configure any combination of:

    * **Files**: upload one or more files. Each upload returns a `file_id` that's appended to the entitlement.
    * **External URL**: a publicly reachable HTTPS link delivered alongside hosted files.
    * **Instructions**: free-form text shown to the customer (e.g., "Unzip and run setup.sh").

    <Frame>
      <img alt="Digital Files entitlement with file upload, external URL, and instructions fields" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Save. The entitlement is now available to attach to any product.
  </Step>
</Steps>

## Attach to Products

Open a product, expand **Advanced Settings → Entitlements & Credits**, and select your Digital Files entitlement. The entitlement is delivered on every successful purchase or active subscription tied to that product.

<Frame>
  <img alt="Product entitlements panel showing Digital Product Delivery selected" />
</Frame>

***

## How Delivery Works

Digital Files delivery follows the standard [grant lifecycle](/features/entitlements/introduction#how-grants-work):

| Event                                            | Behavior                                                                                                                                                             |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (one-time)                   | Issue a grant. The grant carries presigned download URLs valid for \~15 minutes; customers can refresh them by reopening the email link or the customer portal page. |
| `subscription.active`                            | Issue a grant. Files remain accessible while the subscription is active.                                                                                             |
| `subscription.renewed`                           | No-op. The same grant continues; new presigned URLs are minted on every fetch.                                                                                       |
| `subscription.on_hold` / `cancelled` / `expired` | Revoke the grant. New presigned URLs are no longer issued.                                                                                                           |
| `subscription.plan_changed`                      | Revoke the old grant; issue a new one for the new plan's entitlement.                                                                                                |
| `refund.succeeded` (one-time)                    | Revoke the grant.                                                                                                                                                    |
| Manual revoke                                    | Revoke with `revocation_reason: manual`.                                                                                                                             |

<Warning>
  Revocation stops Dodo Payments from issuing new download URLs, but it does **not** invalidate copies a customer has already downloaded. Treat hosted file downloads as "delivered once read."
</Warning>

***

## Customer Experience

### Purchase Confirmation

After a successful transaction, the customer receives an email with download links and any instructions you configured.

<Frame>
  <img alt="Purchase confirmation email showing download links for digital products" />
</Frame>

### Customer Portal Access

Customers can re-fetch download links anytime from the [Customer Portal](/features/customer-portal). The portal page generates fresh presigned URLs on demand, so the same purchase keeps working even after the email's links have expired.

<Frame>
  <img alt="Customer portal interface showing available digital products for download" />
</Frame>

<Check>
  Customers can download files directly from confirmation emails or access them anytime through their portal.
</Check>

***

## Manage Files Programmatically

### Upload a file to an entitlement

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import DodoPayments from 'dodopayments';
  import fs from 'node:fs';

  const client = new DodoPayments({
    bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
    environment: 'test_mode',
  });

  await client.entitlements.files.upload('ent_files_abc', {
    file: fs.createReadStream('./pro-bundle.zip'),
    filename: 'pro-bundle.zip',
  });
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST "https://test.dodopayments.com/entitlements/ent_files_abc/files" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "file=@./pro-bundle.zip" \
    -F "filename=pro-bundle.zip"
  ```
</CodeGroup>

### List grants and resolve download URLs

```typescript theme={null} theme={null}
const grants = await client.entitlements.grants.list('ent_files_abc', {
  customer_id: 'cus_abc123',
});

for (const grant of grants.items) {
  for (const file of grant.digital_product_delivery.files) {
    console.log(file.filename, file.download_url, `expires in ${file.expires_in}s`);
  }
}
```

### Remove a file from an entitlement

```typescript theme={null} theme={null}
await client.entitlements.files.delete('df_a4f6c1de', { id: 'ent_files_abc' });
```

***

## Important Considerations

* **Presigned URLs expire quickly.** Download URLs returned in grant payloads or webhook events are valid for \~15 minutes. Don't store them; re-fetch them when the customer needs to download again.
* **Updating files affects future purchases only.** Replacing or removing a file does not retroactively change downloads already issued. Past customers can still re-fetch the version that was current when their grant was created.
* **Refunds don't invalidate downloaded copies.** A customer who already downloaded a file keeps that copy. For revocable content (license-restricted media, time-limited access), pair Digital Files with [License Keys](/features/license-keys) and validate at runtime.
* **For sensitive content, prefer external URLs with their own auth.** Dodo Payments' presigned URLs are short-lived but unauthenticated within their window; anyone with the URL can download in that window. Externally hosted, account-gated content provides stronger guarantees.

***

## API Management

<CardGroup>
  <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
    Create a Digital Files entitlement with optional external URL and instructions.
  </Card>

  <Card title="Upload File" icon="upload" href="/api-reference/entitlements/upload-file">
    Upload a file (up to 500 MiB) and append it to the entitlement.
  </Card>

  <Card title="Delete File" icon="trash" href="/api-reference/entitlements/delete-file">
    Remove a file from the entitlement.
  </Card>

  <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
    List grants and read the resolved download URLs.
  </Card>

  <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
    Update instructions, external URL, or replace files.
  </Card>

  <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
    Manually revoke a customer's access.
  </Card>
</CardGroup>

***

## Webhooks

Digital file delivery and revocation fire the four [`entitlement_grant.*` webhook events](/developer-resources/webhooks/intents/entitlement-grant). For Digital Files grants, the payload includes a `digital_product_delivery` object with the resolved file list (presigned URLs, filenames, sizes), the optional `instructions`, and the optional `external_url`.

```json theme={null} theme={null}
"digital_product_delivery": {
  "files": [
    {
      "file_id": "df_a4f6c1de",
      "download_url": "https://files.dodopayments.com/.../pro-bundle.zip?Signature=...",
      "filename": "pro-bundle.zip",
      "content_type": "application/zip",
      "file_size": 18742390,
      "expires_in": 900
    }
  ],
  "instructions": "Unzip and run setup.sh from the project root.",
  "external_url": null
}
```

***

## Legacy Digital Product Delivery

<Note>
  Products configured with the older `digital_product_delivery` block on the product itself have been **automatically migrated** to a Digital Files entitlement. Existing files uploaded under the legacy product file API are preserved; they continue to be downloadable and appear in grant payloads alongside newly uploaded files. On the entitlement's `digital_files` configuration they are tracked in the `legacy_file_ids` list. Future updates (adding files, changing instructions, replacing the external URL) should be made by editing the migrated Digital Files entitlement under **Entitlements**.

  The legacy product-level fields (`digital_product_delivery.external_url`, `digital_product_delivery.instructions`) continue to be populated on product responses for backwards compatibility, but the entitlement is the source of truth going forward.
</Note>

***

## Best Practices

* **Treat downloads as one-shot.** Customers will share or lose links, so design your product around the assumption that anything they download is theirs to keep.
* **Use instructions to set expectations.** For multi-file bundles, add an `instructions` line explaining what to install first or how to combine the files.
* **Watch the 500 MiB cap.** Larger artifacts (multi-GB datasets, video courses) should be hosted externally and linked via `external_url` instead of uploaded.
* **Combine with License Keys for revocable access.** If you need to revoke access to in-product features after a refund, pair the Digital Files entitlement with a License Key entitlement and validate the key at runtime.
* **Test the customer-portal refresh flow.** Confirm a customer can return to the portal a week later and still get a working download link. This is the primary recovery path when email links expire.


# Discounts
Source: https://docs.dodopayments.com/features/discount-codes

Create promotional codes to drive conversions, run campaigns, and reward customers with percentage discounts across one‑time and subscription purchases.

<Frame>
  <img alt="Discount codes overview cover" />
</Frame>

Discount codes let you run targeted promotions and incentives. Create percentage-based discounts, set limits and expirations, restrict to products, and apply them seamlessly in checkout.

<CardGroup>
  <Card title="Checkout Sessions" icon="cart-shopping" href="/developer-resources/checkout-session">
    Apply one or more stacked codes during hosted checkout with `discount_codes` and UI controls.
  </Card>

  <Card title="Validate Discount" icon="code" href="/api-reference/discounts/validate-discount">
    Check if a discount is valid by its ID.
  </Card>

  <Card title="Get Discount by Code" icon="tag" href="/api-reference/discounts/get-discount-by-code">
    Look up and validate a discount using its code name (e.g., "SAVE20").
  </Card>

  <Card title="Create Discount (API)" icon="code" href="/api-reference/discounts/create-discount">
    Programmatically create new discount codes.
  </Card>

  <Card title="List & Update Discounts" icon="code" href="/api-reference/discounts/list-discounts">
    Browse and manage existing discounts; update or delete as needed.
  </Card>

  <Card title="Plan Change Discounts" icon="arrows-rotate" href="/api-reference/subscriptions/change-plan">
    Apply discount codes when upgrading or downgrading subscription plans.
  </Card>
</CardGroup>

## What Are Discount Codes?

Discount codes are promotional tokens that reduce order totals at checkout. They’re ideal for:

* **Seasonal campaigns**: Black Friday, product launches, or anniversaries
* **Acquisition offers**: First‑purchase incentives or referral rewards
* **Retention**: Win‑back or loyalty rewards for existing customers
* **B2B deals**: Contracted or negotiated pricing via private codes

## Key Benefits

* **Flexible discounts**: Percentage-based or flat-amount discounts
* **Stackable codes**: Apply up to 20 codes per checkout, payment, or subscription — combine campaigns (e.g. `WELCOME10` + `BLACKFRIDAY20`) without creating bespoke codes
* **Targeted control**: Restrict by product, subscription cycles, and customer eligibility
* **Campaign governance**: Scheduled start dates, expiration dates, overall and per-customer usage limits
* **Per-currency pricing**: Set the flat deduction, amount cap, and minimum subtotal per currency
* **Seamless checkout**: UI field and API support via checkout sessions

## Creating Discount Codes

Create discount codes in your Dodo Payments dashboard, then apply them in hosted checkout or via API.

<Frame>
  <img alt="Discounts list in the Dodo Payments dashboard showing existing discount codes" />
</Frame>

### Dashboard setup

* **Discount Name** (required): Internal and dashboard display name
* **Code** (required): The string customers enter at checkout, or generate a random code using the button provided
* **Type** (required): Choose **Percentage** (a percent off) or **Amount** (a flat deduction)
* **Amount** (required): The percentage value, or the flat amount for an Amount discount
* **Start Date** (optional): Schedule the code to become active later; leave empty to activate immediately
* **Expiration Date** (optional): Date after which the code becomes invalid
* **Usage Limit** (optional): Max total redemptions across all customers
* **Per-Customer Usage Limit** (optional): Max redemptions by any single customer. Must be less than or equal to the overall usage limit when both are set
* **Customer Eligibility** (optional): Restrict who may redeem the code — all customers, first-time customers, existing customers, or a hand-picked list
* **Currency Options** (optional): Per-currency values — see [Per-Currency Options](#per-currency-options)
* **Product Restriction** (optional): Limit applicability to selected products
* **Subscription Cycle Limit** (optional): Number of billing cycles the discount applies to
* **Preserve on Plan Change** (optional): Keep the discount active when the subscription's plan changes (`preserve_on_plan_change`)
* **Metadata** (optional): Attach custom key–value pairs for internal tracking or integrations

The discount details — type, percentage or amount, name, code, and currency options:

<Frame>
  <img alt="New Discount Code form showing type, percentage amount, name, code, and currency options" />
</Frame>

Usage and expiry limits, fully configured:

<Frame>
  <img alt="Usage and expiry limits panel with start date, expiration date, and usage limits configured" />
</Frame>

Further down the form — eligibility, restrictions, and advanced options:

<Frame>
  <img alt="Eligibility, restrictions, and advanced options for a discount code" />
</Frame>

<Tip>
  Use cycle limits for introductory pricing on subscriptions (e.g., "50% off for 3 months").
</Tip>

<Info>
  A percentage `amount` is expressed in **basis points** over the API — `1500` means 15%. A flat `amount` is a money value and is denominated by the code's currency options.
</Info>

## Discount Types

| Type       | API value    | Behaviour                                                                                                |
| ---------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| Percentage | `percentage` | Reduces the price by a percent. Optionally capped per currency with a maximum discount.                  |
| Amount     | `flat`       | Deducts a fixed amount. The deduction is pooled across the whole cart rather than applied per line item. |

Both types can be combined in the same `discount_codes` array and are applied in array order.

<Frame>
  <img alt="Discount code editor with the Amount type selected, showing a flat 500 INR deduction" />
</Frame>

## Customer Eligibility

Set `customer_eligibility` to control who may redeem a code:

| Value        | Who can redeem                                      |
| ------------ | --------------------------------------------------- |
| `any`        | Any customer. This is the default.                  |
| `first_time` | Customers who have not purchased from you before.   |
| `existing`   | Customers who have purchased from you before.       |
| `specific`   | Only customers you attach to the code's allow list. |

<Frame>
  <img alt="Customer eligibility dropdown showing Any, First-time, Existing, and Specific customer options" />
</Frame>

<Warning>
  A `specific` code starts with **zero** eligible customers and rejects every redemption until you attach customers to it. Attach them in the dashboard, or with the discount customers API.
</Warning>

Pair eligibility with **Per-Customer Usage Limit** to cap how often each individual customer can redeem the code, independently of the overall usage limit.

## Per-Currency Options

Currency options let one code behave correctly across the currencies you sell in. Each entry sets, for a single currency:

* **Amount** — for an Amount discount this is the deduction itself; for a Percentage discount it caps how much the code can take off. Maps to `max_amount_possible` over the API.
* **Minimum subtotal** — the code only applies when the cart reaches this subtotal. `0` means no minimum.
* **Default** — one entry can be marked as the default that other, unconfigured currencies convert from.

<Frame>
  <img alt="Currency options panel with per-currency amount and minimum subtotal for INR and USD" />
</Frame>

An Amount discount requires at least one currency option with a resolvable default, since a flat deduction has no meaning without a currency. Currency options are optional for Percentage discounts.

<Info>
  The minimum subtotal is always measured against the cart's original prices, never the running total part-way through a stack. Stacking order therefore never changes whether a minimum is met.
</Info>

## Checkout Experience

1. Shoppers enter the code in the checkout field.
2. Eligible discounts are applied and totals update immediately.

<Frame>
  <img alt="Checkout page showing a discount applied to the order total" />
</Frame>

<Info>
  In Checkout Sessions, pass `discount_codes` (an array) to pre‑apply one or more codes. The discount input field is shown by default — `feature_flags.allow_discount_code` defaults to `true`, so set it to `false` only if you want to hide it. Codes are applied in array order, up to a maximum of 20.
</Info>

## Stacking Discount Codes

Checkout sessions, payments, and subscriptions accept up to **20 stacked codes** via the `discount_codes` array (max 20 entries). Codes are applied **in array order**, so the first eligible code reduces the base price first, the next code reduces the already-discounted price, and so on. The full set of applied discounts is returned in the response under `discount_ids` (on payments/subscriptions) and `discounts` (richer per-discount detail, including position and remaining subscription cycles).

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});
```

<Info>
  The singular `discount_code` field is **deprecated** but still fully supported for backward compatibility — existing integrations continue to work without changes. It cannot be combined with `discount_codes` in the same request. We recommend migrating to `discount_codes` (the array form) when convenient, even for single codes, to take advantage of stacking and the richer response shape.
</Info>

## API Management

<AccordionGroup>
  <Accordion title="Create discounts">
    Create discount codes programmatically with type and amount.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/create-discount">
      View the create discount API.
    </Card>
  </Accordion>

  <Accordion title="List and retrieve">
    List all discounts or retrieve details for management and auditing.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/list-discounts">
      Browse listing and retrieval APIs.
    </Card>
  </Accordion>

  <Accordion title="Get discount by code">
    Look up a discount using its human-readable code (e.g., "SAVE20") instead of the internal ID.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/get-discount-by-code">
      Retrieve discount by code name.
    </Card>
  </Accordion>

  <Accordion title="Update discounts">
    Modify discount configuration such as amount, expiration, or restrictions.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/update-discount">
      Learn how to update discount details.
    </Card>
  </Accordion>

  <Accordion title="Validate discounts">
    Check whether a discount is valid and applicable before applying.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/validate-discount">
      Validate discount usage.
    </Card>
  </Accordion>

  <Accordion title="Delete discounts">
    Deactivate or remove discounts that are no longer needed.

    <Card title="API Reference" icon="code" href="/api-reference/discounts/delete-discount">
      Delete a discount.
    </Card>
  </Accordion>

  <Accordion title="Manage the customer allow list">
    For a discount with `customer_eligibility` set to `specific`, manage the customers that may redeem it:

    * `GET /discounts/{discount_id}/customers` — list the attached customers (paginated, up to 100 per page).
    * `POST /discounts/{discount_id}/customers` — attach customers by ID. The call is idempotent and accepts up to 1000 IDs, all of which must already exist in your business. The response echoes only the IDs submitted in that request, so list the endpoint to read the full allow list.
    * `DELETE /discounts/{discount_id}/customers/{customer_id}` — detach a single customer.
  </Accordion>
</AccordionGroup>

## Common Use Cases

* **Intro offers**: Limited‑time launch promotions for new products
* **Bulk or B2B**: Contracted discounts for select product sets
* **Retention plays**: Win‑back codes in churn‑prevention workflows
* **Seasonal campaigns**: Holiday or event‑based promotions

## Integration Examples

### Create a discount with metadata

Attach custom key–value pairs for internal tracking.

```typescript theme={null}
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});
```

<Tip>
  Use metadata to tag discounts by campaign, source, or internal reference ID so you can reconcile usage and measure ROI later.
</Tip>

### Apply discounts in Checkout Sessions

Pre‑apply one or more stacked discounts and show the code input UI.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order
  customer: { email: 'user@example.com', name: 'Jane Doe' },
  return_url: 'https://yoursite.com/return'
});
```

### Apply discounts during plan changes

Offer promotional pricing when customers upgrade or downgrade their subscription.

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});
```

| `discount_codes` value              | Behavior on plan change                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `undefined` / `null` (not provided) | Existing discounts with `preserve_on_plan_change=true` are preserved if applicable to the new product. |
| `[]` (empty array)                  | **All** existing discounts are removed from the subscription.                                          |
| `['CODE_A', 'CODE_B', ...]`         | Replaces any existing discounts with this stacked set, applied in array order.                         |

<Info>
  Read all applied discounts off the subscription via the new `discounts` array on the subscription response. Each entry includes `discount_id`, `position`, `cycles_remaining` (for subscriptions), and the original code.
</Info>

### Hide the discount code field

The discount input is shown by default, so customers can always enter a code without you passing one upfront. Set `allow_discount_code` to `false` to hide the field entirely.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  feature_flags: {
    allow_discount_code: false
  },
  return_url: 'https://yoursite.com/return'
});
```

## Best Practices

* **Name clearly**: Use recognizable codes that match campaign names
* **Time‑box**: Add expirations to drive urgency and prevent misuse
* **Scope wisely**: Limit to specific products to avoid margin leakage
* **Validate early**: Check code applicability before confirming checkout
* **Monitor impact**: Track usage and conversion by campaign

<Info>
  Discount codes are powerful levers for acquisition and retention. Start with simple, well‑named offers, validate thoroughly, and iterate based on performance.
</Info>


# Discord Entitlement
Source: https://docs.dodopayments.com/features/entitlements/discord

Grant your customers a role in your Discord server when they purchase, and revoke it automatically when their subscription ends.

<Info>
  The Discord entitlement adds a paying customer to your server (and optionally assigns them a role) the moment their subscription becomes active or their one-time purchase clears. Cancellation, refunds, and plan changes revoke the role automatically.
</Info>

## What gets delivered

* The customer connects their Discord account through an OAuth link in their delivery email or customer portal.
* Once they authorize, Dodo Payments adds them to your server (or finds their existing membership) and assigns the role you configured.
* If you didn't pick a specific role, server membership alone is granted.

This integration is ideal for paid communities, supporter perks, and tiered access channels.

## Connect Discord

<Steps>
  <Step title="Open Entitlements">
    In your Dodo Payments dashboard, go to **Entitlements** and click **+** to start a new entitlement.
  </Step>

  <Step title="Pick Discord">
    Choose **Discord Access** as the integration. If you have not yet connected Discord for your business, you'll be prompted to **Connect Discord**.

    <Frame>
      <img alt="New entitlement panel prompting the merchant to connect Discord" />
    </Frame>

    Clicking through opens Discord in a new tab. Sign in, pick the server you want to gate, and confirm the bot's permissions (Manage Roles, Kick Members, Create Invite) on that server.

    <Frame>
      <div>
        <img alt="Discord OAuth screen asking which server to add the Dodo Payments bot to" />

        <img alt="Discord bot permission confirmation screen" />
      </div>
    </Frame>

    When Discord redirects back, you'll see a confirmation that the server is connected.

    <Frame>
      <img alt="Discord Access connected successfully confirmation page" />
    </Frame>
  </Step>

  <Step title="Pick a server and role">
    Back in the dashboard, select the **server** (guild) you just connected. Optionally pick a **role** to assign on delivery, or leave it blank to grant server membership only. Give the entitlement a **name** and click **Create Entitlement**.

    <Frame>
      <img alt="New Entitlement - Discord Access form with connected server, server picker, role dropdown, and name field" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Save the entitlement. It's now available to attach to any product.
  </Step>
</Steps>

## Customer flow

1. The customer completes checkout.
2. Dodo Payments creates a grant in `Pending` status with an `oauth_url` pointing to Discord.
3. The customer receives an email with a "Join the Discord" button (the OAuth link). The link is also visible in their customer portal.
4. After the customer authorizes, the bot adds them to the server and assigns the configured role. The grant moves to `Delivered`.
5. If the subscription is cancelled, paused, or expires, or if the merchant manually revokes, the bot removes the role and the grant moves to `Revoked`.

<Tip>
  Make sure the Dodo Payments bot's role is positioned **above** the role you grant. Discord prevents bots from assigning roles ranked higher than their own.
</Tip>

## Required configuration

| Field      | Required | Description                                                             |
| ---------- | -------- | ----------------------------------------------------------------------- |
| `guild_id` | Yes      | The Discord server ID. The dashboard picker fills this in for you.      |
| `role_id`  | No       | The role to assign on delivery. Omit for server-membership-only access. |

## Create via API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
    environment: 'test_mode',
  });

  const entitlement = await client.entitlements.create({
    name: 'Patrons Discord Role',
    integration_type: 'discord',
    integration_config: {
      guild_id: '123456789012345678',
      role_id: '987654321098765432',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Patrons Discord Role",
      integration_type="discord",
      integration_config={
          "guild_id": "123456789012345678",
          "role_id": "987654321098765432",
      },
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Patrons Discord Role"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeDiscord),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigDiscordConfigParam{
        GuildID: dodopayments.F("123456789012345678"),
        RoleID:  dodopayments.F("987654321098765432"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

Subscribe to the [`entitlement_grant.*` webhook events](/developer-resources/webhooks/intents/entitlement-grant) to track Discord grants:

* `entitlement_grant.created` fires with `status: "Pending"` and an `oauth_url` for the customer to authorize.
* `entitlement_grant.delivered` fires once the role is assigned.
* `entitlement_grant.revoked` fires when the role is removed.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Customer never sees the role assigned">
    The grant is in `Pending` until the customer completes the OAuth flow. Check the entitlement's grants list and confirm whether they clicked the OAuth link. Resend the delivery email if needed.
  </Accordion>

  <Accordion title="Grant moves to failed with permission errors">
    Make sure the Dodo Payments bot remains in the server, has `Manage Roles` permission, and is positioned above the role being assigned. Re-saving the entitlement re-runs validation.
  </Accordion>

  <Accordion title="Customer cancelled but still has the role">
    Discord propagates role removals immediately, but the customer's local Discord client may cache. They should reconnect or refresh; server-side state is correct.
  </Accordion>
</AccordionGroup>


# Feature Flag Entitlement
Source: https://docs.dodopayments.com/features/entitlements/feature-flags

Gate features in your own application off a purchase. Feature flag entitlements deliver a boolean capability instantly on payment and revoke it automatically on cancellation.

<Info>
  A feature flag entitlement turns Dodo Payments into a billing-aware feature-flag store. Attach a flag like `advanced_reports` to a product, and every paying customer gets a grant your application can check via API or keep in sync with webhooks. No external platform, no OAuth, no delivery step — the grant itself is the capability.
</Info>

## What gets delivered

Nothing leaves Dodo Payments — the grant **is** the deliverable:

* On purchase, the grant is created and moves straight to `Delivered`. There is no `Pending` phase, no customer action, and no way for delivery to fail.
* The grant carries a typed `feature` payload: `{ "feature_type": "boolean", "feature_id": "advanced_reports" }`. Your application reads `feature_id` to decide what to unlock.
* Cancellation, refund, or manual revoke moves the grant to `Revoked`, and your application sees the flag disappear.

Common uses include plan-based feature gating (Pro unlocks analytics), add-on capabilities (an "API access" upgrade), and early-access programs sold as one-time purchases.

<Note>
  `feature_id` is a merchant-chosen identifier, not unique across entitlements. Two entitlements can confer the same `feature_id` — for example, a monthly and a yearly Pro plan both granting `advanced_reports`.
</Note>

## Create a feature flag

<Steps>
  <Step title="Open Entitlements">
    In your Dodo Payments dashboard, go to **Entitlements** and click **+** to start a new entitlement, then choose **Feature Flags**.
  </Step>

  <Step title="Name the flag">
    Give the flag a **Display Name** for your dashboard, a **Feature ID** your application will check (the dashboard suggests one from the name), and a **Description** so your team knows what it controls.

    <Frame>
      <img alt="New Feature Flag form with display name, feature ID, description, and metadata key-value entries" />
    </Frame>
  </Step>

  <Step title="Optionally add metadata">
    Toggle **Meta Data** to attach key-value configuration — limits, tier names, quotas — that is delivered to your application alongside the flag. See [Attach limits with metadata](#attach-limits-with-metadata).
  </Step>

  <Step title="Confirm">
    Click **Confirm**. The flag appears in your entitlements list, ready to attach to products.

    <Frame>
      <img alt="Entitlements dashboard showing the Advanced Reports feature flag with its grant activity pane" />
    </Frame>
  </Step>
</Steps>

## Attach to a product

Open a product (or create one), find the **Entitlements** card, and click **+** to attach existing entitlements. Select your feature flag and click **Done**.

<Frame>
  <img alt="Entitlements attach panel with the Advanced Reports feature flag selected" />
</Frame>

The attached flag shows on the product form, and the checkout preview lists it under **Includes**.

<Frame>
  <img alt="Product form with the Advanced Reports feature flag attached in the Entitlements card" />
</Frame>

## Required configuration

| Field          | Required | Description                                                                                  |
| -------------- | -------- | -------------------------------------------------------------------------------------------- |
| `feature_id`   | Yes      | Identifier your application checks, e.g. `advanced_reports`. Not unique across entitlements. |
| `feature_type` | Yes      | Type of capability conferred. Only `boolean` is supported today.                             |

### Create via API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
    environment: 'test_mode',
  });

  const entitlement = await client.entitlements.create({
    name: 'Advanced Reports',
    integration_type: 'feature_flag',
    integration_config: {
      feature_type: 'boolean',
      feature_id: 'advanced_reports',
    },
    metadata: {
      tier: 'pro',
      monthly_report_limit: 100,
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Advanced Reports",
      integration_type="feature_flag",
      integration_config={
          "feature_type": "boolean",
          "feature_id": "advanced_reports",
      },
      metadata={
          "tier": "pro",
          "monthly_report_limit": 100,
      },
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Advanced Reports"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeFeatureFlag),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigFeatureFlagConfigParam{
        FeatureType: dodopayments.F(dodopayments.FeatureTypeBoolean),
        FeatureID:   dodopayments.F("advanced_reports"),
      },
    ),
  })
  ```
</CodeGroup>

***

## Attach limits with metadata

A boolean flag answers "does this customer have the feature?". Metadata answers "with what configuration?". Entitlement metadata accepts string, integer, number, and boolean values, and every grant takes a **frozen snapshot** of the entitlement's metadata at the moment it is created.

That snapshot behavior is what makes metadata safe to use for plan limits:

* Editing the entitlement's metadata later only affects **future** grants. Customers keep the limits they purchased under.
* The snapshot is returned on each grant as its `metadata` field, so one API call gives you both the flag and its configuration.

For example, an `advanced_reports` flag with `{ "tier": "pro", "monthly_report_limit": 100 }` lets your application unlock the dashboard *and* enforce the 100-report quota without a second lookup. If you later raise the limit to 250, existing customers stay at 100 until they receive a new grant (for example, after a plan change).

<Tip>
  Use metadata for limits and configuration; use `feature_id` only for identity. Encoding limits in the id (`advanced_reports_100`) forces a new flag for every limit change and breaks your application's checks.
</Tip>

***

## Check a customer's features

List a customer's delivered feature-flag grants and build the set of enabled features. The endpoint returns one row per grant across all entitlements, filterable by `integration_type` and `status`.

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const features = new Map<string, Record<string, unknown>>();

  for await (const grant of client.customers.listEntitlementGrants('cus_abc123', {
    integration_type: 'feature_flag',
    status: 'Delivered',
  })) {
    if (grant.feature) {
      features.set(grant.feature.feature_id, grant.metadata ?? {});
    }
  }

  if (features.has('advanced_reports')) {
    const limit = features.get('advanced_reports')?.monthly_report_limit;
    // unlock the dashboard, enforce the limit
  }
  ```

  ```python Python theme={null} theme={null}
  page = client.customers.list_entitlement_grants(
      customer_id="cus_abc123",
      integration_type="feature_flag",
      status="Delivered",
  )

  features = {
      grant.feature.feature_id: grant.metadata
      for grant in page.items
      if grant.feature
  }

  if "advanced_reports" in features:
      limit = features["advanced_reports"].get("monthly_report_limit")
  ```

  ```go Go theme={null} theme={null}
  page, _ := client.Customers.ListEntitlementGrants(
    ctx, "cus_abc123",
    dodopayments.CustomerListEntitlementGrantsParams{
      IntegrationType: dodopayments.F("feature_flag"),
      Status:          dodopayments.F("Delivered"),
    },
  )

  features := map[string]bool{}
  for _, grant := range page.Items {
    if grant.Feature.FeatureID != "" {
      features[grant.Feature.FeatureID] = true
    }
  }
  ```
</CodeGroup>

<Note>
  The `feature` payload is populated only on `feature_flag` grants; it is `null` for every other integration type. See the [List Customer Grants](/api-reference/entitlements/list-customer-grants) API reference for the full response shape.
</Note>

Checking the API on every request adds latency to your hot path. Cache the feature set per customer with a short TTL (minutes, not hours), and invalidate the cache from your webhook handler when a grant changes state — that combination keeps checks fast and revocations near-instant.

***

## Lifecycle

Feature flag grants follow the standard [grant lifecycle](/features/entitlements/introduction#how-grants-work) with one simplification: there is no delivery step, so grants never sit in `Pending` and never move to `Failed`.

| Trigger                                                 | Effect                                                                                     |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| One-time payment succeeds / subscription becomes active | Grant created with `status: delivered` and `delivered_at` set.                             |
| Subscription put on hold, cancelled, or expired         | Grant revoked with the matching `revocation_reason`.                                       |
| Refund on a one-time payment                            | Grant revoked with `revocation_reason: refund`.                                            |
| Subscription recovers (for example, dunning succeeds)   | The revoked grant is restored to `Delivered` — same grant `id`, revocation fields cleared. |
| Manual API revoke                                       | Grant revoked with `revocation_reason: manual`. Not auto-restored on renewal.              |

Grants are idempotent per entitlement and customer: while a customer has a non-revoked grant for a flag, repeat purchases and renewals do not create duplicates.

***

## Webhooks

Subscribe to the [`entitlement_grant.*` events](/developer-resources/webhooks/intents/entitlement-grant) to mirror flags into your own database instead of polling:

* `entitlement_grant.created` — arrives already `Delivered` with the `feature` payload. Enable the feature.
* `entitlement_grant.delivered` — fires when a previously revoked grant is restored. Re-enable the feature.
* `entitlement_grant.revoked` — access withdrawn. Disable the feature and check `revocation_reason` to decide your messaging.

```typescript TypeScript theme={null} theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  if (event.type.startsWith('entitlement_grant.') && event.data.feature) {
    const { customer_id, feature } = event.data;
    const enabled = event.type !== 'entitlement_grant.revoked';

    await db.customerFeatures.upsert({
      customerId: customer_id,
      featureId: feature.feature_id,
      enabled,
      config: event.data.metadata ?? {},
    });
  }

  res.sendStatus(200);
});
```

There is no `entitlement_grant.failed` for feature flags — delivery happens entirely inside Dodo Payments and cannot fail.

***

## Example: Pro plan unlocks advanced reports

1. **Create the flag.** `feature_id: advanced_reports` with metadata `{ "tier": "pro", "monthly_report_limit": 100 }`.
2. **Attach it** to your Pro Plan subscription product.
3. **A customer subscribes.** Dodo Payments creates a `Delivered` grant and fires `entitlement_grant.created`; your webhook handler enables `advanced_reports` for the customer with a limit of 100.
4. **Your app gates the feature.** On dashboard load, check the cached feature set (or call `listEntitlementGrants`) and render the reports tab only when `advanced_reports` is present.
5. **The customer cancels.** Dodo Payments revokes the grant and fires `entitlement_grant.revoked`; your handler disables the feature. If the customer later recovers via dunning, `entitlement_grant.delivered` restores it — no code changes needed.

***

## Best practices

* **Use stable, snake\_case feature ids.** Your application code checks these strings; renaming one is a breaking change on both sides.
* **One flag per capability.** Prefer `advanced_reports` + `api_access` as two entitlements over a single `pro_bundle` — revocation and plan mixes stay clean.
* **Drive state from webhooks, verify with the API.** Webhooks keep your database current; the list endpoint is the source of truth for reconciliation jobs and cache misses.
* **Treat `Revoked` as immediate.** A revoked flag means the customer is no longer paying for the feature. Gate on the next request, not the next session.
* **Put limits in metadata, not in code.** Changing a quota then only requires editing the entitlement — new customers pick it up automatically while existing grants keep their purchased snapshot.


# Framer Entitlement
Source: https://docs.dodopayments.com/features/entitlements/framer

Unlock a Framer template remix link for paying customers.

<Info>
  The Framer entitlement unlocks a Framer template remix link for paying customers. You upload the template to Dodo Payments, attach the entitlement to a product, and customers receive a remix link that lets them clone the template into their own Framer account.
</Info>

## What gets delivered

* A unique remix link to the Framer template you uploaded.
* The customer clicks the link to remix the template into their own Framer workspace.
* On cancellation or refund, the remix link is invalidated.

Common uses include paid Framer landing-page templates, portfolio kits, and component libraries.

## Connect Framer

Framer is connected implicitly the first time you create a template entitlement. There's no separate OAuth step.

<Steps>
  <Step title="Open Entitlements">
    In your Dodo Payments dashboard, go to **Entitlements** and click **+**.
  </Step>

  <Step title="Pick Framer">
    Choose **Framer Template** as the integration.
  </Step>

  <Step title="Grab the remix link from Framer">
    Open your Framer project. From the top-left menu, go to **File → Copy Remix Link**. This produces a public remix URL that lets anyone clone the project into their own Framer account — the link Dodo Payments will share with paying customers.

    <Frame>
      <img alt="Framer File menu with Copy Remix Link option highlighted" />
    </Frame>
  </Step>

  <Step title="Add the template and create the entitlement">
    Back in the Dodo Payments dashboard, pick the template from the **Template** dropdown. The first time you do this for a new template, paste in the remix link you copied to register it. Give the entitlement a **name** and click **Create Entitlement**.

    <Frame>
      <img alt="Framer template entitlement form with template picker and name field" />
    </Frame>

    Dodo Payments registers the template and returns a `framer_template_id` you can reference programmatically.
  </Step>
</Steps>

## Customer flow

1. The customer completes checkout.
2. Dodo Payments creates a `Pending` grant and issues a unique remix link tied to that customer.
3. The grant transitions to `Delivered` once the remix link is provisioned and the link is included in the customer's email and portal.
4. The customer clicks the link, signs in to Framer, and remixes the template.
5. On revocation, the remix link is invalidated. Already-remixed copies in the customer's Framer account remain, since Framer doesn't expose a way to revoke them.

## Required configuration

| Field                | Required | Description                                            |
| -------------------- | -------- | ------------------------------------------------------ |
| `framer_template_id` | Yes      | The template ID returned when you upload the template. |

## Create via API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const entitlement = await client.entitlements.create({
    name: 'Portfolio Kit',
    integration_type: 'framer',
    integration_config: {
      framer_template_id: 'tmpl_abc123',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Portfolio Kit",
      integration_type="framer",
      integration_config={"framer_template_id": "tmpl_abc123"},
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Portfolio Kit"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeFramer),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigFramerConfigParam{
        FramerTemplateID: dodopayments.F("tmpl_abc123"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

See [`entitlement_grant.*` webhook events](/developer-resources/webhooks/intents/entitlement-grant). Framer grants arrive `Pending` and transition to `Delivered` once the remix link is provisioned.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Customer's remix link doesn't work">
    The remix link is single-use and tied to the customer. If they cleared the link before remixing, revoke the grant and reissue.
  </Accordion>

  <Accordion title="Refunded customer still has a remixed copy">
    This is expected. Framer treats a remix as the customer's own project once it's cloned; Dodo Payments invalidates the original link but cannot delete copies in the customer's account.
  </Accordion>
</AccordionGroup>


# GitHub Entitlement
Source: https://docs.dodopayments.com/features/entitlements/github

Grant customers collaborator access to a private GitHub repository at the permission level you choose, and revoke automatically on cancellation.

<Info>
  The GitHub entitlement adds a paying customer as a collaborator on a private repository. You choose the permission level (`pull`, `push`, `triage`, `maintain`, or `admin`) and Dodo Payments handles invitation, acceptance tracking, and removal on cancellation.
</Info>

## What gets delivered

* The customer is invited to your GitHub repository through an OAuth flow that links their GitHub account to the purchase.
* Once they accept, GitHub grants them collaborator access at the configured permission level.
* Cancellation, refund, or manual revoke removes the collaborator.

Common uses include source-available products, paid templates, course code repos, and gated client SDKs.

## Connect GitHub

<Steps>
  <Step title="Open Entitlements">
    In your Dodo Payments dashboard, go to **Entitlements** and click **+** to start a new entitlement.
  </Step>

  <Step title="Pick GitHub">
    Choose **GitHub Access** as the integration. If GitHub is not yet connected, you'll be prompted to **Connect GitHub**.

    <Frame>
      <img alt="New entitlement panel prompting the merchant to connect GitHub" />
    </Frame>

    Clicking through opens GitHub in a new tab. Sign in, then install the Dodo Payments GitHub App on the organization or user account that owns the repository. You can grant access to **all repositories** or only the ones you intend to gate.

    <Frame>
      <img alt="GitHub Install and Authorize page with All repositories and Only select repositories options" />
    </Frame>

    When GitHub redirects back, you'll see a confirmation that the account is connected.

    <Frame>
      <img alt="GitHub Access connected successfully confirmation page" />
    </Frame>
  </Step>

  <Step title="Pick a repository and permission">
    Back in the dashboard, choose the **repository** the entitlement should grant access to and pick the **permission** level. The repository picker only shows repositories the GitHub App has access to. Give the entitlement a **name** and click **Create Entitlement**.

    <Frame>
      <img alt="GitHub entitlement form with connected GitHub Access, repository selector, permission dropdown, and name field" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Save and attach the entitlement to any product. Customers who buy that product receive a GitHub invite on delivery.
  </Step>
</Steps>

## Permission levels

GitHub's standard repository permissions apply:

| Permission | Best for                                                                       |
| ---------- | ------------------------------------------------------------------------------ |
| `pull`     | Read-only access. Customers can clone, fetch, and view the repo.               |
| `triage`   | Read access plus the ability to manage issues and pull requests.               |
| `push`     | Read + write access. Customers can push branches and open pull requests.       |
| `maintain` | Push access plus management of repository settings (excluding sensitive ones). |
| `admin`    | Full control of the repository. Use with caution.                              |

<Warning>
  Grant the **least privilege** that fits your use case. Most paid-content scenarios only need `pull`.
</Warning>

## Customer flow

1. The customer completes checkout.
2. Dodo Payments creates a grant in `Pending` status with an `oauth_url` for the customer to link their GitHub account.
3. The customer authorizes through the link in their email or customer portal.
4. Dodo Payments invites the customer's GitHub account to the repository at the configured permission. The grant moves to `Delivered` once the invitation is created.
5. If the subscription is cancelled, refunded, or revoked, the customer is removed as a collaborator.

## Required configuration

| Field        | Required | Description                                                                                        |
| ------------ | -------- | -------------------------------------------------------------------------------------------------- |
| `target_id`  | Yes      | The repository to invite the customer to. The dashboard's repository picker fills this in for you. |
| `permission` | Yes      | One of `pull`, `push`, `triage`, `maintain`, `admin`.                                              |

## Create via API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const entitlement = await client.entitlements.create({
    name: 'Code Share Repository',
    integration_type: 'github',
    integration_config: {
      target_id: 'acme/private-sdk',
      permission: 'pull',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Code Share Repository",
      integration_type="github",
      integration_config={
          "target_id": "acme/private-sdk",
          "permission": "pull",
      },
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Code Share Repository"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeGithub),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigGitHubConfigParam{
        TargetID:   dodopayments.F("acme/private-sdk"),
        Permission: dodopayments.F("pull"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

The standard [`entitlement_grant.*` webhook events](/developer-resources/webhooks/intents/entitlement-grant) cover the GitHub flow:

* `entitlement_grant.created` includes the `oauth_url` for GitHub authorization.
* `entitlement_grant.delivered` fires once the collaborator invitation is created.
* `entitlement_grant.failed` fires with `error_code: "github_permission_denied"` (or similar) if the GitHub App lost access to the repository.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Repository picker is empty">
    The Dodo Payments GitHub App must be installed on the org or user that owns the repository. Open **Entitlements → Integrations → GitHub** and reinstall the app, making sure to grant access to the relevant repositories.
  </Accordion>

  <Accordion title="Grant fails with permission_denied">
    The GitHub App's installation no longer has access to the repository, or the repository was renamed/transferred. Re-grant access to the app and the next regrant will succeed.
  </Accordion>

  <Accordion title="Customer hasn't accepted the invite">
    Customers must accept the GitHub invitation from their notifications page or by clicking the link in their email. Until they accept, they remain "invited" but cannot clone the repo. The grant is still `Delivered` from Dodo Payments' perspective; the invitation is what we issue.
  </Accordion>
</AccordionGroup>


# Introduction
Source: https://docs.dodopayments.com/features/entitlements/introduction

Automatically deliver license keys, downloadable files, feature flags, and access to platforms like Discord, GitHub, Telegram, Framer, and Notion when customers pay.

<Info>
  Entitlements turn a successful payment or active subscription into real access: a license key in your customer's inbox, a feature flag your app checks, a Discord role, a GitHub repository, a Notion template, a Framer remix link, a Telegram chat invite, or a downloadable file bundle. Dodo Payments issues, tracks, and revokes that access automatically as the payment lifecycle changes.
</Info>

<Frame>
  <img alt="Entitlements dashboard with a list of entitlements on the left and grant activity on the right" />
</Frame>

## What are Entitlements?

An **entitlement** is a reusable definition of something you deliver to a customer: a Pro license key, a "Patrons" Discord role, access to your private GitHub repository, a downloadable e-book bundle. You attach entitlements to products, and Dodo Payments handles the rest.

When a customer purchases the product, Dodo Payments creates a **grant**, a single customer's issuance of that entitlement. Grants move through a small set of statuses: `Pending` while delivery is in progress, `Delivered` once the customer has access, `Failed` if delivery could not complete, and `Revoked` when access is withdrawn.

<Tip>
  Entitlements gate **fulfillment** (does the customer have access?). Credits gate **consumption** (how much of it can they use?). Both can be attached to the same product. See [Credit-Based Billing](/features/credit-based-billing) for credits.
</Tip>

## Available Integrations

Dodo Payments delivers each entitlement through a dedicated integration. Pick the integration that matches what you sell.

<CardGroup>
  <Card title="License Keys" icon="key" href="/features/license-keys">
    Generate unique license keys with activation limits and expiry. Best for software, plugins, and CLIs.
  </Card>

  <Card title="Digital Files" icon="download" href="/features/digital-product-delivery">
    Deliver downloadable files (e-books, templates, media) with presigned download URLs and optional instructions.
  </Card>

  <Card title="Feature Flags" icon="flag" href="/features/entitlements/feature-flags">
    Gate features in your own app off a purchase. Delivered instantly, checked via API, revoked on cancellation.
  </Card>

  <Card title="Discord" icon="discord" href="/features/entitlements/discord">
    Grant a customer a role in your Discord server when they purchase. Revoke automatically on cancellation.
  </Card>

  <Card title="GitHub" icon="github" href="/features/entitlements/github">
    Add customers as collaborators to a private repository at the permission level you choose.
  </Card>

  <Card title="Telegram" icon="telegram" href="/features/entitlements/telegram">
    Add customers to a private Telegram chat or channel after purchase.
  </Card>

  <Card title="Framer" icon="puzzle-piece" href="/features/entitlements/framer">
    Unlock a Framer template remix link for paying customers.
  </Card>

  <Card title="Notion" icon="book" href="/features/entitlements/notion">
    Duplicate a Notion template into the customer's workspace on purchase.
  </Card>
</CardGroup>

***

## How Grants Work

Grants are driven by the same payment and subscription events you already receive as webhooks. You don't need to call the grant API yourself for purchases. Dodo Payments creates and revokes grants automatically based on the underlying payment lifecycle.

### Grant Lifecycle

<Steps>
  <Step title="Created">
    A grant is created when a payment completes or a subscription becomes active. Feature flags jump straight to `Delivered`. License keys also jump straight to `Delivered` when the entitlement uses `fulfillment_mode: auto` (the default); under `fulfillment_mode: manual` the grant is created in `Pending` with no key until you supply one via [Fulfill License Key Grant](/api-reference/entitlements/fulfill-license-key). Every other integration starts in `Pending`. OAuth-based integrations (Discord, GitHub, Notion) include an `oauth_url` the customer must visit to complete consent. Platform-direct integrations (Telegram, Framer, Digital Files) sit in `Pending` only briefly while delivery is provisioned, then transition to `Delivered`.
  </Step>

  <Step title="Delivered">
    Once delivery completes (license key generated, role assigned, repository access granted, file links resolved, OAuth completed), the grant moves to `Delivered` and `delivered_at` is set.
  </Step>

  <Step title="Failed">
    If the integration call returns a non-retryable error (revoked OAuth token, denied permission, file no longer exists), the grant moves to `Failed`. The `error_code` and `error_message` fields capture the reason.
  </Step>

  <Step title="Revoked">
    When access is withdrawn (subscription cancelled, refund issued, or merchant-initiated revoke), the grant moves to `Revoked`. The `revocation_reason` field records the trigger.
  </Step>
</Steps>

### Grant Behavior by Event

| Event                                             | Behavior                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (one-time payment)            | Issue one grant per attached entitlement.                                                                                                                                                                                                                                                                                                                |
| `payment.succeeded` (subscription-linked payment) | No-op. Grants are driven by the subscription event below.                                                                                                                                                                                                                                                                                                |
| `subscription.active`                             | Issue grants for any attached entitlements that don't already have one. Re-grant any grants previously revoked for the same subscription.                                                                                                                                                                                                                |
| `subscription.renewed`                            | No-op. Existing grants persist across renewals.                                                                                                                                                                                                                                                                                                          |
| `subscription.on_hold`                            | Revoke all delivered and pending grants. `revocation_reason: subscription_on_hold`.                                                                                                                                                                                                                                                                      |
| `subscription.cancelled`                          | Revoke all. `revocation_reason: subscription_cancelled`.                                                                                                                                                                                                                                                                                                 |
| `subscription.expired`                            | Revoke all. `revocation_reason: subscription_expired`.                                                                                                                                                                                                                                                                                                   |
| `subscription.plan_changed`                       | Revoke all current grants, then issue grants for the new plan's entitlements. `revocation_reason: plan_changed`.                                                                                                                                                                                                                                         |
| `refund.succeeded` (one-time payment)             | Revoke grants for that payment. `revocation_reason: refund`.                                                                                                                                                                                                                                                                                             |
| Manual API revoke                                 | Revoke with `revocation_reason: manual`. Manual revokes are not auto-regranted on subscription renewal.                                                                                                                                                                                                                                                  |
| License key disabled                              | For license-key grants, disabling the underlying key revokes the grant with `revocation_reason: license_key_disabled`. The grant is re-activated automatically if the key is re-enabled.                                                                                                                                                                 |
| Platform drift detected                           | If the platform side of an integration drifts out of sync (a Discord role removed manually, the GitHub App losing repository access, or a reconciliation pass detecting a missing target), the grant is revoked with `revocation_reason: platform_external`. Not auto-regranted on subscription renewal until the underlying platform issue is resolved. |

<Note>
  Subscription-driven grants are idempotent per `(entitlement, customer, subscription)`; renewals and re-activations do not create duplicate grants. One-time grants are idempotent per `(entitlement, customer, payment)`.
</Note>

***

## Create your first entitlement

<Steps>
  <Step title="Open Entitlements">
    Go to **Entitlements** in your Dodo Payments dashboard and click **+** to create a new entitlement.
  </Step>

  <Step title="Pick an integration">
    Choose the integration type: License Key, Digital Files, Feature Flag, Discord, GitHub, Telegram, Figma, Framer, or Notion. For platform integrations, connect your account first if you haven't already.
  </Step>

  <Step title="Configure delivery">
    Fill in the integration-specific fields. For example, GitHub asks for a repository and a permission level; Discord asks for a server and an optional role; License Key asks for activation limits and expiry.

    <Frame>
      <img alt="New Entitlement form with integration selector and configuration fields" />
    </Frame>
  </Step>

  <Step title="Save">
    Save the entitlement. You can now attach it to any product.
  </Step>
</Steps>

## Attach Entitlements to Products

Open a product, expand **Advanced Settings → Entitlements & Credits**, and select the entitlements that should be delivered when the product is purchased. A single product can deliver multiple entitlements at once. For example, a Pro plan can include a license key, GitHub access, and a Discord role.

<Frame>
  <img alt="Product entitlement selection panel showing checkboxes for each available entitlement" />
</Frame>

***

## Customer Experience

### Email and customer portal

Customers receive a delivery email after purchase containing the license key, download links, OAuth invitation links, or platform invite, whichever applies to the entitlements on the product. The same details remain available indefinitely from the [Customer Portal](/features/customer-portal) under their order history.

### OAuth-based delivery

Discord, GitHub, and Notion subscriber access require the customer to authorize Dodo Payments to grant them access. These grants stay in `Pending` status until the customer completes the OAuth flow using the link from their email or customer portal. Once they authorize, the grant moves to `Delivered` and the platform access is provisioned immediately.

### Revocation

Revoked grants are removed at the platform level: the Discord role is removed, the GitHub collaborator is removed, the license key is disabled. Customers see the change reflected in the customer portal.

<Warning>
  For Digital Files, revocation removes access to the presigned URLs going forward but does not invalidate copies a customer has already downloaded. Plan content gating accordingly.
</Warning>

***

## Manage Grants

Open any entitlement from the dashboard to see its grants. The grant detail panel shows total grants, status filters, customer information, delivery dates, and a revoke action.

You can also manage grants programmatically:

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  });

  // List grants for an entitlement
  const grants = await client.entitlements.grants.list('ent_abc123', {
    status: 'Delivered',
  });

  // Revoke a single grant
  await client.entitlements.grants.revoke('grant_xyz789', {
    id: 'ent_abc123',
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.grants.list(
      "ent_abc123",
      status="Delivered",
  )

  client.entitlements.grants.revoke(
      "grant_xyz789",
      id="ent_abc123",
  )
  ```

  ```go Go theme={null} theme={null}
  grants, _ := client.Entitlements.Grants.List(
    ctx, "ent_abc123",
    dodopayments.EntitlementGrantListParams{Status: dodopayments.F("Delivered")},
  )

  _, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")
  ```
</CodeGroup>

***

## API Management

<CardGroup>
  <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
    Create a new entitlement of any integration type.
  </Card>

  <Card title="List Entitlements" icon="list" href="/api-reference/entitlements/list-entitlements">
    List entitlements with filtering by integration type.
  </Card>

  <Card title="Get Entitlement" icon="magnifying-glass" href="/api-reference/entitlements/get-entitlement">
    Retrieve an entitlement and its resolved configuration.
  </Card>

  <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
    Update name, description, or integration configuration.
  </Card>

  <Card title="Delete Entitlement" icon="trash" href="/api-reference/entitlements/delete-entitlement">
    Soft-delete an entitlement; existing grants are unaffected.
  </Card>

  <Card title="Upload File" icon="upload" href="/api-reference/entitlements/upload-file">
    Upload a file to a Digital Files entitlement (up to 500 MiB).
  </Card>

  <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
    List all grants for an entitlement with status and customer filters.
  </Card>

  <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
    Manually revoke a single grant.
  </Card>
</CardGroup>

***

## Webhooks

Dodo Payments fires four webhook events for the grant lifecycle. Subscribe to these events to keep your application in sync with what each customer can access.

| Event                         | Fires when                                                                                                                                                                                                                                                                                                  |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entitlement_grant.created`   | A new grant is created. License-key grants arrive `Delivered` under `auto` fulfillment and `Pending` under `manual` fulfillment; every other integration arrives `Pending` and transitions to `Delivered` once the platform call succeeds (or, for OAuth-based integrations, once the customer authorizes). |
| `entitlement_grant.delivered` | The grant transitions to delivered. The customer now has access.                                                                                                                                                                                                                                            |
| `entitlement_grant.failed`    | The grant could not be delivered. Inspect `error_code` and `error_message`.                                                                                                                                                                                                                                 |
| `entitlement_grant.revoked`   | Access has been withdrawn. Inspect `revocation_reason`.                                                                                                                                                                                                                                                     |

<Card title="Entitlement Grant Webhook Payloads" icon="bell" href="/developer-resources/webhooks/intents/entitlement-grant">
  View the full payload schema, sample events, and `revocation_reason` reference.
</Card>

***

## Best Practices

* **Use one entitlement per delivery channel.** Don't share a single Discord entitlement across products with different role intentions; create one per role for clean revocation.
* **Test in test mode first.** Create the entitlement, attach it to a test product, run a checkout, and watch the grant transition through `pending → delivered`. Confirm that cancelling the test subscription revokes the grant.
* **Listen to `entitlement_grant.delivered`, not `payment.succeeded`.** A payment can succeed before fulfilment finishes (especially for OAuth flows). Wait for the delivered event before unlocking dependent features in your own systems.
* **Treat `entitlement_grant.failed` as actionable.** A failed grant means a customer paid but didn't get access. Surface these to your support team or trigger a regrant.
* **Map `revocation_reason` to your retention flows.** A `subscription_on_hold` revoke is recoverable (the customer may update their card). A `manual` revoke is intentional. Treat them differently in customer comms.


# Notion Entitlement
Source: https://docs.dodopayments.com/features/entitlements/notion

Duplicate a Notion template into the customer's workspace when they purchase.

<Info>
  The Notion entitlement duplicates a template you've prepared into the paying customer's Notion workspace. The customer authorizes through OAuth, picks the workspace they want the template copied into, and Dodo Payments handles the duplication.
</Info>

## What gets delivered

* The customer is prompted to connect their Notion workspace via OAuth.
* Once authorized, Dodo Payments duplicates the configured template into the workspace they chose.
* On cancellation, the duplicated template remains in the customer's workspace (Notion does not support remote deletion). The grant is marked `Revoked` for record-keeping.

Common uses include paid Notion templates, productivity systems, and OS/CRM templates.

## Connect Notion

<Steps>
  <Step title="Open Entitlements">
    In your Dodo Payments dashboard, go to **Entitlements** and click **+**.
  </Step>

  <Step title="Pick Notion">
    Choose **Notion Template** as the integration. If Notion is not yet connected, you'll be prompted to **Connect Notion**.

    <Frame>
      <img alt="New entitlement panel prompting the merchant to connect Notion" />
    </Frame>

    Clicking through opens Notion in a new tab. Sign in to the workspace that owns your source templates, review the permissions Dodo Payments requests, then pick the pages (templates) the integration is allowed to read and duplicate.

    <Frame>
      <div>
        <img alt="Notion OAuth permissions screen for Dodo Payments" />

        <img alt="Notion page picker selecting which templates Dodo Payments can access" />
      </div>
    </Frame>

    When Notion redirects back, you'll see a confirmation that the workspace is connected.

    <Frame>
      <img alt="Notion Template connected successfully confirmation page" />
    </Frame>
  </Step>

  <Step title="Pick a template">
    Back in the dashboard, select the **template** to duplicate from the template picker. Only pages you authorized in the previous step appear here. Give the entitlement a **name** and click **Create Entitlement**.

    <Frame>
      <img alt="Notion entitlement form with connected workspace, template picker, and name field" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Save and attach to any product.
  </Step>
</Steps>

## Customer flow

1. The customer completes checkout.
2. Dodo Payments creates a grant in `Pending` status with a Notion `oauth_url` for the customer to connect their workspace.
3. The customer authorizes via the link in their email or customer portal and picks the workspace they want the template duplicated into.
4. Dodo Payments duplicates the template. The grant moves to `Delivered`.
5. On revocation, the grant is marked `Revoked`; the duplicated copy remains in the customer's workspace.

<Note>
  Notion intentionally treats a duplicated page as the recipient's own content. Dodo Payments cannot delete the copy on revocation.
</Note>

## Required configuration

| Field                | Required | Description                                          |
| -------------------- | -------- | ---------------------------------------------------- |
| `notion_template_id` | Yes      | The template ID. The dashboard picker fills this in. |

## Create via API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const entitlement = await client.entitlements.create({
    name: 'Study Notes',
    integration_type: 'notion',
    integration_config: {
      notion_template_id: 'tmpl_abc123',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Study Notes",
      integration_type="notion",
      integration_config={"notion_template_id": "tmpl_abc123"},
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Study Notes"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeNotion),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigNotionConfigParam{
        NotionTemplateID: dodopayments.F("tmpl_abc123"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

See [`entitlement_grant.*` webhook events](/developer-resources/webhooks/intents/entitlement-grant):

* `entitlement_grant.created` includes the Notion `oauth_url`.
* `entitlement_grant.delivered` fires once the template is duplicated.
* `entitlement_grant.revoked` fires on cancellation; the customer's copy is left untouched.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Customer didn't get the template">
    The grant remains `Pending` until the customer completes Notion OAuth. Resend the delivery email; the OAuth link expires after one week, after which you can revoke and recreate the grant.
  </Accordion>

  <Accordion title="Template picker is empty">
    Reconnect Notion from **Entitlements → Integrations → Notion** with the workspace that owns the source templates.
  </Accordion>

  <Accordion title="Customer wants the template removed after refund">
    Notion does not allow remote deletion of duplicated pages. The customer must delete the copy from their own workspace.
  </Accordion>
</AccordionGroup>


# Telegram Entitlement
Source: https://docs.dodopayments.com/features/entitlements/telegram

Add paying customers to a private Telegram chat or channel automatically when they subscribe or purchase.

<Info>
  The Telegram entitlement gives paying customers access to a private chat or channel. The Dodo Payments Telegram bot generates a one-time invite link for each customer and removes them on cancellation.
</Info>

## What gets delivered

* The grant is created in `Pending` while the bot prepares the invite, then transitions to `Delivered` once the link is ready.
* The customer receives a one-time Telegram invite link in their delivery email and customer portal.
* They tap the link and the bot adds them to the configured chat.
* On cancellation, refund, or manual revoke, the bot removes them from the chat.

Common uses include private alpha channels, paid signal groups, and community-tier perks.

## Connect Telegram

<Steps>
  <Step title="Open Entitlements">
    In your Dodo Payments dashboard, go to **Entitlements** and click **+**, then choose **Telegram Access** as the integration. The dashboard asks for your Telegram user ID so the bot can verify ownership of the chats it manages.

    <Frame>
      <img alt="New Entitlement Telegram Access form prompting for Telegram user ID and Connect Telegram button" />
    </Frame>

    <Tip>
      The next two steps are set-up tasks on Telegram and can be completed in either order — get your user ID and add the bot to your chat as admin. Once both are done, return to the dashboard for the final step.
    </Tip>
  </Step>

  <Step title="Get your Telegram user ID">
    On Telegram, message **`/start`** to:

    * **`@dodo_payments_bot`** if you're using **Live Mode**
    * **`@DodoPaymentsTestBot`** if you're using **Test Mode**

    The bot replies with your numeric Telegram user ID. Copy it — you'll paste it into the dashboard in the last step.
  </Step>

  <Step title="Add the bot to your chat as an admin">
    In the Telegram group or channel you want to gate, open the members list and **add the same bot as admin** (`@dodo_payments_bot` for live, `@DodoPaymentsTestBot` for test) with these two permissions enabled:

    * **Ban Users** — required to remove members on revocation
    * **Add Users** — required to invite paying customers

    Leave every other admin permission off.

    <Frame>
      <img alt="Telegram Promote to admin screen showing Ban Users and Add Users enabled for the Dodo Payments bot" />
    </Frame>
  </Step>

  <Step title="Connect Telegram and pick the chat">
    Back in the dashboard, paste the user ID from step 2 into **Telegram User ID** and click **Connect Telegram**. The chat picker now lists every group and channel where the bot is an admin — pick the one you want to gate, give the entitlement a name, and click **Create Entitlement**.
  </Step>
</Steps>

## Customer flow

1. The customer completes checkout.
2. Dodo Payments creates a `Pending` grant and asks the bot to generate a one-time invite link to the configured chat.
3. Once the link is ready, the grant moves to `Delivered` and the link is included in the delivery email and customer portal.
4. The customer taps the link and is added to the chat.
5. On revocation, the bot removes the customer from the chat.

<Tip>
  The invite link is single-use and expires after the customer joins. If they lose the link before joining, regenerate it by re-sending the delivery email or revoking and recreating the grant from the dashboard.
</Tip>

## Required configuration

| Field     | Required | Description                                                                                                     |
| --------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `chat_id` | Yes      | The Telegram chat ID (numeric, often negative for groups/channels). The dashboard picker fills this in for you. |

## Create via API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const entitlement = await client.entitlements.create({
    name: 'Premium Signals Group',
    integration_type: 'telegram',
    integration_config: {
      chat_id: '-1001234567890',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Premium Signals Group",
      integration_type="telegram",
      integration_config={"chat_id": "-1001234567890"},
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Premium Signals Group"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeTelegram),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigTelegramConfigParam{
        ChatID: dodopayments.F("-1001234567890"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

See [`entitlement_grant.*` webhook events](/developer-resources/webhooks/intents/entitlement-grant). Telegram grants arrive `Pending` and transition to `Delivered` once the bot has issued the invite link.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Chat doesn't appear in the picker">
    The Dodo Payments bot must be added to the chat **as an admin** with **Add Users** enabled. The picker reads live state, so the chat appears as soon as the bot is an admin.
  </Accordion>

  <Accordion title="Customer says the invite link doesn't work">
    Telegram one-time links expire after first use. If the customer tapped it on a logged-out device or lost the link, revoke the grant and reissue.
  </Accordion>

  <Accordion title="Customer cancelled but is still in the chat">
    The bot needs the **Ban Users** admin permission to remove members. Open the chat settings and confirm both **Ban Users** and **Add Users** are checked on the Dodo Payments bot.
  </Accordion>
</AccordionGroup>


# Hybrid Billing Models
Source: https://docs.dodopayments.com/features/hybrid-billing

Combine multiple billing modes to create sophisticated pricing strategies: subscription + usage, seats + add-ons, base + overage, and more.

<Info>
  Hybrid billing combines two or more billing models into a single pricing strategy. This lets you capture value from different dimensions—recurring fees, usage, seats, and features—while giving customers flexibility and predictability.
</Info>

<CardGroup>
  <Card title="Usage-Based Billing" icon="chart-line" href="/features/usage-based-billing/introduction">
    Foundation for consumption-based pricing.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Foundation for recurring billing.
  </Card>

  <Card title="Add-ons" icon="puzzle" href="/features/addons">
    Extend subscriptions with optional upgrades.
  </Card>

  <Card title="Seat-Based Billing" icon="users" href="/features/seat-based-billing">
    Per-user pricing models.
  </Card>
</CardGroup>

***

## What is Hybrid Billing?

Hybrid billing combines multiple pricing dimensions into a single product offering. Instead of choosing between flat-rate subscriptions OR usage-based pricing, you use both together.

### Why Use Hybrid Billing?

| Business Goal                       | Hybrid Solution                     |
| ----------------------------------- | ----------------------------------- |
| Predictable revenue + growth upside | Base subscription + usage overage   |
| Team pricing that scales            | Per-seat + feature add-ons          |
| Land customers, expand later        | Low base fee + consumption charges  |
| Enterprise flexibility              | Committed spend + on-demand charges |
| Fair pricing for variable usage     | Included allowance + pay-per-use    |

### Common Hybrid Patterns

| Model                                   | Description                                    | Example                                         | Native Support |
| --------------------------------------- | ---------------------------------------------- | ----------------------------------------------- | -------------- |
| **1. Subscription + Usage**             | Base fee + consumption charges                 | \$49/mo + \$0.01/API call after 10K free        | ✅ Full         |
| **2. Subscription + Seats**             | Platform fee + per-user charges                | \$99/mo + \$15/seat                             | ✅ Full         |
| **3. Subscription + Feature Add-ons**   | Core plan + optional upgrades                  | \$29/mo + \$19/mo analytics + \$9/mo API access | ✅ Full         |
| **4. Seats + Usage**                    | Per-user fee + consumption overage             | \$10/user/mo + \$0.05/GB after 5GB/user         | ⚠️ Workaround  |
| **5. Subscription + Seats + Usage**     | Platform + users + consumption (triple hybrid) | \$199/mo + \$20/seat + usage overage            | ⚠️ Workaround  |
| **6. Tiered Base + Usage Overage**      | Different tiers with different allowances      | Starter (5K calls) vs Pro (50K calls) + overage | ✅ Full         |
| **7. Subscription + On-Demand Charges** | Recurring fee + variable manual charges        | \$99/mo retainer + hourly billing for work      | ✅ Full         |

***

## Hybrid Model 1: Subscription + Usage

The most common hybrid model. Customers pay a base subscription fee plus charges for consumption that exceeds included allowances.

### How It Works

**Pro Plan: \$49/month**

* **Included**: 10,000 API calls/month
* **Overage**: \$0.005 per call after 10,000

**Example calculation** (customer uses 25,000 calls this month):

* Base subscription: \$49.00
* Overage: (25,000 - 10,000) × $0.005 = $75.00
* **Total: \$124.00**

### Use Cases

* **API platforms**: Base access + per-request charges
* **AI/ML services**: Subscription + token/generation usage
* **Storage services**: Base plan + per-GB overage
* **Communication platforms**: Base + per-message/minute charges

### Implementation

<Steps>
  <Step title="Create Usage Meter">
    Set up a meter to track the billable usage dimension.

    ```bash theme={null}
    Dashboard: Meters → Create Meter
    Event Name: "api.call"
    Aggregation: Count
    This tracks API calls per customer
    ```
  </Step>

  <Step title="Create Subscription Product with Usage Pricing">
    Create a subscription product and attach the usage meter with pricing.

    ```bash theme={null}
    Dashboard: Create Product → Subscription
    Name: "Pro Plan"
    Base Price: $49/month

    Then attach usage pricing:
    - Meter: api.call
    - Price per unit: $0.005
    - Free threshold: 10,000 (included in subscription)
    ```

    <Info>
      The usage meter is attached directly to the subscription product. Usage charges are calculated and added to the subscription invoice automatically.
    </Info>
  </Step>

  <Step title="Create Checkout Session">
    Create a checkout session with your subscription product.

    ```typescript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_pro_plan', quantity: 1 }
      ],
      customer: { email: 'customer@example.com' },
      return_url: 'https://yourapp.com/success'
    });
    ```
  </Step>

  <Step title="Send Usage Events">
    Track usage throughout the billing period.

    ```typescript theme={null}
    await fetch('https://test.dodopayments.com/events/ingest', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        events: [{
          event_id: `call_${Date.now()}`,
          customer_id: 'cus_123',
          event_name: 'api.call',
          timestamp: new Date().toISOString(),
          metadata: { endpoint: '/v1/generate' }
        }]
      })
    });
    ```
  </Step>
</Steps>

### Pricing Variations

<Tabs>
  <Tab title="Included Allowance">
    Free threshold covers usage included in base subscription.

    **Pro Plan: \$49/month**

    * Includes: 10,000 API calls
    * Overage: \$0.005/call after 10,000
    * Customer uses 8,000 → Pays \$49 (no overage)
  </Tab>

  <Tab title="Zero Base + Pure Usage">
    No base fee, every unit is billable from the first use.

    **Pay-As-You-Go: \$0/month base**

    * Includes: 0 API calls
    * Usage: \$0.01/call from first call
    * Customer uses 5,000 → Pays \$50
  </Tab>

  <Tab title="Tiered Allowances">
    Different tiers include different allowances.

    * **Starter**: \$19/month (1,000 calls included)
    * **Pro**: \$49/month (10,000 calls included)
    * **Enterprise**: \$199/month (100,000 calls included)
    * All tiers: \$0.005/call overage
  </Tab>
</Tabs>

***

## Hybrid Model 2: Subscription + Seats

Platform fee plus per-user charges. Ideal for team collaboration tools and B2B SaaS.

### How It Works

**Team Plan: $99/month + $15/seat**

* **Base platform fee**: \$99/month (includes 3 seats)
* **Additional seats**: \$15/seat/month

**Example calculation** (team of 12 users):

* Platform fee: \$99.00
* Extra seats: (12 - 3) × $15 = $135.00
* **Total: \$234.00/month**

### Use Cases

* **Collaboration tools**: Workspace fee + per-member
* **CRM systems**: Platform license + per-sales-rep
* **Project management**: Team plan + per-contributor
* **Developer tools**: Organization fee + per-developer

### Implementation

<Steps>
  <Step title="Create Seat Add-on">
    Create an add-on for additional seats.

    ```bash theme={null}
    Dashboard: Products → Add-ons → Create Add-on
    Name: "Additional Seat"
    Price: $15/month
    Description: "Add another team member"
    ```
  </Step>

  <Step title="Create Base Subscription">
    Create the subscription product with platform fee and attach the add-on.

    ```bash theme={null}
    Dashboard: Create Product → Subscription
    Name: "Team Plan"
    Price: $99/month
    Description: "Includes 3 team members"

    Then in Add-ons section:
    - Attach: "Additional Seat" add-on
    ```
  </Step>

  <Step title="Create Checkout with Seats">
    Specify seat quantity during checkout.

    ```typescript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [{
        product_id: 'pdt_team_plan',
        quantity: 1,
        addons: [{
          addon_id: 'addon_seat',
          quantity: 9  // 9 extra seats (12 total with 3 included)
        }]
      }],
      customer: { email: 'admin@company.com' },
      return_url: 'https://yourapp.com/success'
    });
    ```
  </Step>

  <Step title="Adjust Seats as Needed">
    Add or remove seats on existing subscriptions.

    ```typescript theme={null}
    // Add 5 more seats
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_team_plan',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately',
      addons: [{
        addon_id: 'addon_seat',
        quantity: 14  // New total: 14 extra seats
      }]
    });
    ```
  </Step>
</Steps>

### Pricing Variations

<Tabs>
  <Tab title="Included Seats">
    Base plan includes some seats, charge for extras.

    **Team Plan: \$99/month**

    * Includes: 5 seats
    * Extra seats: \$15/seat/month
    * 20 users = \$99 + (15 × \$15) = \$324/month
  </Tab>

  <Tab title="Pure Per-Seat">
    No platform fee, only per-user charges.

    **Per User: \$25/user/month**

    * No platform fee
    * 5 users = \$125/month
    * 50 users = \$1,250/month

    Implementation: Set base subscription price to \$0, use seat add-on only.
  </Tab>

  <Tab title="Tiered Per-Seat">
    Per-seat price decreases at higher tiers.

    * **Starter**: \$20/seat (1-10 seats)
    * **Growth**: \$15/seat (11-50 seats)
    * **Enterprise**: \$10/seat (51+ seats)

    Implementation: Create separate subscription products for each tier with different add-on prices.
  </Tab>
</Tabs>

***

## Hybrid Model 3: Subscription + Feature Add-ons

Core subscription with optional feature upgrades customers can add.

### How It Works

**Core Plan: \$29/month**

**Optional Add-ons:**

* Advanced Analytics: +\$19/month
* API Access: +\$9/month
* Priority Support: +\$29/month
* White-label: +\$49/month

**Example calculation** (customer chooses Core + Analytics + API Access):

* Core plan: \$29.00
* Analytics: \$19.00
* API Access: \$9.00
* **Total: \$57.00/month**

### Use Cases

* **SaaS platforms**: Core features + premium modules
* **Marketing tools**: Base tool + integrations
* **Analytics products**: Dashboard + advanced reports
* **Security software**: Basic protection + advanced features

### Implementation

<Steps>
  <Step title="Create Feature Add-ons">
    Create an add-on for each optional feature.

    ```bash theme={null}
    # Add-on 1: Advanced Analytics
    Dashboard: Products → Add-ons → Create Add-on
    Name: "Advanced Analytics"
    Price: $19/month

    # Add-on 2: API Access
    Name: "API Access"
    Price: $9/month

    # Add-on 3: Priority Support
    Name: "Priority Support"
    Price: $29/month

    # Add-on 4: White-label
    Name: "White-label"
    Price: $49/month
    ```
  </Step>

  <Step title="Create Core Subscription">
    Define your base subscription and attach all feature add-ons.

    ```bash theme={null}
    Dashboard: Create Product → Subscription
    Name: "Core Plan"
    Price: $29/month

    Then in Add-ons section:
    - Attach all feature add-ons
    ```
  </Step>

  <Step title="Let Customers Choose">
    Checkout with selected features.

    ```typescript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [{
        product_id: 'pdt_core_plan',
        quantity: 1,
        addons: [
          { addon_id: 'addon_analytics', quantity: 1 },
          { addon_id: 'addon_api_access', quantity: 1 }
          // Customer didn't select support or white-label
        ]
      }],
      return_url: 'https://yourapp.com/success'
    });
    ```
  </Step>

  <Step title="Add Features Later">
    Customers can add features to existing subscriptions.

    ```typescript theme={null}
    // Customer wants to add Priority Support
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_core_plan',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately',
      addons: [
        { addon_id: 'addon_analytics', quantity: 1 },
        { addon_id: 'addon_api_access', quantity: 1 },
        { addon_id: 'addon_priority_support', quantity: 1 }  // New!
      ]
    });
    ```
  </Step>
</Steps>

***

## Hybrid Model 4: Seats + Usage

Per-user fee combined with consumption-based charges. Each user gets an allowance.

<Warning>
  **Constraint**: Dodo Payments does not currently support attaching both usage meters and add-ons to the same subscription product. This model requires a workaround using application-level logic.
</Warning>

### How It Works

**Team Analytics: \$20/user/month**

**Each user includes:**

* 5 GB data processing/month
* Overage: \$2/GB after allowance

**Example calculation** (10-user team using 80 GB total):

* Seat fees: 10 × $20 = $200.00
* Included data: 10 × 5 GB = 50 GB
* Overage: (80 - 50) × $2 = $60.00
* **Total: \$260.00/month**

### Use Cases

* **Analytics platforms**: Per-analyst + data processing
* **Design tools**: Per-designer + storage/exports
* **Development environments**: Per-developer + compute hours
* **Communication tools**: Per-user + message/call volume

### Implementation Options

Since you cannot attach both usage meters and add-ons to the same subscription, choose one of these approaches:

<Tabs>
  <Tab title="Option A: Usage Product + App-Managed Seats">
    Use a usage-based subscription and manage seat billing in your application.

    <Steps>
      <Step title="Create Usage Meter">
        ```bash theme={null}
        Dashboard: Meters → Create Meter
        Event Name: "data.processed"
        Aggregation: Sum
        Property: "bytes"
        ```
      </Step>

      <Step title="Create Usage-Based Subscription">
        ```bash theme={null}
        Dashboard: Create Product → Subscription
        Name: "Team Analytics"
        Base Price: $0/month

        Attach usage pricing:
        - Meter: data.processed
        - Price per unit: $2/GB
        - Free threshold: 0 (managed by your app)
        ```
      </Step>

      <Step title="Manage Seats in Your Application">
        Track seat count and calculate seat fees separately.

        ```typescript theme={null}
        // Your application tracks seats and calculates total cost
        async function calculateMonthlyBill(customerId: string) {
          const seatCount = await getSeatCount(customerId);
          const seatFee = seatCount * 20; // $20/seat

          // Usage is billed by Dodo automatically
          // You invoice/charge seat fees separately or include in base price

          // Alternatively, adjust base subscription price when seats change
          const totalBasePrice = seatCount * 2000; // $20/seat in cents
          await client.subscriptions.update('sub_123', {
            // Update subscription to reflect seat-based pricing
          });
        }
        ```
      </Step>

      <Step title="Calculate Dynamic Free Threshold">
        Adjust included usage based on seat count.

        ```typescript theme={null}
        // When checking usage, apply per-seat allowance
        async function checkUsageOverage(customerId: string) {
          const seatCount = await getSeatCount(customerId);
          const includedGB = seatCount * 5; // 5 GB per user

          const currentUsage = await getUsageFromDodo(customerId);
          const overage = Math.max(0, currentUsage - includedGB);

          // Overage is billed by Dodo at $2/GB
          return { included: includedGB, used: currentUsage, overage };
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Option B: Seat Add-on + On-Demand Usage Charges">
    Use add-ons for seats and charge usage manually via on-demand charges.

    <Steps>
      <Step title="Create Seat Add-on">
        ```bash theme={null}
        Dashboard: Products → Add-ons → Create Add-on
        Name: "Team Member"
        Price: $20/month
        ```
      </Step>

      <Step title="Create Subscription with Add-on">
        ```bash theme={null}
        Dashboard: Create Product → Subscription
        Name: "Team Analytics"
        Base Price: $0/month

        Attach add-on:
        - "Team Member" add-on

        Enable on-demand charging
        ```
      </Step>

      <Step title="Track Usage in Your Application">
        ```typescript theme={null}
        // Track usage events in your system
        async function trackDataProcessed(customerId: string, bytes: number) {
          await saveUsageEvent({
            customer_id: customerId,
            event_type: 'data.processed',
            bytes: bytes,
            timestamp: new Date()
          });
        }
        ```
      </Step>

      <Step title="Charge Usage at End of Cycle">
        Calculate and charge usage overages manually.

        ```typescript theme={null}
        async function billUsageOverage(subscriptionId: string) {
          const subscription = await getSubscription(subscriptionId);
          const seatCount = subscription.addons.find(a => a.id === 'addon_seat')?.quantity || 0;

          const includedGB = seatCount * 5;
          const usedGB = await calculatePeriodUsage(subscription.customer_id);
          const overageGB = Math.max(0, usedGB - includedGB);

          if (overageGB > 0) {
            const overageCharge = overageGB * 200; // $2/GB in cents
            await client.subscriptions.charge(subscriptionId, {
              product_price: overageCharge,
              product_description: `Data overage: ${overageGB} GB × $2/GB`
            });
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  **Recommendation**: Option B (Seat Add-on + On-Demand Usage) is often easier to implement because Dodo handles seat billing automatically. You only need to track and charge usage overages.
</Info>

***

## Hybrid Model 5: Subscription + Seats + Usage (Triple Hybrid)

The most comprehensive model: platform fee + per-user + consumption.

<Warning>
  **Constraint**: Dodo Payments does not currently support attaching both usage meters and add-ons to the same subscription product. This model requires a workaround approach.
</Warning>

### How It Works

**Enterprise Platform**

* **Platform Fee**: \$199/month
* **Per Seat**: \$25/user/month
* **Usage**: \$0.10/1000 API calls (50K included)

**Example calculation** (company with 20 users, 150,000 API calls):

* Platform: \$199.00
* Seats: 20 × $25 = $500.00
* Usage: (150K - 50K) × \$0.10/1K = \$10.00
* **Total: \$709.00/month**

### Use Cases

* **Enterprise SaaS**: Platform + team + consumption
* **Data platforms**: Workspace + analysts + queries
* **Integration platforms**: Hub + connectors + transactions
* **AI platforms**: Workspace + developers + inference

### Implementation Options

Choose one of these approaches to implement triple hybrid billing:

<Tabs>
  <Tab title="Option A: Base + Seats (Add-on) + On-Demand Usage">
    Use subscription with seat add-ons, charge usage manually via on-demand charges.

    **This is the recommended approach** because Dodo handles the platform fee and seat billing automatically.

    <Steps>
      <Step title="Create Seat Add-on">
        ```bash theme={null}
        Dashboard: Products → Add-ons → Create Add-on
        Name: "User Seat"
        Price: $25/month
        ```
      </Step>

      <Step title="Create Subscription Product">
        ```bash theme={null}
        Dashboard: Create Product → Subscription
        Name: "Enterprise Platform"
        Base Price: $199/month

        Attach add-on:
        - "User Seat" add-on

        Enable on-demand charging
        ```
      </Step>

      <Step title="Create Checkout with Seats">
        ```typescript theme={null}
        const session = await client.checkoutSessions.create({
          product_cart: [{
            product_id: 'pdt_enterprise_platform',
            quantity: 1,
            addons: [{
              addon_id: 'addon_user_seat',
              quantity: 20  // 20 users
            }]
          }],
          customer: { email: 'enterprise@company.com' },
          return_url: 'https://yourapp.com/success'
        });
        ```
      </Step>

      <Step title="Track Usage in Your Application">
        Store usage events in your system.

        ```typescript theme={null}
        // Track API calls in your system
        async function trackApiCall(customerId: string, endpoint: string) {
          await saveUsageEvent({
            customer_id: customerId,
            event_type: 'api.call',
            endpoint: endpoint,
            timestamp: new Date()
          });
        }
        ```
      </Step>

      <Step title="Charge Usage at End of Cycle">
        Calculate and charge usage overages via on-demand charge.

        ```typescript theme={null}
        async function billUsageOverage(subscriptionId: string) {
          const usage = await calculatePeriodUsage(subscriptionId);
          const includedCalls = 50000;
          const overageCalls = Math.max(0, usage.totalCalls - includedCalls);

          if (overageCalls > 0) {
            // $0.10 per 1000 calls = $0.0001 per call
            const overageCharge = Math.ceil(overageCalls / 1000) * 10; // cents
            await client.subscriptions.charge(subscriptionId, {
              product_price: overageCharge,
              product_description: `API usage: ${overageCalls.toLocaleString()} calls over 50K included`
            });
          }
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Option B: Base + Usage (Meter) + App-Managed Seats">
    Use subscription with usage meter, manage seat billing in your application.

    <Steps>
      <Step title="Create Usage Meter">
        ```bash theme={null}
        Dashboard: Meters → Create Meter
        Event Name: "api.call"
        Aggregation: Count
        ```
      </Step>

      <Step title="Create Subscription Product with Usage">
        ```bash theme={null}
        Dashboard: Create Product → Subscription
        Name: "Enterprise Platform"
        Base Price: $199/month

        Attach usage pricing:
        - Meter: api.call
        - Price: $0.10 per 1000 calls
        - Free threshold: 50,000
        ```
      </Step>

      <Step title="Manage Seats in Your Application">
        Track seat count and adjust base subscription price accordingly.

        ```typescript theme={null}
        // When seats change, update subscription price
        async function updateSeatCount(subscriptionId: string, newSeatCount: number) {
          const basePlatformFee = 19900; // $199 in cents
          const perSeatFee = 2500; // $25 in cents
          const totalPrice = basePlatformFee + (newSeatCount * perSeatFee);

          // Store seat count in your system
          await updateSeatsInDatabase(subscriptionId, newSeatCount);

          // Note: You may need to handle this via plan changes or
          // create multiple tier products for common seat counts
        }
        ```
      </Step>

      <Step title="Send Usage Events to Dodo">
        ```typescript theme={null}
        await fetch('https://test.dodopayments.com/events/ingest', {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            events: [{
              event_id: `api_${Date.now()}`,
              customer_id: 'cus_enterprise',
              event_name: 'api.call',
              timestamp: new Date().toISOString()
            }]
          })
        });
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  **Recommendation**: Option A (Base + Seats + On-Demand Usage) is generally easier because Dodo handles platform and seat billing automatically. You only need to track usage and submit charges at the end of each billing cycle.
</Info>

***

## Hybrid Model 6: Tiered Base + Usage Overage

Different subscription tiers with different included allowances and overage rates.

### How It Works

| Tier           | Price       | Included Calls | Overage Rate |
| -------------- | ----------- | -------------- | ------------ |
| **Starter**    | \$19/month  | 1,000          | \$0.02/call  |
| **Pro**        | \$79/month  | 25,000         | \$0.01/call  |
| **Business**   | \$199/month | 100,000        | \$0.005/call |
| **Enterprise** | \$499/month | 500,000        | \$0.002/call |

### Implementation

Create separate subscription products for each tier, each with its own usage configuration:

```bash theme={null}
# For each tier, create a subscription product:

# Starter Tier
Dashboard: Create Product → Subscription
Name: "Starter"
Base Price: $19/month
Usage Pricing:
- Meter: api.call
- Price: $0.02/call
- Free threshold: 1,000

# Pro Tier
Name: "Pro"
Base Price: $79/month
Usage Pricing:
- Meter: api.call
- Price: $0.01/call
- Free threshold: 25,000

# ... and so on for Business and Enterprise
```

### Upgrade Path

When customers upgrade tiers, they get:

* Higher included allowance
* Lower overage rates
* More value per dollar

```typescript theme={null}
// Customer upgrades from Starter to Pro
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});
```

***

## Hybrid Model 7: Subscription + On-Demand Charges

Recurring subscription plus variable manual charges for services or overages.

### How It Works

**Retainer Plan: \$199/month**

**Includes:**

* Platform access
* 5 hours consulting/month
* Email support

**On-Demand Charges (as needed):**

* Extra consulting: \$150/hour
* Custom development: \$200/hour
* Emergency support: \$100/incident

**Example calculation** (this month):

* Retainer: \$199.00
* 3 extra consulting hours: \$450.00
* 1 emergency support: \$100.00
* **Total: \$749.00**

### Use Cases

* **Consulting services**: Retainer + hourly billing
* **Managed services**: Base fee + incident charges
* **Agency services**: Monthly fee + project charges
* **Support plans**: SLA fee + per-ticket or per-hour

### Implementation

<Steps>
  <Step title="Create On-Demand Subscription">
    Set up subscription with on-demand charging enabled.

    ```typescript theme={null}
    const subscription = await client.subscriptions.create({
      billing: {
        city: 'San Francisco',
        country: 'US',
        state: 'CA',
        street: '123 Main St',
        zipcode: '94105'
      },
      customer: { customer_id: 'cus_123' },
      product_id: 'pdt_retainer',
      quantity: 1,
      payment_link: true,
      return_url: 'https://yourapp.com/success',
      on_demand: {
        mandate_only: false,
        product_price: 19900  // $199 initial charge
      }
    });
    ```
  </Step>

  <Step title="Charge for Services">
    Create charges when services are delivered.

    ```typescript theme={null}
    // Charge for 3 hours of consulting
    await client.subscriptions.charge('sub_123', {
      product_price: 45000,  // $450.00 (3 × $150)
      product_description: 'Consulting - 3 hours (March 15)'
    });

    // Charge for emergency support incident
    await client.subscriptions.charge('sub_123', {
      product_price: 10000,  // $100.00
      product_description: 'Emergency support - Server outage (March 18)'
    });
    ```
  </Step>

  <Step title="Track and Invoice">
    All charges appear on the customer's invoice.

    ```typescript theme={null}
    // Retrieve subscription charges
    const payments = await client.payments.list({
      subscription_id: 'sub_123'
    });

    // Show itemized breakdown to customer
    payments.items.forEach(payment => {
      console.log(`${payment.payment_id}: $${payment.total_amount / 100}`);
    });
    ```
  </Step>
</Steps>

***

## Real-World Examples

<Info>
  These examples show ideal pricing structures. Due to the constraint that usage meters and add-ons cannot be attached to the same product, some combinations require workarounds (using on-demand charges for usage or app-managed seats).
</Info>

### Example 1: AI SaaS Platform

**Pricing Structure:**

* **Base Subscription**: \$99/month (platform access, 5 seats included)
* **Seat Add-on**: \$20/seat/month
* **Feature Add-ons**: Custom Models (\$49/mo), API Access (\$29/mo), Priority Queue (\$19/mo)
* **Usage Overage**: \$0.02 per 1,000 tokens after 100K (charged via on-demand)

**Implementation**: Use subscription with seat and feature add-ons. Track token usage in your application and charge overages via on-demand charges at end of billing cycle.

**Example Customer** (12 users, 500K tokens, Custom Models + API Access):

| Component     | Calculation                  | Amount          |
| ------------- | ---------------------------- | --------------- |
| Base          | Platform fee                 | \$99            |
| Extra seats   | 7 × \$20                     | \$140           |
| Custom Models | Add-on                       | \$49            |
| API Access    | Add-on                       | \$29            |
| Token overage | 400K × \$0.02/1K (on-demand) | \$8             |
| **Total**     |                              | **\$325/month** |

### Example 2: Developer Tools Platform

**Tier Options:**

|             | Free      | Pro        | Enterprise  |
| ----------- | --------- | ---------- | ----------- |
| **Price**   | \$0/month | \$29/month | \$199/month |
| **Users**   | 1         | 5 included | Unlimited   |
| **Builds**  | 100       | 1,000      | 10,000      |
| **Storage** | 1 GB      | 10 GB      | 100 GB      |

**Implementation Options**:

**Option A** (Usage-focused): Create products with usage meters for builds/storage. Manage users in your application.

**Option B** (Seat-focused): Create products with seat add-ons. Track builds/storage usage and charge overages via on-demand.

**Add-ons (if using Option B):**

* Extra users: \$10/user/month
* Priority builds: \$19/month
* Custom domains: \$9/domain/month

### Example 3: Marketing Automation

**Pricing Structure:**

* **Base**: \$79/month (core automation features, 3 seats included)
* **Contact Tiers** (add-ons): 1K included, 5K (+\$30), 25K (+\$80), 100K (+\$200)
* **Feature Add-ons**: SMS Marketing (\$29/mo), Landing Pages (\$19/mo), A/B Testing (\$29/mo)
* **Team Seats**: \$15/user/month add-on
* **Email Volume**: Track in application, charge overage via on-demand (\$1/1,000 emails over limit)

**Implementation**: Use subscription with contact tier add-ons, feature add-ons, and seat add-ons. Track email sends in your application and charge overages via on-demand charges.

***

## Implementation Best Practices

### Pricing Page Clarity

<Tip>
  Make hybrid pricing easy to understand. Show base costs, what's included, and how overages work prominently on your pricing page.
</Tip>

**Good**: "\$49/month includes 10,000 API calls. Additional calls: \$0.005 each"

**Bad**: "\$49/month + usage fees"

### Cost Predictability

Help customers estimate their costs:

```typescript theme={null}
// Provide a cost calculator
function estimateMonthlyCost({
  plan,
  seats,
  expectedUsage,
  addons
}: EstimateParams): number {
  let total = plan.basePrice;

  // Add seat costs
  const extraSeats = Math.max(0, seats - plan.includedSeats);
  total += extraSeats * plan.seatPrice;

  // Add usage overage
  const overage = Math.max(0, expectedUsage - plan.includedUsage);
  total += overage * plan.overageRate;

  // Add feature add-ons
  total += addons.reduce((sum, addon) => sum + addon.price, 0);

  return total;
}
```

### Usage Visibility

Show customers their usage in real-time:

```typescript theme={null}
// Display usage dashboard
async function getUsageSummary(subscriptionId: string) {
  const usage = await client.subscriptions.retrieveUsageHistory(subscriptionId);

  // Each item is a billing period; each meter reports its usage for that period.
  const latestPeriod = usage.items[0];

  return latestPeriod.meters.map((meter) => {
    const consumed = Number(meter.consumed_units);
    const chargeable = Number(meter.chargeable_units);
    return {
      meter: meter.name,
      current: consumed,
      included: meter.free_threshold,
      remaining: Math.max(0, meter.free_threshold - consumed),
      overage: chargeable,
      cost: meter.total_price
    };
  });
}
```

### Billing Transparency

Provide detailed invoices showing all components:

| Line Item                                    | Amount       |
| -------------------------------------------- | ------------ |
| Pro Plan (Monthly)                           | \$49.00      |
| Additional Seats (7 × \$15.00)               | \$105.00     |
| API Usage - Included (10,000 calls)          | \$0.00       |
| API Usage - Overage (15,420 calls × \$0.005) | \$77.10      |
| Advanced Analytics Add-on                    | \$19.00      |
| **Subtotal**                                 | **\$250.10** |
| Tax (8.5%)                                   | \$21.26      |
| **Total Due**                                | **\$271.36** |

***

## Troubleshooting Hybrid Billing

<AccordionGroup>
  <Accordion title="Usage not being tracked correctly">
    **Symptoms**: Usage shows 0 or incorrect values.

    **Solutions**:

    1. Verify event ingestion is working (check API responses)
    2. Confirm `customer_id` matches the subscription customer
    3. Check `event_name` matches the meter configuration
    4. Verify events have correct timestamps (not future-dated)
  </Accordion>

  <Accordion title="Proration confusion with multiple components">
    **Symptoms**: Customer charged unexpected amounts when changing plans.

    **Solutions**:

    1. Use `previewChangePlan` API to show exact charges before confirming
    2. Communicate that proration applies to subscription AND add-ons
    3. Consider using `difference_immediately` for simpler upgrade billing
  </Accordion>

  <Accordion title="Free threshold not applying correctly">
    **Symptoms**: Customer charged for usage that should be free.

    **Solutions**:

    1. Verify free threshold is configured on the usage-based product
    2. Check threshold unit matches event aggregation (calls vs. requests)
    3. Confirm usage meter is correctly attached to the subscription product
  </Accordion>

  <Accordion title="Add-ons not appearing in checkout">
    **Symptoms**: Can't add seats or features during checkout.

    **Solutions**:

    1. Verify add-ons are attached to the subscription product in dashboard
    2. Check add-on IDs are correct in API calls
    3. Ensure add-on currency matches subscription product currency
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Products" icon="box" href="/features/products">
    Overview of all product types and guides.
  </Card>

  <Card title="Usage-Based Billing Guide" icon="chart-line" href="/developer-resources/usage-based-billing-guide">
    Complete usage billing implementation.
  </Card>

  <Card title="Subscription Management" icon="repeat" href="/features/subscription">
    Managing recurring subscriptions.
  </Card>

  <Card title="Add-ons" icon="puzzle" href="/features/addons">
    Extending subscriptions with add-ons.
  </Card>
</CardGroup>


# Invoice Management
Source: https://docs.dodopayments.com/features/invoice-generation

Automatically generate and deliver professional invoices for every successful payment, with customizable branding and seamless email delivery.

<Frame>
  <img alt="Invoice Generation Cover Image" />
</Frame>

## Overview

Dodo Payments automatically generates professional invoices for every successful transaction, eliminating manual invoice creation and ensuring consistent documentation for your business. Invoices are instantly delivered to both you and your customers via email after each payment.

<Info>
  Invoices are generated automatically for both one-time purchases and recurring subscription payments.
</Info>

## Key Features

<CardGroup>
  <Card title="Automatic Generation" icon="wand-magic-sparkles">
    Invoices are created instantly after successful payment processing without manual intervention.
  </Card>

  <Card title="Custom Branding" icon="palette">
    Add your business logo and name to maintain brand consistency across all customer touchpoints.
  </Card>

  <Card title="Email Delivery" icon="envelope">
    Invoices are automatically sent to customers and merchants immediately after generation.
  </Card>

  <Card title="Dashboard Management" icon="table-columns">
    Access and download invoices from a centralized dashboard view.
  </Card>
</CardGroup>

## Setting Up Invoice Branding

<Steps>
  <Step title="Navigate to Business Settings">
    Open the Dodo Payments dashboard and go to **Settings** → **Business**.
  </Step>

  <Step title="Configure Branding">
    Upload your business logo and enter your business name. These details will appear on all generated invoices.

    <Tip>
      Use a high-resolution logo (minimum 300x300px) in PNG format for the best print quality.
    </Tip>
  </Step>

  <Step title="Save Configuration">
    Click **Save** to apply your branding settings. All future invoices will automatically use these details.

    <Check>
      Your invoice branding is now configured and will be applied to all new invoices.
    </Check>
  </Step>
</Steps>

## What's Included in Invoices

Every generated invoice contains comprehensive transaction details:

* **Business Information**: Your business name, logo, and contact details
* **Customer Details**: Customer name and email address
* **Invoice Number**: Unique identifier for tracking and reference
* **Transaction Date**: When the payment was processed
* **Payment Details**: Amount paid, currency, and payment method
* **Product/Service Description**: Itemized list of purchased products or subscriptions
* **Tax Information**: Applicable taxes and tax identification numbers
* **Payment Status**: Confirmation of successful payment

<Note>
  Invoice numbers are automatically generated and follow a sequential format for easy tracking.
</Note>

## How Invoice Generation Works

<Tabs>
  <Tab title="One-Time Purchases">
    When a customer completes a one-time purchase:

    1. Payment is processed successfully
    2. Invoice is automatically generated with transaction details
    3. Invoice is emailed to both customer and merchant
    4. Invoice appears in your dashboard **Invoices** section

    All one-time purchase invoices include product details, pricing, and payment confirmation.
  </Tab>

  <Tab title="Subscription Renewals">
    For recurring subscription payments:

    1. Subscription renewal payment is processed automatically
    2. Invoice is generated for the billing period
    3. Invoice is emailed to customer with subscription details
    4. Invoice is stored in your dashboard for records

    Subscription invoices include the billing period, subscription plan details, and next renewal date.
  </Tab>
</Tabs>

## Managing Invoices

### Accessing Your Invoices

Navigate to the **Invoices** section in your Dodo Payments dashboard to view all generated invoices. You can:

* **View Invoice Details**: Click any invoice to see complete transaction information
* **Download PDF**: Export invoices in PDF format for your records
* **Resend to Customer**: Email the invoice again if needed
* **Filter and Search**: Find specific invoices by date, customer, or invoice number

<Tip>
  Use the search and filter options to quickly locate invoices for accounting or customer support purposes.
</Tip>

## Invoice Template Preview

Here's what your branded invoices will look like:

<Frame>
  <img alt="Invoice template showing business branding, transaction details, and professional layout" />
</Frame>

## Related Features

<CardGroup>
  <Card title="Subscription Management" icon="calendar-days" href="/features/subscription">
    Learn how subscriptions work with automatic recurring invoices.
  </Card>

  <Card title="Multi-Brand Support" icon="layer-group" href="/features/multi-brands">
    Manage multiple brands with separate invoice branding for each.
  </Card>

  <Card title="Customer Portal" icon="user" href="/features/customer-portal">
    Allow customers to access their invoice history through the customer portal.
  </Card>

  <Card title="Tax Configuration" icon="percent" href="/features/tax-inclusive-pricing">
    Configure tax settings to ensure invoices display correct tax information.
  </Card>
</CardGroup>


# License Keys
Source: https://docs.dodopayments.com/features/license-keys

Generate and deliver unique license keys with activation limits and expiry. License keys are the License Key entitlement type. They're issued automatically on payment, tied to subscription lifecycle, and revoked on cancellation or refund.

<Frame>
  <iframe title="License Keys | Dodo Payments" />
</Frame>

<Info>
  License keys are the License Key entitlement type. Create a License Key entitlement once with the activation limit, expiry, and instructions you want, attach it to any product, and Dodo Payments generates and delivers a key per purchase or subscription seat, automatically.
</Info>

## What are License Keys?

License keys are unique tokens that authorize access to your product. They're ideal for:

* **Software licensing**: Desktop apps, plugins, and CLIs
* **Per-seat controls**: Limit activations per user or device
* **Digital goods**: Gate downloads, updates, or premium features

Inside Dodo Payments, license keys are managed through the [Entitlements](/features/entitlements/introduction) system, meaning the lifecycle of every key (creation, expiry, revocation, regrant) is driven by the same payment and subscription events as your other deliverables.

## Create a License Key Entitlement

<Steps>
  <Step title="Open Entitlements">
    Go to **Entitlements** in your Dodo Payments dashboard and click **+** to create a new entitlement.
  </Step>

  <Step title="Choose License Key">
    Select **License Key** as the integration. Configure how each issued key behaves:

    * **Activations Limit**: Maximum concurrent activations per key (e.g., `1` for single-user, `5` for team licenses, leave blank for unlimited).
    * **Duration**: How long the key stays valid after issuance (e.g., 30 days, 1 year). For subscription-issued keys, leave blank; keys remain valid as long as the subscription is active.
    * **Activation Instructions**: Customer-facing instructions emailed with the key. Examples: `Paste the key in Settings → License` or `Run: mycli activate <key>`.

    <Frame>
      <img alt="New License Key entitlement form with name, fulfillment mode, license length, activations limit, and activation message" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Save. The entitlement is now available to attach to any product.
  </Step>
</Steps>

## Attach to Products

Open a product, expand **Advanced Settings → Entitlements & Credits**, and select your License Key entitlement. A single product can deliver a license key alongside other entitlements (Discord access, file downloads, GitHub repo access, etc.) on the same purchase.

<Frame>
  <img alt="Product entitlements panel with License Key selected" />
</Frame>

***

## How Keys Are Issued

Key issuance follows the standard [grant lifecycle](/features/entitlements/introduction#how-grants-work):

| Event                                | Behavior                                                                                                                   |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` (one-time)       | Generate one key per `quantity` purchased. Key expiry honors the entitlement's duration.                                   |
| `subscription.active`                | Generate one key per subscription `quantity` (seat). Key has no expiry; validity is tied to subscription status.           |
| `subscription.renewed`               | No-op. Existing keys persist.                                                                                              |
| `subscription.on_hold`               | Disable the keys. They reactivate when the subscription comes off hold.                                                    |
| `subscription.cancelled` / `expired` | Disable the keys permanently.                                                                                              |
| `subscription.plan_changed`          | Disable the old keys; issue new ones for the new plan.                                                                     |
| `refund.succeeded` (one-time)        | Disable the keys.                                                                                                          |
| Manual revoke via API/dashboard      | Disable the keys with `revocation_reason: manual`. These are not auto-regranted on subscription renewal.                   |
| License key disabled directly        | Revoke the grant with `revocation_reason: license_key_disabled`. Re-enabling the key re-activates the grant automatically. |

### Quantity behavior

* **Subscription products** issue one key per seat (`subscriptions.quantity`).
* **One-time products** issue one key per cart line item (`product_cart.quantity`).
* **Manual API grants** issue exactly one key.

### Fulfillment mode

Every License Key entitlement has a `fulfillment_mode` that controls who supplies the key:

* **`auto`** (default): Dodo Payments generates and emails the key automatically on payment or subscription. This is the behavior described above and applies when `fulfillment_mode` is omitted.
* **`manual`**: The purchase creates a `Pending` grant with no key, and you supply each key value yourself. See [Manual Fulfillment](#manual-fulfillment) below.

***

## Manual Fulfillment

By default, Dodo Payments generates and emails a license key the moment a customer pays. With **manual fulfillment** you supply the key yourself: the purchase creates a `Pending` grant with no key, notifies you, and waits for you to submit the key value. Use it when keys come from your own system, a third-party vendor, or a finite pool of pre-printed codes.

<Info>
  Looking for a step-by-step build? See the [Manual License Key Fulfillment Integration Guide](/developer-resources/manual-license-key-fulfillment) for an end-to-end walkthrough from product creation to delivering the key.
</Info>

### When to use it

Auto fulfillment is the right default for most software licensing. Choose manual fulfillment when Dodo Payments cannot mint the key itself:

* **Bring-your-own-keys**: The key is generated by your application, a desktop product, or your own license server.
* **Third-party vendors**: You resell keys issued by an upstream provider (a game key, an API credential, a partner platform).
* **Finite inventory**: You hand out codes from a pre-allocated pool and want to assign them one at a time.
* **Human review**: You want to vet a purchase before releasing access.

### Enable manual fulfillment

Set `fulfillment_mode: "manual"` on the License Key entitlement's integration config:

<CodeGroup>
  ```typescript Node.js theme={null} theme={null}
  const entitlement = await client.entitlements.create({
    name: 'Pro License (Manual)',
    integration_type: 'license_key',
    integration_config: {
      fulfillment_mode: 'manual',
      activations_limit: 5,
      duration_count: 1,
      duration_interval: 'Year',
    },
  });
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST https://test.dodopayments.com/entitlements \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Pro License (Manual)",
      "integration_type": "license_key",
      "integration_config": {
        "fulfillment_mode": "manual",
        "activations_limit": 5,
        "duration_count": 1,
        "duration_interval": "Year"
      }
    }'
  ```
</CodeGroup>

<Note>
  `fulfillment_mode` is backward compatible. Entitlements created before this setting existed have no `fulfillment_mode` and continue to behave as `auto`. Switching to `manual` only affects grants created **after** the change; keys already delivered are untouched.
</Note>

### Find grants awaiting fulfillment

When a customer buys a manual-mode product, the grant is created in `Pending` status with no key and an [`entitlement_grant.created`](/developer-resources/webhooks/intents/entitlement-grant) webhook fires with `integration_type: "license_key"` and `status: "Pending"`. You can react to that webhook, or poll the [List Customer Grants](/api-reference/entitlements/list-customer-grants) endpoint with the `integration_type` and `status` filters:

```typescript theme={null} theme={null}
const pending = await client.customers.listEntitlementGrants('customer_id', {
  integration_type: 'license_key',
  status: 'Pending',
});
```

### Deliver the key

Submit the key with the [Fulfill License Key Grant](/api-reference/entitlements/fulfill-license-key) endpoint. The grant moves to `Delivered` and the customer is sent the key automatically — the same email they would receive under auto fulfillment.

```bash cURL theme={null} theme={null}
curl -X POST https://test.dodopayments.com/grants/grant_8VbC6JDZ/license-key \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "activations_limit": 5,
    "expires_at": "2027-05-01T00:00:00Z"
  }'
```

`activations_limit` and `expires_at` are optional and fall back to the entitlement config when omitted. Each grant can be fulfilled once; retrying an already-fulfilled grant returns `409` rather than issuing a second key.

<Check>
  You do not need to email the key yourself — delivery happens automatically when the grant is fulfilled. This differs from [importing keys](#import-existing-license-keys-via-api) via `POST /license_keys`, which intentionally does **not** notify the customer.
</Check>

***

## Activation, Validation, Deactivation

The activation/validation/deactivation API endpoints are **public** and require no API key. Use them directly from desktop software, CLIs, or browser-based clients to verify keys at runtime.

<Info>
  **Public Endpoints**: The activate, deactivate, and validate license endpoints are public and do not require an API key. Call them directly from your client applications without exposing your API credentials.
</Info>

### Activate a license

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import DodoPayments from 'dodopayments';

  // No API key needed for public license endpoints
  const client = new DodoPayments();

  const response = await client.licenses.activate({
    license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
    name: 'Device Name',
  });

  console.log(response.id);
  ```

  ```python Python theme={null} theme={null}
  client.licenses.activate(
      license_key="PRO-AAAA-BBBB-CCCC-DDDD",
      name="Device Name",
  )
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST https://test.dodopayments.com/licenses/activate \
    -H "Content-Type: application/json" \
    -d '{
      "license_key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "name": "Device Name"
    }'
  ```
</CodeGroup>

### Validate a license

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const response = await client.licenses.validate({
    license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  });

  console.log(response.valid);
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST https://test.dodopayments.com/licenses/validate \
    -H "Content-Type: application/json" \
    -d '{ "license_key": "PRO-AAAA-BBBB-CCCC-DDDD" }'
  ```
</CodeGroup>

### Deactivate an activation instance

```typescript theme={null} theme={null}
await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'instance_abc123',
});
```

***

## Manage Keys

Open the License Key entitlement from your dashboard to see every grant (one row per customer key) with delivery date, activation count, and a revoke action. Each grant detail surfaces the underlying license key, expiry, activations used, and the activations limit.

You can also list grants programmatically:

```typescript theme={null} theme={null}
const grants = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'Delivered',
});

for (const grant of grants.items) {
  console.log(grant.license_key.key, grant.license_key.activations_used);
}
```

## Import Existing License Keys via API

Already have license keys in another system? Use the [Create License Key](/api-reference/licenses/create-license-key) API to import them into Dodo Payments. This lets you migrate existing keys without disrupting your customers — they continue to activate, validate, and deactivate against the same key strings without re-issuance.

<Warning>
  License keys created or updated through the API do not trigger email notifications to customers. If you need to notify customers about an imported key, handle that separately in your application.
</Warning>

```typescript theme={null} theme={null}
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});
```

### How keys differ by source

| Field                       | Auto-generated key                    | Manually fulfilled key                                         | Imported key                              |
| --------------------------- | ------------------------------------- | -------------------------------------------------------------- | ----------------------------------------- |
| `source`                    | `"auto"`                              | `"manual"`                                                     | `"import"`                                |
| Origin                      | Generated by Dodo Payments on payment | [Supplied by you](#manual-fulfillment) against a pending grant | Created/migrated via `POST /license_keys` |
| `payment_id`                | Set to the originating payment        | Resolved from the grant or its subscription                    | `null` (no Dodo Payments transaction)     |
| `subscription_id`           | Set if issued via a subscription      | Set if the grant came from a subscription                      | `null` unless explicitly linked           |
| Customer email notification | Sent on issuance                      | Sent on fulfillment                                            | Not sent — handle separately              |

Use the `source` field on `GET /license_keys` responses to distinguish migrated inventory and manually fulfilled keys from organically issued keys when reconciling or auditing.

<Tip>
  Migrating from **Polar.sh** or **Lemon Squeezy**? The [`dodo-migrate` CLI](/migrate-to-dodo) automates bulk imports of products, customers, discounts, and license keys in a single command and maps external IDs to Dodo IDs automatically.
</Tip>

***

## License Keys in Return URL

When a customer completes a purchase for a product with a License Key entitlement, the generated key is automatically appended to your `return_url` as a query parameter. This lets you display the key immediately on your success page without making an extra API call.

```text theme={null} theme={null}
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
```

If the purchase generates multiple keys (quantity > 1), they are comma-separated:

```text theme={null} theme={null}
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com
```

For subscriptions, `subscription_id` is used instead of `payment_id`:

```text theme={null} theme={null}
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com
```

<Tip>
  Parse the `license_key` parameter on your return page to show the key immediately, improving the post-purchase experience.
</Tip>

***

## API Management

<AccordionGroup>
  <Accordion title="Lifecycle Operations (Public Endpoints)">
    Activation, deactivation, and validation are public; no API key required.

    <CardGroup>
      <Card title="Activate License" icon="code" href="/api-reference/licenses/activate-license">
        Create or record an activation instance for a license key.
      </Card>

      <Card title="Deactivate License" icon="code" href="/api-reference/licenses/deactivate-license">
        Revoke a prior activation to free up capacity.
      </Card>

      <Card title="Validate License" icon="code" href="/api-reference/licenses/validate-license">
        Check authenticity, status, and constraints before granting access.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="License Key Management">
    Create, list, retrieve, and update individual license key records. Use these to import existing keys or fetch usage details.

    <CardGroup>
      <Card title="Create License Key" icon="code" href="/api-reference/licenses/create-license-key">
        Create a new license key or import an existing one.
      </Card>

      <Card title="List License Keys" icon="code" href="/api-reference/licenses/list-license-keys">
        Browse all keys with status and usage details.
      </Card>

      <Card title="Get License Key" icon="code" href="/api-reference/licenses/get-license-key">
        Retrieve a specific key and its metadata.
      </Card>

      <Card title="Update License Key" icon="code" href="/api-reference/licenses/update-license-key">
        Modify expiry, activation limits, or enable/disable a key.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Entitlement Management">
    Manage the License Key entitlement itself: its activation limit, duration, and instructions.

    <CardGroup>
      <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
        Create a License Key entitlement.
      </Card>

      <Card title="Update Entitlement" icon="pen" href="/api-reference/entitlements/update-entitlement">
        Update the entitlement's configuration.
      </Card>

      <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
        List the keys issued for an entitlement.
      </Card>

      <Card title="Revoke Grant" icon="ban" href="/api-reference/entitlements/revoke-grant">
        Manually revoke a customer's key.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

## Webhooks

License-key delivery and revocation fire the four [`entitlement_grant.*` webhook events](/developer-resources/webhooks/intents/entitlement-grant). The grant payload includes a populated `license_key` object with the key, expiry, activations used, and limit.

The legacy `license_key.*` events (`license_key.created`) continue to fire for the underlying license-key record lifecycle; see the [License Key webhook payload page](/developer-resources/webhooks/intents/license-key).

<Tip>
  For new integrations, listen to `entitlement_grant.delivered` rather than `license_key.created`. The entitlement event tells you delivery is complete across all integrations on the product, not just the license key.
</Tip>

***

## Legacy License Keys

<Note>
  Products created with the older `license_key_enabled` flag have been **automatically migrated** to a License Key entitlement. The migration is transparent: existing customers' keys continue to work unchanged, the public `/licenses/activate`, `/licenses/validate`, `/licenses/deactivate` endpoints continue to function, and the `/license_keys/*` API endpoints continue to read and write to the same key store.

  The standalone **License Keys** dashboard section remains available as a flat list of every key issued, useful for audit and search. New configuration (changing activation limits, durations, or instructions) should be done by editing the migrated License Key entitlement under **Entitlements**.
</Note>

***

## Best Practices

* **Keep activation limits clear**: Choose sensible defaults (1 for single-user apps, 3–5 for team licenses) and document them.
* **Provide precise activation instructions**: Customers paste these from their email, so exact paths and commands save support tickets.
* **Validate keys server-side**: For network-connected products, validate via `/licenses/validate` rather than caching activation locally.
* **Use webhooks for revocation**: Listen to `entitlement_grant.revoked` to disable in-app features immediately when a customer cancels or refunds.
* **Test with subscriptions and one-times**: License key behavior differs subtly between the two, so test both before going live.


# Localized Pricing
Source: https://docs.dodopayments.com/features/localized-pricing

Set your own fixed price for each currency or country instead of letting exchange rates decide. Charge round, market-tuned prices and run per-country promotions.

## What Is Localized Pricing?

Every product has a base price in a base currency. Localized Pricing lets you override that base with **fixed prices you set per currency or per country**. Turn it on by setting a `pricing_mode` on the product, then attach one rule per market.

It's one of three independent levers for international pricing, each solving a different problem:

| Mechanism                                            | What it does                                            | The number the customer sees                      |
| :--------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------ |
| **Localized Pricing**                                | A fixed price you set per currency or country           | Exactly the amount you set                        |
| [**Adaptive Currency**](/features/adaptive-currency) | Automatically converts your base price at live FX rates | Base price converted at the current exchange rate |
| [**Discount codes**](/features/discount-codes)       | A percentage reduction off the base price               | Base price minus the discount                     |

<Info>
  Localized Pricing and Adaptive Currency work together. When no localized rule matches, the product falls back to its base price — charged directly if the customer is already in your base currency, or converted through Adaptive Currency if not.
</Info>

***

## Use Cases

<CardGroup>
  <Card title="Purchasing Power Parity (PPP)" icon="earth-asia" href="/features/purchasing-power-parity">
    Charge less in price-sensitive markets without discounting your home market. A `by_country` rule lets a \$20 base product sell for **₹999 in India** — tuned to local purchasing power, not a straight FX conversion. The recommended, native way to run PPP.
  </Card>

  <Card title="Charm Pricing" icon="tag">
    A live FX conversion of \$19.99 lands on an awkward number like €18.43. A `by_currency` rule sets the clean, psychologically-tuned price customers expect — **€9.99**, **¥1000**, **₹499** — exactly as typed.
  </Card>

  <Card title="Reversible Market-Entry Promotions" icon="rocket">
    Launching in a new country? Add a `by_country` rule with an introductory price, then **archive it** when the promotion ends to fall back to base/adaptive pricing. Rules are archived, never deleted, so you keep a clean record of what was live and when.
  </Card>

  <Card title="Competitive Price-Matching" icon="bullseye">
    Pin a single market to match a local competitor. A `by_country` rule for **£9.00 in the United Kingdom** holds that exact price regardless of how the GBP/USD rate moves.
  </Card>
</CardGroup>

***

## Core Concepts

* **Pricing modes** — A product is in exactly one mode at a time, set by its `pricing_mode`:
  * `by_currency`: one price per currency, regardless of country. Everyone paying in EUR sees €9.99.
  * `by_country`: a price specific to a country (₹999 in India), even when several countries share a currency.
* **Fixed amounts, in the smallest unit** — A rule's `amount` is an integer in the currency's smallest unit, the same as everywhere else in the API: `99900` is ₹999.00, `999` is €9.99. It's a price you set, never a converted value.
* **When no rule matches** — The product keeps its existing behavior: customers in your base currency pay the base price directly; everyone else gets it converted through [Adaptive Currency](/features/adaptive-currency).
* **Fees are inclusive when a rule matches** — The customer pays **exactly** the amount you set. The [Adaptive Currency](/features/adaptive-currency#choose-who-bears-the-fee) FX fee is absorbed by you (treated as fees-inclusive for that transaction) rather than added on top, so your stated local price is always the price charged.

***

## Set Up in the Dashboard

<Steps>
  <Step title="Open the product form">
    In your Merchant Dashboard, go to **Products** and create a product (or open an existing one to edit). Set the base **Price** and currency as usual.
  </Step>

  <Step title="Enable Localized Pricing and choose a mode">
    In the **Pricing** section, tick **Localized Pricing**, then choose **By Country** or **By Currency**.

    <Frame>
      <img alt="Localized Pricing enabled on the product form with By Country selected" />
    </Frame>
  </Step>

  <Step title="Add a price for each market">
    Click **Add Country Price** or **Add Currency Price**, fill in the **Localized pricing** panel, and click **Add**. Each market you add appears in the overrides table, where you can edit or remove it later.

    <Tabs>
      <Tab title="By Country">
        Pick a country, choose the currency, and enter the amount (for example ₹999 for India), then click **Add**.

        <Frame>
          <img alt="Adding a 999 INR override for India" />
        </Frame>

        The country now appears in the **Country overrides** table, where you can edit or remove it.

        <Frame>
          <img alt="Country overrides table showing India at 999 INR" />
        </Frame>
      </Tab>

      <Tab title="By Currency">
        Pick a currency and enter the amount (for example €9.99 for EUR), then click **Add**.

        <Frame>
          <img alt="Adding a 9.99 EUR override" />
        </Frame>

        The currency now appears in the **Currency overrides** table, where you can edit or remove it.

        <Frame>
          <img alt="Currency overrides table showing EUR at 9.99" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Save the product">
    Save with **Add product**. Localized prices apply to future checkouts immediately.

    <Check>
      Run a test checkout with a billing country that has a rule, and confirm the localized amount appears.
    </Check>
  </Step>
</Steps>

***

## Manage via API

Localized Pricing is fully available over the API. First set the product's pricing mode, then attach rules.

### Set the pricing mode

Set `pricing_mode` when you create the product (or update an existing one). `null` means base-only, the existing behavior.

<CodeGroup>
  ```typescript theme={null} theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode',
  });

  const product = await client.products.update('pdt_premium_plan', {
    pricing_mode: 'by_country',
  });
  ```

  ```python theme={null} theme={null}
  import os
  from dodopayments import DodoPayments

  client = DodoPayments(
      bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
      environment="test_mode",
  )

  product = client.products.update(
      "pdt_premium_plan",
      pricing_mode="by_country",
  )
  ```

  ```go theme={null} theme={null}
  package main

  import (
  	"context"
  	"os"

  	"github.com/dodopayments/dodopayments-go"
  	"github.com/dodopayments/dodopayments-go/option"
  )

  func main() {
  	client := dodopayments.NewClient(
  		option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
  	)

  	_, err := client.Products.Update(
  		context.TODO(),
  		"pdt_premium_plan",
  		dodopayments.ProductUpdateParams{
  			PricingMode: dodopayments.F(dodopayments.PricingModeByCountry),
  		},
  	)
  	if err != nil {
  		panic(err)
  	}
  }
  ```
</CodeGroup>

### Add a localized price

Attach a rule to the product. In `by_country` mode `country_code` is required; in `by_currency` mode it must be omitted.

<CodeGroup>
  ```typescript theme={null} theme={null}
  // ₹999.00 for customers in India
  const localizedPrice = await client.products.localizedPrices.create('pdt_premium_plan', {
    currency: 'INR',
    country_code: 'IN',
    amount: 99900,
  });
  ```

  ```python theme={null} theme={null}
  # ₹999.00 for customers in India
  localized_price = client.products.localized_prices.create(
      "pdt_premium_plan",
      currency="INR",
      country_code="IN",
      amount=99900,
  )
  ```

  ```go theme={null} theme={null}
  // ₹999.00 for customers in India
  localizedPrice, err := client.Products.LocalizedPrices.New(
  	context.TODO(),
  	"pdt_premium_plan",
  	dodopayments.ProductLocalizedPriceNewParams{
  		Currency:    dodopayments.F(dodopayments.CurrencyInr),
  		CountryCode: dodopayments.F(dodopayments.CountryCodeIn),
  		Amount:      dodopayments.F(int64(99900)),
  	},
  )
  ```
</CodeGroup>

For a `by_currency` product, omit `country_code`. For example, a flat `€9.99` for everyone paying in EUR (`currency: 'EUR'`, `amount: 999`).

### List, update, and archive

You can update only a rule's `amount`; currency and country are fixed once created. Archiving is an idempotent soft-delete, so the rule stops matching but stays in your history.

<CodeGroup>
  ```typescript theme={null} theme={null}
  // List all active rules on a product
  const rules = await client.products.localizedPrices.list('pdt_premium_plan');

  // Change the amount (e.g. end a promo)
  await client.products.localizedPrices.update('lcp_india_price', {
    product_id: 'pdt_premium_plan',
    amount: 119900,
  });

  // Archive a rule
  await client.products.localizedPrices.archive('lcp_india_price', {
    product_id: 'pdt_premium_plan',
  });
  ```

  ```python theme={null} theme={null}
  # List all active rules on a product
  rules = client.products.localized_prices.list("pdt_premium_plan")

  # Change the amount (e.g. end a promo)
  client.products.localized_prices.update(
      "lcp_india_price",
      product_id="pdt_premium_plan",
      amount=119900,
  )

  # Archive a rule
  client.products.localized_prices.archive(
      "lcp_india_price",
      product_id="pdt_premium_plan",
  )
  ```

  ```go theme={null} theme={null}
  // List all active rules on a product
  rules, err := client.Products.LocalizedPrices.List(context.TODO(), "pdt_premium_plan")

  // Change the amount (e.g. end a promo)
  _, err = client.Products.LocalizedPrices.Update(
  	context.TODO(),
  	"pdt_premium_plan",
  	"lcp_india_price",
  	dodopayments.ProductLocalizedPriceUpdateParams{
  		Amount: dodopayments.F(int64(119900)),
  	},
  )

  // Archive a rule
  err = client.Products.LocalizedPrices.Archive(
  	context.TODO(),
  	"pdt_premium_plan",
  	"lcp_india_price",
  )
  ```
</CodeGroup>

<Card title="API Reference" icon="code" href="/api-reference/products/post-products-localized-prices">
  See the full Product Localized Prices endpoints: create, list, retrieve, update, and archive.
</Card>

***

## How It Applies at Checkout

Localized pricing is resolved per cart line, and only for products that have a `pricing_mode` set. Dodo Payments reads two signals from the request: the customer's **billing country**, and an optional **`billing_currency`** (when omitted, a currency is derived from the billing country).

* **By Country**: looks for a rule matching the billing country. If one exists, the customer is charged the rule's amount in the rule's currency.
* **By Currency**: looks for a rule matching the customer's currency (the `billing_currency`, or the currency derived from their country). If one exists, the customer is charged the rule's amount in that currency.
* **No match, or no `pricing_mode`**: the base price applies, charged directly when the customer's currency equals the base currency, otherwise converted through [Adaptive Currency](/features/adaptive-currency).

Each cart line is resolved on its own, so you can localize one product and leave others on base pricing in the same checkout. If any line matches a localized rule, the whole transaction is forced fees-inclusive (see [Core Concepts](#core-concepts)).

***

## How It Applies on Subscription Plan Changes

Localized pricing follows your subscribers when they switch plans. When an existing subscription [changes plan](/features/subscription#subscription-plan-changes) into a product that has a `pricing_mode`, the new plan's price is resolved with the same rules as checkout, using the billing country and currency already locked on the subscription:

* **By Country**: a rule matching the subscription's billing country applies. If the rule's currency differs from the currency the subscription is billed in, the rule's amount is converted at live FX rates — the rule is applied, not skipped.
* **By Currency**: a rule matching the currency the customer is billed in applies, and the customer is charged exactly the rule's amount.
* **No match, or no `pricing_mode`**: the new plan's base price applies, converted through [Adaptive Currency](/features/adaptive-currency) when needed — the same fallback as checkout.

This holds everywhere a plan change can originate: the [Change Plan API](/api-reference/subscriptions/change-plan), the [Customer Portal](/features/customer-portal)'s self-service plan changes, and changes scheduled for the end of the billing period.

* **Previews are exact.** [Preview Change Plan](/api-reference/subscriptions/preview-change-plan) returns the same localized amount the actual change charges.
* **Renewals keep the localized price.** After the change, the new plan renews at its localized amount — and stays fees-inclusive — exactly like a subscription created at that price.
* **Proration uses real amounts.** On an upgrade, the credit for unused time is based on what the customer actually paid for the old plan, while the new plan is priced by its localized rule.
* **Scheduled changes lock the price when scheduled.** A change scheduled for the end of the billing period charges the amount calculated at scheduling time, even if you edit the rule in between.
* **The billing currency never changes.** A plan change never switches the currency a subscription settles in; a rule in another currency is FX-converted into it.
* **Add-ons are not localized.** Add-on prices on the new plan always use their base pricing.

***

## Important Behaviors

| Behavior                          | Detail                                                                                                                                                                                                                   |
| :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pre-tax amounts**               | A localized amount is the price *before* tax. For tax-exclusive products, tax is added on top at checkout, so the localized amount is not the final total. See [Tax-Inclusive Pricing](/features/tax-inclusive-pricing). |
| **Not for Pay What You Want**     | Localized rules never apply to [Pay What You Want](/features/pay-what-you-want) products, where the customer chooses the amount.                                                                                         |
| **By-currency differs from base** | A `by_currency` rule must use a currency different from the product's base currency.                                                                                                                                     |
| **One rule per market**           | A product can have at most one active rule per currency (by-currency) or per country (by-country).                                                                                                                       |
| **All product types**             | Applies to one-time, subscription, and usage-based products — including when an existing subscriber [changes plan](#how-it-applies-on-subscription-plan-changes).                                                        |

<Info>
  Localized rule changes do not emit their own webhooks. The resolved amount appears on the resulting payment or subscription exactly like any other price.
</Info>

***

## Best Practices

* **Keep a sensible base price.** It is the fallback for every market without a rule, converted through Adaptive Currency.
* **Round to local charm prices.** The whole point of a fixed amount is a clean number like ₹999, €9.99, or ¥1000, not an FX result.
* **Pick the mode for the job.** Use `by_country` for purchasing-power pricing; use `by_currency` when one price per currency zone is enough.
* **Archive, don't recreate, for promotions.** Archiving a rule reverts the market to base/adaptive while preserving history; recreate or re-price later as needed.
* **Mind the tax line before advertising a total.** For tax-exclusive products the customer pays the localized amount *plus* tax, so don't quote it as the final price in ads.

***

## Related

<CardGroup>
  <Card title="Purchasing Power Parity" icon="money-bill-trend-up" href="/features/purchasing-power-parity">
    Native localized pricing vs. location-based discount codes for PPP.
  </Card>

  <Card title="Adaptive Currency" icon="money-bill-transfer" href="/features/adaptive-currency">
    Automatic FX conversion and the fee handling localized pricing builds on.
  </Card>

  <Card title="Tax-Inclusive Pricing" icon="receipt" href="/features/tax-inclusive-pricing">
    Control whether your prices include tax.
  </Card>

  <Card title="Pay What You Want" icon="hand-holding-dollar" href="/features/pay-what-you-want">
    Let customers choose the amount. Localized rules do not apply there.
  </Card>
</CardGroup>


# Multi-Brand Setup
Source: https://docs.dodopayments.com/features/multi-brands

Learn how to set up multi-brand in Dodo Payments.

## Introduction

Multi-Brand lets you attach several brands, each with its own logo, descriptor, and website URL, to **one verified business**. Your payout account, fees, and KYC stay exactly the same, while every Product, Payment Link, Subscription, Invoice, and Transaction can now be filed under a specific brand. Use it to test new niches, localise a site, or separate B2B and B2C lines without opening extra business accounts.

## Merchant Dashboard Flow

<Steps>
  <Step title="Open Settings → Business">
    Navigate to **Settings → Business**. The **Brands Under \[Your Business]** panel on the right lists your Primary brand and any Secondary brands.

    <Frame>
      <img alt="Brands panel in Business Settings showing primary and secondary brands with a plus button to add a new brand" />
    </Frame>
  </Step>

  <Step title="Click the '+' button">
    In the Brands panel, click the **+** button in the top-right corner to open the new brand form.
  </Step>

  <Step title="Fill in the brand details">
    Complete the following fields:

    * **Brand Name** (required): Enter your brand name.
    * **Website URL** (required): Your brand's website, for example `https://www.yourcompany.com`.
    * **Support Email**: The email customers can use to reach support for this brand.
    * **Brand Description** (required): Describe your brand, products, and what makes it unique.
    * **Brand Logo**: Upload a logo to represent the brand on checkout, invoices, and payment links.

    Submit the form to create the brand. Products can now be tagged to this brand and payment links will display its branding.
  </Step>

  <Step title="Brand Selector">
    A Brand filter is now visible on Product creation.
  </Step>

  <Step title="Brand ID in Transactions">
    Transactions and Subscriptions have a Brand ID to help you identify which brand the transaction belongs to.
  </Step>
</Steps>

## Additional Points

* **No payout changes:** All funds, payout cycles and fees still flow to the business-level wallet and merchant bank account.
* **Brand ID on webhooks:** Payment, subscription, refund, dispute, license key, credit ledger entry, credit balance low, entitlement grant, dunning attempt, and abandoned checkout payloads all include a `brand_id`, so you can attribute them to a specific brand. Where an entity has no brand of its own, `brand_id` falls back to the business's primary brand. Payout payloads are business-level and do not carry a `brand_id`.
* **Suspensions:** If a brand is suspended, only its payment links stop. Other brands under the same business keep transacting.
* No changes to Storefront, Invoices, License Keys, Discount Codes, Payout Settings and any other business level features.


# One‑Time Payments
Source: https://docs.dodopayments.com/features/one-time-payment-products

Sell fixed‑price digital goods or services with a single upfront charge, no renewals.

<Info>
  One‑time payments let you sell lifetime access, downloads, or single‑use services with a single charge. There are no renewals, proration rules, or billing cycles. Just a clean, instant purchase experience.
</Info>

<CardGroup>
  <Card title="License Keys" icon="code" href="/features/license-keys">
    Issue unique license keys after purchase.
  </Card>

  <Card title="Digital Delivery" icon="code" href="/features/digital-product-delivery">
    Automatically deliver files and content after payment.
  </Card>

  <Card title="Payment Webhooks" icon="code" href="/developer-resources/webhooks/intents/payment">
    React to payment succeeded/failed and receipt events.
  </Card>

  <Card title="Refunds API" icon="code" href="/api-reference/refunds/post-refunds">
    Create full or partial refunds programmatically.
  </Card>
</CardGroup>

## What Are One‑Time Payments?

One‑time payments are fixed, up‑front purchases - ideal for:

* **Software licenses**: Lifetime or major‑version unlocks
* **Digital downloads**: E‑books, templates, graphics, or plugins
* **Services**: Audits, onboarding packages, or one‑off consulting
* **Courses and tickets**: Courses, workshops, or live sessions

## Key Benefits

* **Simple checkout**: No renewals or proration logic
* **Instant fulfillment**: Deliver licenses or files right away
* **Flexible pricing**: Discounts and taxes supported
* **Developer‑first**: Clear APIs for creation, refunds, and webhooks

## Creating One‑Time Products

Create products in your Dodo Payments dashboard, then sell them via hosted checkout, payment links, or your API.

<Frame>
  <img alt="One-Time Payment Products" />
</Frame>

### Product configuration

Configure the fields in the dashboard to define how your product appears and sells.

#### Product details

* **Product Name** (required): Display name shown in checkout and invoices
* **Product Description** (required): Clear value statement customers see before paying
* **Product Image** (required): PNG/JPG/WebP up to 3 MB
* **Brand**: Associate the product with a specific brand for theming and emails
* **Tax Category** (required): Choose the correct category to determine tax rules

<Tip>
  Pick the most accurate tax category to ensure correct tax collection per region.
</Tip>

#### Pricing

* **Pricing Type**: Choose <b>Single Payment</b>
* **Price** (required): Fixed charge with currency
* **Discount Applicable (%)**: Optional percentage discount displayed in checkout and invoices

<Warning>
  Changing product pricing affects only new purchases. Existing customers aren’t impacted.
</Warning>

#### Advanced settings

* **Tax Inclusive Pricing**: Display prices inclusive of applicable taxes
* **Generate license keys**: Issue a unique key after purchase. See <a href="/features/license-keys">License Keys</a>
* **Digital Product Delivery**: Deliver files or content automatically. See <a href="/features/digital-product-delivery">Digital Product Delivery</a>
* **Metadata**: Attach custom key–value pairs for internal tagging or integrations. See <a href="/api-reference/metadata">Metadata</a>

<Tip>
  Use metadata to store identifiers from your system (e.g., orderId) to reconcile events and receipts later.
</Tip>

## API Management

<AccordionGroup>
  <Accordion title="Create payments">
    Use `POST /checkouts` to create one‑time charges from products.

    <Card title="API Reference" icon="code" href="/api-reference/checkout-sessions/create">
      View the create payment API.
    </Card>
  </Accordion>

  <Accordion title="Refund payments">
    Use `POST /refunds` to create full or partial refunds.

    <Card title="API Reference" icon="code" href="/api-reference/refunds/post-refunds">
      Learn how to refund a payment.
    </Card>
  </Accordion>

  <Accordion title="List and retrieve payments">
    Use `GET /payments` to list payments and `GET /payments/{payment_id}` to retrieve one. Retrieve line items with `GET /payments/{payment_id}/line-items`.

    <Card title="List Payments" icon="code" href="/api-reference/payments/get-payments">
      Browse the listing API.
    </Card>

    <Card title="Get Payment Detail" icon="code" href="/api-reference/payments/get-payments-1">
      See the retrieval API.
    </Card>

    <Card title="Retrieve Line Items" icon="code" href="/api-reference/payments/retrieve-line-items">
      Inspect purchased items for a payment.
    </Card>
  </Accordion>

  <Accordion title="Payment webhooks">
    React to events like payment.succeeded or payment.failed in your backend.

    <Card title="Webhook Guide" icon="code" href="/developer-resources/webhooks/intents/payment">
      Handle payment lifecycle events.
    </Card>
  </Accordion>
</AccordionGroup>

## Common Use Cases

* **License‑based tools**: Unlock features with a one‑time key
* **Digital assets**: Themes, templates, icon sets, or media
* **Professional services**: Fixed‑fee implementation or setup
* **Education**: Course tickets and one‑off workshops

## Integration Examples

### Checkout Sessions (single payment)

Create a checkout session with a one‑time product in the cart:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_one_time', quantity: 1 }
  ]
});
```

## Best Practices

* **Clarify deliverables**: Tell buyers exactly what they get and how it’s delivered
* **Deliver instantly**: Use license keys or digital delivery for immediate access
* **Track with metadata**: Store your IDs for easy reconciliation

<Info>
  One‑time payments are the fastest path to selling fixed‑price products. Start simple, verify delivery, and iterate your offer based on conversion and feedback.
</Info>


# Pay What You Want Pricing
Source: https://docs.dodopayments.com/features/pay-what-you-want

Let customers choose their price above a minimum. Optionally show a suggested price. Optimized for one‑time purchases.

**Pay What You Want (PWYW)** lets customers decide how much they pay—at or above a merchant‑defined minimum. It increases engagement, encourages community support, and provides flexible pricing for digital products.

<Frame>
  <iframe title="Pay What You Want Pricing | Dodo Payments" />
</Frame>

## What Is Pay What You Want?

PWYW is a pricing model where customers set their own price within guardrails you define. It’s ideal for:

* **Digital products and media**: Templates, e‑books, courses, plugins
* **Experimental launches**: Early access, beta releases, time‑boxed promos
* **Bundles and extras**: Add a PWYW tier to boost participation

## Key Benefits

* **Customer‑driven pricing**: Buyers choose what they pay
* **Revenue floor**: Enforce a minimum to protect margins
* **Anchored expectations**: Optional suggested price to guide choices
* **Seamless checkout**: Hosted checkout and receipts handled for you
* **Developer‑first**: Clear APIs for creation, refunds, and webhooks

<Warning>
  PWYW is available only for **Single Payment** (one‑time) products.
</Warning>

## Creating Pay What You Want

Create a one‑time product and enable PWYW in your Dodo Payments dashboard. The sections below map directly to the creation form.

### Product creation

#### Product details

* **Product Name** (required): Display name shown in checkout and invoices
* **Product Description** (required): Clear value statement customers see before paying
* **Product Image** (required): PNG/JPG/WebP up to 3 MB
* **Brand**: Associate the product with a specific brand for theming and emails
* **Tax Category** (required): Choose the correct category to determine tax rules

<Tip>
  Pick the most accurate tax category to ensure correct tax collection per region.
</Tip>

#### Pricing

* **Pricing Type**: Choose <b>Single Payment</b>
* **Pay What You Want** (toggle): Enable to let buyers choose the amount
* **Minimum Price** (required): Lowest allowed amount a customer can pay
* **Suggested Price** (optional): Recommended amount shown on the product page

<Tip>
  Use metadata to store identifiers from your system (e.g., orderId) so you can reconcile events and receipts later.
</Tip>

#### Sharing A Link With A Fixed Amount

When you share a checkout link for a PWYW product from **Products**, open **Advanced Settings** and set a **Payment amount** to charge exactly that value instead of letting the buyer choose. The amount must be at or above the product's Minimum Price, and it is carried on the link as the `paymentAmount` query parameter in major currency units (e.g. `12.5` for \$12.50). Leave the field empty to keep the buyer-chooses-amount behaviour.

## API Management

<AccordionGroup>
  <Accordion title="Create checkout sessions (PWYW)">
    Use `POST /checkouts` to create one‑time checkout sessions from products. Checkout will prompt buyers to enter an amount that meets your PWYW minimum.

    <Card title="API Reference" icon="code" href="/api-reference/checkout-sessions/create">
      View the create checkout session API.
    </Card>
  </Accordion>

  <Accordion title="Refund payments">
    Use `POST /refunds` to create full or partial refunds. Customers are refunded the exact amount they paid.

    <Card title="API Reference" icon="code" href="/api-reference/refunds/post-refunds">
      Learn how to refund a payment.
    </Card>
  </Accordion>

  <Accordion title="List and retrieve">
    Use `GET /payments` to list payments and `GET /payments/{payment_id}` to retrieve one. Retrieve line items with `GET /payments/{payment_id}/line-items`.

    <Card title="List Payments" icon="code" href="/api-reference/payments/get-payments">
      Browse the listing API.
    </Card>

    <Card title="Get Payment Detail" icon="code" href="/api-reference/payments/get-payments-1">
      See the retrieval API.
    </Card>

    <Card title="Retrieve Line Items" icon="code" href="/api-reference/payments/retrieve-line-items">
      Inspect purchased items for a payment.
    </Card>
  </Accordion>

  <Accordion title="Payment webhooks">
    React to events like payment.succeeded or payment.failed in your backend.

    <Card title="Webhook Guide" icon="code" href="/developer-resources/webhooks/intents/payment">
      Handle payment lifecycle events.
    </Card>
  </Accordion>
</AccordionGroup>

## Common Use Cases

* **Digital assets**: Themes, templates, icon sets, media, or plugins
* **Content and education**: E‑books, courses, workshops with supporter pricing
* **Community & donations**: Fundraisers, open‑source sponsorships, creator support
* **Launch experiments**: Beta access and time‑boxed campaigns to gauge demand

## Integration Examples

### Checkout Sessions (single payment, PWYW)

Add a PWYW product to the cart. Checkout collects the buyer’s amount (respecting your minimum) — no extra fields are required.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_pwyw_demo', quantity: 1 }
  ],
  return_url: 'https://yoursite.com/checkout/success'
});
```

## Best Practices

* **Choose a sensible minimum**: Cover costs while keeping participation easy
* **Use a suggested price**: Anchor expectations to improve average order value
* **Explain value clearly**: Tell buyers what their contribution unlocks
* **A/B test campaigns**: Time‑box offers and experiment with messaging
* **Monitor distribution**: Track paid amounts to refine minimum and suggested price

<Info>
  PWYW is a flexible way to invite more customers in while preserving a revenue floor. Start simple, test thoroughly, and iterate based on conversion, contribution distribution, and refund rates.
</Info>


# Payment Methods
Source: https://docs.dodopayments.com/features/payment-methods

Complete guide to payment methods supported by Dodo Payments, including credit/debit cards, digital wallets, BNPL, UPI/Rupay, European options, and how to configure them for your checkout.

Dodo Payments supports a wide range of payment methods to help you serve customers globally. Turn on new payment methods instantly — no additional contracts, integrations, or merchant accounts needed.

## Why Offer Multiple Payment Methods?

<CardGroup>
  <Card title="Boost Conversion" icon="chart-line">
    Local methods increase sales 20-30% in target markets.
  </Card>

  <Card title="One Platform" icon="layer-group">
    All methods managed through a single API.
  </Card>

  <Card title="Smart Routing" icon="route">
    Right options shown based on location and device.
  </Card>
</CardGroup>

## How It Works

Payment methods are automatically presented to customers based on:

* **Customer Location** — Regional methods like iDEAL (Netherlands) or UPI (India) only appear for customers in those regions
* **Transaction Currency** — Payment methods are filtered by supported currencies
* **Device Type** — Apple Pay only appears on compatible Apple devices and browsers
* **Transaction Type** — Some methods don't support subscriptions or have minimum amounts

<Info>
  **Automatic Activation:** All payment methods are pre-configured and managed by Dodo Payments. No additional setup needed — they become available once your account is verified and live mode is enabled.
</Info>

## Supported Payment Methods

| Payment Method        | Supported Countries | Supported Currencies   | Subscriptions | Min Amount |
| :-------------------- | :------------------ | :--------------------- | :-----------: | :--------- |
| **Credit Cards**      | Global              | All currencies         |      Yes      | \$0.50     |
| **Debit Cards**       | Global              | All currencies         |      Yes      | \$0.50     |
| **Apple Pay**         | Global (Excl. IN)   | All currencies         |      Yes      | \$0.50     |
| **Google Pay**        | Global (Excl. IN)   | All currencies         |      Yes      | \$0.50     |
| **Amazon Pay**        | Global (Excl. IN)   | USD                    |       No      | \$0.50     |
| **Cash App Pay**      | US                  | USD                    |      Yes      | \$0.50     |
| **ACH Direct Debit**  | US                  | USD                    |       No      | \$0.50     |
| **SEPA Direct Debit** | Eurozone            | EUR                    |       No      | €0.50      |
| **Klarna**            | US, Europe          | USD, EUR, GBP + 7 more |      Yes      | \$50.01    |
| **Afterpay**          | US, UK              | USD, GBP               |       No      | \$50.01    |
| **UPI**               | India               | INR                    |     Yes\*     | ₹1         |
| **Rupay**             | India               | INR                    |     Yes\*     | ₹1         |
| **iDEAL**             | Netherlands         | EUR                    |       No      | €0.50      |
| **Bancontact**        | Belgium             | EUR                    |       No      | €0.50      |
| **EPS**               | Austria             | EUR                    |       No      | €0.50      |
| **Multibanco**        | Portugal            | EUR                    |       No      | €0.50      |
| **BLIK**              | Poland              | PLN                    |       No      | 2.00 PLN   |
| **Satispay**          | Europe              | EUR                    |      Yes      | €0.50      |
| **PAYCO**             | South Korea         | KRW                    |       No      | \~\$1.00   |
| **Naver Pay**         | South Korea         | KRW                    |      Yes      | \~\$1.00   |
| **Kakao Pay**         | South Korea         | KRW                    |      Yes      | \~\$1.00   |
| **RevolutPay**        | Global              | GBP                    |       No      | £0.50      |
| **Billie**            | Global              | GBP                    |       No      | £0.50      |
| **Pix**               | Brazil              | BRL                    |       No      | \$0.50     |
| **Stablecoins**       | Global (Excl. IN)   | USD                    |       No      | \$0.50     |
| **WeChat Pay**        | Global              | USD, CNY               |       No      | \$0.50     |

<Note>
  \*All Indian-issued cards (Visa, Mastercard, Rupay, etc.) and UPI support subscriptions with RBI-compliant mandates. The 48-hour processing delay applies to all Indian-issued cards and UPI. See the <a href="/features/payment-methods/india">India Payment Methods</a> page for details on mandate requirements.
</Note>

<Warning>
  **PayPal Support Paused:** PayPal is temporarily unavailable for new transactions. We'll update this page when restored.
</Warning>

## Payment Method Categories

<CardGroup>
  <Card title="Credit & Debit Cards" icon="credit-card" href="/features/payment-methods/cards">
    Accept Visa, Mastercard, Amex, Discover, JCB, UnionPay, and regional networks like Cartes Bancaires and Interac.
  </Card>

  <Card title="Digital Wallets" icon="wallet" href="/features/payment-methods/digital-wallets">
    Apple Pay, Google Pay, Amazon Pay, Cash App Pay, and RevolutPay for fast, secure one-tap checkout.
  </Card>

  <Card title="Buy Now Pay Later" icon="calendar-days" href="/features/payment-methods/bnpl">
    Klarna, Afterpay, and Billie installment options to increase average order value and conversion.
  </Card>

  <Card title="ACH Direct Debit" icon="building-columns" href="/features/payment-methods/ach">
    Bank account debits for US customers paying in USD, available on one-time payments.
  </Card>

  <Card title="India" icon="indian-rupee-sign" href="/features/payment-methods/india">
    UPI and Rupay cards with RBI-compliant subscription mandates for the Indian market.
  </Card>

  <Card title="Europe" icon="euro-sign" href="/features/payment-methods/europe">
    iDEAL (Netherlands), Bancontact (Belgium), EPS (Austria), Multibanco (Portugal), and BLIK (Poland).
  </Card>

  <Card title="South Korea" icon="won-sign" href="/features/payment-methods/south-korea">
    Kakao Pay, Naver Pay, and PAYCO wallets plus Korean local cards, billed in KRW.
  </Card>

  <Card title="Pix" icon="brazilian-real-sign" href="/features/payment-methods/pix">
    Instant bank transfers for the Brazilian market via QR code or copy-paste key.
  </Card>

  <Card title="Stablecoins" icon="dollar-sign" href="/features/payment-methods/stablecoins">
    Accept stablecoin payments from customers worldwide (excluding India), billed in USD.
  </Card>

  <Card title="WeChat Pay" icon="comment-dollar" href="/features/payment-methods/wechat">
    QR code payments for Chinese customers via WeChat, supporting USD and CNY.
  </Card>
</CardGroup>

## Business-Level Payment Method Disabling

You can disable specific payment methods at the business level from your dashboard. This applies across all checkout sessions for your business, without needing to configure it per product or session.

<Steps>
  <Step title="Navigate to Settings">
    Go to **Settings > Payment Methods** in the Dodo Payments dashboard.
  </Step>

  <Step title="Disable Payment Methods">
    Toggle off any payment methods you don't want to offer to customers.
  </Step>
</Steps>

<Tip>
  Use this to disable payment methods that have high fraud rates in your region, or to limit options to only the methods your business supports operationally.
</Tip>

<Info>
  Business-level settings act as a global filter. Per-checkout restrictions via `allowed_payment_method_types` further narrow the available methods within what's enabled at the business level.
</Info>

## Per-Checkout Payment Method Configuration

In addition to business-level settings, you can restrict which methods are shown for individual checkout sessions using `allowed_payment_method_types`:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
      allowed_payment_method_types: [
        'credit',
        'debit', 
        'apple_pay',
        'google_pay'
      ],
      return_url: 'https://example.com/success'
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    session = client.checkout_sessions.create(
        product_cart=[{"product_id": "pdt_123", "quantity": 1}],
        allowed_payment_method_types=[
            "credit",
            "debit",
            "apple_pay", 
            "google_pay"
        ],
        return_url="https://example.com/success"
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://test.dodopayments.com/checkouts \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "product_cart": [{"product_id": "pdt_123", "quantity": 1}],
        "allowed_payment_method_types": ["credit", "debit", "apple_pay", "google_pay"],
        "return_url": "https://example.com/success"
      }'
    ```
  </Tab>
</Tabs>

### Available Method Types

| Type                | Description                                 |
| :------------------ | :------------------------------------------ |
| `credit`            | Credit cards (Visa, Mastercard, Amex, etc.) |
| `debit`             | Debit cards                                 |
| `apple_pay`         | Apple Pay                                   |
| `google_pay`        | Google Pay                                  |
| `amazon_pay`        | Amazon Pay                                  |
| `cashapp`           | Cash App Pay                                |
| `ach`               | ACH Direct Debit (United States)            |
| `klarna`            | Klarna BNPL                                 |
| `afterpay_clearpay` | Afterpay / Clearpay                         |
| `upi_collect`       | UPI Collect (QR code)                       |
| `ideal`             | iDEAL (Netherlands)                         |
| `bancontact_card`   | Bancontact (Belgium)                        |
| `eps`               | EPS (Austria)                               |
| `multibanco`        | Multibanco (Portugal)                       |
| `blik`              | BLIK (Poland)                               |
| `sepa`              | SEPA Direct Debit (Eurozone)                |
| `satispay`          | Satispay (Europe)                           |
| `payco`             | PAYCO (South Korea)                         |
| `naver_pay`         | Naver Pay (South Korea)                     |
| `kakao_pay`         | Kakao Pay (South Korea)                     |
| `revolut_pay`       | RevolutPay                                  |
| `billie`            | Billie B2B BNPL                             |
| `pix`               | Pix (Brazil)                                |
| `crypto_currency`   | Stablecoins                                 |
| `we_chat_pay`       | WeChat Pay                                  |

<Warning>
  Always include `credit` and `debit` as fallbacks. If all specified payment methods are unavailable for a customer, the checkout will fail.
</Warning>

### API Endpoints

<CardGroup>
  <Card title="Checkout Sessions" icon="cart-shopping" href="/api-reference/checkout-sessions/create">
    Create checkout with allowed methods.
  </Card>

  <Card title="Payments" icon="credit-card" href="/api-reference/payments/post-payments">
    One-time payments with method filtering.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/api-reference/subscriptions/post-subscriptions">
    Recurring payments with method restrictions.
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Match methods to your market">
    Include regional payment methods for your target markets. iDEAL captures \~60% of online payments in the Netherlands; UPI dominates in India. Omitting these methods significantly hurts conversion.
  </Accordion>

  <Accordion title="Always provide card fallbacks">
    Even when targeting specific methods, include `credit` and `debit` as fallbacks. Not all customers have access to every payment method.
  </Accordion>

  <Accordion title="Consider transaction minimums">
    BNPL methods have per-provider minimums: Klarna and Afterpay require \$50.01. Don't include them for products outside these ranges — they simply won't appear, which is fine.
  </Accordion>

  <Accordion title="Test across regions and devices">
    Use test mode to verify payment method availability for different customer locations, currencies, and device types before going live.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Payment method not appearing">
    **Check these factors:**

    1. Method included in `allowed_payment_method_types`?
    2. Customer location matches method's supported region?
    3. Transaction currency supported by method?
       4\. Transaction amount within the method's supported range (e.g., Klarna/Afterpay min \$50.01)?
    4. For subscriptions: method supports recurring payments?

    **Solution:** Remove `allowed_payment_method_types` temporarily to see all eligible methods, then narrow down the issue.
  </Accordion>

  <Accordion title="Unexpected methods appearing">
    **Possible causes:**

    * `allowed_payment_method_types` not being passed correctly
    * Parameter formatted incorrectly (must be array of strings)

    **Solution:** Log your API request payload and verify the parameter structure.
  </Accordion>

  <Accordion title="Regional method not available">
    **Check:**

    * Customer billing address matches method's region
    * Currency is set correctly (e.g., EUR for iDEAL)
    * Adaptive Currency is enabled if customer is international

    **Solution:** Verify billing address country code and currency in your API request.
  </Accordion>

  <Accordion title="Indian payment method issues">
    UPI and Rupay subscriptions have unique requirements including 48-hour processing delays and RBI mandate limits.

    **See:** <a href="/features/payment-methods/india">India Payment Methods</a> for complete guidance.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    Supported currencies and automatic conversion.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    Test cards, UPI IDs, and wallet testing.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Recurring billing and payment method updates.
  </Card>
</CardGroup>

## Expanding Payment Options

We continuously add new payment methods. If you need a specific method not listed here, contact us at [support@dodopayments.com](mailto:support@dodopayments.com).


# ACH Direct Debit
Source: https://docs.dodopayments.com/features/payment-methods/ach

Accept ACH Direct Debit payments from US customers paying in USD. Learn about bank account debits, settlement timing, and configuration for one-time payments.

ACH Direct Debit lets customers in the United States pay directly from their bank account instead of using a card. It runs on the Automated Clearing House network and is offered on USD checkouts for one-time payments.

## Why Offer ACH Direct Debit?

<CardGroup>
  <Card title="Lower Processing Cost" icon="piggy-bank">
    Bank debits typically cost less to process than card payments, especially on high-value orders.
  </Card>

  <Card title="No Card Required" icon="building-columns">
    Reach US customers who prefer paying from a bank account or who don't want to use a card for large purchases.
  </Card>

  <Card title="Higher Value Orders" icon="chart-line">
    The cost advantage over cards grows with order value, making ACH well suited to large one-time purchases.
  </Card>
</CardGroup>

## Overview

| Detail                  | Value           |
| :---------------------- | :-------------- |
| **Billing Currency**    | USD             |
| **Supported Countries** | United States   |
| **Subscriptions**       | No              |
| **Min Amount**          | \$0.50          |
| **Settlement**          | 4 business days |

<Warning>
  ACH Direct Debit is not instant. A payment takes **4 business days** to confirm, so do not treat authorization as settlement — fulfill only once the payment reaches a succeeded state.
</Warning>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant ACH as ACH Network
    participant Bank

    Customer->>Checkout: Select ACH Direct Debit
    Checkout->>Customer: Prompt for bank account authorization
    Customer->>Checkout: Authorize the debit
    Checkout->>Dodo: Create payment
    Dodo->>ACH: Submit debit request
    Note over ACH,Bank: Clearing takes 4 business days
    ACH->>Bank: Debit customer account
    Bank->>ACH: Confirm or return
    ACH->>Dodo: Final status
    Dodo->>Checkout: Payment succeeded or failed
```

## Customer Experience

1. Customer selects ACH Direct Debit at checkout
2. Customer authorizes the debit against their US bank account
3. The payment is submitted to the ACH network and enters a processing state
4. Clearing completes over the following business days
5. The payment moves to a succeeded state, or fails if the bank returns it

<Info>
  Because clearing is asynchronous, rely on [webhooks](/developer-resources/webhooks) to learn the final outcome rather than the checkout redirect. A successful redirect only means the customer authorized the debit.

  The payment emits `payment.processing` once the debit is submitted, then `payment.succeeded` or `payment.failed` when clearing completes. Only `payment.succeeded` is safe to fulfill on.
</Info>

## Availability

ACH Direct Debit appears at checkout when all of the following are true:

* **Billing currency** is `USD`
* **Billing country** is `US`
* The transaction is a **one-time payment**

<Note>
  ACH Direct Debit is not available for subscriptions. Its multi-day clearing window makes it unsuitable for recurring billing cycles. For recurring payments, use cards or another method that supports subscriptions — see the [Payment Methods overview](/features/payment-methods).
</Note>

## Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['ach', 'credit', 'debit'],
  billing_currency: 'USD',
  billing_address: {
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://example.com/success'
});
```

<Note>
  ACH Direct Debit requires a **USD** billing currency and a **US** billing address. If you quote your prices in another currency, enable [Adaptive Currency](/features/adaptive-currency) so US customers are billed in USD and ACH becomes available.
</Note>

## API Method Type

| Type  | Method           | Country       |
| :---- | :--------------- | :------------ |
| `ach` | ACH Direct Debit | United States |

## Refunds and Disputes

Refunds and disputes for ACH payments use the same APIs and dashboard flows as every other payment method — there is no ACH-specific handling to implement.

<Warning>
  Because ACH payments can be returned by the customer's bank after they appear to have gone through, avoid issuing refunds until the original payment has reached a succeeded state.
</Warning>

## Testing

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Set currency and billing address">
    Set the billing currency to `USD` and the billing address country to `US`.
  </Step>

  <Step title="Include `ach` in allowed methods">
    Pass `ach` in `allowed_payment_method_types`, or omit the field entirely to show every eligible method.
  </Step>

  <Step title="Enter the test bank details">
    Enter one of the test routing and account number pairs below, then confirm your webhook handler receives the final payment status.
  </Step>
</Steps>

### Test Bank Accounts

Customers enter their account and routing number directly at checkout. In test mode, use the routing number `110000000` with any of the account numbers below to force a specific outcome.

| Account Number | Routing Number | Behavior                                                                                         |
| :------------- | :------------- | :----------------------------------------------------------------------------------------------- |
| `000123456789` | `110000000`    | The payment succeeds.                                                                            |
| `000222222227` | `110000000`    | The payment fails due to insufficient funds.                                                     |
| `000111111113` | `110000000`    | The payment fails because the account is closed.                                                 |
| `000111111116` | `110000000`    | The payment fails because no account is found.                                                   |
| `000333333335` | `110000000`    | The payment fails because debits aren't authorized on the account.                               |
| `000444444440` | `110000000`    | The payment fails due to an invalid currency.                                                    |
| `000555555559` | `110000000`    | The payment succeeds, then triggers a dispute.                                                   |
| `000000000009` | `110000000`    | The payment stays in processing indefinitely, which is useful for exercising a pending-state UI. |

<Note>
  Most test payments reach a final status far faster than the live clearing window, so you don't need to wait days to verify your integration. The exception is `000000000009`, which is designed to stay in processing.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Don't fulfill on authorization">
    ACH authorization is not payment. Wait for the payment to reach a succeeded state before granting access or shipping — a debit can still be returned by the customer's bank.
  </Accordion>

  <Accordion title="Set customer expectations at checkout">
    Tell customers that bank payments don't clear instantly. This reduces support tickets asking why an order is still pending.
  </Accordion>

  <Accordion title="Provide card fallbacks">
    Always include `credit` and `debit` alongside `ach` so customers who need instant access to your product can choose a faster method.
  </Accordion>

  <Accordion title="Use ACH for high-value one-time purchases">
    The cost advantage of ACH grows with order value, so it is most useful on large one-time purchases rather than small ones.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ACH not appearing at checkout">
    **Check:**

    1. Billing currency set to `USD`?
    2. Customer billing country is `US`?
    3. `ach` included in `allowed_payment_method_types`?
    4. Is this a one-time payment? ACH is not offered on subscriptions.

    **Solution:** Remove `allowed_payment_method_types` temporarily to see all eligible methods, then verify the billing currency and address country in your API request.
  </Accordion>

  <Accordion title="ACH not appearing on a subscription checkout">
    **Cause:** ACH Direct Debit is only offered for one-time payments.

    **Solution:** Use cards or another subscription-capable method for recurring billing.
  </Accordion>

  <Accordion title="Payment stuck in processing">
    **Cause:** This is expected. ACH payments remain in a processing state for the full clearing window, far longer than card payments.

    **Solution:** Wait for the final webhook. Do not retry the payment — retrying can debit the customer twice.
  </Accordion>

  <Accordion title="Payment failed after initially succeeding at checkout">
    **Cause:** The customer's bank returned the debit — most commonly for insufficient funds or a closed account.

    **Solution:** Treat the payment as failed and ask the customer to retry with another payment method. Always gate fulfillment on the succeeded state to avoid this.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    Currency support and automatic conversion.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle delayed payment confirmations asynchronously.
  </Card>
</CardGroup>


# Buy Now Pay Later (BNPL)
Source: https://docs.dodopayments.com/features/payment-methods/bnpl

Offer Klarna, Afterpay, and Billie installment payments to increase average order value and conversion. Learn about eligibility, minimum amounts, and testing.

Buy Now Pay Later (BNPL) lets customers split purchases into interest-free installments, increasing average order value by 20-50% and conversion rates by 10-30% for eligible transactions.

## Why Offer BNPL?

<CardGroup>
  <Card title="Higher AOV" icon="chart-line">
    Customers spend more when they can spread payments over time. Average order value increases 20-50%.
  </Card>

  <Card title="Better Conversion" icon="percent">
    Removing payment friction at checkout. Conversion rates improve 10-30% for high-ticket items.
  </Card>

  <Card title="Zero Risk" icon="shield-check">
    BNPL providers handle credit risk and collections. You receive full payment upfront.
  </Card>
</CardGroup>

## Supported Providers

### Klarna

| Feature           | Details                                          |
| :---------------- | :----------------------------------------------- |
| **Availability**  | US + 19 European countries                       |
| **Currencies**    | USD, EUR, GBP, DKK, NOK, SEK, CZK, RON, PLN, CHF |
| **Minimum**       | \$50.01 (or equivalent)                          |
| **Subscriptions** | Yes                                              |

**Supported Countries:** Austria, Belgium, Czech Republic, Denmark, Finland, France, Germany, Greece, Ireland, Italy, Netherlands, Norway, Poland, Portugal, Romania, Spain, Sweden, Switzerland, United Kingdom, United States

**Payment Options:**

* **Pay in 4** — Split into 4 interest-free payments
* **Pay in 30 days** — Full payment due in 30 days
* **Financing** — Longer-term installment plans

### Afterpay (Clearpay)

| Feature           | Details                 |
| :---------------- | :---------------------- |
| **Availability**  | US, UK                  |
| **Currencies**    | USD, GBP                |
| **Minimum**       | \$50.01 (or equivalent) |
| **Subscriptions** | No                      |

**Payment Options:**

* **Pay in 4** — 4 interest-free payments every 2 weeks

<Note>
  In the UK, Afterpay operates as "Clearpay" but uses the same API type (`afterpay_clearpay`).
</Note>

### Billie

| Feature           | Details |
| :---------------- | :------ |
| **Availability**  | Global  |
| **Currencies**    | GBP     |
| **Minimum**       | None    |
| **Subscriptions** | No      |

**About Billie:**
Billie is a B2B Buy Now Pay Later solution that enables businesses to offer flexible payment terms to their customers. It's designed for business-to-business transactions where buyers need invoice-based payment options.

**Payment Options:**

* **Invoice Payment** — Pay within agreed payment terms
* **Flexible Terms** — Business-friendly payment schedules

## Configuration

### API Method Types

| Type                | Provider            |
| :------------------ | :------------------ |
| `klarna`            | Klarna              |
| `afterpay_clearpay` | Afterpay / Clearpay |
| `billie`            | Billie (B2B)        |

### Example

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'customer@example.com',
    name: 'Jane Smith'
  },
  billing_address: {
    country: 'US',
    zipcode: '10001'
  },
  return_url: 'https://example.com/success'
});
```

<Warning>
  Always include `credit` and `debit` as fallbacks. Not all customers are eligible for BNPL, and transactions below the provider's minimum won't qualify.
</Warning>

## Transaction Amount Limits

Each BNPL provider has its own minimum (and sometimes maximum) transaction amount:

| Provider | Minimum | Maximum |
| :------- | :------ | :------ |
| Klarna   | \$50.01 | —       |
| Afterpay | \$50.01 | —       |

Transactions outside these thresholds:

* BNPL options won't appear at checkout
* No error is thrown — options simply don't show
* Card payments remain available

This is expected behavior. Don't include a BNPL method in `allowed_payment_method_types` if your product price is unlikely to fall within that provider's supported range.

## How Installments Work

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant BNPL Provider
    
    Customer->>Checkout: Select Klarna/Afterpay
    Checkout->>Dodo: Process payment
    Dodo->>BNPL Provider: Create installment plan
    BNPL Provider->>Customer: Approve/Deny based on credit
    BNPL Provider->>Dodo: Full payment (if approved)
    Dodo->>You: Payout (full amount)
    BNPL Provider->>Customer: Collect installments over time
```

**Key points:**

* You receive the **full payment upfront** from the BNPL provider
* The BNPL provider handles **credit risk and collections**
* Customer pays the provider directly over **4 installments** (typically)
* **No chargebacks** from installment failures — that's the provider's risk

## Testing

### Klarna Test Data

Use these details in test mode:

| Field             | Approved                                      | Denied                                                      |
| :---------------- | :-------------------------------------------- | :---------------------------------------------------------- |
| **Date of Birth** | 07-10-1970                                    | 07-10-1970                                                  |
| **First Name**    | Test                                          | Test                                                        |
| **Last Name**     | Person-us                                     | Person-us                                                   |
| **Email**         | [customer@email.us](mailto:customer@email.us) | [customer+denied@email.us](mailto:customer+denied@email.us) |
| **Street**        | Amsterdam Ave                                 | Amsterdam Ave                                               |
| **House Number**  | 509                                           | 509                                                         |
| **City**          | New York                                      | New York                                                    |
| **State**         | New York                                      | New York                                                    |
| **Postal Code**   | 10024-3941                                    | 10024-3941                                                  |
| **Phone**         | +13106683312                                  | +13106354386                                                |

<Note>
  Transaction must be at least \$50 for Klarna to appear as an option.
</Note>

### Afterpay Testing

<Steps>
  <Step title="Select Afterpay">
    Choose Afterpay in checkout and click Pay.
  </Step>

  <Step title="Successful payment">
    Use any valid email and shipping address.
  </Step>

  <Step title="Failed authentication">
    To test failure: close the Afterpay modal on the redirect page. Payment status transitions to `requires_payment_method`.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Target high-ticket items">
    BNPL works best for products $100-$1000. The value proposition of "pay over time" is most compelling in this range.
  </Accordion>

  <Accordion title="Show installment amounts">
    "4 payments of $25" is more compelling than "$100 with Klarna". Display the per-payment amount when possible.
  </Accordion>

  <Accordion title="Don't force BNPL for low-value products">
    Under $50, BNPL won't appear anyway. Under $100, most customers prefer cards. Focus BNPL promotion on higher-ticket items.
  </Accordion>

  <Accordion title="Collect billing address">
    BNPL providers require billing information for credit checks. Ensure your checkout collects full address details.
  </Accordion>

  <Accordion title="Set clear expectations">
    Customers should understand they're entering a credit agreement with Klarna/Afterpay, not with you.
  </Accordion>
</AccordionGroup>

## Limitations

### No Subscriptions

BNPL payment methods **do not support recurring payments**. For subscription products, use cards or other recurring-compatible methods.

### Credit-Based Approval

BNPL providers perform instant credit checks. Not all customers will be approved. Approval rates vary by:

* Customer credit history with the provider
* Transaction amount
* Customer location

### Currency & Country Mapping

Each currency is restricted to its corresponding region:

| Currency | Supported Countries                                                                                                                                                                                        |
| :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **USD**  | United States only                                                                                                                                                                                         |
| **EUR**  | All supported European countries (Austria, Belgium, Czech Republic, Denmark, Finland, France, Germany, Greece, Ireland, Italy, Netherlands, Norway, Poland, Portugal, Romania, Spain, Sweden, Switzerland) |
| **GBP**  | United Kingdom and all supported European countries                                                                                                                                                        |

Other Klarna-supported currencies (DKK, NOK, SEK, CZK, RON, PLN, CHF) work in their respective countries.

<Info>
  For example, a USD transaction will only show BNPL options to customers in the US. A EUR transaction will show BNPL options across all supported European countries. A GBP transaction will show BNPL options to customers in the UK and all supported European countries.
</Info>

| Provider | Supported Currencies                             |
| :------- | :----------------------------------------------- |
| Klarna   | USD, EUR, GBP, DKK, NOK, SEK, CZK, RON, PLN, CHF |
| Afterpay | USD (US), GBP (UK)                               |

## Troubleshooting

<AccordionGroup>
  <Accordion title="BNPL not appearing at checkout">
    **Check:**

    1. Transaction amount within the provider's supported range? (Klarna/Afterpay: min \$50.01)
    2. Customer location in supported country?
    3. Currency supported by BNPL provider?
    4. BNPL method included in `allowed_payment_method_types`?

    **Solution:** Most commonly, the transaction is below the minimum or above the maximum. Verify the amount falls within the provider's supported range.
  </Accordion>

  <Accordion title="Customer denied by BNPL provider">
    **Causes:**

    * Insufficient credit history with provider
    * Too many active installment plans
    * Failed identity verification

    **Solution:** This is expected for some customers. Ensure card fallbacks are available. Don't expose specific denial reasons.
  </Accordion>

  <Accordion title="Payment stuck in pending">
    **Cause:** Customer didn't complete authentication flow with BNPL provider.

    **Solution:** Payment will timeout and fail. Customer can retry or use a different method.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    All test data for payment methods.
  </Card>

  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    Currency support and conversion.
  </Card>
</CardGroup>


# Credit & Debit Cards
Source: https://docs.dodopayments.com/features/payment-methods/cards

Accept all major credit and debit card networks globally with Dodo Payments. Learn about 3D Secure, saved cards, tokenization, and regional card support.

Card payments are the foundation of online payments, accepted globally and trusted by customers worldwide. Dodo Payments supports all major card networks with built-in fraud protection and PCI compliance.

## Supported Card Networks

### Global Networks

| Network              | Coverage                                |
| :------------------- | :-------------------------------------- |
| **Visa**             | Global leader, 4B+ cards worldwide      |
| **Mastercard**       | Global reach, strong security features  |
| **American Express** | Premium cardholders, higher spending    |
| **Discover**         | US-focused, growing globally            |
| **JCB**              | Leading in Japan, expanding across Asia |
| **UnionPay**         | Dominant in China, 8B+ cards            |
| **Diners Club**      | Premium international travelers         |

### Regional Networks

| Network                | Region                    |
| :--------------------- | :------------------------ |
| **Interac**            | Canada's debit network    |
| **Cartes Bancaires**   | France's national network |
| **Korean Local Cards** | Korean domestic networks  |
| **Rupay**              | India's national network  |

## Configuration

Use these values in `allowed_payment_method_types`:

| Type     | Description      |
| :------- | :--------------- |
| `credit` | All credit cards |
| `debit`  | All debit cards  |

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

<Tip>
  Include both `credit` and `debit` unless you have a specific reason to exclude one. Debit cards are preferred by many customers and often have lower fees.
</Tip>

## 3D Secure Authentication

3D Secure (3DS) adds an authentication layer that reduces fraud and chargebacks by verifying the cardholder's identity.

### When 3DS is Triggered

3DS is automatically triggered when:

* Required by the card network
* Required by regional regulations (e.g., PSD2 in Europe)
* The transaction is flagged as high-risk

### Force 3DS

You can require 3DS on all transactions:

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  force_3ds: true,
  return_url: 'https://example.com/success'
});
```

<Note>
  Enabling 3DS for all transactions reduces fraud but may slightly decrease conversion as some customers abandon during authentication.
</Note>

### Handling Authentication Failures

When a payment needs 3DS authentication, the payment moves through intermediate states before it succeeds or fails:

| Status                     | Meaning                                                                                                                         | What to do                                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `requires_customer_action` | The customer must complete a 3DS challenge                                                                                      | Have the customer complete authentication during checkout                                                              |
| `requires_payment_method`  | The customer never provided a payment method (didn't enter details or abandoned the prompt) — usually a drop-off, not a decline | Re-engage the customer to complete checkout; see [Abandoned Cart Recovery](/features/recovery/abandoned-cart-recovery) |

If authentication does not complete, the payment fails with one of these decline codes:

* `AUTHENTICATION_FAILURE` — the customer could not be authenticated.
* `AUTHENTICATION_REQUIRED` — authentication is required but was not performed.
* `AUTHENTICATION_TIMEOUT` — the customer did not respond in time.

See the [Transaction Failures](/api-reference/transaction-failures) reference for the recommended action for each.

#### At Checkout vs. on Renewal

* **At checkout (customer present):** The customer is present, so the 3DS challenge is shown during checkout. If it fails, ask them to retry or use another card.
* **On subscription renewal (customer not present):** The customer is not present, so a 3DS challenge cannot be displayed in real time. If a renewal requires authentication, the subscription moves to `on_hold`. Recover it by prompting the customer to return and update their payment method — see [Handle Payment Failures](/developer-resources/handle-payment-failures) and [Subscription Dunning](/features/recovery/subscription-dunning).

## Saved Payment Methods

Customers can save their cards for faster future checkouts.

<CardGroup>
  <Card title="Tokenized" icon="lock">
    Original card numbers never stored.
  </Card>

  <Card title="PCI Compliant" icon="shield-check">
    Dodo handles all compliance.
  </Card>

  <Card title="Customer-Scoped" icon="user">
    Cards tied to specific customers.
  </Card>
</CardGroup>

### Enable Saved Cards

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  show_saved_payment_methods: true,
  customer: { customer_id: 'cus_existing_123' },
  return_url: 'https://example.com/success'
});
```

### One-Click Purchases

```javascript theme={null}
// Get customer's saved payment methods
const methods = await client.customers.retrievePaymentMethods('cus_123');

// Use saved card for instant checkout
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  payment_method_id: methods.items[0].payment_method_id,
  confirm: true,
  return_url: 'https://example.com/success'
});
```

## Testing

<Tabs>
  <Tab title="Successful Payments">
    | Region | Brand      | Card Number        | Expiry | CVV |
    | :----- | :--------- | :----------------- | :----- | :-- |
    | US     | Visa       | `4242424242424242` | 06/32  | 123 |
    | US     | Mastercard | `5555555555554444` | 06/32  | 123 |
    | India  | Visa       | `4576238912771450` | 06/32  | 123 |
    | India  | Mastercard | `5409162669381034` | 06/32  | 123 |
  </Tab>

  <Tab title="Declined Payments">
    | Region | Brand      | Card Number        | Scenario           |
    | :----- | :--------- | :----------------- | :----------------- |
    | US     | Visa       | `4000000000000002` | Generic decline    |
    | US     | Mastercard | `4000000000009995` | Insufficient funds |
    | India  | Visa       | `4706131211212123` | Generic decline    |
    | India  | Mastercard | `5105105105105100` | Generic decline    |
  </Tab>
</Tabs>

<Warning>
  Test cards only work in test mode. Never use them for production transactions.
</Warning>

## Security & Compliance

| Feature             | Description                        |
| :------------------ | :--------------------------------- |
| **PCI DSS Level 1** | Highest level of certification     |
| **Tokenization**    | Card numbers immediately tokenized |
| **Fraud Scoring**   | Real-time risk assessment          |
| **AVS**             | Address Verification Service       |
| **CVV Validation**  | Security code verification         |
| **3D Secure**       | Cardholder authentication          |

## Best Practices

<AccordionGroup>
  <Accordion title="Accept all major networks">
    Don't restrict card types unless necessary. Customers expect their preferred card to work.
  </Accordion>

  <Accordion title="Display card logos">
    Show Visa, Mastercard, Amex logos on your checkout to build trust.
  </Accordion>

  <Accordion title="Handle declines gracefully">
    Show clear error messages. Don't expose raw error codes to customers.
  </Accordion>

  <Accordion title="Enable saved cards for returning customers">
    Saved payment methods significantly boost conversion for repeat purchases.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Card declined">
    **Causes:** Insufficient funds, card expired, incorrect CVV, bank fraud protection.

    **Solution:** Ask customer to verify details or try a different card. Look up the specific decline `Error Code` and its recommended action in the [Transaction Failures](/api-reference/transaction-failures) reference, and see [Handle Payment Failures](/developer-resources/handle-payment-failures) for programmatic handling.
  </Accordion>

  <Accordion title="3DS authentication failed">
    **Causes:** Customer abandoned, bank system unavailable, timeout.

    **Solution:** Retry or ask customer to contact their bank. See [Handling Authentication Failures](#handling-authentication-failures) for the payment states and decline codes involved.
  </Accordion>

  <Accordion title="Card not supported">
    **Causes:** Regional card not supported, prepaid restrictions.

    **Solution:** Customer should try a different card from a major network.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="layer-group" href="/features/payment-methods">
    All supported payment methods.
  </Card>

  <Card title="Upsells & Downsells" icon="arrow-up-right-dots" href="/features/upsells-and-downsells">
    One-click purchases with saved cards.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    Complete testing guide.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Recurring billing with cards.
  </Card>
</CardGroup>


# Digital Wallets
Source: https://docs.dodopayments.com/features/payment-methods/digital-wallets

Accept Apple Pay, Google Pay, Amazon Pay, Cash App Pay, and RevolutPay for fast, secure one-tap checkout. Learn about setup, domain verification, and testing.

Digital wallets let customers pay with a single tap using payment methods saved on their devices. They offer higher conversion rates, stronger security through tokenization, and a streamlined checkout experience.

## Supported Wallets

| Wallet           | Availability         | Currencies | Subscriptions | Setup Required      |
| :--------------- | :------------------- | :--------- | :-----------: | :------------------ |
| **Apple Pay**    | Global (excl. India) | All        |      Yes      | Domain verification |
| **Google Pay**   | Global (excl. India) | All        |      Yes      | None                |
| **Amazon Pay**   | Global (excl. India) | USD        |       No      | None                |
| **Cash App Pay** | US only              | USD        |      Yes      | None                |
| **RevolutPay**   | Global               | GBP        |       No      | None                |

<Warning>
  **PayPal Support Paused:** PayPal is temporarily unavailable for new transactions.
</Warning>

## Apple Pay

Apple Pay allows customers to pay using cards saved in their Apple Wallet, with Face ID or Touch ID authentication.

<Info>
  Apple Pay is offered for subscriptions even when the first charge is \*\*$0** (for example, free trials) so the payment mandate can be set up at signup. For one-time payments, Apple Pay is only shown when the amount is greater than $0.
</Info>

### Requirements

* **Devices:** iOS 17+, iPadOS 17+, Safari 17+ on macOS
* **Protocol:** HTTPS required
* **Domain:** Must be verified with Apple

### Domain Verification

<Info>
  Domain verification is only required for **inline (embedded) checkout**. Overlay checkout, hosted checkout, and payment links don't need it.
</Info>

<Steps>
  <Step title="Open Wallet domains">
    In your dashboard, go to **Settings → Payment Methods** and, on the **Apple Pay** row, click **Manage domains**.

    <Frame>
      <img alt="Manage domains button on the Apple Pay row in Payment Methods settings" />
    </Frame>
  </Step>

  <Step title="Download the domain association file">
    From the Wallet domains panel, download the association file.

    <Frame>
      <img alt="Wallet domains panel with the Download file button" />
    </Frame>
  </Step>

  <Step title="Register your domain">
    Click **Register domain** and enter the domain where you embed checkout (e.g., `shop.example.com`), then **Continue**.

    <Frame>
      <img alt="Register a domain form with a domain entered" />
    </Frame>
  </Step>

  <Step title="Host the file on your domain">
    Upload to your server at:

    ```
    https://shop.example.com/.well-known/apple-developer-merchantid-domain-association
    ```

    The file must be served over HTTPS, accessible without redirects, and served with `Content-Type: application/octet-stream` or `text/plain`.
  </Step>

  <Step title="Verify the domain">
    Click **Verify domain**. Dodo Payments checks the hosted file and submits your domain to Apple.

    <Frame>
      <img alt="Verify your domain screen with the association file host path and Verify domain button" />
    </Frame>
  </Step>

  <Step title="Confirm it's active">
    When the status shows **Active**, Apple Pay is live for that domain. Use the **Enabled** toggle to turn it on or off per domain.

    <Frame>
      <img alt="Wallet domains list showing domains with an Active Apple Pay status and Enabled toggles" />
    </Frame>
  </Step>

  <Step title="Test the integration">
    1. Open checkout on an Apple device
    2. Verify Apple Pay button appears
    3. Complete a test transaction
  </Step>
</Steps>

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['apple_pay', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

## Google Pay

Google Pay allows customers to pay using cards saved in their Google account, with built-in fraud protection.

### Requirements

* **Browsers:** Chrome (desktop/mobile), Safari, Firefox
* **Devices:** Android devices with Google Pay app
* **Settings:** "Allow sites to check if you have payment methods" enabled in Chrome

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['google_pay', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

<Info>
  No domain verification needed for Google Pay — it works automatically once your account is live.
</Info>

## Amazon Pay

Amazon Pay lets customers use their Amazon account credentials and saved payment methods for a familiar checkout experience.

### Availability

* **Region:** Global, excluding India
* **Currency:** USD only
* **Subscriptions:** Not supported

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['amazon_pay', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

## Cash App Pay

Cash App Pay enables payments from Cash App, popular among US consumers for peer-to-peer payments.

### Availability

* **Region:** US only
* **Currency:** USD only
* **Subscriptions:** Supported

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['cashapp', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

## RevolutPay

RevolutPay enables fast, seamless payments for Revolut users globally, leveraging their existing Revolut account balance or linked cards.

### Availability

* **Region:** Global
* **Currency:** GBP only
* **Subscriptions:** Not supported

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['revolut_pay', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

## Testing

### Apple Pay Testing

<Steps>
  <Step title="Use test mode">
    Enable test mode in your Dodo Payments dashboard.
  </Step>

  <Step title="Add a card to Apple Wallet">
    Add a real card to your Apple Wallet. In test mode, the card won't be charged.
  </Step>

  <Step title="Complete test purchase">
    Open checkout on an Apple device and complete the Apple Pay flow.
  </Step>
</Steps>

<Warning>
  Apple Pay requires HTTPS. It won't appear on `localhost` without proper SSL setup.
</Warning>

### Google Pay Testing

<Steps>
  <Step title="Join the test card group">
    [Join the Google Pay test card group](https://groups.google.com/g/googlepay-test-mode-stub-data) to get test cards automatically added to your wallet.
  </Step>

  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Complete test purchase">
    Select one of the test cards in Google Pay to complete the transaction.
  </Step>
</Steps>

### Amazon Pay & Cash App Pay

Use your test API keys and follow the standard checkout flow. Test transactions will be simulated without actual charges.

## SDK Support

### Web SDKs

All digital wallets are fully supported in:

* Overlay Checkout
* Inline Checkout
* Direct API integration

### Mobile SDKs (Checkout)

The [Android](/developer-resources/sdks/android), [iOS](/developer-resources/sdks/ios),
[React Native](/developer-resources/sdks/react-native), and
[Flutter](/developer-resources/sdks/flutter) checkout SDKs open Dodo's hosted
checkout in the platform's real browser surface (`SFSafariViewController` /
Chrome Custom Tabs), not a WebView, so Apple Pay and Google Pay work the
same way they do on the web. See the [Mobile Integration Guide](/developer-resources/mobile-integration) for setup.

## Best Practices

<AccordionGroup>
  <Accordion title="Prioritize wallets on mobile">
    Mobile users expect Apple Pay and Google Pay. Show these options prominently on mobile checkouts.
  </Accordion>

  <Accordion title="Complete domain verification early">
    Apple Pay requires domain verification. Don't wait until launch day — start the process during development.
  </Accordion>

  <Accordion title="Always include card fallbacks">
    Not all customers have digital wallets. Always include `credit` and `debit` in your allowed methods.
  </Accordion>

  <Accordion title="Test on real devices">
    Simulators don't fully replicate wallet behavior. Test on actual iOS and Android devices before launch.
  </Accordion>

  <Accordion title="Handle wallet unavailability gracefully">
    If a wallet isn't available (wrong device, no cards saved), ensure other payment options are visible.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Apple Pay button not appearing">
    **Check:**

    1. Domain verified with Dodo Payments?
    2. Using HTTPS?
    3. Device is iOS 17+ / Safari 17+ / iPadOS 17+?
    4. Customer has cards in Apple Wallet?
    5. `apple_pay` included in `allowed_payment_method_types`?

    **Solution:** Complete domain verification and ensure HTTPS. Test on a real Apple device.
  </Accordion>

  <Accordion title="Google Pay button not appearing">
    **Check:**

    1. Using Chrome or compatible browser?
    2. Customer has cards in Google Pay?
    3. Chrome setting "Allow sites to check payment methods" enabled?
    4. `google_pay` included in `allowed_payment_method_types`?

    **Solution:** Verify browser compatibility and customer's Google Pay setup.
  </Accordion>

  <Accordion title="Wallet payment failed">
    **Common causes:**

    * Card in wallet expired or invalid
    * Bank declined the transaction
    * Network connectivity issue

    **Solution:** Customer should verify card in their wallet or try a different payment method.
  </Accordion>

  <Accordion title="Wrong device type">
    Digital wallets only appear on compatible devices:

    * Apple Pay: Apple devices only
    * Google Pay: Chrome browser or Android devices

    **Solution:** This is expected behavior. Ensure card fallbacks are available.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Overlay Checkout" icon="window-restore" href="/developer-resources/overlay-checkout">
    Implement checkout with digital wallet support.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    Complete testing guide for all payment methods.
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    Opens hosted checkout in a native browser tab — Apple Pay and Google Pay work the same as on the web.
  </Card>
</CardGroup>


# European Payment Methods
Source: https://docs.dodopayments.com/features/payment-methods/europe

Accept iDEAL, Bancontact, EPS, Multibanco, BLIK, SEPA Direct Debit, and Satispay to increase conversion rates across European markets. Learn about regional availability, bank coverage, and configuration.

European customers strongly prefer local payment methods that integrate with their banking systems. Offering these methods can increase conversion rates by 20-40% in target markets.

## Why Local European Payment Methods?

<CardGroup>
  <Card title="Higher Conversion" icon="chart-line">
    iDEAL captures \~60% of Dutch online payments. Not offering it means losing customers.
  </Card>

  <Card title="Lower Fraud" icon="shield-check">
    Bank-authenticated payments have near-zero fraud rates and no chargebacks.
  </Card>

  <Card title="Real-Time Settlement" icon="bolt">
    Most European methods provide instant payment confirmation.
  </Card>
</CardGroup>

## Supported Methods

| Method                | Country        | Market Share | Currency | Subscriptions |
| :-------------------- | :------------- | :----------- | :------- | :-----------: |
| **iDEAL**             | Netherlands    | \~60%        | EUR      |       No      |
| **Bancontact**        | Belgium        | \~50%        | EUR      |       No      |
| **EPS**               | Austria        | \~30%        | EUR      |       No      |
| **Multibanco**        | Portugal       | \~40%        | EUR      |       No      |
| **BLIK**              | Poland         | \~60%        | PLN      |       No      |
| **SEPA Direct Debit** | Eurozone       | Widely used  | EUR      |       No      |
| **Satispay**          | Europe (Italy) | Growing      | EUR      |      Yes      |

## iDEAL (Netherlands)

iDEAL is the dominant online payment method in the Netherlands, connecting directly to all major Dutch banks.

### How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant iDEAL
    participant Bank
    
    Customer->>Checkout: Select iDEAL
    Checkout->>Dodo: Create payment
    Dodo->>iDEAL: Initiate payment
    iDEAL->>Customer: Redirect to bank selection
    Customer->>Bank: Select bank & authenticate
    Bank->>iDEAL: Payment confirmed
    iDEAL->>Dodo: Success callback
    Dodo->>Checkout: Payment complete
```

### Supported Banks

All major Dutch banks are supported:

* ABN AMRO
* ASN Bank
* Bunq
* ING
* Knab
* Rabobank
* RegioBank
* Revolut
* SNS
* Triodos Bank
* Van Lanschot

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['ideal', 'credit', 'debit'],
  billing_currency: 'EUR',
  billing_address: {
    country: 'NL',
    zipcode: '1012JS'
  },
  return_url: 'https://example.com/success'
});
```

## Bancontact (Belgium)

Bancontact is Belgium's national payment scheme, used by virtually all Belgian banks for online payments.

### Features

* Works with existing Belgian debit cards
* Mobile app support (Payconiq by Bancontact)
* Instant payment confirmation
* No additional registration needed for customers

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['bancontact_card', 'credit', 'debit'],
  billing_currency: 'EUR',
  billing_address: {
    country: 'BE',
    zipcode: '1000'
  },
  return_url: 'https://example.com/success'
});
```

## EPS (Austria)

EPS (Electronic Payment Standard) enables direct online bank transfers for Austrian customers.

### Features

* Direct integration with Austrian banks
* Real-time payment confirmation
* High trust among Austrian consumers
* No chargebacks

### Supported Banks

Major Austrian banks including:

* Erste Bank
* Bank Austria
* Raiffeisen
* BAWAG
* Volksbank

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['eps', 'credit', 'debit'],
  billing_currency: 'EUR',
  billing_address: {
    country: 'AT',
    zipcode: '1010'
  },
  return_url: 'https://example.com/success'
});
```

## Multibanco (Portugal)

Multibanco is Portugal's interbank network, offering both online payments and ATM-based payments.

### Payment Options

1. **Online Banking** — Direct bank transfer via internet banking
2. **ATM Payment** — Customer receives a reference to pay at any Multibanco ATM
3. **Mobile Banking** — Payment via bank mobile apps

### How ATM Payment Works

For ATM payments, customers receive a payment reference:

```
Entity: 12345
Reference: 123 456 789
Amount: €50.00
Expiry: 24 hours
```

Customer can pay at any Portuguese ATM or via online banking using this reference.

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['multibanco', 'credit', 'debit'],
  billing_currency: 'EUR',
  billing_address: {
    country: 'PT',
    zipcode: '1000-001'
  },
  return_url: 'https://example.com/success'
});
```

<Note>
  Multibanco ATM payments may have a delay between checkout and actual payment. Monitor webhooks for payment confirmation.
</Note>

## BLIK (Poland)

BLIK is Poland's most popular mobile payment method, allowing customers to pay using a one-time 6-digit code generated in their banking app. BLIK settles in **PLN** (Polish Złoty), not EUR.

### How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant BLIK
    participant BankApp

    Customer->>Checkout: Select BLIK
    Checkout->>Dodo: Create payment
    Customer->>BankApp: Generate 6-digit code
    Customer->>Checkout: Enter BLIK code
    Checkout->>Dodo: Submit code
    Dodo->>BLIK: Authorize payment
    BLIK->>BankApp: Confirmation request
    Customer->>BankApp: Approve payment
    BankApp->>BLIK: Payment confirmed
    BLIK->>Dodo: Success callback
    Dodo->>Checkout: Payment complete
```

### Availability

* **Billing currency:** PLN only
* **Transaction type:** One-time payments only (not available for subscriptions)
* **Coverage:** All major Polish banks supporting BLIK

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['blik', 'credit', 'debit'],
  billing_currency: 'PLN',
  billing_address: {
    country: 'PL',
    zipcode: '00-001'
  },
  return_url: 'https://example.com/success'
});
```

<Note>
  BLIK requires a **PLN** billing currency. If you quote your prices in EUR, enable [Adaptive Currency](/features/adaptive-currency) so Polish customers are billed in PLN and BLIK becomes available.
</Note>

## SEPA Direct Debit (Eurozone)

SEPA Direct Debit lets customers across the Eurozone pay directly from their bank account instead of using a card. It is offered on EUR checkouts for one-time payments.

### How It Works

The customer authorizes the debit during checkout and the payment is collected from their bank account. Unlike most European methods on this page, confirmation is not immediate.

<Warning>
  SEPA Direct Debit is not instant. A payment takes **6 business days** to confirm, so do not treat authorization as settlement — fulfill only once the payment reaches a succeeded state.
</Warning>

### Availability

* **Billing currency:** EUR
* **Transaction type:** One-time payments only (not available for subscriptions)

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['sepa', 'credit', 'debit'],
  billing_currency: 'EUR',
  billing_address: {
    country: 'DE',
    zipcode: '10115'
  },
  return_url: 'https://example.com/success'
});
```

### SEPA Test IBANs

In test mode, enter one of the IBANs below at checkout to force a specific outcome.

| Test IBAN                | Behavior                                                              |
| :----------------------- | :-------------------------------------------------------------------- |
| `DE89370400440532013000` | The payment succeeds.                                                 |
| `DE08370400440532013003` | The payment succeeds after a delay of at least three minutes.         |
| `DE62370400440532013001` | The payment fails.                                                    |
| `DE78370400440532013004` | The payment fails after a delay of at least three minutes.            |
| `DE35370400440532013002` | The payment succeeds, then is immediately disputed.                   |
| `DE65370400440002222227` | The payment fails due to insufficient funds.                          |
| `DE18370400440000066666` | The bank account is unusable, so the payment method can't be created. |

To test country-specific behavior, use the equivalent success IBAN for another Eurozone country:

| Country    | Success IBAN                  |
| :--------- | :---------------------------- |
| Austria    | `AT611904300234573201`        |
| Belgium    | `BE62510007547061`            |
| Estonia    | `EE382200221020145685`        |
| Finland    | `FI2112345600000785`          |
| France     | `FR1420041010050500013M02606` |
| Ireland    | `IE29AIBK93115212345678`      |
| Luxembourg | `LU280019400644750000`        |

<Note>
  The delayed test IBANs are useful for confirming that your webhook handler — rather than the checkout redirect — is what grants access, since SEPA payments confirm long after the customer leaves the checkout.
</Note>

## Satispay (Europe)

Satispay is a popular European mobile payment network, especially in Italy, that lets customers pay directly from their Satispay app without sharing card or bank details. Satispay settles in **EUR**.

### Features

* App-based payments independent of card networks
* Strong adoption across Italy and growing in other European markets
* Supports both one-time payments and subscriptions

### Availability

* **Billing currency:** EUR
* **Transaction type:** One-time payments and subscriptions

### Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['satispay', 'credit', 'debit'],
  billing_currency: 'EUR',
  billing_address: {
    country: 'IT',
    zipcode: '00100'
  },
  return_url: 'https://example.com/success'
});
```

## API Method Types

| Type              | Method            | Country        |
| :---------------- | :---------------- | :------------- |
| `ideal`           | iDEAL             | Netherlands    |
| `bancontact_card` | Bancontact        | Belgium        |
| `eps`             | EPS               | Austria        |
| `multibanco`      | Multibanco        | Portugal       |
| `blik`            | BLIK              | Poland         |
| `sepa`            | SEPA Direct Debit | Eurozone       |
| `satispay`        | Satispay          | Europe (Italy) |

## Multi-Country European Checkout

For businesses serving multiple European countries, include all regional methods:

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: [
    'ideal',           // Netherlands
    'bancontact_card', // Belgium
    'eps',             // Austria
    'multibanco',      // Portugal
    'blik',            // Poland (requires PLN billing currency)
    'sepa',            // Eurozone (one-time payments only)
    'satispay',        // Europe / Italy
    'credit',          // Fallback
    'debit'            // Fallback
  ],
  billing_currency: 'EUR',
  return_url: 'https://example.com/success'
});
```

Dodo automatically shows only the relevant methods based on customer location. A Dutch customer will see iDEAL; a Belgian customer will see Bancontact.

## Testing

European payment methods can be tested in Test Mode. The test flow simulates the bank authentication process.

<Note>
  SEPA Direct Debit is tested differently — instead of a simulated bank flow, you enter a test IBAN directly. See [SEPA Test IBANs](#sepa-test-ibans).
</Note>

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Set appropriate billing address">
    Set the billing address country to match the payment method:

    * `NL` for iDEAL
    * `BE` for Bancontact
    * `AT` for EPS
    * `PT` for Multibanco
    * `PL` for BLIK (with PLN billing currency)
    * `IT` for Satispay
  </Step>

  <Step title="Complete the test flow">
    Follow the simulated bank authentication flow in the test environment.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Always include regional methods for target markets">
    If you sell to Dutch customers, include iDEAL. Not doing so is like not accepting Visa in the US — you'll lose significant sales.
  </Accordion>

  <Accordion title="Match currency to region">
    Most European payment methods require EUR — ensure your pricing supports Euro transactions. The one exception is BLIK, which is offered only on **PLN** (Polish Złoty) billing.
  </Accordion>

  <Accordion title="Handle redirects gracefully">
    All European methods involve redirects to bank sites. Ensure your return URL handling is robust and accounts for users who abandon mid-flow.
  </Accordion>

  <Accordion title="Provide card fallbacks">
    Not all European customers have access to these regional methods (tourists, expats, etc.). Always include `credit` and `debit` as fallbacks.
  </Accordion>

  <Accordion title="Consider Multibanco timing">
    Multibanco ATM payments may take hours to complete. Don't block fulfillment on immediate payment — use webhooks for async confirmation.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="European method not appearing">
    **Check:**

    1. Customer billing country matches method's country?
    2. Currency set to EUR?
    3. Method included in `allowed_payment_method_types`?

    **Solution:** European methods are strictly regional. A customer with billing country `DE` (Germany) won't see iDEAL, which is Netherlands-only.
  </Accordion>

  <Accordion title="Bank authentication failed">
    **Causes:**

    * Customer cancelled during bank authentication
    * Bank's authentication system temporarily unavailable
    * Customer entered incorrect credentials

    **Solution:** Customer should retry. If persistent, suggest trying a different payment method.
  </Accordion>

  <Accordion title="Redirect not completing">
    **Causes:**

    * Customer closed browser during bank redirect
    * Network issues during authentication
    * Return URL misconfigured

    **Solution:** Verify return URL is correct and accessible. Ensure it handles both success and failure states.
  </Accordion>

  <Accordion title="Multibanco payment pending">
    **Cause:** Customer received payment reference but hasn't paid yet.

    **Solution:** This is expected for ATM-based payments. Wait for webhook confirmation. Reference typically expires in 24-72 hours.
  </Accordion>
</AccordionGroup>

## PSD2 Compliance

All European payment methods comply with PSD2 (Payment Services Directive 2) regulations:

* **Strong Customer Authentication (SCA)** — Built into the bank authentication flow
* **Secure Communication** — All data transmitted via secure channels
* **Consumer Protection** — Full compliance with EU consumer rights

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    Currency support and automatic conversion.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle payment confirmations asynchronously.
  </Card>
</CardGroup>


# India Payment Methods
Source: https://docs.dodopayments.com/features/payment-methods/india

Accept UPI and all Indian-issued cards in India with RBI-compliant subscription mandates. Understand the 48-hour processing delay, mandate limits, and webhook handling.

India has unique payment infrastructure dominated by UPI (60%+ of digital transactions) and Indian-issued cards (Visa, Mastercard, Rupay, etc.). Dodo Payments supports all of these with full RBI compliance for subscription mandates.

## Why India Payment Methods Matter

<CardGroup>
  <Card title="UPI Dominance" icon="mobile">
    UPI processes 10B+ transactions/month. Many Indian customers don't have international cards.
  </Card>

  <Card title="Low Transaction Costs" icon="indian-rupee-sign">
    UPI has near-zero transaction fees. Excellent for high-volume, lower-value transactions.
  </Card>

  <Card title="Subscription Support" icon="repeat">
    Unlike most alternative payment methods, UPI and all Indian-issued cards (Visa, Mastercard, Rupay, etc.) support recurring payments via RBI mandates.
  </Card>
</CardGroup>

## Supported Methods

| Method           | Type          | Subscriptions | Min Amount |
| :--------------- | :------------ | :-----------: | :--------- |
| **UPI Collect**  | QR code / VPA |     Yes\*     | ₹1         |
| **Rupay Credit** | Card          |     Yes\*     | ₹1         |
| **Rupay Debit**  | Card          |     Yes\*     | ₹1         |

\*Subscriptions require RBI-compliant mandates with special processing rules. The 48-hour processing delay applies to all Indian-issued cards and UPI.

## Configuration

### API Method Types

| Type          | Description                  |
| :------------ | :--------------------------- |
| `upi_collect` | UPI via QR code or VPA entry |
| `credit`      | Credit cards including Rupay |
| `debit`       | Debit cards including Rupay  |

### Example: India-Focused Checkout

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  billing_currency: 'INR',
  customer: {
    email: 'customer@example.in',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    country: 'IN',
    zipcode: '560001'
  },
  return_url: 'https://example.com/success'
});
```

### Requirements for UPI

For UPI to appear at checkout:

1. **Billing country** must be India (`IN`)
2. **Currency** must be INR
3. For non-Indian merchants: **Adaptive Currency** must be enabled

<Warning>
  If you're a non-Indian merchant and Adaptive Currency is not enabled, UPI will not be available to your customers.
</Warning>

## Subscriptions with RBI Mandates

Indian payment method subscriptions operate under RBI (Reserve Bank of India) regulations with unique requirements.

### How RBI Mandates Work

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Your App
    participant Dodo
    participant Bank
    
    Customer->>Your App: Subscribe
    Your App->>Dodo: Create subscription
    Dodo->>Bank: Create mandate
    Bank->>Customer: Authorize mandate
    Customer->>Bank: Approve (face value or Rs 15K limit)
    Bank->>Dodo: Mandate active
    
    Note over Dodo,Bank: On renewal date...
    
    Dodo->>Bank: Initiate charge
    Note over Bank: 48-hour window starts
    Bank->>Customer: Pre-debit notification
    Note over Bank: After 48 hours...
    Bank->>Dodo: Debit completed
    Dodo->>Your App: payment.succeeded webhook
```

### Mandate Types

| Subscription Amount               | Mandate Type         | Limit                           |
| :-------------------------------- | :------------------- | :------------------------------ |
| **Below the mandate floor**       | On-demand mandate    | Mandate floor (default ₹15,000) |
| **At or above the mandate floor** | Fixed-amount mandate | Exact subscription amount       |

The amount registered with the customer's bank is `max(mandate_floor, billing_amount)`. So the floor is effectively the customer-facing **authorization ceiling** whenever billing is lower than the floor.

**Important for plan changes:** If an upgrade results in a charge exceeding the existing mandate limit, the charge will fail and the customer must re-authorize.

### Configurable Mandate Floor

The mandate floor for INR e-mandates is configurable via the `mandate_min_amount_inr_paise` field (in **INR paise** — 1 INR = 100 paise). You can override the system default of ₹15,000 at three levels:

| Level           | Where to set                                                         | Scope                      |
| --------------- | -------------------------------------------------------------------- | -------------------------- |
| **Per request** | `mandate_min_amount_inr_paise` on a checkout session or subscription | One transaction            |
| **Merchant**    | Business settings                                                    | All your INR subscriptions |
| **System**      | —                                                                    | ₹15,000 default            |

Resolution priority: per-request override → merchant setting → system default.

```typescript theme={null}
// Per-checkout override
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_inr_monthly', quantity: 1 }],
  mandate_min_amount_inr_paise: 2_000_000, // ₹20,000 ceiling
  return_url: 'https://yoursite.com/return'
});

// Per-subscription override
const subscription = await client.subscriptions.create({
  product_id: 'pdt_inr_monthly',
  quantity: 1,
  customer: { email: 'customer@example.in' },
  billing: { country: 'IN', /* ... */ },
  mandate_min_amount_inr_paise: 2_000_000
});
```

| Field                          | Type                  | Validation | Applies to                                                |
| ------------------------------ | --------------------- | ---------- | --------------------------------------------------------- |
| `mandate_min_amount_inr_paise` | `integer` (INR paise) | `>= 1`     | Indian-card INR subscriptions on non-Airwallex connectors |

<Info>
  Setting a higher floor lets you support larger one-off charges later (for example, plan upgrades or usage-based overages) without forcing customers to re-authorize. Setting a lower floor brings the customer's authorization closer to the actual billing amount but limits headroom for future variable charges.
</Info>

<Warning>
  This setting only affects e-mandates registered for Indian-issued cards (Visa, Mastercard, RuPay) on INR subscriptions. UPI subscriptions follow their own AutoPay flow and are unaffected.
</Warning>

### The 48-Hour Processing Delay

This is the most important difference from international card payments:

<Steps>
  <Step title="Charge Initiated (Day 0)">
    On the scheduled renewal date, Dodo initiates the charge with the bank.
  </Step>

  <Step title="Pre-Debit Notification">
    Customer receives notification from their bank about the upcoming debit.
  </Step>

  <Step title="48-Hour Window">
    Customer can cancel the mandate during this period via their banking app.
  </Step>

  <Step title="Debit Completed (~48-51 hours)">
    After 48 hours (plus up to 3 additional hours for bank processing), funds are debited.
  </Step>

  <Step title="Webhook Sent">
    `payment.succeeded` webhook is sent after actual debit, not at initiation.
  </Step>
</Steps>

<Warning>
  **Do not grant benefits at charge initiation.** Wait for the `payment.succeeded` webhook, which arrives \~48-51 hours after the scheduled charge date.
</Warning>

### Handling the 48-Hour Window

```javascript theme={null}
// DON'T do this:
async function handleSubscriptionRenewal(subscription) {
  // ❌ Bad: Granting access immediately when charge is initiated
  grantPremiumAccess(subscription.customer_id);
}

// DO this:
async function handlePaymentWebhook(event) {
  if (event.type === 'payment.succeeded') {
    // ✅ Good: Only grant access after payment is confirmed
    grantPremiumAccess(event.data.customer_id);
  }
  
  if (event.type === 'payment.failed') {
    // Handle failed payment (mandate cancelled, insufficient funds)
    revokePremiumAccess(event.data.customer_id);
  }
}
```

### Webhook Events for Indian Subscriptions

| Event                  | When                      | Action                           |
| :--------------------- | :------------------------ | :------------------------------- |
| `subscription.active`  | Mandate authorized        | Record subscription start        |
| `payment.succeeded`    | \~48h after charge date   | Grant/continue access            |
| `payment.failed`       | Debit failed              | Notify customer, pause access    |
| `subscription.on_hold` | Payment failed            | Prompt for payment method update |
| `subscription.active`  | Reactivated after payment | Restore access                   |

## Testing

### UPI Test IDs

| Status  | UPI ID        |
| :------ | :------------ |
| Success | `success@upi` |
| Failure | `failure@upi` |

### Indian Card Test Numbers

| Brand      | Scenario | Card Number        | Expiry | CVV |
| :--------- | :------- | :----------------- | :----- | :-- |
| Visa       | Success  | `4576238912771450` | 06/32  | 123 |
| Visa       | Declined | `4706131211212123` | 06/32  | 123 |
| Mastercard | Success  | `5409162669381034` | 06/32  | 123 |
| Mastercard | Declined | `5105105105105100` | 06/32  | 123 |

## Best Practices

<AccordionGroup>
  <Accordion title="Plan for the 48-hour delay">
    Build your application to handle the gap between charge initiation and actual payment. Consider:

    * Grace periods for subscription access
    * Clear communication to customers about processing time
    * Webhook-driven fulfillment, not date-driven
  </Accordion>

  <Accordion title="Handle mandate cancellations">
    Customers can cancel mandates via their bank apps at any time. Monitor `subscription.on_hold` webhooks and prompt customers to re-subscribe or update payment methods.
  </Accordion>

  <Accordion title="Set appropriate mandate amounts">
    For variable pricing (e.g., usage-based), consider whether a Rs 15,000 on-demand mandate is sufficient. If charges might exceed this, customers will need to re-authorize.
  </Accordion>

  <Accordion title="Offer UPI prominently">
    For Indian customers, UPI should be the primary payment option. Many users prefer it over cards due to familiarity and lower friction.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="UPI not appearing at checkout">
    **Check:**

    1. Billing country set to `IN`?
    2. Currency set to `INR`?
    3. If non-Indian merchant: Adaptive Currency enabled?
    4. `upi_collect` included in `allowed_payment_method_types`?

    **Solution:** Verify billing address has `country: "IN"` and `billing_currency: "INR"`.
  </Accordion>

  <Accordion title="Subscription charge failed after upgrade">
    **Cause:** New charge amount exceeds existing mandate limit (Rs 15,000 threshold).

    **Solution:** Customer must update payment method to establish a new mandate with the correct limit.
  </Accordion>

  <Accordion title="Subscription on hold but customer claims they didn't cancel">
    **Cause:** Customer may have cancelled the mandate during the 48-hour window, or their bank declined the debit.

    **Solution:** Customer needs to re-authorize the mandate or update their payment method.
  </Accordion>

  <Accordion title="Payment deduction delayed beyond 48 hours">
    **Cause:** Bank API delays can extend processing by 2-3 additional hours.

    **Solution:** This is expected. Build your system to handle variable delays up to \~51 hours total.
  </Accordion>

  <Accordion title="Mandate cancelled but subscription still active">
    **Cause:** Edge case in RBI regulations — mandate cancellation during processing window doesn't immediately cancel subscription.

    **Solution:** The next charge will fail and subscription will move to `on_hold`. Monitor webhooks for `payment.failed`.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Complete subscription documentation including RBI mandates.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Webhook handling for payment events.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    All test data including UPI IDs and Indian cards.
  </Card>
</CardGroup>


# Pix
Source: https://docs.dodopayments.com/features/payment-methods/pix

Accept Pix payments from Brazilian customers. Learn about real-time bank transfers, QR code payments, and configuration for the Brazilian market.

Pix is Brazil's instant payment system created by the Central Bank of Brazil (Banco Central do Brasil). It enables real-time transfers 24/7, including weekends and holidays, and has become the most popular payment method in Brazil.

## Why Offer Pix?

<CardGroup>
  <Card title="Dominant in Brazil" icon="chart-line">
    Pix is the most-used payment method in Brazil, surpassing credit cards and boleto.
  </Card>

  <Card title="Instant Settlement" icon="bolt">
    Payments confirm in seconds, 24/7/365 — no waiting for bank processing windows.
  </Card>

  <Card title="Low Friction" icon="mobile">
    Customers pay via QR code or copy-paste key — no card numbers or bank details needed.
  </Card>
</CardGroup>

## Overview

| Detail                  | Value   |
| :---------------------- | :------ |
| **Billing Currency**    | BRL     |
| **Supported Countries** | Brazil  |
| **Subscriptions**       | No      |
| **Min Amount**          | \$0.50  |
| **Settlement**          | Instant |

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant Pix
    participant Bank

    Customer->>Checkout: Select Pix
    Checkout->>Dodo: Create payment
    Dodo->>Pix: Generate QR code
    Pix->>Customer: Display QR code / copy-paste key
    Customer->>Bank: Scan QR or paste key in banking app
    Bank->>Pix: Payment confirmed
    Pix->>Dodo: Success callback
    Dodo->>Checkout: Payment complete
```

## Customer Experience

1. Customer selects Pix at checkout
2. A QR code and copy-paste key are displayed
3. Customer opens their banking app and scans the QR code or pastes the key
4. Payment confirms instantly
5. Customer is redirected to the success page

<Info>
  Pix QR codes typically expire after a set period. If the customer doesn't complete payment in time, they need to restart the checkout.
</Info>

## Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['pix', 'credit', 'debit'],
  billing_currency: 'BRL',
  return_url: 'https://example.com/success'
});
```

## API Method Type

| Type  | Method | Country |
| :---- | :----- | :------ |
| `pix` | Pix    | Brazil  |

## Testing

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Set billing currency to BRL">
    Ensure the billing currency is set to `BRL` in your checkout request.
  </Step>

  <Step title="Enter test CPF and scan the QR code">
    When prompted for a Pix CPF, enter `1234567890`. A test QR code will be generated — scan it with your normal phone camera (no Pix app needed). You'll be redirected to a test page where you can simulate the transaction as a success or failure.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Set billing currency to BRL">
    Pix only works with BRL. Ensure your pricing supports Brazilian Real transactions for the Brazilian market.
  </Accordion>

  <Accordion title="Provide card fallbacks">
    Not all Brazilian customers may prefer Pix. Always include `credit` and `debit` as fallback options.
  </Accordion>

  <Accordion title="Handle QR code expiration">
    Pix QR codes expire after a set period. Ensure your checkout handles expiration gracefully and allows customers to regenerate the code.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pix not appearing at checkout">
    **Check:**

    1. Billing currency set to `BRL`?
    2. `pix` included in `allowed_payment_method_types`?
    3. Customer billing country is Brazil?

    **Solution:** Pix is only available for BRL transactions. Verify currency and billing address in your API request.
  </Accordion>

  <Accordion title="QR code expired">
    **Cause:** Customer didn't complete payment within the expiration window.

    **Solution:** Customer needs to restart the checkout to generate a new QR code.
  </Accordion>

  <Accordion title="Payment pending">
    **Cause:** Pix payments confirm instantly in most cases, but occasional bank-side delays can occur.

    **Solution:** Monitor webhooks for payment confirmation. If payment doesn't confirm within a few minutes, treat it as failed.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    Currency support and automatic conversion.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle payment confirmations asynchronously.
  </Card>
</CardGroup>


# South Korea Payment Methods
Source: https://docs.dodopayments.com/features/payment-methods/south-korea

Accept Korean local wallets PAYCO, Naver Pay, and Kakao Pay alongside Korean local cards and international cards, billed in KRW. Learn about availability, subscription support, and configuration.

South Korean customers strongly prefer local wallets and domestic cards over international payment methods. Dodo Payments supports the major Korean wallets — **PAYCO**, **Naver Pay**, and **Kakao Pay** — alongside **Korean local cards** and international cards, all billed in **KRW** (South Korean Won).

## Why Korean Payment Methods Matter

<CardGroup>
  <Card title="Wallet-First Market" icon="wallet">
    Korean shoppers overwhelmingly check out with local wallets like Kakao Pay and Naver Pay rather than entering card details.
  </Card>

  <Card title="Domestic Card Networks" icon="credit-card">
    Many Korean cards run on local networks. Supporting Korean local cards avoids declines on cards that international rails can't process.
  </Card>

  <Card title="Higher Conversion" icon="chart-line">
    Offering familiar local methods reduces checkout friction and abandonment for customers in South Korea.
  </Card>
</CardGroup>

## Supported Methods

| Method                   | Type                 | Subscriptions | Min Amount |
| :----------------------- | :------------------- | :-----------: | :--------- |
| **Kakao Pay**            | Wallet               |      Yes      | \~\$1.00   |
| **Naver Pay**            | Wallet               |      Yes      | \~\$1.00   |
| **PAYCO**                | Wallet               |       No      | \~\$1.00   |
| **Korean Local Cards**   | Card                 |      Yes      | \~\$1.00   |
| **Credit & Debit Cards** | Card (international) |      Yes      | \~\$1.00   |

<Info>
  Wallet availability depends on the transaction type. **Kakao Pay** and **Naver Pay** are offered for subscriptions, while **PAYCO** is offered for one-time payments. All require a **KRW** billing currency.
</Info>

## Configuration

### API Method Types

| Type        | Description                                |
| :---------- | :----------------------------------------- |
| `kakao_pay` | Kakao Pay wallet                           |
| `naver_pay` | Naver Pay wallet                           |
| `payco`     | PAYCO wallet                               |
| `credit`    | Credit cards, including Korean local cards |
| `debit`     | Debit cards, including Korean local cards  |

### Example: South Korea-Focused Checkout

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: [
    'kakao_pay',
    'naver_pay',
    'payco',
    'credit',
    'debit'
  ],
  billing_currency: 'KRW',
  billing_address: {
    country: 'KR',
    zipcode: '06236'
  },
  return_url: 'https://example.com/success'
});
```

### Requirements

For Korean payment methods to appear at checkout:

1. **Billing country** is South Korea (`KR`)
2. **Currency** is KRW
3. For merchants priced in another currency: **Adaptive Currency** must be enabled so customers are billed in KRW

<Warning>
  If you price in another currency and Adaptive Currency is not enabled, Korean customers will not be billed in KRW and the Korean wallets will not be available.
</Warning>

<Note>
  KRW is a zero-decimal currency — amounts are expressed in whole won with no minor units. Send and read KRW amounts as whole-number values rather than dividing by 100.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Offer wallets prominently">
    For Korean customers, local wallets should be the primary options. Kakao Pay and Naver Pay are the most familiar checkout methods for most Korean shoppers.
  </Accordion>

  <Accordion title="Include card fallbacks">
    Always include `credit` and `debit` so customers without a preferred wallet — and customers paying with Korean local cards — can still complete checkout.
  </Accordion>

  <Accordion title="Match currency to region">
    Korean payment methods require KRW. If your catalog is priced in another currency, enable Adaptive Currency so Korean customers are quoted and billed in KRW.
  </Accordion>

  <Accordion title="Choose wallets by transaction type">
    Use Kakao Pay and Naver Pay for subscriptions and PAYCO for one-time payments. Including all three lets Dodo present the right option based on the checkout context.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Korean wallets not appearing at checkout">
    **Check:**

    1. Billing country set to `KR`?
    2. Currency set to `KRW`?
    3. If priced in another currency: Adaptive Currency enabled?
    4. The wallet (`kakao_pay`, `naver_pay`, or `payco`) included in `allowed_payment_method_types`?

    **Solution:** Verify the billing address has `country: "KR"` and `billing_currency: "KRW"`.
  </Accordion>

  <Accordion title="Wallet missing for a subscription">
    **Cause:** PAYCO is offered for one-time payments only. For recurring billing, use Kakao Pay or Naver Pay.

    **Solution:** Include `kakao_pay` and `naver_pay` in `allowed_payment_method_types` for subscription checkouts.
  </Accordion>

  <Accordion title="Korean card declined on the international network">
    **Cause:** Some Korean cards run on domestic networks that international rails can't process.

    **Solution:** Keep `credit` and `debit` enabled so Korean local cards are routed correctly.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Credit & Debit Cards" icon="credit-card" href="/features/payment-methods/cards">
    Card networks, including Korean local cards.
  </Card>

  <Card title="Adaptive Currency" icon="globe" href="/features/adaptive-currency">
    Bill customers in their local currency, including KRW.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    Test data and checkout testing guidance.
  </Card>
</CardGroup>


# Stablecoins
Source: https://docs.dodopayments.com/features/payment-methods/stablecoins

Accept stablecoin payments from customers worldwide (excluding India). Learn about supported stablecoins, USD billing, and configuration for stablecoin checkout.

Stablecoin payments allow customers to pay using stablecoins from anywhere in the world (excluding India). Transactions are billed in USD, so you receive fiat currency while customers pay with their preferred stablecoin wallet.

## Why Offer Stablecoins?

<CardGroup>
  <Card title="Global Reach" icon="globe">
    Accept payments from any country — no banking infrastructure required on the customer's side.
  </Card>

  <Card title="No Chargebacks" icon="shield-check">
    Stablecoin transactions are irreversible, eliminating chargeback fraud entirely.
  </Card>

  <Card title="USD Settlement" icon="dollar-sign">
    You receive USD — no need to manage volatility or wallets.
  </Card>
</CardGroup>

## Overview

| Detail                  | Value             |
| :---------------------- | :---------------- |
| **Billing Currency**    | USD               |
| **Supported Countries** | Global (Excl. IN) |
| **Subscriptions**       | No                |
| **Min Amount**          | \$0.50            |
| **Settlement**          | USD               |

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant StablecoinProcessor
    participant Blockchain

    Customer->>Checkout: Select Stablecoins
    Checkout->>Dodo: Create payment
    Dodo->>StablecoinProcessor: Generate payment request
    StablecoinProcessor->>Customer: Display wallet address / QR code
    Customer->>Blockchain: Send stablecoins from wallet
    Blockchain->>StablecoinProcessor: Transaction confirmed
    StablecoinProcessor->>Dodo: Payment confirmed (USD)
    Dodo->>Checkout: Payment complete
```

## Customer Experience

1. Customer selects Stablecoins at checkout
2. A wallet address and QR code are displayed with the amount in stablecoins
3. Customer sends the exact amount from their stablecoin wallet
4. Transaction is confirmed on the blockchain
5. Customer is redirected to the success page

<Info>
  Stablecoin payments are billed in USD. The stablecoin amount displayed at checkout reflects the real-time exchange rate at the time of payment.
</Info>

## Supported Currencies & Networks

| Currency | Networks                        |
| :------- | :------------------------------ |
| **USDC** | Ethereum, Solana, Polygon, Base |
| **USDP** | Ethereum, Solana                |
| **USDG** | Ethereum                        |

## Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['crypto_currency', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

## API Method Type

| Type              | Method      | Country           |
| :---------------- | :---------- | :---------------- |
| `crypto_currency` | Stablecoins | Global (Excl. IN) |

## Testing

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Create a test checkout">
    Create a checkout session with `crypto_currency` in the allowed payment methods.
  </Step>

  <Step title="Complete the test flow">
    Follow the simulated stablecoin payment flow in the test environment.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Always include card fallbacks">
    Not all customers have stablecoin wallets. Always include `credit` and `debit` as fallback payment methods.
  </Accordion>

  <Accordion title="Set clear expectations on confirmation time">
    Blockchain confirmations can take minutes depending on the network. Ensure your checkout communicates this to customers.
  </Accordion>

  <Accordion title="Handle underpayments and overpayments">
    Stablecoin payments may occasionally differ slightly from the exact amount due to network fees. Monitor webhooks for payment status updates.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Stablecoins not appearing at checkout">
    **Check:**

    1. `crypto_currency` included in `allowed_payment_method_types`?
    2. Transaction amount meets minimum (\$0.50)?

    **Solution:** Verify the payment method type is correctly passed in your API request.
  </Accordion>

  <Accordion title="Payment not confirming">
    **Cause:** Blockchain confirmation times vary. Some networks take longer than others.

    **Solution:** Wait for webhook confirmation. Do not treat the payment as failed until the confirmation window has passed.
  </Accordion>

  <Accordion title="Amount mismatch">
    **Cause:** Network fees can cause the received amount to differ slightly from the requested amount.

    **Solution:** Monitor webhooks for the final confirmed amount. Small discrepancies are handled automatically.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle payment confirmations asynchronously.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    Complete testing guide for all payment methods.
  </Card>
</CardGroup>


# WeChat Pay
Source: https://docs.dodopayments.com/features/payment-methods/wechat

Accept WeChat Pay for Chinese customers. Learn about USD and CNY billing, QR code payments, and configuration.

WeChat Pay is one of China's two dominant mobile payment platforms, used by over a billion people. It enables payments via QR codes within the WeChat app, making it essential for businesses targeting Chinese consumers.

## Why Offer WeChat Pay?

<CardGroup>
  <Card title="1B+ Users" icon="users">
    WeChat Pay is used by over a billion people, making it one of the world's largest payment platforms.
  </Card>

  <Card title="Mobile-First" icon="mobile">
    Payments are completed entirely within the WeChat app — fast, familiar, and frictionless for Chinese customers.
  </Card>

  <Card title="Dual Currency" icon="money-bill-transfer">
    Accept payments in both USD and CNY, giving flexibility for cross-border and domestic transactions.
  </Card>
</CardGroup>

## Overview

| Detail               | Value          |
| :------------------- | :------------- |
| **Billing Currency** | USD, CNY       |
| **Subscriptions**    | No             |
| **Min Amount**       | \$0.50 / ¥1.00 |
| **Settlement**       | USD            |

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Checkout
    participant Dodo
    participant Dodo
    participant WeChat

    Customer->>Checkout: Select WeChat Pay
    Checkout->>Dodo: Create payment
    Dodo->>WeChat: Initiate payment
    WeChat->>Customer: Display QR code
    Customer->>WeChat: Scan QR in WeChat app
    WeChat->>Dodo: Payment confirmed
    Dodo->>Checkout: Payment complete
    Dodo->>Checkout: Payment complete
```

## Customer Experience

1. Customer selects WeChat Pay at checkout
2. A QR code is displayed on the checkout page
3. Customer opens WeChat on their phone and scans the QR code
4. Customer confirms payment in the WeChat app
5. Payment confirms instantly and customer is redirected to the success page

<Info>
  Customers pay in USD or CNY, and you receive settlement in USD.
</Info>

## Configuration

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['we_chat_pay', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

## API Method Type

| Type          | Method     | Currencies |
| :------------ | :--------- | :--------- |
| `we_chat_pay` | WeChat Pay | USD, CNY   |

## Testing

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Create a test checkout">
    Create a checkout session with `we_chat_pay` in the allowed payment methods.
  </Step>

  <Step title="Scan the QR code">
    A test QR code will be generated — scan it with your normal phone camera (no WeChat app needed). You'll be redirected to a test page where you can simulate the transaction as a success or failure.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Target Chinese customers">
    WeChat Pay is primarily used by Chinese consumers. Include it when your customer base includes Chinese buyers or you're targeting the Chinese market.
  </Accordion>

  <Accordion title="Always include card fallbacks">
    Not all customers have WeChat. Always include `credit` and `debit` as fallback payment methods.
  </Accordion>

  <Accordion title="Optimize for mobile">
    Many WeChat Pay users browse on mobile. Ensure your checkout page is responsive — QR code scanning works best when the checkout is displayed on a desktop or tablet while the customer scans with their phone.
  </Accordion>

  <Accordion title="Consider both currencies">
    WeChat Pay supports both USD and CNY. Choose the billing currency that best suits your target market — USD for cross-border, CNY for domestic Chinese transactions.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="WeChat Pay not appearing at checkout">
    **Check:**

    1. `we_chat_pay` included in `allowed_payment_method_types`?
    2. Billing currency set to USD or CNY?
    3. Transaction amount meets minimum?

    **Solution:** Verify the payment method type and currency are correctly passed in your API request.
  </Accordion>

  <Accordion title="QR code not scanning">
    **Cause:** QR code may have expired, or the customer's WeChat version is outdated.

    **Solution:** Refresh the checkout page to generate a new QR code. Ensure customer is using a current version of WeChat.
  </Accordion>

  <Accordion title="Payment not confirming">
    **Cause:** WeChat Pay typically confirms instantly, but network delays can occur.

    **Solution:** Monitor webhooks for payment confirmation. If payment doesn't confirm within a few minutes, the customer may need to retry.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Payment Methods Overview" icon="credit-card" href="/features/payment-methods">
    See all supported payment methods.
  </Card>

  <Card title="Checkout Guide" icon="book" href="/developer-resources/checkout-session">
    Complete checkout implementation guide.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle payment confirmations asynchronously.
  </Card>

  <Card title="Testing Process" icon="flask" href="/miscellaneous/testing-process">
    Complete testing guide for all payment methods.
  </Card>
</CardGroup>


# Payouts Process
Source: https://docs.dodopayments.com/features/payouts/payout-structure

Consolidate your eligible earnings and manage your payout threshold directly from the dashboard.

## Introduction

The **Payouts Section** consolidates all eligible earnings that can be disbursed in the next payout cycle. It provides transparency on the net available balance after accounting for all fees, refunds, and taxes.

<Frame>
  <img alt="Payouts page showing balance eligible for payout, schedule settings, linked bank accounts, and payout history" />
</Frame>

## Key Features

* Displays the total balance eligible for payout in the upcoming cycle in USD
* Automatically applies FX conversion for non-USD currencies
* Lets businesses **set or modify their payout threshold** directly from the wallet settings

<Info>
  The displayed amount is **for reference only**. Final payout amounts may vary based on the actual exchange rate at the time of transfer. Charges applied by your own bank or by intermediary banks can reduce the credited amount further — see [Payout Currency and Bank Conversion](#payout-currency-and-bank-conversion).
</Info>

## Payout Cycles

We support the following payout cycles:

<Steps>
  <Step title="Bi-Monthly (Default)">
    **Billing Period 1:** 1st to 15th of the month\
    **Payout Date 1:** 18th of the same month

    **Billing Period 2:** 16th to the end of the month\
    **Payout Date 2:** 4th of the following month
  </Step>

  <Step title="Weekly">
    **Billing Period 1:** 1st to 7th\
    **Payout Date 1:** 11th of the same month

    **Billing Period 2:** 8th to 14th\
    **Payout Date 2:** 18th of the same month

    **Billing Period 3:** 15th to 21st\
    **Payout Date 3:** 25th of the same month

    **Billing Period 4:** 22nd to the end of the month\
    **Payout Date 4:** 4th of the following month
  </Step>

  <Step title="Monthly">
    **Billing Period:** 1st to the end of the month\
    **Payout Date:** 11th of the following month
  </Step>
</Steps>

**Note:**

* Payouts will only be initiated if all verifications are successful and Payout Threshold is crossed in the billing period.
* The default payout cycle for all businesses is **bi-monthly**.
* Businesses with higher transaction volumes may request **weekly** payouts by contacting [support@dodopayments.com](mailto:support@dodopayments.com).
* Certain high-risk businesses may be placed on a **monthly** payout cycle at our discretion.

## Payout Processing and Bank Timelines

1. The dates provided above are the **initiation dates** for payouts.
2. It typically takes **1-2 business days** for the amount to appear in your bank account.
3. Delays may occur if payout processing dates fall on weekends or bank holidays.

## Payout Currency and Bank Conversion

Payout balances are held in your USD, GBP, and EUR wallets. Once a transfer leaves Dodo Payments, two things outside our control can change the amount your account is finally credited:

* **Conversion by your bank.** Where the currency your account is credited in differs from the currency the transfer is sent in, your bank performs the conversion when the transfer arrives, at **its own exchange rate**, and may apply its own receiving or conversion charges.
* **Intermediary bank charges.** Cross-border transfers can pass through correspondent banks, which may levy their own charges on the transfer.

Because both happen at the banks rather than at Dodo Payments, the amount credited to your account can be lower than the payout amount shown in your dashboard, and these charges do not appear on your payout invoice.

<Info>
  Payout routes and currencies vary by country. Contact [support@dodopayments.com](mailto:support@dodopayments.com) to confirm how your payouts will be sent and credited before you link a bank account.
</Info>

## Minimum Payout Threshold

| Currency | Minimum Threshold |
| -------- | ----------------- |
| USD      | \$50              |

<Info>
  If your balance does not meet the threshold, it will carry forward to the next payout cycle.
</Info>

<Warning>
  **INR native wallet discontinued:** Support for the INR native wallet and INR-denominated payouts has been discontinued. Payouts are now consolidated through the USD/GBP/EUR wallets only. INR remains supported as a transaction currency for UPI, RuPay, and Indian-card subscriptions.
</Warning>

<Warning>
  Payouts will only be initiated when the overall wallet balance across all currencies is greater than **\$50 USD** (equivalent). Even if an individual wallet meets its currency-specific threshold, the payout will not be processed unless the total balance exceeds \$50.
</Warning>

## Flexible Minimum Payout Threshold

You can customize the balance that must build up in your USD wallet before Dodo Payments triggers a payout.

**Configuration:**

* **Allowed values:** \$50 or any higher amount
* **Effective from:** Your current payout cycle
* **Note:** Payouts already scheduled (if entry is created in the payout table) remain unchanged

### How to Edit Your Threshold

<Frame>
  <img alt="Edit payout threshold in dashboard" />
</Frame>

<Steps>
  <Step title="Navigate to Payout Settings">
    Go to **Payouts → Payouts Page → Minimum Threshold**
  </Step>

  <Step title="Enter New Threshold">
    Choose edit threshold and enter a number **≥ 50** (e.g., "250")
  </Step>

  <Step title="Confirm Changes">
    Click **Confirm** to save your new threshold
  </Step>

  <Step title="Verify Update">
    You will see the updated amount in the Minimum Payout Threshold field
  </Step>
</Steps>

<Note>
  This feature applies to the USD/EUR/GBP wallets.
</Note>

## Payout Accounts

Manage the bank accounts that receive your payouts directly from the **Payouts** page under **Linked Bank Accounts**. You can maintain **multiple payout accounts** rather than a single fixed one, adding an account per **currency** and **transfer method**.

* **Add an account** for the currency and transfer method you want to be paid in.
* **Save a draft** if you do not have every detail on hand, and finish the submission later.
* **Resubmit** an account placed on hold. The hold or failure reason is shown inline on the account so you know exactly what to correct.
* The **first approved account is activated automatically**. Only the active account receives payouts.
* **Choose Other for an unlisted bank.** If your bank is not in the dropdown, select **Other** and type the name in yourself.

<Info>
  Additional approved accounts remain available so you can switch the active account whenever you need to, for example when you start receiving payouts in a different currency.
</Info>

<Note>
  Bank verification during business onboarding is driven by the same payout accounts flow, so the account you submit while onboarding appears on the **Payouts** page as your first payout account. See [Account Verification](/miscellaneous/verification-process).
</Note>

<Warning>
  Bank account details must match your verified identity or registered entity name. Dodo Payments cannot process payouts to mismatched or third-party accounts. See [Account Verification](/miscellaneous/verification-process) for the full name-matching rules.
</Warning>

## Payout Deductions

The following amounts are deducted from your sales before payout:

**Taxes:**
All applicable taxes as per the Tax Calculator will be deducted from the sales amount before payout.

**Fees:**
Dodo Payment Fees and Payout Fees will be deducted before sending the payout.

<Note>
  Charges levied by your own bank or by intermediary banks are not deducted here and are not shown on your payout invoice. See [Payout Currency and Bank Conversion](#payout-currency-and-bank-conversion).
</Note>

<Tip>
  For detailed fee information, check out our [Pricing Page](https://dodopayments.com/pricing).
</Tip>

## Payout Status

Track the progress of your payouts through the following status indicators:

| Status        | Description                                                                              | Webhook event        |
| ------------- | ---------------------------------------------------------------------------------------- | -------------------- |
| Not Initiated | Payout due date has not yet arrived hence it has not been initiated                      | `payout.created`     |
| In Progress   | Payout due date has arrived and payout is in progress                                    | `payout.in_progress` |
| On Hold       | Payout is put on hold by the Payout Team (by backend until admin dashboard is available) | `payout.on_hold`     |
| Successful    | Payout to the business account is processed successfully                                 | `payout.success`     |
| Failed        | Payout to the business account has failed                                                | `payout.failed`      |

Every status transition also emits a webhook, so you can reconcile payouts in your own systems without polling. See [Payout Webhooks](/developer-resources/webhooks/intents/payout) for the payload and delivery caveats. To receive email or in-app notifications for the same transitions instead, see [Communication Preferences](/features/communication-preferences).

## Payout Invoice

A reverse invoice is generated to indicate the amount paid by Dodo Payments to the business.

### Invoice Structure

<Frame>
  <img alt="Payout invoice structure example" />
</Frame>

<Card title="Balances & Wallets" icon="file-invoice-dollar" href="/features/account-summary-payout-wallet">
  Get a comprehensive overview of all your USD, GBP, and EUR wallet balances, transaction ledgers, and payout-related financial activity.
</Card>


# Product Collections
Source: https://docs.dodopayments.com/features/product-collections

Group related products together for unified checkout experiences, plan selection, and seamless upgrade/downgrade paths within the Customer Portal.

<Info>
  Product Collections let you group related products (e.g., Starter, Pro, Enterprise plans) under one umbrella. Display all options in a single checkout, define upgrade/downgrade paths, and give customers the flexibility to switch plans directly from the Customer Portal.
</Info>

<Frame>
  <img alt="Screenshot of the Product Collection checkout page showing multiple products displayed" />
</Frame>

## Key Highlights

* **Collection-based structure**: Group related products (plans, tiers, pricing options) under a single collection for organized management.
* **One collection, many products**: Include multiple products like Starter, Pro, Lifetime, etc., each with its own pricing model.
* **Dynamic checkout experience**: Display all products from a collection in one checkout view, letting customers choose their preferred plan.
* **Merchant-level control**: Enable, disable, and reorder products within each collection. The first product is automatically pre-selected at checkout.
* **Lifecycle awareness**: Enable customers to upgrade or downgrade between products in the same collection via the Customer Portal.

## Creating a Product Collection

Product Collections are created and managed from the dashboard or via API. Each collection acts as a container for related products.

<Steps>
  <Step title="Create the collection">
    Define the collection with a name and optional description. Upload an image to visually represent the collection in checkout.

    <Frame>
      <img alt="Screenshot of the Product Collection creation form in the dashboard showing fields for name, description, and image upload" />
    </Frame>

    **Collection fields:**

    * **Name** (required): Display name for the collection (e.g., "SaaS Plans", "License Tiers")
    * **Description** (optional): Brief explanation shown in checkout
    * **Image** (optional): Visual branding for the collection
  </Step>

  <Step title="Add products to the collection">
    Add existing products to your collection. Products can be organized into groups for better structure.

    <Frame>
      <img alt="Screenshot of the Product Collection products page showing a list of products and the ability to add them to the collection" />
    </Frame>

    **Product organization:**

    * **Groups**: Optionally organize products into named groups (e.g., "Monthly Plans", "Annual Plans")
    * **Ungrouped products**: Products without a group appear at the collection level
    * **Ordering**: Drag and drop to set the display order

    <Warning>
      Each product can only belong to one collection. If a product is already in another collection, you'll need to remove it first.
    </Warning>
  </Step>

  <Step title="Configure ordering and visibility">
    Control the display order and visibility of products within the collection.

    **Configuration options:**

    * **Product status**: Enable or disable individual products within the collection
    * **Display order**: Drag and drop to set the sequence products appear in checkout

    <Info>
      The first product in the collection is automatically pre-selected as the default at checkout. Reorder products to change which one is selected by default.
    </Info>
  </Step>
</Steps>

## Collection Checkout

Collections enable a unified checkout experience where customers can view and select from all available products in one place.

### Checkout Types

| Type                        | Description                                      | Use Case                                    |
| --------------------------- | ------------------------------------------------ | ------------------------------------------- |
| **Collection Checkout**     | Displays all active products within a collection | Subscription plan selection, tiered pricing |
| **Single Product Checkout** | Displays only one specific product               | Direct purchase, promotional links          |

### Collection Checkout Experience

When using a collection checkout:

1. **All active products displayed**: Customers see every enabled product in the collection
2. **First product pre-selected**: The first product in the collection order is automatically selected
3. **Product details shown**: Each product displays its name, description, and pricing
4. **Single selection**: Customer selects one product to purchase
5. **Standard flow continues**: After selection, the checkout proceeds with the chosen product's pricing and billing settings

<Frame>
  <img alt="Screenshot of the Product Collection checkout page showing multiple products displayed" />
</Frame>

<Tip>
  Collection checkout is ideal for subscription businesses where you want customers to compare plans side-by-side before purchasing.
</Tip>

### API Integration

Create a checkout session for a collection:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_collection_id: 'pdc_abc123',
  product_cart: [], // Required: pass an empty array for collection checkout
  return_url: 'https://yoursite.com/return'
});

// Redirect customer to the checkout
window.location.href = session.checkout_url;
```

<Warning>
  When using `product_collection_id`, discount codes cannot be applied at session creation. Customers can still enter discount codes during checkout if enabled.
</Warning>

## Customer Portal Integration

Customers can upgrade or downgrade between products within the same collection directly from the Customer Portal.

<Tip>
  **Already have subscription products?** Simply add them to a Product Collection to enable upgrade/downgrade flows in the Customer Portal. No need to recreate your products.
</Tip>

### Plan Management Actions

| Action                | Description                                           | Merchant Control                |
| --------------------- | ----------------------------------------------------- | ------------------------------- |
| **View Current Plan** | Display current product name, price, and renewal date | Always available                |
| **Upgrade Plan**      | Move to a higher-tier product in the same collection  | Configurable (default: allowed) |
| **Downgrade Plan**    | Move to a lower-tier product in the same collection   | Configurable (default: allowed) |
| **Cancel**            | Cancel the subscription entirely                      | Always available                |

<Frame>
  <img alt="Screenshot of the Product Collection customer portal plan change interface showing the plan management actions" />
</Frame>

### Upgrade/Downgrade Rules

* Upgrades and downgrades are only available between products **within the same collection**
* Proration is applied based on your subscription settings
* Email notifications are sent to the business on every upgrade, downgrade, or cancellation

<Frame>
  <img alt="Screenshot of the Product Collection customer portal plan change interface showing the plan management actions" />
</Frame>

<Info>
  Customers cannot change to products outside their current collection. Create separate collections for distinct product lines.
</Info>

## Subscription Settings

Configure how subscriptions and plan changes work across your business from **Settings → Subscriptions** in your dashboard.

<Frame>
  <img alt="Screenshot of the subscription settings page showing Allow Multiple Subscriptions and Allow Subscription Updates toggles" />
</Frame>

### Available Settings

| Setting                             | Description                                                                                                              | Default  |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- |
| **Allow Multiple Subscriptions**    | Customers can hold more than one active subscription at the same time                                                    | Enabled  |
| **Allow Subscription Updates**      | Customers can upgrade or downgrade their existing subscriptions anytime via Customer Portal                              | Disabled |
| **Allow Subscription Cancellation** | Customers can cancel their own subscriptions from the Customer Portal                                                    | Enabled  |
| **Prevent Trial Misuse**            | Customers who have already redeemed a trial are degraded to a paid, no-trial purchase instead of receiving a fresh trial | Disabled |

<Info>
  Plan changes via Customer Portal are disabled by default. Enable "Allow Subscription Updates" in **Settings → Subscriptions** to let customers upgrade or downgrade between products in the same collection.
</Info>

<Info>
  Turning off "Allow Subscription Cancellation" hides self-service cancellation from customers and rejects cancellation requests made through the Customer Portal API. Your own merchant-side cancellations are unaffected. See [Cancelling a Subscription](/features/customer-portal#cancelling-a-subscription).
</Info>

<Info>
  For details on how trial redemptions are matched and recorded, see [Preventing Trial Misuse](/features/subscription#preventing-trial-misuse).
</Info>

<Card title="Subscription Plan Changes" icon="repeat" href="/features/subscription#subscription-plan-changes">
  Learn more about proration modes and plan change behavior.
</Card>

## Managing Collections

Product Collections can be managed either through the Dodo Payments dashboard or programmatically via API. The API provides full control over collection creation, updates, image uploads, archiving, and managing nested groups and products.

### Dashboard Operations

* **Create**: Set up new collections with products and groups
* **Update**: Modify name, description, image, and product organization
* **Reorder**: Drag and drop to change product display order
* **Enable/Disable products**: Control which products appear in checkout
* **Archive**: Hide a collection without permanently deleting it (can be unarchived later)

<Frame>
  <img alt="Screenshot of the Product Collection dashboard showing the collection management operations" />
</Frame>

### API Management

The following endpoints allow you to create, update, retrieve, archive, and organize product collections programmatically — including managing nested groups and the products within them.

<AccordionGroup>
  <Accordion title="Listing Product Collections">
    Fetch all product collections associated with your account using a `GET` request to the `/product-collections` endpoint. Supports pagination, filtering by brand, and including archived collections.

    <Card title="List Product Collections API" icon="code" href="/api-reference/product-collections/list-product-collections">
      View detailed request and response structure in the List Product Collections API documentation.
    </Card>
  </Accordion>

  <Accordion title="Creating a Product Collection">
    Create a new product collection by sending a `POST` request to the `/product-collections` endpoint with details such as name, description, and brand.

    <Card title="Create Product Collection API" icon="code" href="/api-reference/product-collections/create-product-collection">
      View detailed request and response structure in the Create Product Collection API documentation.
    </Card>
  </Accordion>

  <Accordion title="Retrieving a Product Collection">
    Get detailed information about a specific product collection — including its groups and product items — using a `GET` request to the `/product-collections/{id}` endpoint.

    <Card title="Get Product Collection API" icon="code" href="/api-reference/product-collections/get-product-collection">
      View detailed request and response structure in the Get Product Collection API documentation.
    </Card>
  </Accordion>

  <Accordion title="Updating a Product Collection">
    Modify a product collection's details (name, description, brand, etc.) by sending a `PATCH` request to the `/product-collections/{id}` endpoint.

    <Card title="Update Product Collection API" icon="code" href="/api-reference/product-collections/update-product-collection">
      View detailed request and response structure in the Update Product Collection API documentation.
    </Card>
  </Accordion>

  <Accordion title="Uploading Collection Images">
    Associate an image with a collection by uploading it via a pre-signed URL. Request an upload URL from the `/product-collections/{id}/images` endpoint, then `PUT` the image to the returned URL within 60 seconds.

    <Warning>
      The pre-signed URL expires in 60 seconds, so the image must be uploaded within that timeframe.
    </Warning>

    <Card title="Update Collection Images API" icon="code" href="/api-reference/product-collections/update-product-collection-images">
      View detailed request and response structure in the Update Collection Images API documentation.
    </Card>
  </Accordion>

  <Accordion title="Archiving a Product Collection">
    Archive a collection by sending a `DELETE` request to the `/product-collections/{id}` endpoint. This hides the collection from new use but does not permanently remove it.

    <Card title="Archive Product Collection API" icon="code" href="/api-reference/product-collections/archive-product-collection">
      View detailed request and response structure in the Archive Product Collection API documentation.
    </Card>
  </Accordion>

  <Accordion title="Unarchiving a Product Collection">
    Restore an archived collection by sending a `POST` request to the `/product-collections/{id}/unarchive` endpoint.

    <Card title="Unarchive Product Collection API" icon="code" href="/api-reference/product-collections/unarchive-product-collection">
      View detailed request and response structure in the Unarchive Product Collection API documentation.
    </Card>
  </Accordion>

  <Accordion title="Managing Groups within a Collection">
    Groups let you organize products inside a collection (for example, "Monthly Plans" vs. "Annual Plans"). Use the groups endpoints to add, update, or remove groups within a collection.

    * **Create a group**: `POST /product-collections/{id}/groups`
    * **Update a group**: `PATCH /product-collections/{id}/groups/{group_id}`
    * **Delete a group**: `DELETE /product-collections/{id}/groups/{group_id}`

    <CardGroup>
      <Card title="Create Group" icon="code" href="/api-reference/product-collections/create-group">
        Add a new group to a product collection.
      </Card>

      <Card title="Update Group" icon="code" href="/api-reference/product-collections/update-group">
        Modify a group's name or attributes.
      </Card>

      <Card title="Delete Group" icon="code" href="/api-reference/product-collections/delete-group">
        Remove a group from a collection.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Managing Products within a Group">
    Manage the individual product items inside a group — add new products, update existing items (such as display order), or remove them entirely.

    * **Add products to a group**: `POST /product-collections/{id}/groups/{group_id}/items`
    * **Update a group item**: `PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}`
    * **Delete a group item**: `DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}`

    <CardGroup>
      <Card title="Add Products to Group" icon="code" href="/api-reference/product-collections/add-group-items">
        Add one or more products to a group within a collection.
      </Card>

      <Card title="Update Group Item" icon="code" href="/api-reference/product-collections/update-group-item">
        Update a product item within a group.
      </Card>

      <Card title="Delete Group Item" icon="code" href="/api-reference/product-collections/delete-group-item">
        Remove a product item from a group.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Best Practices

* **Group logically**: Organize products by billing interval (monthly/annual) or feature tier (starter/pro/enterprise)
* **Order strategically**: Place your most popular or recommended plan first, as it will be pre-selected at checkout
* **Use clear naming**: Product names should clearly communicate value differences
* **Enable both directions**: Allow both upgrades and downgrades to give customers flexibility
* **Consider proration**: Choose a proration mode that aligns with your business model
* **Test thoroughly**: Verify checkout and plan change flows in test mode before going live

<Check>
  You're ready to create product collections and offer customers a unified plan selection experience.
</Check>

<CardGroup>
  <Card title="Products" icon="box" href="/features/products">
    Create one-time, subscription, or usage-based products to add to collections.
  </Card>

  <Card title="Checkout" icon="cart-shopping" href="/features/checkout">
    Display collection products in a unified checkout experience.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    Let customers upgrade or downgrade within the same collection.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Manage recurring plans with proration and plan changes.
  </Card>
</CardGroup>


# Products
Source: https://docs.dodopayments.com/features/products

Create one-time, subscription, or usage-based products in minutes. Manage pricing, media, fields, and automated entitlements - all in one place.

<Info>
  Products are the foundation of Dodo Payments. Whether you sell a one‑time download, a recurring subscription, or usage‑based access, you start by creating a product. Each product defines how it’s priced, presented at checkout, and fulfilled after purchase.
</Info>

<CardGroup>
  <Card title="One‑Time" icon="credit-card" href="/features/one-time-payment-products">
    Charge once for lifetime access or a single deliverable.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Bill on a schedule with trials, proration, and add‑ons.
  </Card>

  <Card title="Usage‑Based" icon="arrow-trend-up" href="/features/usage-based-billing/introduction">
    Meter consumption and bill by actual usage.
  </Card>
</CardGroup>

## Create a product

You can create products from the dashboard or via API. Choose the pricing model up‑front, One‑Time, Subscription, or Usage‑Based and then configure details. The pricing model can’t be changed later; create a new product if you need a different model.

<Steps>
  <Step title="Name & description">
    Provide a clear title and a concise value‑oriented description. Markdown is supported in descriptions.

    <Tip>
      Keep the first sentence customer‑facing and outcome‑oriented; it appears prominently in checkout.
    </Tip>

    <Frame>
      <img alt="Products" />
    </Frame>
  </Step>

  <Step title="Pricing model & price">
    Select the pricing model:

    * **One‑Time**: Fixed price paid once.
    * **Subscription**: Recurring price with interval and optional trial.
    * **Usage‑Based**: Price derived from metered events.

    Then set pricing:

    * **Price**: Base amount and currency. You can set the base price in **any currency Dodo Payments can charge**, not just USD. Use the searchable currency selector to find a currency; **USD, GBP, EUR, and INR** are pinned to the top of the list.
    * **Discount (%)**: Optional inline discount shown in checkout and invoices.
    * For subscriptions, set **Repeat every** (e.g., 1 month or 1 year), **Trial days**, and an optional **Trial amount** for a [paid trial](/features/subscription#paid-trials). The subscription price must be at least **\$1** (or the equivalent in your chosen currency); amounts below this minimum are not supported and the subscription will not work.

    <Info>
      Customers outside your base currency are still billed through [Adaptive Currency](/features/adaptive-currency), so you can author prices in whichever currency best fits your market without changing how buyers are charged.
    </Info>

    <Tip>
      Want a fixed price per currency or country instead of a live FX conversion? Set a `pricing_mode` on the product and attach [Localized Pricing](/features/localized-pricing) rules — for example €9.99 in EUR or ₹999 in India.
    </Tip>

    <Warning>
      Changing price affects only new purchases. Existing subscriptions follow plan‑change rules.
    </Warning>
  </Step>

  <Step title="Product media">
    Upload images to showcase the product on checkout and invoices. Supported PNG/JPG/WebP up to 3 MB. Reorder or replace any time.
  </Step>

  <Step title="Automated entitlements (Under Advanced Settings)">
    Attach fulfillment that activates automatically after payment:

    * **License Keys**: Issue and validate unique keys
    * **File Downloads**: Grant secure file access
    * **Custom**: Trigger your own entitlement logic via webhooks

    Add or remove benefits as your offer evolves. Existing subscribers gain or lose access accordingly.
  </Step>
</Steps>

## Variants and pricing options

Instead of variants under one product, create separate products for each pricing option (for example, Monthly and Yearly). Then group them into a **Product Collection** to present all options in a single checkout and enable plan switching in the Customer Portal.

<Frame>
  <img alt="Product Collections" />
</Frame>

### Why this approach?

* **Clear pricing models**: Each product has a single, well-defined pricing model (one-time, subscription, or usage-based)
* **Predictable APIs**: Simpler integrations without nested variant logic
* **Easier reporting**: Track revenue and metrics per product without variant aggregation
* **Flexible checkout**: Display multiple products side-by-side, letting customers compare and choose

### How Product Collections work

1. **Create products**: Set up individual products for each plan (e.g., Starter Monthly, Starter Annual, Pro Monthly, Pro Annual)
2. **Group into a collection**: Add related products to a Product Collection
3. **Unified checkout**: Customers see all options in one checkout and select their preferred plan
4. **Plan switching**: Customers can upgrade or downgrade between products in the same collection via the Customer Portal

<Card title="Product Collections" icon="layer-group" href="/features/product-collections">
  Group related products together for unified checkout experiences and seamless upgrade/downgrade paths.
</Card>

## Managing products

You can manage products through the dashboard or programmatically via API. The API provides full control over product creation, updates, retrieval, image uploads, and archiving.

### Dashboard Management

* **Update**: Edit name, description, images, price, fields, and benefits at any time (pricing model is immutable).
* **Archive**: Hide a product from new purchases without disrupting existing customers. You can unarchive later.
* **Drafts**: An in-progress product is saved as a draft so you can return to it later. Drafts are kept **separately for test mode and live mode**, so an unfinished product in one mode never bleeds into the other. Use **Clear Draft** to discard it and start fresh.

<Tip>
  Product and collection form pages include header action buttons, so you can save without scrolling to the bottom of a long form.
</Tip>

### API Management

The following instructions allow you to create, update, manage, and retrieve products, including uploading images.

<AccordionGroup>
  <Accordion title="Creating a Product">
    A product can be a one-time item or a subscription-based service. To create a new product, send a `POST` request to the `/products` endpoint with details such as name, description, price, currency, and whether it is a recurring product.

    For recurring products, set the `price` object to a recurring price (`type: recurring_price`) and specify `payment_frequency_interval` and `subscription_period_interval` (`Day`, `Week`, `Month`, or `Year`) along with their corresponding counts.

    <Card title="Create Product API" icon="code" href="/api-reference/products/post-products">
      View detailed request and response structure in the Create Product API documentation.
    </Card>
  </Accordion>

  <Accordion title="Updating a Product">
    To modify an existing product, send a `PATCH` request to the `/products/{product_id}` endpoint. You can update properties such as name, price, and description while keeping other details unchanged.

    Ensure that the `product_id` in the endpoint matches an existing product.

    <Card title="Update Product API" icon="code" href="/api-reference/products/patch-products">
      View detailed request and response structure in the Update Product API documentation.
    </Card>
  </Accordion>

  <Accordion title="Retrieving Products">
    You can fetch a list of products stored in your account using a `GET` request to the `/products` endpoint. This allows you to retrieve product details, including active and archived products.

    <Card title="Retrieve Products API" icon="code" href="/api-reference/products/get-products">
      View detailed request and response structure in the Retrieve Products API documentation.
    </Card>
  </Accordion>

  <Accordion title="Uploading Product Images">
    You can associate an image with a product by uploading it to AWS S3 using a pre-signed URL provided by the API. First, request an image upload URL from the `/products/{product_id}/images` endpoint, then use the provided URL to upload the image within 60 seconds.

    <Warning>
      The pre-signed URL expires in 60 seconds, so the image must be uploaded within that timeframe.
    </Warning>

    Once the pre-signed URL is received from the API, upload the image using the `PUT` method. This ensures secure and temporary access to AWS S3 for uploading the image.

    **Supported libraries for uploading to S3:**

    * **Node.js**: `axios`, `node-fetch`
    * **Python**: `requests`, `boto3`
    * **Go**: `net/http`
    * **PHP**: `GuzzleHttp`
    * **Ruby**: `rest-client`

    If the upload is successful, AWS S3 will return a `200 OK` status, indicating that the image has been stored successfully.

    <Card title="Upload Product Image API" icon="code" href="/api-reference/products/put-products-images">
      View detailed request and response structure in the Upload Product Image API documentation.
    </Card>
  </Accordion>

  <Accordion title="Archiving a Product">
    If you no longer wish to display or use a product, you can archive it using a `DELETE` request to the `/products/{id}` endpoint. This action hides the product but does not delete it permanently.

    <Card title="Archive Product API" icon="code" href="/api-reference/products/archive-product">
      View detailed request and response structure in the Archive Product API documentation.
    </Card>
  </Accordion>

  <Accordion title="Unarchiving a Product">
    If you need to restore an archived product, send a `POST` request to the `/products/{product_id}/unarchive` endpoint. This will reactivate the product and make it available for use again.

    <Card title="Unarchive Product API" icon="code" href="/api-reference/products/unarchive-product">
      View detailed request and response structure in the Unarchive Product API documentation.
    </Card>
  </Accordion>

  <Accordion title="Checkout & fulfillment">
    Create payment or subscription flows from products, and fulfill automatically via benefits and webhooks.

    <CardGroup>
      <Card title="Checkout Sessions" icon="code" href="/developer-resources/checkout-session">
        Create checkout sessions for one‑time or subscription purchases.
      </Card>

      <Card title="Payment Webhooks" icon="code" href="/developer-resources/webhooks/intents/payment">
        React to payment lifecycle events.
      </Card>

      <Card title="Subscription Webhooks" icon="code" href="/developer-resources/webhooks/intents/subscription">
        Handle subscription created, renewed, and canceled events.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Best practices

* **Start with clarity**: Separate products for each pricing option (Monthly vs Yearly)
* **Use trials thoughtfully**: Pair trials with onboarding to drive activation
* **Automate fulfillment**: Use benefits and webhooks to deliver instantly
* **Tag with metadata**: Store your system IDs for reconciliation

<Check>
  You're ready to create products and start selling - one‑time, recurring, or by usage.
</Check>

## Related

<CardGroup>
  <Card title="Product Analytics" icon="chart-mixed" href="/features/analytics-and-reporting#product-level-analytics">
    Track revenue, customers, retention, subscribers, and MRR for each individual product.
  </Card>

  <Card title="Localized Pricing" icon="earth-americas" href="/features/localized-pricing">
    Set fixed per-currency or per-country prices on a product instead of relying on live exchange rates.
  </Card>
</CardGroup>


# Purchasing Power Parity
Source: https://docs.dodopayments.com/features/purchasing-power-parity

Run purchasing power parity pricing on Dodo Payments with native Localized Pricing, fixed local prices per country, or with location-based discount codes via ParityDeals and Evendeals.

Purchasing power parity (PPP) pricing adjusts what you charge to match the buying power of each customer's location. There are two ways to do it on Dodo Payments.

<Info>
  **Recommended:** Use native [Localized Pricing](/features/localized-pricing) to set a fixed local price per country, for example ₹999 in India for a product with a \$20 base. You control the exact number, it carries across one-time, subscription, and usage-based products, and there is no banner or script to install.
</Info>

<CardGroup>
  <Card title="Localized Pricing" icon="earth-americas" href="/features/localized-pricing">
    Native, recommended. Set a fixed local price per country or currency, no third-party tool required.
  </Card>

  <Card title="Discount Codes" icon="percent" href="/features/discount-codes">
    Create and manage location-based discount codes in the Dodo Payments dashboard.
  </Card>
</CardGroup>

## Two ways to run PPP

|                              | Localized Pricing (native)                       | Location-based discount codes                                                                                   |
| :--------------------------- | :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| How it works                 | You set a fixed local price per country/currency | A percentage off your base price, applied via a code                                                            |
| Tooling                      | Built into Dodo Payments                         | [ParityDeals](https://www.paritydeals.com/) / [Evendeals](https://www.evendeals.com/integrations/dodo-payments) |
| Banner / script on your site | Not required                                     | Required to surface the code                                                                                    |
| Price the customer sees      | The exact amount you set                         | Base price minus the discount                                                                                   |
| Best for                     | Clean, market-tuned prices you fully control     | Promotional banners and time/holiday-based deals                                                                |

For native setup, see [Localized Pricing](/features/localized-pricing). The rest of this page covers the location-based discount-code approach with ParityDeals and Evendeals.

***

## Location-based discount codes

[ParityDeals](https://www.paritydeals.com/) and [Evendeals](https://www.evendeals.com/integrations/dodo-payments) are platforms that enable automatic pricing optimization based on a customer's geographical location by generating discount codes.

<Info>
  While you can't directly embed discount banners on a Dodo Payments storefront (as custom scripts aren't supported), you can still implement these tools effectively on your own website or application.
</Info>

### Choosing an Integration

Both platforms integrate directly with Dodo Payments to create and manage discount codes automatically. Use the comparison below to choose the tool that best fits your needs.

| Feature                      |                      ParityDeals                     |                     Evendeals                     |
| :--------------------------- | :--------------------------------------------------: | :-----------------------------------------------: |
| PPP / Location-based pricing |                          Yes                         |                        Yes                        |
| Holiday / Time-based deals   |                          Yes                         |                         No                        |
| Subscription support         |                          Yes                         |                        Yes                        |
| Auto coupon refresh          |                           —                          |                        Yes                        |
| Banner customization         |                          Yes                         |                         No                        |
| Pricing                      | [View Pricing](https://www.paritydeals.com/pricing/) | [View Pricing](https://www.evendeals.com/pricing) |

### ParityDeals

When ParityDeals is integrated into your website, eligible visitors will see a banner that includes a location-based discount code they can use at checkout. These discount codes are automatically created and managed by ParityDeals and will appear in your **Dodo Payments Dashboard** under **Sales → Discounts**.

<Frame>
  <img alt="ParityDeals discount banner example" />
</Frame>

#### Setup

<Steps>
  <Step title="Sign up on ParityDeals">
    Visit [app.paritydeals.com](https://app.paritydeals.com/) and create an account.
  </Step>

  <Step title="Create Deals">
    After signing in, locate the option to create deals. From the dropdown menu, select **"Create Deals via Dodo Payments"**.

    <Frame>
      <img alt="Creating deals via Dodo Payments" />
    </Frame>
  </Step>

  <Step title="Generate a Dodo Payments API Key">
    Log in to your **Dodo Payments dashboard** and navigate to **Developers → API Keys**. Click **"Create New API"**.

    <Tip>
      Name your API key descriptively (e.g., 'ParityDeals') so you can identify it later.
    </Tip>

    <Frame>
      <img alt="Creating a new API key in Dodo Payments" />
    </Frame>
  </Step>

  <Step title="Connect Your API Key to ParityDeals">
    Copy the API key you created and paste it into the ParityDeals interface to establish the connection with your Dodo Payments account.

    <Frame>
      <img alt="Connecting API key to ParityDeals" />
    </Frame>
  </Step>

  <Step title="Select Products">
    Once connected, ParityDeals will fetch your Dodo Payments product catalog. Select the products you want to associate with your deals.

    <Frame>
      <img alt="Selecting products for ParityDeals" />
    </Frame>
  </Step>

  <Step title="Configure Deal Settings">
    Enter your website URL and optionally select specific target pages where the discount banner should appear. Then choose your preferred deal type:

    * Location-based deals
    * Holiday deals
    * Time-based flash deals

    <Frame>
      <img alt="Configuring deal settings" />
    </Frame>
  </Step>

  <Step title="Set Country-Based Rules">
    Select the countries you want to offer localized discounts to and define the discount percentage for each. ParityDeals provides recommended defaults that you can adjust as needed.

    <Frame>
      <img alt="Setting country-based discount rules" />
    </Frame>
  </Step>

  <Step title="Customize the Banner">
    Design your discount banner by customizing the text, selecting colors and layout, and choosing the banner position (top or bottom of page). This banner will be displayed to eligible visitors based on your configured rules.

    <Frame>
      <img alt="Customizing the discount banner" />
    </Frame>
  </Step>

  <Step title="Add the ParityDeals Script to Your Website">
    After saving your deal, ParityDeals will generate a script. Add this script to your website code (typically in the `<head>` section). This script automatically detects visitor locations and displays the appropriate discount banner.

    <Frame>
      <img alt="ParityDeals integration script" />
    </Frame>
  </Step>
</Steps>

#### Additional Features

With ParityDeals, you can also offer [automatic time-based discounts](https://www.paritydeals.com/features/time-based-discounts/) and [holiday-based promotions](https://www.paritydeals.com/features/holiday-based-discounts/) throughout the year. For more detailed information, refer to the [ParityDeals Documentation](https://www.paritydeals.com/docs/).

### Evendeals

[Evendeals](https://www.evendeals.com/integrations/dodo-payments) is another platform that integrates with Dodo Payments to offer location-based purchasing power parity pricing. It supports both one-time and subscription products.

<Frame>
  <img alt="Evendeals Dodo Payments integration overview" />
</Frame>

#### Key Features

* **Auto coupon sync** — Coupons are created and managed in Dodo Payments automatically
* **Percentage discounts** — Offer percentage-off discounts per country group
* **Subscription support** — Discounts apply across subscription billing cycles
* **Auto-refresh rules** — Rotate coupon codes automatically by time interval, redemption count, or view count to prevent abuse

<Info>
  Discount codes created by Evendeals will automatically appear in your Dodo Payments dashboard under Sales → Discounts.
</Info>

<Frame>
  <img alt="Evendeals key features for Dodo Payments integration" />
</Frame>

#### Setup

<Steps>
  <Step title="Create a Dodo Payments API key">
    In your Dodo Payments dashboard, go to **Developers → API Keys** and generate a new key.
  </Step>

  <Step title="Connect in Evendeals">
    In your [Evendeals dashboard](https://www.evendeals.com/signin), navigate to **Integrations**, find the Dodo Payments card, and paste your API key.
  </Step>

  <Step title="Configure regional discounts">
    Set percentage discounts for each country group and hit sync. Evendeals creates coupons in Dodo Payments automatically.

    <Check>
      After syncing, open **Sales → Discounts** in your Dodo Payments dashboard to confirm the generated coupons appear. Each coupon will have a recognizable Evendeals prefix.
    </Check>
  </Step>
</Steps>

<Frame>
  <img alt="Evendeals setup guide for Dodo Payments" />
</Frame>

Both ParityDeals and Evendeals work seamlessly with Dodo Payments to help you optimize your global pricing strategy. For more details, visit the [ParityDeals Documentation](https://www.paritydeals.com/docs/) or the [Evendeals Dodo Payments integration page](https://www.evendeals.com/integrations/dodo-payments).


# Abandoned Cart Recovery
Source: https://docs.dodopayments.com/features/recovery/abandoned-cart-recovery

Automatically detect incomplete or failed checkouts and send targeted email sequences to bring customers back to complete their purchase.

<Info>
  Abandoned Cart Recovery (ACR) detects incomplete or failed checkouts and sends automated email sequences to bring customers back. Combine with optional discount incentives to maximize recovery rates.
</Info>

## What Is Abandoned Cart Recovery?

ACR automatically identifies customers who started but didn't complete a checkout — whether the payment failed or they left before paying — and sends a sequence of recovery emails to bring them back.

* **Failed payments**: Customer attempted payment but it was declined or errored
* **Incomplete checkouts**: Customer visited checkout but never attempted payment

## How ACR Works

<Steps>
  <Step title="Detection">
    We scan for payments that are 60+ minutes old and haven't succeeded. This includes failed payments and checkouts where the customer never attempted payment.
  </Step>

  <Step title="Classification">
    Each abandoned checkout is classified by reason:

    * **Payment Failed**: The customer attempted payment but it failed
    * **Checkout Incomplete**: The customer visited checkout but never attempted payment
  </Step>

  <Step title="Email Sequence">
    Based on the classification, the system sends up to 3 recovery emails at configured intervals. Each email contains a unique recovery link.
  </Step>

  <Step title="Recovery">
    When the customer clicks the recovery link, they are taken to a recovery page showing their original cart. They can complete payment with a fresh checkout session.
  </Step>
</Steps>

## Status Lifecycle

Each abandoned checkout progresses through these states:

| Status       | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `abandoned`  | Checkout detected as abandoned, no emails sent yet                        |
| `recovering` | At least one recovery email has been sent                                 |
| `recovered`  | Customer completed payment via the recovery link                          |
| `exhausted`  | All emails sent with no recovery, or a newer checkout superseded this one |
| `opted_out`  | Customer unsubscribed from recovery emails                                |

## Configuring ACR

Enable and configure ACR from **Settings** in your dashboard.

<Frame>
  <img alt="ACR settings page showing enable toggle, discount configuration, and email sequence editor" />
</Frame>

### Global Settings

| Setting                 | Description                                                                | Default |
| ----------------------- | -------------------------------------------------------------------------- | ------- |
| **Enabled**             | Master toggle for ACR                                                      | Off     |
| **Discount Enabled**    | Auto-generate a discount code for recovery emails                          | Off     |
| **Discount Percentage** | Percentage discount that will be applied to the checkout for this customer | 0       |
| **Discount Valid Days** | How many days the auto-generated discount code remains valid               | 5       |

### Email Sequences

ACR supports two email sequences — **Payment Failed** and **Checkout Incomplete** — each with up to 3 configurable emails.

<Frame>
  <img alt="Email sequence editor showing subject, body, timing, and enable toggle for each email in the sequence" />
</Frame>

| Setting      | Description                                              |
| ------------ | -------------------------------------------------------- |
| **Enabled**  | Toggle individual emails on or off without deleting them |
| **Delay**    | How long after abandonment detection to send this email  |
| **Subject**  | Email subject line with variable placeholders            |
| **Body**     | HTML email body with variable placeholders               |
| **Reply-To** | Email address for customer replies                       |

**Default email timing:**

| Email # | Default Delay |
| ------- | ------------- |
| 1       | 1 hour        |
| 2       | 24 hours      |
| 3       | 72 hours      |

### Example Recovery Emails

ACR sends different emails depending on the abandonment reason. Below are examples of each type as seen by the customer.

<Tabs>
  <Tab title="Payment Failed">
    <Frame>
      <img alt="Recovery email for a failed payment showing store name, message about payment failure, order summary with product details, discount, and a Resume Checkout button" />
    </Frame>
  </Tab>

  <Tab title="Checkout Incomplete">
    <Frame>
      <img alt="Recovery email for an incomplete checkout showing store name, message about saved cart, order summary with product details, discount, and a Resume Checkout button" />
    </Frame>
  </Tab>
</Tabs>

## Recovery Discounts

When discount is enabled, ACR automatically generates a unique, single-use discount code for each abandoned checkout. The discount:

* Is restricted to the product(s) from the original checkout
* Has a configurable expiration period
* Is limited to one redemption
* Is hidden from your dashboard discount list (internal use only)

<Tip>
  Start with a modest discount (5-10%) to test conversion impact before increasing. Even a small incentive can significantly improve recovery rates.
</Tip>

## Customer Recovery Experience

When a customer clicks the recovery link in an email, they're taken back to
their original checkout session. The page displays the product they left
behind, along with a discount code if one has been configured.

## Analytics

Track the performance of ACR from the **Analytics** section of your dashboard.

<Frame>
  <img alt="Recovery analytics dashboard showing abandoned checkout counts, recovery rates, recovered revenue, average time to recover, and breakdowns by product and email" />
</Frame>

| Metric                  | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| **Abandoned Checkouts** | Total number of detected abandoned checkouts                |
| **Recovery Rate**       | Percentage of abandoned checkouts that were recovered       |
| **Recovered Revenue**   | Total revenue recovered through ACR                         |
| **Avg. Recovery Time**  | Average time from abandonment to recovery                   |
| **Recovery by Email**   | Breakdown of which email in the sequence drove the recovery |
| **Recovery by Product** | Which products have the highest recovery rates              |

## Webhook Events

| Event                          | Description                                                    |
| ------------------------------ | -------------------------------------------------------------- |
| `abandoned_checkout.detected`  | An abandoned checkout has been detected and recovery has begun |
| `abandoned_checkout.recovered` | A customer completed payment through the recovery flow         |

<Card title="Recovery Webhook Payloads" icon="code" href="/developer-resources/webhooks/intents/recovery">
  View the full webhook payload schemas for ACR events.
</Card>

## Edge Cases

| Scenario                                       | Behavior                                                                       |
| ---------------------------------------------- | ------------------------------------------------------------------------------ |
| Customer completes purchase before next email  | Recovery is detected at send time; checkout is marked as recovered if eligible |
| Customer starts a new checkout                 | Old abandoned checkout is marked as `exhausted`                                |
| Customer clicks "Pay" after already recovering | Recovery page shows a confirmation that payment was already completed          |
| Customer unsubscribes                          | Abandoned Checkout is marked as `opted_out`; no further emails are sent        |

## Best Practices

* **Start with defaults**: The default email timing and subjects are optimized for common recovery patterns. Customize after you have baseline data.
* **Personalize emails**: Use template variables to make emails feel personal and relevant to the customer.
* **Monitor analytics**: Track recovery rates by email to identify which messages drive the most conversions. Disable underperforming emails.
* **Use discounts strategically**: Start small (5-10%) to protect margins while testing conversion impact.
* **Keep emails concise**: Recovery emails should be short and action-oriented. A clear call-to-action drives better results than lengthy explanations.

<Info>
  ACR is designed to work automatically once enabled. Start with the default settings, monitor your analytics, and iterate based on performance data.
</Info>

## Related

<CardGroup>
  <Card title="Recovery Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/recovery">
    React to `abandoned_checkout.detected` and `abandoned_checkout.recovered` events.
  </Card>

  <Card title="Subscription Dunning" icon="rotate" href="/features/recovery/subscription-dunning">
    Recover lapsed subscriptions with automated dunning emails.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    Customers complete recovery actions through the customer portal.
  </Card>

  <Card title="Discounts" icon="percent" href="/features/discount-codes">
    ACR can auto-generate discount codes to incentivize recovery.
  </Card>
</CardGroup>


# Revenue Recovery
Source: https://docs.dodopayments.com/features/recovery/overview

Recover revenue lost to failed payments and abandoned checkouts with Dodo Payments' automatic retries, dunning emails, and abandoned cart recovery.

<Info>
  Not every failed payment is lost revenue. Dodo Payments includes three recovery tools that automatically win back failed renewals and abandoned checkouts — most with no integration work.
</Info>

## Recovery Tools

<CardGroup>
  <Card title="Subscription Payment Retries" icon="arrow-rotate-right" href="/features/recovery/payment-retries">
    Silently re-attempt failed subscription renewals on a smart back-off schedule.
  </Card>

  <Card title="Subscription Dunning" icon="repeat" href="/features/recovery/subscription-dunning">
    Email customers to update their payment method when a renewal fails or they cancel.
  </Card>

  <Card title="Abandoned Cart Recovery" icon="cart-shopping" href="/features/recovery/abandoned-cart-recovery">
    Email customers who fail or abandon a one-time checkout to bring them back.
  </Card>
</CardGroup>

## Which Tool Recovers What

Pick the tool that matches the failure scenario:

| Scenario                                                                                 | Recovery tool                                                         | How it recovers                                                   |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Subscription **renewal** fails on a **soft decline** (insufficient funds, network error) | [Payment Retries](/features/recovery/payment-retries)                 | Automatically re-charges the existing card on a back-off schedule |
| Subscription **renewal** fails on a **hard decline** (expired/invalid card)              | [Subscription Dunning](/features/recovery/subscription-dunning)       | Emails the customer to update their payment method                |
| Customer **cancels** a subscription                                                      | [Subscription Dunning](/features/recovery/subscription-dunning)       | Emails the customer to re-purchase                                |
| **One-time** checkout fails or is abandoned                                              | [Abandoned Cart Recovery](/features/recovery/abandoned-cart-recovery) | Emails the customer to complete the purchase                      |

## How They Work Together

For subscriptions, **Payment Retries** and **Dunning** are complementary: retries silently recover transient soft declines, while dunning brings back customers whose payment method genuinely needs updating. Enabling both gives you the widest recovery coverage. To understand the underlying failure codes and when a retry is worthwhile, see [Handle Payment Failures](/developer-resources/handle-payment-failures).

## Analytics

Track recovery performance from the **Recovery** tab in the **Analytics** section of your dashboard — including retry, dunning, and abandoned cart metrics. See [Analytics & Reporting](/features/analytics-and-reporting) for the full breakdown.

## Related

<CardGroup>
  <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
    Read failure codes and decide when to retry.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Understand the subscription states involved in recovery flows.
  </Card>

  <Card title="Recovery Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/recovery">
    React to dunning and abandoned checkout events.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    Where customers update their payment method to recover.
  </Card>
</CardGroup>


# Subscription Payment Retries
Source: https://docs.dodopayments.com/features/recovery/payment-retries

Automatically retry failed subscription renewal payments on a smart back-off schedule to recover revenue with no integration work.

<Info>
  Payment Retries automatically re-attempt failed subscription **renewal** payments on a progressive back-off schedule. When a retry succeeds, the subscription is reactivated automatically — no customer action or integration work required.
</Info>

## What Are Payment Retries?

When a subscription renewal payment fails, the subscription is placed **on hold**. With Payment Retries enabled, Dodo Payments automatically re-charges the customer's existing payment method on a smart schedule until the payment succeeds or the recovery window closes.

This recovers revenue lost to temporary failures — expired card holds, insufficient funds that get topped up, transient network errors — without emailing the customer or asking them to update anything.

<Note>
  Payment Retries only apply to subscription **renewal** payments. First payments (mandate setup), one-time payments, plan-change charges, and on-demand charges are not retried by this feature.
</Note>

## How Payment Retries Work

<Steps>
  <Step title="Renewal fails">
    A subscription renewal payment fails and the subscription moves to the `on_hold` state.
  </Step>

  <Step title="Retryability check">
    The failure's error code is checked. **Soft declines** (insufficient funds, generic decline, processing or network errors, etc.) are retryable. **Hard declines** end the retry chain immediately, since retrying won't change the outcome.
  </Step>

  <Step title="Scheduled retry">
    If the decline is retryable and the recovery window allows it, the next attempt is scheduled. Retries fire off-session against the customer's existing payment method on a progressive back-off schedule.
  </Step>

  <Step title="Recovery">
    On the first successful retry, the subscription returns to `active` and the next billing date is advanced as normal. If the window closes before any retry succeeds, retries stop and the subscription remains on hold.
  </Step>
</Steps>

## Configuring Payment Retries

Enable and configure Payment Retries from **Settings → Recovery** in your dashboard.

<Frame>
  <img alt="Recovery Settings page with the Enable Payment Retries toggle on and a Recovery window (days) field set to 13" />
</Frame>

| Setting                    | Description                                                                                | Default      |
| -------------------------- | ------------------------------------------------------------------------------------------ | ------------ |
| **Enable Payment Retries** | Automatically retry failed subscription renewal payments to recover revenue.               | Off (opt-in) |
| **Recovery window (days)** | How long to keep retrying a failed payment before giving up. Must be between **1 and 30**. | 13           |

The **recovery window** is anchored to the time the failed renewal invoice was created. Retries are only scheduled while the cumulative back-off delay still fits inside the window.

## Retry Schedule

Retries back off progressively. Up to **8 attempts** are made, as long as each one fits within your recovery window:

| Attempt | Delay after previous attempt | Approx. time since failure |
| ------- | ---------------------------- | -------------------------- |
| 1       | 12 hours                     | 12 hours                   |
| 2       | 24 hours                     | 36 hours                   |
| 3       | 48 hours                     | \~3.5 days                 |
| 4       | 72 hours                     | \~6.5 days                 |
| 5       | 96 hours                     | \~10.5 days                |
| 6       | 120 hours                    | \~15.5 days                |
| 7       | 7 days                       | \~22.5 days                |
| 8       | 7 days                       | \~29.5 days                |

<Tip>
  A recovery window of **13 days** (the default) covers attempts 1 through 5 (attempt 5 fires \~10.5 days after the failure). Increase the window toward the 30-day maximum if you want the later, more widely-spaced attempts (6 through 8) to run.
</Tip>

## Subscription Status Transitions

| Event                     | Subscription status                                                 |
| ------------------------- | ------------------------------------------------------------------- |
| Renewal payment fails     | `active` → `on_hold`                                                |
| Retry attempt fails       | stays `on_hold` (next retry scheduled if window allows)             |
| Retry attempt succeeds    | `on_hold` → `active`, next billing date advanced                    |
| Recovery window exhausted | stays `on_hold`                                                     |
| Subscription cancelled    | scheduled retries stop immediately (terminal — no further attempts) |

<Note>
  If a subscription is cancelled while retries are still scheduled, the retry chain ends immediately and no further attempts are made. Other non-active statuses (`on_hold`, `expired`, `pending`, `failed`) keep retrying, because their open renewal invoices represent debt for periods the customer has already consumed.
</Note>

These transitions emit the standard subscription webhook events, so you can drive entitlement logic from them with no special retry handling:

| Event                  | Fires when                                             |
| ---------------------- | ------------------------------------------------------ |
| `subscription.on_hold` | A renewal fails and the subscription is placed on hold |
| `subscription.active`  | A retry succeeds and the subscription is reactivated   |

<Card title="Subscription Webhook Payloads" icon="webhook" href="/developer-resources/webhooks/intents/subscription">
  View the full webhook payload schemas for subscription lifecycle events.
</Card>

## Retryable vs. Non-Retryable Failures

| Failure type     | Examples                                                                                                              | Retried?                    |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **Soft decline** | Insufficient funds, generic decline, card velocity exceeded, processing error, network error/timeout, try again later | Yes                         |
| **Hard decline** | Stolen/lost card, invalid card, do-not-honor, account closed, and other terminal declines                             | No — chain ends immediately |

<Info>
  Retrying a hard decline won't change the outcome, so the retry chain terminates as soon as a hard decline is observed. Pair Payment Retries with [Subscription Dunning](/features/recovery/subscription-dunning) to prompt the customer to update their payment method in those cases.
</Info>

## Payment Retries vs. Dunning

Payment Retries and [Subscription Dunning](/features/recovery/subscription-dunning) are complementary recovery tools:

|                     | Payment Retries                                   | Subscription Dunning                               |
| ------------------- | ------------------------------------------------- | -------------------------------------------------- |
| **Mechanism**       | Silently re-charges the existing payment method   | Emails the customer to update their payment method |
| **Customer action** | None required                                     | Customer updates payment method in the portal      |
| **Best for**        | Temporary/soft declines that resolve on their own | Expired or invalid cards that need replacing       |

Enabling both gives you the widest recovery coverage: automatic retries catch transient failures, while dunning brings back customers whose payment method genuinely needs updating.

## Related

<CardGroup>
  <Card title="Subscription Dunning" icon="repeat" href="/features/recovery/subscription-dunning">
    Email sequences that prompt customers to update their payment method.
  </Card>

  <Card title="Abandoned Cart Recovery" icon="cart-shopping" href="/features/recovery/abandoned-cart-recovery">
    Recover incomplete or failed one-time checkouts with targeted emails.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Understand the subscription states involved in recovery flows.
  </Card>

  <Card title="Subscription Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/subscription">
    React to `subscription.on_hold` and `subscription.active` events.
  </Card>
</CardGroup>


# Subscription Dunning
Source: https://docs.dodopayments.com/features/recovery/subscription-dunning

Automatically send email sequences to recover lapsed or cancelled subscriptions by prompting customers to update their payment method.

<Info>
  Subscription Dunning automatically sends email sequences to customers whose subscriptions have lapsed due to payment failure or customer cancellation, prompting them to update their payment method and reactivate.
</Info>

## What Is Subscription Dunning?

Dunning automatically detects when a subscription enters a recoverable state and sends a sequence of emails prompting the customer to take action:

* **On Hold subscriptions**: Renewal payment failed (insufficient funds, expired card, etc.)
* **Cancelled subscriptions**: Customer cancelled from the customer portal

## How Dunning Works

<Steps>
  <Step title="Trigger">
    Dunning is triggered when a subscription enters one of two states:

    * **On Hold**: A renewal payment failed (insufficient funds, expired card, etc.)
    * **Cancelled**: The customer cancelled their subscription from the customer portal
  </Step>

  <Step title="Email Sequence">
    Based on the trigger state, the system sends up to 4 dunning emails at
    configured intervals. Each email includes a link to the customer portal where
    the customer can update their payment method or re-purchase the subscription.
  </Step>

  <Step title="Recovery">
    When the customer updates their payment method through the customer portal, a charge is automatically created for remaining dues. If the payment succeeds, the subscription is reactivated and the dunning attempt is marked as recovered.
  </Step>
</Steps>

## Status Lifecycle

| Status       | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `recovering` | Dunning attempt is active; emails are being sent                             |
| `recovered`  | Customer updated payment method and payment succeeded                        |
| `exhausted`  | All emails sent with no recovery, or subscription state changed unexpectedly |

<Info>
  When a dunning attempt is marked as `exhausted`, the subscription state is not modified. The subscription remains in its current state (on hold or cancelled).
</Info>

## Configuring Dunning

Enable and configure Dunning from **Settings** in your dashboard.

<Frame>
  <img alt="Dunning settings page with enable toggle, four on-hold emails at 1, 3, 5, and 7 day intervals, and four cancelled emails at the same intervals" />
</Frame>

### Email Sequences

Dunning supports two email sequences — **On Hold** and **Cancelled** — each with up to 4 configurable emails.

Each email has the following configurable fields:

| Setting      | Description                                              |
| ------------ | -------------------------------------------------------- |
| **Enabled**  | Toggle individual emails on or off without deleting them |
| **Delay**    | How long after the trigger event to send this email      |
| **Subject**  | Email subject line with variable placeholders            |
| **Body**     | HTML email body with variable placeholders               |
| **Reply-To** | Email address for customer replies                       |

**Default email timing:**

| Sequence  | Email # | Default Delay |
| --------- | ------- | ------------- |
| On Hold   | 1       | 1 day         |
| On Hold   | 2       | 3 days        |
| On Hold   | 3       | 5 days        |
| On Hold   | 4       | 7 days        |
| Cancelled | 1       | 1 day         |
| Cancelled | 2       | 3 days        |
| Cancelled | 3       | 5 days        |
| Cancelled | 4       | 7 days        |

### Example Dunning Emails

Dunning sends different emails depending on the subscription state. Below are examples of each type as seen by the customer.

<Tabs>
  <Tab title="On Hold">
    <Frame>
      <img alt="Dunning email for an on-hold subscription showing store name, message about failed payment, subscription details with plan and amount, and an Update Payment Method button" />
    </Frame>
  </Tab>

  <Tab title="Cancelled">
    <Frame>
      <img alt="Dunning email for a cancelled subscription showing store name, message about cancellation, subscription details with plan and amount, and a Re-purchase Subscription button" />
    </Frame>
  </Tab>
</Tabs>

## Customer Recovery Experience

When a customer clicks the link in a dunning email, they are taken to the customer portal where they can see their subscription status and update their payment method.

<Frame>
  <img alt="Customer portal showing an on-hold subscription for Pro Plan at $95.00/year with an Update payment method button and a warning banner about the failed payment" />
</Frame>

After the customer updates their payment method, a charge is automatically created for any outstanding dues. If the payment succeeds, the subscription is reactivated immediately.

For a cancelled subscription, customer is taken to a checkout page that already has the subscription added as the product.

## Analytics

Track the performance of Dunning from the **Recovery** tab in the **Analytics** section of your dashboard.

<Frame>
  <img alt="Recovery analytics dashboard showing dunning entry counts, success rates, recovered revenue, and per-email performance breakdown" />
</Frame>

| Metric                  | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| **Dunning Entries**     | Total number of dunning attempts created                    |
| **Success Rate**        | Percentage of dunning attempts that led to recovery         |
| **Recovered Revenue**   | Total revenue recovered through dunning                     |
| **Recovery by Attempt** | Breakdown of which email in the sequence drove the recovery |

## Webhook Events

| Event               | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `dunning.started`   | A dunning attempt has been started for a subscription |
| `dunning.recovered` | A subscription has been recovered through dunning     |

<Card title="Recovery Webhook Payloads" icon="code" href="/developer-resources/webhooks/intents/recovery">
  View the full webhook payload schemas for dunning events.
</Card>

## Edge Cases

| Scenario                                                   | Behavior                                                                   |
| ---------------------------------------------------------- | -------------------------------------------------------------------------- |
| Customer updates payment method before any email           | Recovery is detected; dunning attempt is marked as recovered               |
| Customer purchases another subscription from same business | Dunning attempt is marked as exhausted                                     |
| All dunning emails exhausted                               | Dunning attempt is marked as exhausted; subscription state is not modified |

## Best Practices

* **Start with defaults**: The default email timing is designed with reasonable spacing (1, 3, 5 and, 7 days) to avoid overwhelming customers while maintaining urgency.
* **Monitor success rates**: Track which email in the sequence drives the most recoveries. If later emails have near-zero conversion, consider disabling them.
* **Coordinate with support**: Ensure your support team knows that dunning emails are being sent, so they can assist customers who reach out.
* **Review subscription states**: Pair dunning with `subscription.on_hold` and `subscription.cancelled` webhooks for comprehensive lifecycle tracking.

<Info>
  Dunning works alongside the existing subscription on-hold and reactivation flows in the customer portal. Once enabled, it runs automatically with no additional integration required.
</Info>

## Related

<CardGroup>
  <Card title="Recovery Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/recovery">
    React to `dunning.started` and `dunning.recovered` events.
  </Card>

  <Card title="Abandoned Cart Recovery" icon="cart-shopping" href="/features/recovery/abandoned-cart-recovery">
    Recover incomplete or failed one-time checkouts with targeted emails.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    Customers update payment methods through the customer portal.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Understand subscription states that trigger dunning workflows.
  </Card>
</CardGroup>


# Seat-Based Billing
Source: https://docs.dodopayments.com/features/seat-based-billing

Implement per-user pricing for team software, SaaS products, and enterprise licenses with flexible seat management and proration.

<Info>
  Seat-based billing lets you charge customers based on the number of users, team members, or licenses they need. It's the standard pricing model for team collaboration tools, enterprise software, and B2B SaaS products.
</Info>

<CardGroup>
  <Card title="Implementation Tutorial" icon="code" href="/developer-resources/seat-based-pricing">
    Step-by-step guide with code examples.
  </Card>

  <Card title="Add-ons Documentation" icon="puzzle" href="/features/addons">
    Learn about the add-on system that powers seat-based billing.
  </Card>

  <Card title="Subscription Management" icon="repeat" href="/features/subscription">
    Manage seat-based subscriptions and plan changes.
  </Card>

  <Card title="Webhooks" icon="bell" href="/developer-resources/webhooks/intents/subscription">
    Track seat changes with subscription webhooks.
  </Card>
</CardGroup>

***

## What is Seat-Based Billing?

Seat-based billing (also called per-user or per-seat pricing) charges customers based on the number of users who access your product. Instead of a flat fee, the price scales with team size.

### Common Use Cases

| Industry           | Example              | Pricing Model         |
| ------------------ | -------------------- | --------------------- |
| Team Collaboration | Slack, Notion, Asana | Per active user/month |
| Developer Tools    | GitHub, GitLab, Jira | Per seat/month        |
| CRM Software       | Salesforce, HubSpot  | Per user license      |
| Design Tools       | Figma, Canva         | Per editor seat       |
| Security Software  | 1Password, Okta      | Per user/month        |
| Video Conferencing | Zoom, Teams          | Per host license      |

### Benefits of Seat-Based Pricing

**For Your Business:**

* Revenue scales naturally as customers grow
* Predictable pricing customers can budget for
* Clear upgrade path from individual to team to enterprise
* Higher lifetime value as teams expand

**For Your Customers:**

* Pay only for what they use
* Easy to understand and forecast costs
* Flexibility to add/remove users as needed
* Fair pricing that matches team size

***

## How Seat-Based Billing Works in Dodo Payments

Dodo Payments implements seat-based billing using the **Add-ons** system. Here's how it works:

### Architecture Overview

A Team Pro subscription costs $99/month and includes 5 seats. If you have more than 5 users, you pay an additional $15/month for each extra seat.

For example, if your team needs 15 seats:

* Base Plan: \$99/month (includes 5 seats)
* Add-ons: 10 extra seats × $15/month = $150/month
* Total monthly cost: $99 + $150 = \$249 for 15 seats

### Key Components

| Component    | Purpose                               | Example                                     |
| ------------ | ------------------------------------- | ------------------------------------------- |
| Base Product | Core subscription with included seats | "Team Plan - \$99/month (5 seats included)" |
| Seat Add-on  | Per-seat charge for additional users  | "Extra Seat - \$15/month each"              |
| Quantity     | Number of additional seats purchased  | 10 extra seats                              |

***

## Pricing Strategies

Choose the seat-based pricing strategy that fits your business:

### Strategy 1: Base + Per-Seat Add-on

Include a set number of seats in the base plan, charge for additional seats.

**Example:**

```
Starter Plan: $49/month
├── Includes: 3 seats
├── Extra seats: $10/month each
└── 8 total seats = $49 + (5 × $10) = $99/month
```

**Best for:** Products where small teams can function with the base offering.

### Strategy 2: Pure Per-Seat Pricing

Charge a flat rate per seat with no base fee.

**Example:**

```
Per User: $12/month
├── 5 users = $60/month
├── 20 users = $240/month
└── 100 users = $1,200/month
```

**Implementation:** Set base plan price to \$0, use only the seat add-on.

**Best for:** Simple, transparent pricing; usage-based models.

### Strategy 3: Tiered Seat Pricing

Different base plans with different per-seat rates.

**Example:**

```
Starter: $0/month base + $15/seat
├── Lower features, higher per-seat cost

Professional: $99/month base + $10/seat
├── More features, lower per-seat cost

Enterprise: $499/month base + $7/seat
└── All features, volume discount on seats
```

**Implementation:** Create separate products for each tier with different add-on prices.

**Best for:** Encouraging upgrades to higher tiers; enterprise sales.

### Strategy 4: Seat Bundles

Sell seats in packs rather than individually.

**Example:**

```
5-Seat Pack: $50/month ($10/seat)
10-Seat Pack: $80/month ($8/seat)
25-Seat Pack: $175/month ($7/seat)
```

**Implementation:** Create multiple add-ons for different pack sizes.

**Best for:** Simplifying purchasing decisions; encouraging larger commitments.

***

## Setting Up Seat-Based Billing

### Step 1: Plan Your Pricing

Before implementation, define your pricing structure:

<Steps>
  <Step title="Define Base Plan">
    Decide what's included in the base subscription:

    * Base price (can be \$0 for pure per-seat)
    * Number of included seats
    * Features available at this tier
  </Step>

  <Step title="Set Seat Pricing">
    Determine the per-seat add-on cost:

    * Price per additional seat
    * Any volume discounts (via multiple add-ons)
    * Maximum seats allowed (if applicable)
  </Step>

  <Step title="Consider Billing Frequency">
    Align seat pricing with your billing cycle:

    * Monthly subscriptions → monthly seat charges
    * Annual subscriptions → annual seat charges (often discounted)
  </Step>
</Steps>

### Step 2: Create the Seat Add-on

In your Dodo Payments dashboard:

1. Navigate to **Products** → **Add-Ons**
2. Click **Create Add-On**
3. Configure the add-on:

| Field        | Value                                       | Notes                           |
| ------------ | ------------------------------------------- | ------------------------------- |
| Name         | "Additional Seat" or "Team Member"          | Clear, user-friendly name       |
| Description  | "Add another team member to your workspace" | Explain what customers get      |
| Price        | Your per-seat price                         | e.g., \$10.00                   |
| Currency     | Match your base product                     | Must be the same currency       |
| Tax Category | Same as base product                        | Ensures consistent tax handling |

<Tip>
  Create descriptive add-on names that make sense on invoices. "Additional Team Seat" is clearer than "Seat Add-on" for customers reviewing their bills.
</Tip>

### Step 3: Create the Base Subscription

Create your subscription product:

1. Navigate to **Products** → **Create Product**
2. Select **Subscription**
3. Configure pricing and details
4. In the **Add-Ons** section, attach your seat add-on

### Step 4: Attach Add-on to Product

Link the seat add-on to your subscription:

1. Edit your subscription product
2. Scroll to **Add-Ons** section
3. Click **Add Add-Ons**
4. Select your seat add-on
5. Save changes

<Check>
  Your subscription product now supports seat-based pricing. Customers can purchase any quantity of additional seats during checkout.
</Check>

***

## Managing Seats

### Adding Seats to New Subscriptions

When creating a checkout session, specify the seat quantity:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{
    product_id: 'pdt_team_plan',
    quantity: 1,
    addons: [{
      addon_id: 'addon_seat',
      quantity: 10  // 10 additional seats
    }]
  }],
  customer: { email: 'admin@company.com' },
  return_url: 'https://yourapp.com/success'
});
```

### Changing Seat Count on Existing Subscriptions

Use the Change Plan API to adjust seats:

```typescript theme={null}
// Add 5 more seats to existing subscription
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [{
    addon_id: 'addon_seat',
    quantity: 15  // New total: 15 additional seats
  }]
});
```

### Removing Seats

To reduce seat count, specify the lower quantity:

```typescript theme={null}
// Reduce from 15 to 8 additional seats
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{
    addon_id: 'addon_seat',
    quantity: 8  // Reduced to 8 additional seats
  }]
});
```

### Removing All Additional Seats

Pass an empty addons array to remove all add-ons:

```typescript theme={null}
// Remove all additional seats, keep only base plan seats
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: []  // Removes all add-ons
});
```

***

## Proration for Seat Changes

When customers add or remove seats mid-cycle, proration determines how they're billed.

```mermaid theme={null}
sequenceDiagram
    participant A as Admin
    participant App as Your App
    participant D as Dodo Payments
    A->>App: Add/remove seats
    App->>D: Preview change
    D-->>App: Prorated charge preview
    App->>A: Show cost details
    A->>App: Confirm
    App->>D: changePlan (new seat count)
    D->>D: Prorate & charge/credit
    D-->>App: Updated subscription
    D->>App: Webhook: plan_changed
    App->>A: Seats updated
```

### Proration Modes

| Mode                     | Adding Seats                       | Removing Seats                    | Billing cycle   |
| ------------------------ | ---------------------------------- | --------------------------------- | --------------- |
| `prorated_immediately`   | Charge for remaining days in cycle | Credit for unused days            | Resets to today |
| `difference_immediately` | Charge full seat price             | Credit applied to future renewals | Resets to today |
| `full_immediately`       | Charge full seat price             | No credit                         | Resets to today |
| `do_not_bill`            | Seat added, no charge now          | Seat removed, no credit           | Stays the same  |

<Warning>
  `prorated_immediately`, `difference_immediately`, and `full_immediately` all **reset the billing cycle to the change date** — the next renewal is re-anchored to the day the seat change is applied. Only **`do_not_bill`** keeps the original renewal date (the new seat count is billed in full at the next renewal, with no charge at the time of change).
</Warning>

### Proration Examples

**Scenario: 15-day billing cycle remaining, adding 5 seats at \$10/seat**

<Tabs>
  <Tab title="prorated_immediately">
    ```
    Prorated charge = ($10 × 5 seats) × (15 days / 30 days)
                    = $50 × 0.5
                    = $25 immediate charge
    Billing cycle resets to today
    ```

    Customer pays the prorated amount now, and the billing cycle re-anchors to the change date — the next renewal (\$50/month for the added seats) is charged one cycle from today, not from the original renewal date.
  </Tab>

  <Tab title="difference_immediately">
    ```
    Immediate charge = $10 × 5 seats = $50
    Billing cycle resets to today
    ```

    Customer pays the full seat price now, regardless of cycle position, and the billing cycle re-anchors to the change date.
  </Tab>

  <Tab title="full_immediately">
    ```
    Immediate charge = Full subscription + add-ons
    Billing cycle resets to today
    ```

    Customer pays full amount, new billing cycle starts.
  </Tab>

  <Tab title="do_not_bill">
    ```
    Immediate charge = $0
    Billing cycle unchanged
    ```

    Seats are added immediately with no charge at the time of change. The original renewal date is preserved, and the new seat count is billed in full at the next renewal. Use this when you need to keep the existing billing cycle.
  </Tab>
</Tabs>

**Scenario: Removing 3 seats mid-cycle with prorated\_immediately**

```
Current: Team Plan ($99/month) + 10 extra seats × $10/seat = $199/month
Change: Remove 3 seats (10 → 7 extra seats) on day 20 of 30-day cycle
Remaining: 10 days

Credit for removed seats:
  = ($10 × 3 seats) × (10 days / 30 days)
  = $30 × 0.333
  = $10.00 credit

→ $10.00 credit added to subscription
→ Next renewal: $99 + (7 × $10) = $169.00/month
→ Credit auto-applies: $169.00 − $10.00 = $159.00 on next invoice
```

<Tip>
  **Choosing a proration mode for seat changes**: Use `prorated_immediately` for fair day-based billing when teams frequently adjust seats. Use `difference_immediately` for simpler math that charges or credits the full seat price. If you need to keep the existing renewal date unchanged, use `do_not_bill` — the only mode that does not reset the billing cycle (the new seat count is billed at the next renewal). See the [Proration Guide](/developer-resources/subscription-upgrade-downgrade#proration-modes) for detailed comparisons.
</Tip>

### Preview Before Changing

Always preview proration before making changes:

```typescript theme={null}
const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [{ addon_id: 'addon_seat', quantity: 20 }]
});

console.log('Immediate charge:', preview.immediate_charge.summary);
// Show customer: "Adding 5 seats will cost $25 today"
```

***

## Tracking Seats with Webhooks

Monitor seat changes by listening to subscription webhooks:

### Relevant Events

| Event                       | When Triggered             | Use Case                      |
| --------------------------- | -------------------------- | ----------------------------- |
| `subscription.active`       | New subscription activated | Provision initial seats       |
| `subscription.plan_changed` | Seats added/removed        | Update seat count in your app |
| `subscription.renewed`      | Subscription renewed       | Confirm seat count unchanged  |
| `subscription.cancelled`    | Subscription cancelled     | Deprovision all seats         |

### Webhook Handler Example

```typescript theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'subscription.active':
      // New subscription - provision seats
      const seats = calculateTotalSeats(event.data);
      await provisionSeats(event.data.customer_id, seats);
      break;

    case 'subscription.plan_changed':
      // Seats changed - update access
      const newSeats = calculateTotalSeats(event.data);
      await updateSeatCount(event.data.subscription_id, newSeats);
      break;

    case 'subscription.cancelled':
      // Subscription cancelled - deprovision
      await deprovisionAllSeats(event.data.subscription_id);
      break;
  }

  res.json({ received: true });
});

function calculateTotalSeats(subscriptionData) {
  const baseSeats = 5;  // Included in plan
  const addonSeats = subscriptionData.addons?.reduce(
    (total, addon) => total + addon.quantity, 0
  ) || 0;
  return baseSeats + addonSeats;
}
```

***

## Enforcing Seat Limits

Your application must enforce seat limits. Dodo Payments tracks billing, but you control access.

### Enforcement Strategies

<Tabs>
  <Tab title="Hard Limit">
    Strictly prevent adding users beyond the seat count.

    ```typescript theme={null}
    async function inviteUser(teamId: string, email: string) {
      const team = await getTeam(teamId);
      const subscription = await getSubscription(team.subscriptionId);
      const totalSeats = calculateTotalSeats(subscription);
      const usedSeats = await countTeamMembers(teamId);

      if (usedSeats >= totalSeats) {
        throw new Error('No seats available. Please upgrade your plan.');
      }

      await sendInvitation(teamId, email);
    }
    ```
  </Tab>

  <Tab title="Soft Limit with Warning">
    Allow exceeding with a warning and grace period.

    ```typescript theme={null}
    async function inviteUser(teamId: string, email: string) {
      const team = await getTeam(teamId);
      const { totalSeats, usedSeats } = await getSeatInfo(team);

      if (usedSeats >= totalSeats) {
        // Allow but flag for billing
        await flagOverage(teamId, usedSeats - totalSeats + 1);
        await notifyAdmin(team.adminEmail, 'You have exceeded your seat limit');
      }

      await sendInvitation(teamId, email);
    }
    ```
  </Tab>

  <Tab title="Auto-Upgrade">
    Automatically add seats when limit is reached.

    ```typescript theme={null}
    async function inviteUser(teamId: string, email: string) {
      const team = await getTeam(teamId);
      const { totalSeats, usedSeats, subscriptionId } = await getSeatInfo(team);

      if (usedSeats >= totalSeats) {
        // Automatically add a seat
        await client.subscriptions.changePlan(subscriptionId, {
          product_id: team.productId,
          quantity: 1,
          proration_billing_mode: 'prorated_immediately',
          addons: [{ addon_id: 'addon_seat', quantity: totalSeats - baseSeats + 1 }]
        });

        await notifyAdmin(team.adminEmail, 'A new seat was added to your plan');
      }

      await sendInvitation(teamId, email);
    }
    ```
  </Tab>
</Tabs>

***

## Advanced Patterns

### Different Seat Types

Offer different seat types with different pricing:

```
Full Seats: $20/month - Full access to all features
View-Only Seats: $5/month - Read-only access
Guest Seats: $0/month - Limited external collaborator access
```

**Implementation:** Create separate add-ons for each seat type.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{
    product_id: 'pdt_team_plan',
    quantity: 1,
    addons: [
      { addon_id: 'addon_full_seat', quantity: 10 },
      { addon_id: 'addon_viewer_seat', quantity: 25 },
      { addon_id: 'addon_guest_seat', quantity: 50 }
    ]
  }]
});
```

### Annual Seat Discounts

Offer discounted annual seat pricing:

```
Monthly: $15/seat/month
Annual: $12/seat/month (20% savings)
```

**Implementation:** Create separate products for monthly and annual plans with different add-on prices.

### Minimum Seat Requirements

Require a minimum number of seats for certain plans:

```typescript theme={null}
async function validateSeatCount(planId: string, seatCount: number) {
  const minimums = {
    'pdt_starter': 1,
    'pdt_team': 5,
    'pdt_enterprise': 25
  };

  if (seatCount < minimums[planId]) {
    throw new Error(`${planId} requires at least ${minimums[planId]} seats`);
  }
}
```

***

## Best Practices

### Pricing Best Practices

* **Clear Communication**: Show per-seat pricing prominently on your pricing page
* **Included Seats**: Consider including a few seats in the base price to reduce friction
* **Volume Discounts**: Offer lower per-seat rates for larger teams to win enterprise deals
* **Annual Incentives**: Discount annual plans to improve cash flow and retention

### Technical Best Practices

* **Cache Seat Counts**: Cache subscription seat counts locally to avoid API calls on every request
* **Sync Regularly**: Periodically sync your local seat count with Dodo Payments via API
* **Handle Failures**: If a seat change fails, show clear error messages and retry options
* **Audit Trail**: Log all seat changes for billing disputes and compliance

### User Experience Best Practices

* **Real-Time Feedback**: Show immediate cost impact when adjusting seats
* **Confirmation Steps**: Require confirmation before billing changes
* **Proration Transparency**: Clearly explain prorated charges before applying
* **Easy Downgrades**: Don't make it difficult to reduce seats (it builds trust)

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Seat count mismatch between app and billing">
    **Symptom**: Your app shows a different seat count than the subscription.

    **Causes**:

    * Webhook not received or processed
    * Race condition during seat change
    * Cached data not updated

    **Solutions**:

    1. Implement webhook handlers for `subscription.plan_changed`
    2. Add a "Sync with billing" button that fetches current subscription
    3. Set cache TTL to ensure regular refresh
  </Accordion>

  <Accordion title="Proration charges unexpected">
    **Symptom**: Customer confused by mid-cycle charge amount.

    **Causes**:

    * Proration mode not communicated clearly
    * Customer didn't see preview before confirming

    **Solutions**:

    1. Always use `previewChangePlan` before making changes
    2. Show clear breakdown: "Adding X seats = \$Y today (prorated for Z days)"
    3. Document your proration policy in help center
  </Accordion>

  <Accordion title="Add-on not appearing in checkout">
    **Symptom**: Seat add-on not available during checkout.

    **Causes**:

    * Add-on not attached to product
    * Add-on archived or deleted
    * Currency mismatch between product and add-on

    **Solutions**:

    1. Verify add-on is attached in product settings
    2. Check add-on status in Add-Ons dashboard
    3. Ensure currencies match exactly
  </Accordion>

  <Accordion title="Cannot reduce seats below current usage">
    **Symptom**: Customer wants to reduce seats but has users assigned.

    **Solutions**:

    1. Show which users must be removed before reducing seats
    2. Implement a workflow: Remove users → Reduce seats
    3. Consider a grace period before enforcing seat reduction
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Seat-Based Pricing Tutorial" icon="code" href="/developer-resources/seat-based-pricing">
    Complete implementation guide with code.
  </Card>

  <Card title="Add-ons" icon="puzzle" href="/features/addons">
    Understand the add-on system in depth.
  </Card>

  <Card title="Plan Changes & Proration" icon="arrows-rotate" href="/developer-resources/subscription-upgrade-downgrade">
    Handle subscription modifications.
  </Card>

  <Card title="Subscription Webhooks" icon="bell" href="/developer-resources/webhooks/intents/subscription">
    Track subscription events.
  </Card>
</CardGroup>


# Storefront
Source: https://docs.dodopayments.com/features/storefront

The Storefront Feature allows you to create a simple, branded, and mobile-friendly online store where you can showcase both One-Time Payment products and Subscription products. This feature eliminates the complexity of building an entire website, enabling you to quickly offer your products or services online without additional web development efforts.

<Frame>
  <img alt="Storefront Cover Image" />
</Frame>

## Key Highlights of the Feature

1. **Branded Storefront**
   * Customize your store with a Store Name, Logo, and Cover Image.
   * Easily share your store URL (e.g., `store.dodopayments.com/your-store`).
2. **Product Segregation**
   * Automatically organizes your products into One-Time Payment and Subscription sections.
3. **Simple Checkout Flow**
   * Customers can select a product & quantity and click **“Buy Now”** to be redirected to Dodopayments checkout.
4. **Publish/Unpublish**
   * Control which products appear on your store: quickly publish or unpublish within the Merchant Dashboard.
5. **No Extra Setup**
   * You don’t need a separate CMS; all product management happens in your Merchant Dashboard, where you already manage pricing, descriptions, and subscription details.
6. **Mobile-Friendly**
   * The storefront layout is responsive, ensuring a seamless shopping experience on phones, tablets, and desktops.

## Store Front Setup

Below is the step-by-step process for merchants to set up and manage their storefront:

<img />

### Accessing Your Storefront Settings

1. Open Business Section → Select Store Front

### Store Branding

1. **Store Name**: Enter the public-facing name of your store. This appears prominently at the top of your storefront.
2. **Logo**: Upload an image (e.g., PNG or JPG) for your brand logo.
3. **Cover Image**: Select or upload a banner/cover image that appear on the storefront homepage.
4. **Store URL**:
   * Typically auto-generated based on your business name (e.g., `business.dodopayments.com/my-store`).
   * You can edit this URL if the system supports custom slugs.
5. **Products:** You can select the Products you want to display on your storefront

### Saving & Viewing Your Store

<img />

1. **Click Publish**: Click Publish to confirm your storefront setup and product publishing decisions.
2. **Preview Store**: You can preview your storefront at the generated URL.
3. **Share URL**: Once satisfied, share the link with your customers via email, social media, or your website.

### Test Mode

<img />

Test Mode and Live Mode have separate storefronts. You can see the test mode indicator on the top of your website and store front generated through test mode as well.

Test Mode is for you try out the user flow and purchase experience on the store. Please share the live mode Store link with your users to facilitate real purchases

Once you are happy with how your store looks in test mode, you can copy the design and storefront branding straight into live mode instead of rebuilding it. See [Copy Design From Test to Live Mode](/features/design#copy-design-from-test-to-live-mode).

## Customer Experience

<img />

### Landing on the Storefront

* **Visual Branding**: Customers see your store name, logo, and cover image immediately.
* **Organized Products**: Two categories are displayed: One-Time Payment and Subscription.

### Browsing Products

* **Product Cards**: Each product shows a name, description, and price. Description can be viewed by clicking the i icon on the bottom right of the card.
* **Quantity Selection**: Customers can pick how many items they want to buy.
* **Subscription Frequency & Trial**: Subscription products explicitly state billing frequency (e.g., monthly) and if a trial is available (e.g., 7-day free trial).

<img />

### Buying Process

1. **Select “Buy Now”**: Once ready, the customer clicks “Purchase” for the desired product, selects quantity and clicks “Buy Now”
2. **Redirect to Dodo Payments checkout**:
   * The customer will be taken to the Dodo Payments checkout
   * The customer completes the secure checkout flow on Dodo Payments.
3. **Confirmation**:
   * After successful payment, Dodo Payments shows a confirmation.
   * Optionally, the customer may be redirected back to a “Thank You” page on your storefront based on the redirect URL entered.

<Card title="Design & Theme Customization" icon="palette" href="/features/design">
  Customize your storefront appearance with pre-built themes, typography, colors, and live preview from the Design page.
</Card>


# Subscriptions
Source: https://docs.dodopayments.com/features/subscription

Offer recurring billing for memberships, SaaS, or services with flexible cycles, trials, proration, add-ons, and on‑demand charges.

<Info>
  Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.
</Info>

<CardGroup>
  <Card title="Upgrade & Downgrade" icon="repeat" href="/developer-resources/subscription-upgrade-downgrade">
    Control plan changes with proration and quantity updates.
  </Card>

  <Card title="On‑Demand Subscriptions" icon="bolt" href="/developer-resources/ondemand-subscriptions">
    Authorize a mandate now and charge later with custom amounts.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    Let customers manage plans, billing, and cancellations.
  </Card>

  <Card title="Subscription Webhooks" icon="code" href="/developer-resources/webhooks/intents/subscription">
    React to lifecycle events like created, renewed, and canceled.
  </Card>
</CardGroup>

## What Are Subscriptions?

Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:

* **SaaS licenses**: Apps, APIs, or platform access
* **Memberships**: Communities, programs, or clubs
* **Digital content**: Courses, media, or premium content
* **Support plans**: SLAs, success packages, or maintenance

## Key Benefits

* **Predictable revenue**: Recurring billing with automated renewals
* **Flexible cycles**: Monthly, annual, custom intervals, and trials
* **Plan agility**: Proration for upgrades and downgrades
* **Add‑ons and seats**: Attach optional, quantifiable upgrades
* **Seamless checkout**: Hosted checkout and customer portal
* **Developer-first**: Clear APIs for creation, changes, and usage tracking

## Creating Subscriptions

Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.

### Subscription product creation

Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.

#### Product details

* **Product Name** (required): The display name shown in checkout, customer portal, and invoices.
* **Product Description** (required): A clear value statement that appears in checkout and invoices.
* **Product Image** (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
* **Brand**: Associate the product with a specific brand for theming and emails.
* **Tax Category** (required): Choose the category (for example, SaaS) to determine tax rules.

<Tip>
  Pick the most accurate tax category to ensure correct tax collection per region.
</Tip>

#### Pricing

* **Pricing Type**: Choose <b>Subscription</b> (this guide). Alternatives are Single Payment and Usage Based Billing.
* **Price** (required): Base recurring price with currency. The price must be at least **\$1** (or the equivalent in your chosen currency). Amounts below this minimum are not supported and the subscription will not work.
* **Discount Applicable (%)**: Optional percentage discount applied to the base price; reflected in checkout and invoices.
* **Repeat payment every** (required): Interval for renewals, e.g., every 1 Month. Select the cadence (months or years) and quantity.
* **Subscription Period** (required): Total term for which the subscription remains active (e.g., 10 Years). After this period ends, renewals stop unless extended.
* **Trial Period Days** (required): Set trial length in days. Use 0 to disable trials. The first charge occurs automatically when the trial ends.
* **Trial Amount**: Optional upfront charge for a paid trial. Leave it unset for a free trial. See [Paid Trials](#paid-trials).
* **Select add‑on**: Attach up to 10 add‑ons that customers can purchase alongside the base plan.

<Warning>
  Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.
</Warning>

<Info>
  Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.
</Info>

#### Advanced settings

* **Tax Inclusive Pricing**: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
* **Generate license keys**: Issue a unique key to each customer after purchase. See the <a href="/features/license-keys">License Keys</a> guide.
* **Digital Product Delivery**: Deliver files or content automatically after purchase. Learn more in <a href="/features/digital-product-delivery">Digital Product Delivery</a>.
* **Metadata**: Attach custom key–value pairs for internal tagging or client integrations. See <a href="/api-reference/metadata">Metadata</a>.

<Tip>
  Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.
</Tip>

## Subscription Trials

Trials let customers evaluate a subscription before paying the full recurring price. A trial can be **free**, where nothing is charged until the trial ends, or **paid**, where a reduced amount is charged upfront. In both cases the full price begins at the first renewal after the trial ends.

### Configuring Trials

Set **Trial Period Days** in the product pricing section (use `0` to disable). You can override this when creating subscriptions:

```typescript theme={null}
// Via subscription creation
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});
```

<Warning>
  The `trial_period_days` value must be between 0 and 10,000 days.
</Warning>

### Paid Trials

Trials do not have to be free. Set a **Trial Amount** on a subscription product's recurring price to charge a reduced upfront fee for the trial window. The full recurring price then takes over at the first renewal.

<Frame>
  <img alt="Subscription pricing form with a trial duration and an optional trial amount for a paid trial" />
</Frame>

Paid trials are configured on the product's price, not per subscription or per checkout session:

| Field                   | Type    | Description                                                                                                                                                                        |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trial_amount`          | integer | Amount charged today for the trial, in the price currency's minor units (for example, `500` for \$5.00). Requires `trial_period_days > 0`. Omit or set to `null` for a free trial. |
| `trial_apply_discounts` | boolean | Whether checkout discount codes reduce the trial charge. Defaults to `false`, so the trial amount is charged in full even when a discount applies to the recurring price.          |

```typescript theme={null}
const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    discount: 0,
    purchasing_power_parity: false,
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});
```

Paid trials flow through checkout as well. The trial amount is taxed, surfaced in checkout session calculations and payment link pricing, and Adaptive Currency markup is applied per currency. The [preview endpoint](/developer-resources/checkout-session) returns `trial_amount` and `trial_period_days` so you can show the amount due today before the subscription is created.

<Info>
  Free trials are unchanged. Leaving **Trial Amount** unset keeps the existing behavior, where the first charge is `0` and the full price is charged when the trial ends.
</Info>

### Preventing Trial Misuse

**Prevent Trial Misuse** stops customers from repeatedly claiming trials for the same business. When enabled, a customer who has already redeemed a trial is automatically degraded to a **paid, no-trial purchase** instead of receiving a fresh trial.

<Frame>
  <img alt="Prevent Trial Misuse toggle in the Subscriptions settings tab" />
</Frame>

Enable it from the **Subscriptions** tab in **Settings**. Once enabled:

* Customers are matched by **normalized email**, with plus-aliases stripped, so `user+trial@example.com` and `user@example.com` count as the same person.
* Redemptions are recorded at **trial activation**, so a customer who cancels the same day has still consumed their trial.
* Existing customers are backfilled from their historical trials by email, so past trial users are recognized immediately.

<Info>
  The setting is **off by default**. See [Subscription Settings](/features/product-collections#subscription-settings) for the full list of business-level subscription controls.
</Info>

### Detecting Trial Status

<Warning>
  Currently, there is no direct field to detect trial status. The following is a workaround that requires querying payments, which is inefficient. We are working on a more efficient solution.
</Warning>

To determine if a **free trial** subscription is in trial, retrieve the list of payments for the subscription. If there is exactly one payment with amount 0, the subscription is in trial period:

```typescript theme={null}
const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;
```

<Warning>
  This zero-amount check only works for free trials. For a [paid trial](#paid-trials) the first payment equals the trial amount, not `0`. Compare the first payment against the subscription's `trial_amount` instead, or check whether `next_billing_date` is still within the trial window.
</Warning>

### Updating Trial Period

Extend the trial by updating `next_billing_date`:

```typescript theme={null}
await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});
```

<Warning>
  You cannot set `next_billing_date` to a past time. The date must be in the future.
</Warning>

## Subscription Plan Changes

Plan changes let you upgrade or downgrade subscriptions, adjust quantities, or migrate to different products. Depending on the proration mode you select, a change may trigger an immediate charge, create credit, or apply no billing adjustment.

<Tip>
  You can change subscription plans and update the next billing date directly from the Dodo Payments dashboard. This provides a quick way to adjust subscriptions for customer support requests, promotional upgrades, or plan migrations without making API calls.
</Tip>

<Tip>
  **Enable self-service plan changes:** Want customers to upgrade or downgrade their own subscriptions via the Customer Portal? Add your subscription products to a Product Collection and enable "Allow Subscription Updates" in your Subscription Settings.
</Tip>

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant A as Your App
    participant D as Dodo Payments
    C->>A: Request plan change
    A->>D: Preview change (optional)
    D-->>A: Charge breakdown
    A->>C: Show cost
    C->>A: Confirm
    A->>D: changePlan API
    D->>D: Prorate & charge
    D-->>A: Result
    D->>A: Webhook: plan_changed
    A->>C: Access updated
```

<Card title="Product Collections" icon="layer-group" href="/features/product-collections">
  Group related products into collections to enable seamless upgrade/downgrade paths in the Customer Portal.
</Card>

### Proration Modes

Choose how customers are billed when changing plans:

<Info>
  **Quick comparison of the four proration modes:**

  |                   | `prorated_immediately`             | `difference_immediately`        | `full_immediately`          | `do_not_bill`                        |
  | ----------------- | ---------------------------------- | ------------------------------- | --------------------------- | ------------------------------------ |
  | **Upgrade**       | Prorated charge for remaining days | Full price difference charged   | Full new plan price charged | No charge — switch immediately       |
  | **Downgrade**     | Prorated credit for remaining days | Full price difference as credit | No credit, full charge      | No credit — switch immediately       |
  | **Billing cycle** | Resets to today                    | Resets to today                 | Resets to today             | Stays the same                       |
  | **Best for**      | Fair time-based billing            | Simple tier changes             | Billing cycle resets        | Free migrations or courtesy switches |
</Info>

#### `prorated_immediately`

Charges prorated amount based on remaining time in the current billing cycle. Best for fair billing that accounts for unused time.

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});
```

#### `difference_immediately`

Charges the price difference immediately (upgrade) or adds credit for future renewals (downgrade). Best for simple upgrade/downgrade scenarios.

```typescript theme={null}
// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});
```

<Info>
  Credits from downgrades using `difference_immediately` are subscription-scoped and auto-applied to future renewals. They're distinct from <a href="/features/credit-based-billing">Credit-Based Billing</a> entitlements.
</Info>

When a customer downgrades with `difference_immediately`, the unused value becomes a subscription-scoped credit that automatically offsets future renewals:

```mermaid theme={null}
flowchart LR
    A[Downgrade] --> B[Calculate Credit]
    B --> C[Credit Added]
    C --> D[Next Renewal]
    D --> E{Credit Left?}
    E -->|Yes| F[Apply to invoice]
    F --> D
    E -->|No| G[Full price charged]
```

#### `full_immediately`

Charges full new plan amount immediately, ignoring remaining time. Best for resetting billing cycles.

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});
```

#### `do_not_bill`

Switches to the new plan without any billing adjustment. No proration charges, no credits — the customer simply moves to the new plan. Best for courtesy migrations, free plan switches, or scenarios where you want to absorb the cost difference.

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});
```

<AccordionGroup>
  <Accordion title="Example: Prorated upgrade calculation">
    **Scenario**: Customer on Basic ($30/month) upgrades to Pro ($80/month) on day 16 of a 30-day cycle using `prorated_immediately`.

    ```
    Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
    Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
    ────────────────────────────────────────────────────────────────────
    Immediate charge         = $40.00 − $15.00 = $25.00
    ```

    Next renewal on **February 15** (January 16 + 30 days): **\$80.00/month**.

    <Tip>
      For more detailed calculation examples and edge cases, see our full [Upgrade & Downgrade Guide](/developer-resources/subscription-upgrade-downgrade).
    </Tip>
  </Accordion>

  <Accordion title="Example: Downgrade credit calculation">
    **Scenario**: Customer on Pro ($80/month) downgrades to Starter ($20/month) using `difference_immediately`.

    ```
    Credit = Old plan − New plan = $80 − $20 = $60.00
    ```

    The \$60 credit auto-applies to future renewals:

    * Renewal 1: $20 − $20 (credit) = \*\*$0.00** ($40 credit remaining)
    * Renewal 2: $20 − $20 (credit) = \*\*$0.00** ($20 credit remaining)
    * Renewal 3: $20 − $20 (credit) = **\$0.00** (credit exhausted)
    * Renewal 4: **\$20.00** (full price)

    <Info>
      Learn more about how credits are managed in the [Upgrade & Downgrade Guide](/developer-resources/subscription-upgrade-downgrade).
    </Info>
  </Accordion>
</AccordionGroup>

### Changing Plans with Add-ons

Modify add-ons when changing plans. Add-ons are included in proration calculations:

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});
```

<Info>
  By default (`effective_at: 'immediately'`) plan changes trigger immediate charges. Pass `effective_at: 'next_billing_date'` to schedule the change for the next billing date instead — the pending change is returned on the subscription as `scheduled_change`, and you can cancel it with [Cancel Scheduled Plan Change](/api-reference/subscriptions/cancel-change-plan). Failed charges may move the subscription to `on_hold` status, unless you pass `on_payment_failure: 'prevent_change'`, which keeps the subscription on its current plan until payment succeeds. Track changes via `subscription.plan_changed` webhook events.
</Info>

### Previewing Plan Changes

Before committing to a plan change, preview the exact charge and resulting subscription:

```typescript theme={null}
const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);
```

<Card title="Preview Change Plan API" icon="eye" href="/api-reference/subscriptions/preview-change-plan">
  Preview plan changes before committing to them.
</Card>

## Subscription States

A subscription moves through a defined set of statuses over its lifetime. This table is the reference for every status, what causes it, and how (or whether) you can recover it.

| Status      | What it means                                                                     | Recoverable?      | Recovery path / next step                                                                                                                                                                                                                                                     |
| ----------- | --------------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`   | The subscription is being created or processed                                    | —                 | Wait for `subscription.active` (or `subscription.failed`)                                                                                                                                                                                                                     |
| `active`    | The subscription is active and will renew automatically                           | —                 | No action needed                                                                                                                                                                                                                                                              |
| `on_hold`   | A renewal payment (or plan-change charge) failed; the subscription is paused      | **Yes**           | Update the payment method to reactivate — automatically via [Payment Retries](/features/recovery/payment-retries) and [Dunning](/features/recovery/subscription-dunning), or manually via the [Update Payment Method API](/api-reference/subscriptions/update-payment-method) |
| `cancelled` | The subscription was cancelled and will not renew                                 | Re-purchase only  | Customer must start a new subscription; [Dunning](/features/recovery/subscription-dunning) can prompt a re-purchase                                                                                                                                                           |
| `failed`    | Subscription **creation** failed (the initial mandate or payment did not succeed) | **No — terminal** | Customer must create a new subscription with a working payment method                                                                                                                                                                                                         |
| `expired`   | The subscription reached the end of its term                                      | —                 | Customer must start a new subscription if desired                                                                                                                                                                                                                             |

<Warning>
  `on_hold` and `failed` are often confused. `on_hold` is a **recoverable** state for an already-active subscription whose renewal failed. `failed` is a **terminal** state that only occurs when the **initial** subscription creation fails — it cannot be reactivated.
</Warning>

### State Machine

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending
    pending --> active: Creation succeeds
    pending --> failed: Mandate creation fails
    active --> on_hold: Renewal or plan-change charge fails
    on_hold --> active: Payment method updated / retry succeeds
    active --> cancelled: Cancelled
    on_hold --> cancelled: Cancelled
    active --> expired: Term ends
    failed --> [*]
    cancelled --> [*]
    expired --> [*]
```

### On Hold State

A subscription enters `on_hold` state when:

* A renewal payment fails (insufficient funds, expired card, etc.)
* A plan change charge fails
* Payment method authorization fails

<Warning>
  When a subscription is in `on_hold` state, it will not renew automatically. You must update the payment method to reactivate the subscription.
</Warning>

### Reactivating from On Hold

To reactivate a subscription from `on_hold` state, update the payment method. This automatically:

1. Creates a charge for remaining dues
2. Generates an invoice
3. Processes the payment using the new payment method
4. Reactivates the subscription to `active` state upon successful payment

```typescript theme={null}
// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}
```

<Info>
  After successfully updating the payment method for an `on_hold` subscription, you'll receive `payment.succeeded` followed by `subscription.active` webhook events.
</Info>

### Webhook Events by Transition

Each transition emits a webhook so you can drive entitlement logic without polling:

| Transition                  | Event                       |
| --------------------------- | --------------------------- |
| Subscription activated      | `subscription.active`       |
| Renewal succeeds            | `subscription.renewed`      |
| Renewal fails → paused      | `subscription.on_hold`      |
| Subscription paused         | `subscription.paused`       |
| Paused subscription resumed | `subscription.unpaused`     |
| Creation fails              | `subscription.failed`       |
| Plan upgraded/downgraded    | `subscription.plan_changed` |
| Cancelled                   | `subscription.cancelled`    |
| Term ended                  | `subscription.expired`      |
| Any field changes           | `subscription.updated`      |

<Card title="Subscription Webhook Payloads" icon="webhook" href="/developer-resources/webhooks/intents/subscription">
  View the full payload schema for subscription lifecycle events.
</Card>

## API Management

<AccordionGroup>
  <Accordion title="Create subscriptions">
    Use `POST /subscriptions` to create subscriptions programmatically from products, with optional trials and add‑ons.

    <Card title="API Reference" icon="code" href="/api-reference/subscriptions/post-subscriptions">
      View the create subscription API.
    </Card>
  </Accordion>

  <Accordion title="Update subscriptions">
    Use `PATCH /subscriptions/{subscription_id}` to cancel at the next billing date, extend the subscription period, update billing details, or modify metadata. To change the quantity, use the [Change Plan API](/api-reference/subscriptions/change-plan) instead — `PATCH` does not accept `quantity`.

    <Card title="API Reference" icon="code" href="/api-reference/subscriptions/patch-subscriptions">
      Learn how to update subscription details.
    </Card>
  </Accordion>

  <Accordion title="Change plans (proration)">
    Change the active product and quantities with proration controls.

    <Card title="API Reference" icon="code" href="/api-reference/subscriptions/change-plan">
      Review plan change options.
    </Card>
  </Accordion>

  <Accordion title="On‑demand charges">
    For on‑demand subscriptions, charge specific amounts on demand.

    <Card title="API Reference" icon="code" href="/api-reference/subscriptions/create-charge">
      Charge an on‑demand subscription.
    </Card>
  </Accordion>

  <Accordion title="List and retrieve">
    Use `GET /subscriptions` to list all subscriptions and `GET /subscriptions/{id}` to retrieve one.

    <Card title="API Reference" icon="code" href="/api-reference/subscriptions/get-subscriptions">
      Browse listing and retrieval APIs.
    </Card>
  </Accordion>

  <Accordion title="Usage history">
    Fetch recorded usage for metered or hybrid pricing models.

    <Card title="API Reference" icon="code" href="/api-reference/subscriptions/get-usage-history">
      See usage history API.
    </Card>
  </Accordion>

  <Accordion title="Update payment method">
    Update the payment method for a subscription. For active subscriptions, this updates the payment method for future renewals. For subscriptions in `on_hold` state, this reactivates the subscription by creating a charge for remaining dues.

    When generating a new payment-method link (the `New` request type), you can pass `allowed_payment_method_types` to restrict which payment methods the customer sees on that page. Customers will never see a method that isn't in the list, though including a method does not guarantee it appears (availability still depends on factors like customer location and your business settings).

    <Card title="API Reference" icon="code" href="/api-reference/subscriptions/update-payment-method">
      Learn how to update payment methods and reactivate subscriptions.
    </Card>
  </Accordion>
</AccordionGroup>

## Common Use Cases

* **SaaS and APIs**: Tiered access with add‑ons for seats or usage
* **Content and media**: Monthly access with introductory trials
* **B2B support plans**: Annual contracts with premium support add‑ons
* **Tools and plugins**: License keys and versioned releases

## Integration Examples

### Checkout Sessions (subscriptions)

When creating checkout sessions, include your subscription product and optional add‑ons:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ]
});
```

### Plan changes with proration

Upgrade or downgrade a subscription and control proration behavior:

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});
```

### Cancel at next billing date

Schedule a cancellation that takes effect at the end of the current billing period:

```typescript theme={null}
await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});
```

### Extend the subscription period

Extend how long a subscription runs by passing a new `subscription_period_count` and `subscription_period_interval` to `PATCH /subscriptions/{subscription_id}`. The subscription's expiry is recomputed from the new count and interval — for example, to grant a customer extra time on their current plan:

```typescript theme={null}
await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});
```

<Note>
  A subscription's period can only be **increased**, never shortened.
</Note>

### On‑demand subscriptions

Create an on‑demand subscription and charge later as needed:

```typescript theme={null}
const onDemand = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_on_demand',
  quantity: 1,
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});
```

### Update payment method for active subscription

Update the payment method for an active subscription:

```typescript theme={null}
// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});
```

### Reactivate subscription from on\_hold

Reactivate a subscription that went on hold due to failed payment:

```typescript theme={null}
// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}
```

## Subscriptions with RBI-Compliant Mandates

UPI and Indian card subscriptions operate under RBI (Reserve Bank of India) regulations with specific mandate requirements:

### Mandate Limits

The mandate type and amount depend on your subscription's recurring charge:

* **Charges below the mandate floor (default ₹15,000):** We create an on-demand mandate for the floor amount. The subscription amount is charged periodically according to your subscription frequency, up to the mandate limit.
* **Charges at or above the mandate floor:** We create a subscription mandate (or on-demand mandate) for the exact subscription amount.

The mandate floor is configurable per merchant or per request via `mandate_min_amount_inr_paise` (INR paise). The amount registered with the bank is `max(mandate_floor, billing_amount)` — so the floor effectively becomes the customer-facing authorization ceiling whenever billing is lower.

For detailed information about RBI-compliant mandates and the configurable mandate floor for Indian payment methods, see the <a href="/features/payment-methods/india#configurable-mandate-floor">India Payment Methods</a> page.

### Upgrade and Downgrade Considerations

**Important:** When upgrading or downgrading subscriptions, carefully consider the mandate limits:

* If an upgrade/downgrade results in a charge amount that exceeds Rs 15,000 and goes beyond the existing on-demand payment limit, the transaction charge may fail.
* In such cases, the customer may need to update their payment method or change the subscription again to establish a new mandate with the correct limit.

### Authorization for High-Value Charges

For subscription charges of Rs 15,000 or more:

* The customer will be prompted by their bank to authorize the transaction.
* If the customer fails to authorize the transaction, the transaction will fail and the subscription will be put on hold.

### 48-Hour Processing Delay

**Processing Timeline:** Recurring charges on Indian cards and UPI subscriptions follow a unique processing pattern:

* Charges are **initiated** on the scheduled date according to your subscription frequency.
* The actual **deduction** from the customer's account occurs only after **48 hours** from payment initiation.
* This 48-hour window may extend up to **2-3 additional hours** depending on bank API responses.

### Mandate Cancellation Window

During the 48-hour processing window:

* Customers can cancel the mandate via their banking apps.
* If a customer cancels the mandate during this period, the subscription will remain **active** (this is an edge case specific to Indian card and UPI AutoPay subscriptions).
* However, the actual deduction may fail, and in that case, we will put the subscription **on hold**.

**Edge Case Handling:** If you provide benefits, credits, or subscription usage to customers immediately upon charge initiation, you need to handle this 48-hour window appropriately in your application. Consider:

* Delaying benefit activation until payment confirmation
* Implementing grace periods or temporary access
* Monitoring subscription status for mandate cancellations
* Handling subscription hold states in your application logic

<Tip>
  Monitor subscription webhooks to track payment status changes and handle edge cases where mandates are cancelled during the 48-hour window.
</Tip>

## Best Practices

* **Start with clear tiers**: 2–3 plans with obvious differences
* **Communicate pricing**: Show totals, proration, and next renewal
* **Use trials thoughtfully**: Convert with onboarding, not just time
* **Leverage add‑ons**: Keep base plans simple and upsell extras
* **Test changes**: Validate plan changes and proration in test mode

<Info>
  Subscriptions are a flexible foundation for recurring revenue. Start simple, test thoroughly, and iterate based on adoption, churn, and expansion metrics.
</Info>


# Tax Inclusive Pricing
Source: https://docs.dodopayments.com/features/tax-inclusive-pricing

Show final, tax‑inclusive prices upfront. Dodo calculates tax by location and clearly breaks it out at checkout and on invoices.

## What Is Tax Inclusive Pricing?

Tax Inclusive Pricing lets you embed applicable taxes directly in your displayed product price. Customers see one final amount upfront for a more transparent, conversion‑friendly experience. At checkout, Dodo calculates the tax‑exclusive portion and tax amount from the displayed price based on customer location, and clearly breaks them out on the invoice.

<Info>
  Final tax still varies by customer location and tax category. Checkout and invoices show the calculated tax portion derived from the displayed price.
</Info>

## Key Benefits

* **Clarity for customers**: One final price displayed upfront
* **Compliance by region**: Tax is calculated per location and broken out
* **Accurate invoicing**: Invoices show net amount and tax derived from price
* **Conversion friendly**: Reduced surprises at checkout

## Product Setup

Create or edit a product in your dashboard, then enable tax‑inclusive pricing under pricing settings.

#### Pricing

* **Price** (required): Base price that is displayed to the customer.
* **Tax Inclusive Pricing**: Toggle on to treat the displayed price as tax inclusive. Dodo will compute the net (pre‑tax) amount and tax portion at checkout based on customer location and tax category.

<Warning>
  Only future purchases reflect updated tax‑inclusive settings. Existing purchases and active subscriptions are not retroactively changed.
</Warning>

<Tip>
  Use consistent product copy such as “Tax inclusive” so customers understand totals at a glance.
</Tip>

## API Management

<AccordionGroup>
  <Accordion title="Create products (tax inclusive)">
    Use `POST /products` to create products with `tax_inclusive` set to `true`.

    <Card title="API Reference" icon="code" href="/api-reference/products/post-products">
      Create product via API
    </Card>
  </Accordion>

  <Accordion title="Update products">
    Use `PATCH /products/{id}` to toggle `tax_inclusive` on existing products.

    <Card title="API Reference" icon="code" href="/api-reference/products/patch-products">
      Update product via API
    </Card>
  </Accordion>

  <Accordion title="Checkout Sessions">
    Use `POST /checkouts` to sell products marked as tax inclusive. The displayed price remains the same; checkout derives net amount and tax.

    <Card title="API Reference" icon="code" href="/api-reference/checkout-sessions/create">
      Create checkout session
    </Card>
  </Accordion>

  <Accordion title="Refunds (tax handling)">
    Use `POST /refunds` to issue refunds. For partial, per-item refunds you can specify whether tax is included using the `tax_inclusive` flag on each entry of the `items` array (defaults to `true`). Omit `items` to refund the payment in full.

    <Card title="API Reference" icon="code" href="/api-reference/refunds/post-refunds">
      Create a refund
    </Card>
  </Accordion>
</AccordionGroup>

## Integration Examples

### Create a product with tax‑inclusive pricing

```typescript theme={null}
const product = await client.products.create({
  name: 'Pro Plan',
  description: 'All features included',
  tax_category: 'saas',
  price: {
    type: 'one_time_price',
    currency: 'USD',
    price: 10000,
    discount: 0,
    purchasing_power_parity: false,
    tax_inclusive: true
  }
});
```

### Update an existing product to toggle tax inclusive

```typescript theme={null}
// `price` is a discriminated union, so send the complete price object,
// not just the field you want to change.
await client.products.update(product.product_id, {
  price: {
    type: 'one_time_price',
    currency: 'USD',
    price: 10000,
    discount: 0,
    purchasing_power_parity: false,
    tax_inclusive: true
  }
});
```

## Best Practices

* **Choose the right tax category** to ensure correct calculation per region.
* **Communicate totals** clearly with “Tax Inclusive” labels in product copy.
* **Test in Test Mode** to validate.

## Related

<CardGroup>
  <Card title="Products" icon="dollar-sign" href="/features/products">
    Manage pricing options across products.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    Configure recurring products with advanced settings.
  </Card>

  <Card title="Discount Codes" icon="percent" href="/features/discount-codes">
    Offer promotions while keeping invoice clarity.
  </Card>
</CardGroup>


# Team Members
Source: https://docs.dodopayments.com/features/team

The Team feature enables you to add teammates to your Dodo Payments dashboard, granting them access based on customizable permissions. You can allow full modification rights or restrict access to view-only mode, ensuring secure and flexible collaboration.

<Frame>
  <img alt="Team Cover Image" />
</Frame>

## How to add a teammate?

<img />

1. Go to Settings → Team.
2. Click on +**invite** button on the top right corner.

<img />

3. Provide the teammates email and assign a role to them.
4. Click on **Send Invite**.

## How can a teammate access the dashboard?

<img />

1. The teammate receives an invitation link via email and clicks on it.
2. If they do not have a Dodo Payments account, they are directed to the signup page where they need to provide the required details. If they already have a Dodo Payments account they can access the business through the business toggle on the bottom left.
3. After completing the signup process, they gain access to the dashboard.

## Roles and Permissions

<img />

The Dodo Dashboard has three types of user roles, each with different levels of access. The role icon of the user can be seen in the bottom left of the dashboard.

### 1. Owner

The **Owner** has the highest level of access and full control over the account. Only the account owner holds this role and has the exclusive ability to invite new users. The ownership of the account cannot be transferred.

### 2. Editor

Editors have almost the same permissions as the Owner, except they cannot invite new Editors. However, they can invite and remove users with the Viewer role. Additionally, they can create, edit, and delete products and make other modifications within the dashboard.

### 3. Viewer

Viewers have read-only access to the dashboard. They can view all information, including products, transactions, and reports, but cannot add, edit, or delete products or make any modifications.


# Disputes
Source: https://docs.dodopayments.com/features/transactions/disputes

The Disputes section is dedicated to managing customer disputes related to payments. Merchants can view and manage disputes from the Transactions page, including tracking the status of chargebacks and responding to disputes.

## Introduction

The disputes section provides a detailed view of all the disputes raised along with the current status of these disputes. You will have to manage the dispute resolution at your end but the dashboard will provide a visibility into the status, reason for dispute, dispute ID for convenience of access to information.

## Viewing and Understanding Disputes

<Steps>
  <Step title="Open the Transactions Page">
    Go to the <strong>Transactions</strong> page in your dashboard and select the <strong>Disputes</strong> tab. This displays a list of all disputes associated with your account.
  </Step>

  <Step title="View Dispute Details">
    Click the <strong>eye icon</strong> next to any dispute entry to open a detailed view. Here, you can review the dispute reason, status, dispute ID, and other relevant information.
  </Step>

  <Step title="Access Associated Payment Information">
    In the dispute details, locate the <strong>Associated Payment</strong> field. Click the <strong>eye icon</strong> here to view the full payment details related to the dispute.
  </Step>
</Steps>

## Responding to a Dispute

When a dispute is raised against your transaction, follow these steps to respond effectively:

1. **Check Your Dashboard**
   * Navigate to the transactions → disputes section
   * Look for the new dispute entry

2. **Review Email Notification**
   * Check your registered email for dispute creation notification

3. **Choose Your Response**

   * You can either accept or counter the dispute

   <Frame>
     <img alt="Dispute Creation" />
   </Frame>

4. **If Accepting**
   * No further action required
   * You will lose the dispute

5. **If Countering**

   * Prepare to submit evidence
   * Follow the best practices below

   <Frame>
     <img alt="Dispute Creation" />
   </Frame>

   <Frame>
     <img alt="Dispute Creation" />
   </Frame>

<Info>
  You have **10 days** to respond to a dispute after it is created. The countdown shown on the dispute in your dashboard reflects the same window.
</Info>

## Dispute Response Best Practices

<Steps>
  <Step title="Understand the Dispute Reason">
    Review the dispute reason carefully. Common reasons include:

    <CardGroup>
      <Card title="Fraudulent Transaction">
        The customer claims they did not authorize the transaction
      </Card>

      <Card title="Product/Service Not Received">
        The customer claims they did not receive the product/service after payment
      </Card>

      <Card title="Not as Described">
        The customer claims the product/service differs from what was advertised
      </Card>
    </CardGroup>

    <Info>
      Your response must directly address the specific reason. Avoid submitting generic or unrelated evidence.
    </Info>
  </Step>

  <Step title="Gather the Right Evidence">
    Focus on customer identity, access, and usage evidence.

    <Tabs>
      <Tab title="Fraudulent Transaction">
        <Card title="Required Evidence">
          * **Invoice** of the purchase
          * **IP address, device, and location** details at time of purchase
          * **Login timestamps** showing access to your platform or service
          * **Browser/device fingerprint** or account activity logs
          * Previous successful transactions from the same customer or account
          * Terms of Service and Refund Policy accepted at time of purchase
        </Card>
      </Tab>

      <Tab title="Product/Service Not Received">
        <Card title="Required Evidence">
          * **Invoice** of the purchase
          * Screenshot or logs showing **successful login**
          * Timestamped activity (downloads, content viewed, sessions started)
          * Emails or support messages confirming access was granted
          * Welcome emails or onboarding steps completed by the customer
          * Internal logs showing product/service was delivered as promised
        </Card>
      </Tab>

      <Tab title="Not as Described">
        <Card title="Required Evidence">
          * **Invoice** of the purchase
          * Product/service description from your website at time of purchase
          * Comparison of what was promised vs. what was delivered
          * Documentation or screenshots of what was accessed
          * Any customer communication acknowledging receipt or usage
          * Refund policy and support options made available to the customer
        </Card>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Craft a Clear Description">
    <Card title="Focus Points">
      * What the customer purchased
      * When and how they accessed it
      * Why the dispute claim is inaccurate
    </Card>

    <Info>
      Keep your language factual and professional. Avoid emotional or accusatory statements.
    </Info>

    <Card title="Example Response">
      "We offer a digital image generation from text service using AI. The customer purchased a monthly subscription on March 5 and accessed the product multiple times from March 5–10 and generated 4 images in the duration. Please see attached access logs and the accepted terms showing our no-refund policy."
    </Card>
  </Step>

  <Step title="Format & Submit Evidence">
    <Card title="Submission Guidelines">
      * Use **PDF, JPG, or PNG** formats only
      * Clearly **label each file** (e.g., `Login_Log_March_5.pdf`)
      * Submit only **relevant** and **organized** files
      * Keep files under 5 MB each
      * Do **not include links or URLs**
    </Card>
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Common Mistakes to Avoid">
    <Card title="Avoid These Errors">
      * Ignoring the actual dispute reason
      * Using vague or emotional statements
      * Uploading unrelated or unstructured files
      * Providing links instead of files
    </Card>
  </Accordion>

  <Accordion title="Bonus Tips">
    <Card title="Strengthen Your Case">
      * Include **timestamps with timezone** to prove access timelines
      * Highlight any **two-factor authentication** or verification steps
      * Share **refund refusal communication** if it aligns with your policy
      * Keep your policies clearly visible and easy to prove were accepted
    </Card>
  </Accordion>
</AccordionGroup>

## Visa Rapid Dispute Resolution (RDR)

Visa Rapid Dispute Resolution (RDR) is an automated dispute prevention tool that resolves eligible disputes **before they become formal chargebacks**. When a cardholder initiates a dispute with their bank, RDR intercepts the dispute and automatically issues a refund on your behalf if the transaction is below your configured threshold -- preventing the chargeback from ever being filed.

### Why RDR Matters

Disputes are one of the most costly and time-consuming challenges for digital businesses. Beyond the direct financial impact, high dispute rates can have severe consequences:

<CardGroup>
  <Card title="Financial Impact" icon="money-bill">
    Each dispute costs you the transaction amount **plus** a non-refundable dispute fee, regardless of whether you win or lose.
  </Card>

  <Card title="Dispute Rate Penalties" icon="chart-line-down">
    Card networks monitor your dispute-to-transaction ratio. Visa's threshold is **0.9%** -- exceeding it places you in a monitoring program with escalating fines.
  </Card>

  <Card title="Account Risk" icon="triangle-exclamation">
    Consistently high dispute rates can lead to increased processing fees, reserve requirements, or even account termination by payment processors.
  </Card>

  <Card title="Operational Overhead" icon="clock">
    Each dispute requires evidence gathering, response preparation, and follow-up -- consuming valuable time that could be spent building your product.
  </Card>
</CardGroup>

<Warning>
  Visa's Dispute Monitoring Program (VDMP) kicks in when your dispute rate exceeds **0.9%** or you receive more than **100 disputes** in a month. Penalties escalate monthly and can reach **\$50,000+** per month in fines for merchants that remain in the program.
</Warning>

### How RDR Works

<Steps>
  <Step title="Cardholder initiates a dispute">
    The customer contacts their bank to dispute a Visa transaction on their statement.
  </Step>

  <Step title="RDR intercepts the dispute">
    Before the dispute becomes a formal chargeback, Visa's RDR system checks if the transaction qualifies for automatic resolution based on your configured rules.
  </Step>

  <Step title="Automatic refund issued">
    If the transaction amount is within your threshold, a refund is automatically issued to the cardholder via Visa's network. The dispute is resolved instantly.
  </Step>

  <Step title="No chargeback recorded">
    Because the dispute was resolved before becoming a formal chargeback, it **does not count against your dispute rate** with Visa.
  </Step>
</Steps>

<Info>
  Transactions auto-refunded through RDR will appear as a **lost dispute** in your Dodo Payments dashboard. This is expected behavior -- the refund was issued automatically to prevent a formal chargeback, and the "lost" status reflects that the funds were returned to the cardholder.
</Info>

### Key Benefits

| Benefit                           | Description                                                                                                                                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Lower dispute rate**            | RDR-resolved disputes don't count toward your Visa dispute ratio, keeping you below the 0.9% threshold                                                                                                                         |
| **Dispute fee still applies**     | A dispute fee is still charged on RDR-resolved transactions. This fee covers the cost of contesting the dispute with Visa on your behalf -- an intentional part of actively keeping your dispute rate below the 0.9% threshold |
| **Zero operational overhead**     | No need to gather evidence, write responses, or track dispute deadlines -- resolution is fully automatic                                                                                                                       |
| **Better customer experience**    | Cardholders receive their refund instantly instead of waiting weeks for a dispute to be resolved                                                                                                                               |
| **Protect your account standing** | Stay out of Visa's monitoring programs and avoid escalating fines and processing restrictions                                                                                                                                  |

### Configuration

RDR is configured with a **USD threshold** -- any Visa dispute at or below this amount is automatically resolved with a refund. Disputes above the threshold proceed through the normal dispute process, giving you the opportunity to counter them with evidence.

<Info>
  For example, with a \$100 threshold: a \$75 dispute is auto-resolved (refunded), while a \$150 dispute proceeds normally for you to review and respond to.
</Info>

### Enable RDR for Your Account

Visa RDR is **enabled by default** on all Dodo Payments accounts with a **\$100 USD threshold**. This means any Visa dispute at or below \$100 is automatically resolved with a refund -- no action needed from you.

<Frame>
  <img alt="Visa RDR settings showing the enabled toggle and threshold configuration" />
</Frame>

#### Customizing Your Threshold

You can adjust the RDR threshold to match your business needs:

<Steps>
  <Step title="Open the Disputes Settings">
    Navigate to **Settings → Business** in your Dodo Payments dashboard and locate the **Visa Rapid Dispute Resolution (RDR)** section.
  </Step>

  <Step title="Edit the Threshold">
    Click the **Edit** button next to the current threshold value. Enter your desired USD amount -- any Visa dispute at or below this amount will be automatically resolved.
  </Step>

  <Step title="Save Your Changes">
    Confirm the new threshold. The updated threshold takes effect immediately for all future Visa disputes.
  </Step>
</Steps>

<Info>
  You can also disable RDR entirely by toggling it off, though we recommend keeping it enabled to protect your dispute rate.
</Info>

<Tip>
  We recommend starting with a threshold around your average transaction value. You can always adjust it later based on your dispute patterns.
</Tip>

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why am I charged a dispute fee on RDR-resolved transactions?">
    Dispute fees are still charged even when a transaction is resolved through RDR. The fee covers the cost of contesting the dispute with Visa on your behalf. This is intentional -- it's part of how we actively keep your dispute rate below the 0.9% threshold, which is critical for maintaining good standing with banks and payment processors. A necessary cost, but one working in your favour.
  </Accordion>

  <Accordion title="Can a cardholder dispute the same transaction again after RDR resolution?">
    No. Once a transaction is resolved via RDR, it is closed at the Visa network level. The issuer will not re-process a chargeback for the same transaction ID -- if a cardholder tries again, their bank will see the prior resolution and reject it. This is enforced upstream by Visa, so there is nothing you need to manage on your end.
  </Accordion>
</AccordionGroup>


# Payments
Source: https://docs.dodopayments.com/features/transactions/payments

The Payments section provides merchants with a detailed overview of all payment transactions. Merchants can track payment statuses, initiate refunds, and access payment details for each transaction.

<Frame>
  <iframe title="Checkout Experience | Dodo Payments" />
</Frame>

## **Payments Listing Page**

The Payments listing page provides a record of all the payments that have taken place and includes important information about the payment like the transaction amount, payment status and payment method along with the invoice for reference to the purchase associated with the payment.&#x20;

* The following Payment statuses are shown:

  * **In Progress**: The payment is currently being processed.

  * **Failed**: The payment attempt was unsuccessful.

  * **Successful**: The payment was completed successfully.

<Info>The payment method and timestamp are updated once the payment is completed.</Info>

***

## **Payment Details Page**

Upon clicking a payment in the listing, merchants are directed to the **Payment Details Page**, which provides a comprehensive breakdown of the transaction

### Successful payment

<Frame>
  <img alt="Payment details page showing a successful payment with green status and transaction breakdown" />
</Frame>

* **Status**: Shows as **Successful** at the top with the final captured amount.
* **Transaction details**: Displays `Payment ID`, `Payment date`, `Payment method`, and `Settlement amount`.
* **Card information**: Card network, last four, issuing country, and type.
* **Customer details**: Name, email, and billing info.
* **Product cart**: Product IDs and quantities purchased.
* **Actions**: You can generate the invoice or initiate a refund from the top-right.

### Failed payment

<Frame>
  <img alt="Payment details page showing a failed payment with red error banner, decline error code and message" />
</Frame>

* **Status**: Shows as **Failed** with a red banner.
* **Error context**: Includes the gateway `Error Code` and human-readable `Error Message` (for example, `INSUFFICIENT_FUNDS` – “Your card was declined”).
* **Other information**: The error fields are repeated in the details section for quick reference.
* **Next steps**:
  * Retry the payment with a different card or funding source.
  * Verify card details and available funds.
  * If the decline persists, contact the issuer and try again.

<Info>
  Look up any `Error Code` in the [Transaction Failures](/api-reference/transaction-failures) reference to see what it means and the recommended action. To handle failed payments programmatically, see [Handle Payment Failures](/developer-resources/handle-payment-failures).
</Info>

## **Important Information**

* **Automatic Activation**: All the payment methods listed above will become available to customers automatically once the merchant's account is verified and live mode is enabled.

* **No Additional Configuration Required**: Merchants do not need to configure these payment options, as they are pre-defined and managed by Dodo Payments.

* **Additional Payment Methods**: We are constantly adding more payment methods to our roster. We will keep updating this page as and when we add more methods. If you have a requirement for any particular payment method, please write to us at [support@dodopayments.com](mailto:support@dodopayments.com) and we will add this to our roadmap if not present.

## How to Navigate and Use the Payments Page

<Steps>
  <Step title="Navigate to the Payments section">
    Open the **Transactions** page and click on the **Payments** tab to view all payment transactions.
  </Step>

  <Step title="Filter and search payments">
    Use the available filters to narrow down your payment list:

    * **Status filter**: View payments by status.
    * **Date range**: Select custom date ranges to view payments from specific periods
  </Step>

  <Step title="View payment details">
    Click on the **Array icon** next to any payment to access the detailed payment information.
  </Step>

  <Step title="Review payment information">
    On the payment details page, you can view:

    * **Transaction details**: Amount, currency, payment method, and timestamp
    * **Customer information**: Name, email, and billing details
    * **Payment status**: Current status with timestamp of status changes
  </Step>

  <Step title="Download invoice">
    To download the associated invoice, click the **download Invoice** (📥) on the invoice preview section.
  </Step>
</Steps>


# Refunds
Source: https://docs.dodopayments.com/features/transactions/refunds

The Refunds section allows merchants to manage and initiate refunds for transactions. Merchants can initiate full or partial refunds directly from the transaction details view, with built-in rules ensuring compliance and protecting against errors.

## Initiate Refund

You can initiate two types of refunds from the Payment Details Page:

* **Full refund**: Refunds the entire payment amount to the customer.
* **Partial refund**: Refunds only a portion of the payment amount, as specified by you.

To begin, click the **Initiate Refund** button. The refund will only proceed if all refund rules are met.

<Frame>
  <img alt="Initiate refund button on the payment details page" />
</Frame>

<Tip>
  Partial refunds are useful when only a portion of the order needs to be refunded.
</Tip>

### Details Required for Refund

* **Refund Amount**: The amount to be refunded. For partial refunds, enter the specific amount you wish to return to the customer. The system will prevent you from refunding more than the original payment.

* **Refund Reason**: The reason for the refund, to be recorded in the system.

### Refund Rules

1. The payment must have been successful.

2. Refunds (full or partial) must be initiated within 30 days of the transaction date. Initiating refunds will not be allowed post that.

3. Refunds are issued to the original payment method used by the customer.

If any rule is violated, the refund request will be denied. Please reach out to support for assistance if needed.

## Refund Status

Track the progress of your refund through the following status indicators:

| Status    | Description                                               | Possible Reason                                                                                  |
| --------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| succeeded | The refund has been successfully processed.               | —                                                                                                |
| pending   | The refund is being processed and is awaiting completion. | —                                                                                                |
| review    | The refund is held for manual review before processing.   | Risk or compliance check triggered on the refund                                                 |
| failed    | The refund could not be processed due to an error.        | <ul><li>Payment was disputed</li><li>Insufficient balance in wallet</li><li>Bank issue</li></ul> |

## Refunds Page

The **Refunds Page** provides a detailed view of all refund transactions:&#x20;

* Clicking the **Associated Payment ID** will take the merchant to the **Payment Details Page** for that transaction.

* Merchants can export the refund report in CSV format for a specified date range.

Here’s how the **Refunds Page** looks:

<Frame>
  <img alt="Refunds page showing a list of refund transactions" />
</Frame>

## Refund Receipt

Once a refund is successfully processed, a **Refund Receipt** is automatically sent to the customer.

**Refund Receipt Template:**

<Frame>
  <img alt="Refund receipt template showing the refund details" />
</Frame>

The refund receipt includes:

* **Refund ID**: The unique identifier for the refund.
* **Refund amount**: The amount refunded to the customer.
* **Refund date**: The date the refund was processed.
* **Refund method**: The method used to refund the customer.
* **Refund status**: The status of the refund.
* **Refund reason**: The reason for the refund.


# Upsells & Downsells
Source: https://docs.dodopayments.com/features/upsells-and-downsells

Increase revenue with one-click purchases using saved payment methods for post-purchase offers, subscription upgrades, and cross-sells.

<Info>
  Upsells and downsells let you offer additional products or plan changes to customers using their saved payment methods. This enables one-click purchases that skip payment collection, dramatically improving conversion rates.
</Info>

<CardGroup>
  <Card title="Post-Purchase Upsells" icon="cart-plus">
    Offer complementary products immediately after checkout with one-click purchasing.
  </Card>

  <Card title="Subscription Upgrades" icon="arrow-up">
    Move customers to higher tiers with automatic proration and instant billing.
  </Card>

  <Card title="Cross-Sells" icon="grid-2-plus">
    Add related products to existing customers without re-entering payment details.
  </Card>
</CardGroup>

## Overview

Upsells and downsells are powerful revenue optimization strategies:

* **Upsells**: Offer a higher-value product or upgrade (e.g., Pro plan instead of Basic)
* **Downsells**: Offer a lower-priced alternative when a customer declines or downgrades
* **Cross-sells**: Suggest complementary products (e.g., add-ons, related items)

Dodo Payments enables these flows through the `payment_method_id` parameter, which lets you charge a customer's saved payment method without requiring them to re-enter card details.

### Key Benefits

| Benefit                 | Impact                                             |
| ----------------------- | -------------------------------------------------- |
| **One-click purchases** | Skip payment form entirely for returning customers |
| **Higher conversion**   | Reduce friction at the moment of decision          |
| **Instant processing**  | Charges process immediately with `confirm: true`   |
| **Seamless UX**         | Customers stay in your app throughout the flow     |

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant A as Your App
    participant D as Dodo API
    
    C->>A: Completes purchase
    A->>D: Get payment methods
    D-->>A: payment_method_id
    A->>C: Show upsell offer
    C->>A: Accept (one click)
    A->>D: Charge with payment_method_id
    D-->>A: Payment success
    D->>A: Webhook: payment.succeeded
```

## Prerequisites

Before implementing upsells and downsells, ensure you have:

<Steps>
  <Step title="Customer with Saved Payment Method">
    Customers must have completed at least one purchase. Payment methods are automatically saved when customers complete checkout.
  </Step>

  <Step title="Products Configured">
    Create your upsell products in the Dodo Payments dashboard. These can be one-time payments, subscriptions, or add-ons.
  </Step>

  <Step title="Webhook Endpoint">
    Set up webhooks to handle `payment.succeeded`, `payment.failed`, and `subscription.plan_changed` events.
  </Step>
</Steps>

## Getting Customer Payment Methods

Before offering an upsell, retrieve the customer's saved payment methods:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: 'live_mode',
    });

    async function getPaymentMethods(customerId: string) {
      const paymentMethods = await client.customers.retrievePaymentMethods(customerId);
      
      // Returns { items: [...] } — the list of saved payment methods.
      // Each item has: payment_method_id, payment_method, payment_method_type, last_used_at,
      // recurring_enabled, and card (last4_digits, card_network, card_type, expiry_month, expiry_year)
      return paymentMethods;
    }

    // Example usage
    const methods = await getPaymentMethods('cus_123');
    console.log('Available payment methods:', methods);

    // Use the first available method for upsell
    const primaryMethod = methods.items[0]?.payment_method_id;
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from dodopayments import DodoPayments

    client = DodoPayments(
        bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
        environment="live_mode",
    )

    def get_payment_methods(customer_id: str):
        payment_methods = client.customers.retrieve_payment_methods(customer_id)
        
        # Returns an object with an `items` list of saved payment methods.
        # Each item has: payment_method_id, payment_method, payment_method_type, last_used_at,
        # recurring_enabled, and card (last4_digits, card_network, card_type, expiry_month, expiry_year)
        return payment_methods

    # Example usage
    methods = get_payment_methods("cus_123")
    print("Available payment methods:", methods)

    # Use the first available method for upsell
    primary_method = methods.items[0].payment_method_id if methods.items else None
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "context"
        "fmt"
        "github.com/dodopayments/dodopayments-go"
        "github.com/dodopayments/dodopayments-go/option"
    )

    func getPaymentMethods(customerID string) ([]dodopayments.CustomerGetPaymentMethodsResponseItem, error) {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        resp, err := client.Customers.GetPaymentMethods(
            context.TODO(),
            customerID,
        )
        if err != nil {
            return nil, err
        }
        
        return resp.Items, nil
    }

    func main() {
        methods, err := getPaymentMethods("cus_123")
        if err != nil {
            panic(err)
        }
        
        fmt.Println("Available payment methods:", methods)
        
        // Use the first available method for upsell
        if len(methods) > 0 {
            primaryMethod := methods[0].PaymentMethodID
            fmt.Println("Primary method:", primaryMethod)
        }
    }
    ```
  </Tab>
</Tabs>

<Info>
  Payment methods are automatically saved when customers complete checkout. You don't need to explicitly save them.
</Info>

## Post-Purchase One-Click Upsells

Offer additional products immediately after a successful purchase. The customer can accept with a single click since their payment method is already saved.

```mermaid theme={null}
flowchart LR
    A[Purchase] --> B{Upsell?}
    B -->|Yes| C[Show Offer]
    B -->|No| F[Done]
    C --> D{Accept?}
    D -->|Yes| E[One-Click Charge] --> F
    D -->|No| F
```

### Implementation

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: 'live_mode',
    });

    async function createOneClickUpsell(
      customerId: string,
      paymentMethodId: string,
      upsellProductId: string
    ) {
      // Create checkout session with saved payment method
      // confirm: true processes the payment immediately
      const session = await client.checkoutSessions.create({
        product_cart: [
          {
            product_id: upsellProductId,
            quantity: 1
          }
        ],
        customer: {
          customer_id: customerId
        },
        payment_method_id: paymentMethodId,
        confirm: true,  // Required when using payment_method_id
        return_url: 'https://yourapp.com/upsell-success',
        feature_flags: {
          redirect_immediately: true  // Skip success page
        },
        metadata: {
          upsell_source: 'post_purchase',
          original_order_id: 'order_123'
        }
      });

      return session;
    }

    // Example: Offer premium add-on after initial purchase
    async function handlePostPurchaseUpsell(customerId: string) {
      // Get customer's payment methods
      const methods = await client.customers.retrievePaymentMethods(customerId);
      
      if (methods.items.length === 0) {
        console.log('No saved payment methods available');
        return null;
      }

      // Create the upsell with one-click checkout
      const upsell = await createOneClickUpsell(
        customerId,
        methods.items[0].payment_method_id,
        'pdt_premium_addon'
      );

      console.log('Upsell processed:', upsell.session_id);
      return upsell;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from dodopayments import DodoPayments

    client = DodoPayments(
        bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
        environment="live_mode",
    )

    def create_one_click_upsell(
        customer_id: str,
        payment_method_id: str,
        upsell_product_id: str
    ):
        """Create a one-click upsell using saved payment method."""
        
        # Create checkout session with saved payment method
        # confirm=True processes the payment immediately
        session = client.checkout_sessions.create(
            product_cart=[
                {
                    "product_id": upsell_product_id,
                    "quantity": 1
                }
            ],
            customer={
                "customer_id": customer_id
            },
            payment_method_id=payment_method_id,
            confirm=True,  # Required when using payment_method_id
            return_url="https://yourapp.com/upsell-success",
            feature_flags={
                "redirect_immediately": True  # Skip success page
            },
            metadata={
                "upsell_source": "post_purchase",
                "original_order_id": "order_123"
            }
        )
        
        return session


    def handle_post_purchase_upsell(customer_id: str):
        """Offer premium add-on after initial purchase."""
        
        # Get customer's payment methods
        methods = client.customers.retrieve_payment_methods(customer_id)
        
        if not methods.items:
            print("No saved payment methods available")
            return None
        
        # Create the upsell with one-click checkout
        upsell = create_one_click_upsell(
            customer_id=customer_id,
            payment_method_id=methods.items[0].payment_method_id,
            upsell_product_id="pdt_premium_addon"
        )
        
        print(f"Upsell processed: {upsell.session_id}")
        return upsell
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "context"
        "fmt"
        "os"
        
        "github.com/dodopayments/dodopayments-go"
        "github.com/dodopayments/dodopayments-go/option"
    )

    func createOneClickUpsell(
        customerID string,
        paymentMethodID string,
        upsellProductID string,
    ) (*dodopayments.CheckoutSessionResponse, error) {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        // Create checkout session with saved payment method
        // Confirm: true processes the payment immediately
        session, err := client.CheckoutSessions.New(context.TODO(), dodopayments.CheckoutSessionNewParams{
            CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
                ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{
                    {
                        ProductID: dodopayments.F(upsellProductID),
                        Quantity:  dodopayments.F(int64(1)),
                    },
                }),
                Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
                    dodopayments.AttachExistingCustomerParam{
                        CustomerID: dodopayments.F(customerID),
                    },
                ),
                PaymentMethodID: dodopayments.F(paymentMethodID),
                Confirm:         dodopayments.F(true), // Required when using payment_method_id
                ReturnURL:       dodopayments.F("https://yourapp.com/upsell-success"),
                FeatureFlags: dodopayments.F(dodopayments.CheckoutSessionFlagsParam{
                    RedirectImmediately: dodopayments.F(true), // Skip success page
                }),
                Metadata: dodopayments.F(map[string]string{
                    "upsell_source":     "post_purchase",
                    "original_order_id": "order_123",
                }),
            },
        })
        
        return session, err
    }

    func handlePostPurchaseUpsell(customerID string) (*dodopayments.CheckoutSessionResponse, error) {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        // Get customer's payment methods
        resp, err := client.Customers.GetPaymentMethods(context.TODO(), customerID)
        if err != nil {
            return nil, err
        }
        
        if len(resp.Items) == 0 {
            fmt.Println("No saved payment methods available")
            return nil, nil
        }
        
        // Create the upsell with one-click checkout
        upsell, err := createOneClickUpsell(
            customerID,
            resp.Items[0].PaymentMethodID,
            "pdt_premium_addon",
        )
        if err != nil {
            return nil, err
        }
        
        fmt.Printf("Upsell processed: %s\n", upsell.SessionID)
        return upsell, nil
    }
    ```
  </Tab>
</Tabs>

<Warning>
  When using `payment_method_id`, you must set `confirm: true` and provide an existing `customer_id`. The payment method must belong to that customer.
</Warning>

## Subscription Upgrades

Move customers to higher-tier subscription plans with automatic proration handling.

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant A as Your App
    participant D as Dodo API
    
    C->>A: Request upgrade
    A->>D: Preview change plan
    D-->>A: Charge amount
    A->>C: Confirm $50 charge?
    C->>A: Confirm
    A->>D: Change plan
    D->>A: Webhook: plan_changed
```

### Preview Before Committing

Always preview plan changes to show customers exactly what they'll be charged:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    async function previewUpgrade(
      subscriptionId: string,
      newProductId: string
    ) {
      const preview = await client.subscriptions.previewChangePlan(subscriptionId, {
        product_id: newProductId,
        quantity: 1,
        proration_billing_mode: 'difference_immediately'
      });

      return {
        immediateCharge: preview.immediate_charge?.summary,
        newPlan: preview.new_plan,
        effectiveAt: preview.immediate_charge?.effective_at
      };
    }

    // Show customer the charge before confirming
    const preview = await previewUpgrade('sub_123', 'pdt_pro_plan');
    console.log(`Upgrade will charge: ${preview.immediateCharge}`);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def preview_upgrade(subscription_id: str, new_product_id: str):
        preview = client.subscriptions.preview_change_plan(
            subscription_id=subscription_id,
            product_id=new_product_id,
            quantity=1,
            proration_billing_mode="difference_immediately"
        )
        
        return {
            "immediate_charge": preview.immediate_charge.summary if preview.immediate_charge else None,
            "new_plan": preview.new_plan,
            "effective_at": preview.immediate_charge.effective_at if preview.immediate_charge else None,
        }

    # Show customer the charge before confirming
    preview = preview_upgrade("sub_123", "pdt_pro_plan")
    print(f"Upgrade will charge: {preview['immediate_charge']}")
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    func previewUpgrade(subscriptionID string, newProductID string) (map[string]interface{}, error) {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        preview, err := client.Subscriptions.PreviewChangePlan(
            context.TODO(),
            subscriptionID,
            dodopayments.SubscriptionPreviewChangePlanParams{
                UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                    ProductID:            dodopayments.F(newProductID),
                    Quantity:             dodopayments.F(int64(1)),
                    ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately),
                },
            },
        )
        if err != nil {
            return nil, err
        }
        
        return map[string]interface{}{
            "immediate_charge": preview.ImmediateCharge.Summary,
            "new_plan":         preview.NewPlan,
            "effective_at":     preview.ImmediateCharge.EffectiveAt,
        }, nil
    }
    ```
  </Tab>
</Tabs>

### Execute the Upgrade

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    async function upgradeSubscription(
      subscriptionId: string,
      newProductId: string,
      prorationMode: 'prorated_immediately' | 'difference_immediately' | 'full_immediately' | 'do_not_bill' = 'difference_immediately'
    ) {
      // change-plan returns 200 with an empty body — resolving without an error means it was accepted.
      await client.subscriptions.changePlan(subscriptionId, {
        product_id: newProductId,
        quantity: 1,
        proration_billing_mode: prorationMode
      });

      // Re-read the subscription to observe the applied state.
      return await client.subscriptions.retrieve(subscriptionId);
    }

    // Upgrade from Basic ($30) to Pro ($80)
    // With difference_immediately: charges $50 instantly
    const upgrade = await upgradeSubscription('sub_123', 'pdt_pro_plan');
    console.log('Upgrade status:', upgrade.status);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def upgrade_subscription(
        subscription_id: str,
        new_product_id: str,
        proration_mode: str = "difference_immediately"
    ):
        # change_plan returns 200 with an empty body — returning without an error means it was accepted.
        client.subscriptions.change_plan(
            subscription_id=subscription_id,
            product_id=new_product_id,
            quantity=1,
            proration_billing_mode=proration_mode
        )

        # Re-read the subscription to observe the applied state.
        return client.subscriptions.retrieve(subscription_id)

    # Upgrade from Basic ($30) to Pro ($80)
    # With difference_immediately: charges $50 instantly
    upgrade = upgrade_subscription("sub_123", "pdt_pro_plan")
    print(f"Upgrade status: {upgrade.status}")
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    func upgradeSubscription(
        subscriptionID string,
        newProductID string,
        prorationMode dodopayments.UpdateSubscriptionPlanReqProrationBillingMode,
    ) error {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        // ChangePlan returns no response body; a nil error means the change succeeded.
        err := client.Subscriptions.ChangePlan(
            context.TODO(),
            subscriptionID,
            dodopayments.SubscriptionChangePlanParams{
                UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                    ProductID:            dodopayments.F(newProductID),
                    Quantity:             dodopayments.F(int64(1)),
                    ProrationBillingMode: dodopayments.F(prorationMode),
                },
            },
        )
        
        return err
    }

    // Upgrade from Basic ($30) to Pro ($80)
    // With DifferenceImmediately: charges $50 instantly
    err := upgradeSubscription(
        "sub_123",
        "pdt_pro_plan",
        dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately,
    )
    if err != nil {
        panic(err)
    }
    fmt.Println("Upgrade succeeded")
    ```
  </Tab>
</Tabs>

### Proration Modes

Choose how customers are billed when upgrading:

| Mode                     | Behavior                                                                                                                                | Best For                              |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `difference_immediately` | Charges price difference instantly ($30→$80 = \$50)                                                                                     | Simple upgrades                       |
| `prorated_immediately`   | Charges based on remaining time in billing cycle                                                                                        | Fair time-based billing               |
| `full_immediately`       | Charges full new plan price, ignores remaining time                                                                                     | Billing cycle resets                  |
| `do_not_bill`            | Applies the plan change with no immediate charge; the new plan is billed at the next renewal and the original billing date is preserved | Courtesy upgrades and free migrations |

<Tip>
  Use `difference_immediately` for straightforward upgrade flows. Use `prorated_immediately` when you want to account for unused time on the current plan.
</Tip>

## Cross-Sells

Add complementary products for existing customers without requiring them to re-enter payment details.

```mermaid theme={null}
flowchart LR
    A[View Product] --> B{Existing Customer?}
    B -->|Yes| C[One-Click Buy] --> E[Deliver]
    B -->|No| D[Standard Checkout] --> E
```

### Implementation

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    async function createCrossSell(
      customerId: string,
      paymentMethodId: string,
      productId: string,
      quantity: number = 1
    ) {
      // Create a one-time payment using saved payment method
      const payment = await client.payments.create({
        product_cart: [
          {
            product_id: productId,
            quantity: quantity
          }
        ],
        customer: { customer_id: customerId },
        billing: { country: 'US', city: 'San Francisco', state: 'CA', street: '1 Market St', zipcode: '94105' },
        payment_method_id: paymentMethodId,
        return_url: 'https://yourapp.com/purchase-complete',
        metadata: {
          purchase_type: 'cross_sell',
          source: 'product_recommendation'
        }
      });

      return payment;
    }

    // Example: Customer bought a course, offer related ebook
    async function offerRelatedProduct(customerId: string, relatedProductId: string) {
      const methods = await client.customers.retrievePaymentMethods(customerId);
      
      if (methods.items.length === 0) {
        // Fall back to standard checkout
        return client.checkoutSessions.create({
          product_cart: [{ product_id: relatedProductId, quantity: 1 }],
          customer: { customer_id: customerId },
          return_url: 'https://yourapp.com/purchase-complete'
        });
      }

      // One-click purchase
      return createCrossSell(customerId, methods.items[0].payment_method_id, relatedProductId);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def create_cross_sell(
        customer_id: str,
        payment_method_id: str,
        product_id: str,
        quantity: int = 1
    ):
        """Create a one-time payment using saved payment method."""
        
        payment = client.payments.create(
            product_cart=[
                {
                    "product_id": product_id,
                    "quantity": quantity
                }
            ],
            customer={"customer_id": customer_id},
            billing={"country": "US", "city": "San Francisco", "state": "CA", "street": "1 Market St", "zipcode": "94105"},
            payment_method_id=payment_method_id,
            return_url="https://yourapp.com/purchase-complete",
            metadata={
                "purchase_type": "cross_sell",
                "source": "product_recommendation"
            }
        )
        
        return payment


    def offer_related_product(customer_id: str, related_product_id: str):
        """Offer related product with one-click purchase if possible."""
        
        methods = client.customers.retrieve_payment_methods(customer_id)
        
        if not methods.items:
            # Fall back to standard checkout
            return client.checkout_sessions.create(
                product_cart=[{"product_id": related_product_id, "quantity": 1}],
                customer={"customer_id": customer_id},
                return_url="https://yourapp.com/purchase-complete"
            )
        
        # One-click purchase
        return create_cross_sell(customer_id, methods.items[0].payment_method_id, related_product_id)
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    func createCrossSell(
        customerID string,
        paymentMethodID string,
        productID string,
        quantity int64,
    ) (*dodopayments.PaymentNewResponse, error) {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        payment, err := client.Payments.New(context.TODO(), dodopayments.PaymentNewParams{
            ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{
                {
                    ProductID: dodopayments.F(productID),
                    Quantity:  dodopayments.F(quantity),
                },
            }),
            Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
                dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F(customerID)},
            ),
            Billing: dodopayments.F(dodopayments.BillingAddressParam{
                Country: dodopayments.F(dodopayments.CountryCodeUs),
                City:    dodopayments.F("San Francisco"),
                State:   dodopayments.F("CA"),
                Street:  dodopayments.F("1 Market St"),
                Zipcode: dodopayments.F("94105"),
            }),
            PaymentMethodID: dodopayments.F(paymentMethodID),
            ReturnURL:       dodopayments.F("https://yourapp.com/purchase-complete"),
            Metadata: dodopayments.F(map[string]string{
                "purchase_type": "cross_sell",
                "source":        "product_recommendation",
            }),
        })
        
        return payment, err
    }

    func offerRelatedProduct(customerID string, relatedProductID string) (interface{}, error) {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        resp, err := client.Customers.GetPaymentMethods(context.TODO(), customerID)
        if err != nil {
            return nil, err
        }
        
        if len(resp.Items) == 0 {
            // Fall back to standard checkout
            return client.CheckoutSessions.New(context.TODO(), dodopayments.CheckoutSessionNewParams{
                CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
                    ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{
                        {ProductID: dodopayments.F(relatedProductID), Quantity: dodopayments.F(int64(1))},
                    }),
                    Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
                        dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F(customerID)},
                    ),
                    ReturnURL: dodopayments.F("https://yourapp.com/purchase-complete"),
                },
            })
        }
        
        // One-click purchase
        return createCrossSell(customerID, resp.Items[0].PaymentMethodID, relatedProductID, 1)
    }
    ```
  </Tab>
</Tabs>

## Subscription Downgrades

When customers want to move to a lower-tier plan, handle the transition gracefully with automatic credits.

### How Downgrades Work

1. Customer requests downgrade (Pro → Basic)
2. System calculates remaining value on current plan
3. Credit is added to subscription for future renewals
4. Customer moves to new plan immediately

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    async function downgradeSubscription(
      subscriptionId: string,
      newProductId: string
    ) {
      // Preview the downgrade first
      const preview = await client.subscriptions.previewChangePlan(subscriptionId, {
        product_id: newProductId,
        quantity: 1,
        proration_billing_mode: 'difference_immediately'
      });

      console.log('Credit to be applied:', preview.immediate_charge.summary.customer_credits);

      // Execute the downgrade. change-plan returns 200 with an empty body.
      await client.subscriptions.changePlan(subscriptionId, {
        product_id: newProductId,
        quantity: 1,
        proration_billing_mode: 'difference_immediately'
      });

      // Credits are automatically applied to future renewals
      return await client.subscriptions.retrieve(subscriptionId);
    }

    // Downgrade from Pro ($80) to Basic ($30)
    // $50 credit added to subscription, auto-applied on next renewal
    const downgrade = await downgradeSubscription('sub_123', 'pdt_basic_plan');
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def downgrade_subscription(subscription_id: str, new_product_id: str):
        # Preview the downgrade first
        preview = client.subscriptions.preview_change_plan(
            subscription_id=subscription_id,
            product_id=new_product_id,
            quantity=1,
            proration_billing_mode="difference_immediately"
        )
        
        print(f"Credit to be applied: {preview.immediate_charge.summary.customer_credits}")
        
        # Execute the downgrade. change_plan returns 200 with an empty body.
        client.subscriptions.change_plan(
            subscription_id=subscription_id,
            product_id=new_product_id,
            quantity=1,
            proration_billing_mode="difference_immediately"
        )

        # Credits are automatically applied to future renewals
        return client.subscriptions.retrieve(subscription_id)

    # Downgrade from Pro ($80) to Basic ($30)
    # $50 credit added to subscription, auto-applied on next renewal
    downgrade = downgrade_subscription("sub_123", "pdt_basic_plan")
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    func downgradeSubscription(subscriptionID string, newProductID string) error {
        client := dodopayments.NewClient(
            option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
        )
        
        // Preview the downgrade first
        preview, err := client.Subscriptions.PreviewChangePlan(
            context.TODO(),
            subscriptionID,
            dodopayments.SubscriptionPreviewChangePlanParams{
                UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                    ProductID:            dodopayments.F(newProductID),
                    Quantity:             dodopayments.F(int64(1)),
                    ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately),
                },
            },
        )
        if err != nil {
            return err
        }
        
        fmt.Printf("Customer credits to be applied: %v\n", preview.ImmediateCharge.Summary.CustomerCredits)
        
        // Execute the downgrade (returns no response body; nil error means success)
        return client.Subscriptions.ChangePlan(
            context.TODO(),
            subscriptionID,
            dodopayments.SubscriptionChangePlanParams{
                UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
                    ProductID:            dodopayments.F(newProductID),
                    Quantity:             dodopayments.F(int64(1)),
                    ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeDifferenceImmediately),
                },
            },
        )
    }
    ```
  </Tab>
</Tabs>

<Info>
  Credits from downgrades using `difference_immediately` are subscription-scoped and automatically applied to future renewals. They're distinct from [Credit-Based Billing](/features/credit-based-billing) entitlements.
</Info>

## Complete Example: Post-Purchase Upsell Flow

Here's a complete implementation showing how to offer an upsell after a successful purchase:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import DodoPayments from 'dodopayments';
    import express from 'express';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: 'live_mode',
    });

    const app = express();

    // Store for tracking upsell eligibility (use your database in production)
    const eligibleUpsells = new Map<string, { customerId: string; productId: string }>();

    // Webhook handler for initial purchase success
    app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
      const event = JSON.parse(req.body.toString());
      
      switch (event.type) {
        case 'payment.succeeded':
          // Check if customer is eligible for upsell
          const customerId = event.data.customer_id;
          const productId = event.data.product_id;
          
          // Define upsell rules (e.g., bought Basic, offer Pro)
          const upsellProduct = getUpsellProduct(productId);
          
          if (upsellProduct) {
            eligibleUpsells.set(customerId, {
              customerId,
              productId: upsellProduct
            });
          }
          break;
          
        case 'payment.failed':
          console.log('Payment failed:', event.data.payment_id);
          // Handle failed upsell payment
          break;
      }
      
      res.json({ received: true });
    });

    // API endpoint to check upsell eligibility
    app.get('/api/upsell/:customerId', async (req, res) => {
      const { customerId } = req.params;
      const upsell = eligibleUpsells.get(customerId);
      
      if (!upsell) {
        return res.json({ eligible: false });
      }
      
      // Get payment methods
      const methods = await client.customers.retrievePaymentMethods(customerId);
      
      if (methods.items.length === 0) {
        return res.json({ eligible: false, reason: 'no_payment_method' });
      }
      
      // Get product details for display
      const product = await client.products.retrieve(upsell.productId);
      
      res.json({
        eligible: true,
        product: {
          id: product.product_id,
          name: product.name,
          price: product.price,
          currency: product.price.currency
        },
        paymentMethodId: methods.items[0].payment_method_id
      });
    });

    // API endpoint to accept upsell
    app.post('/api/upsell/:customerId/accept', async (req, res) => {
      const { customerId } = req.params;
      const upsell = eligibleUpsells.get(customerId);
      
      if (!upsell) {
        return res.status(400).json({ error: 'No upsell available' });
      }
      
      try {
        const methods = await client.customers.retrievePaymentMethods(customerId);
        
        // Create one-click purchase
        const session = await client.checkoutSessions.create({
          product_cart: [{ product_id: upsell.productId, quantity: 1 }],
          customer: { customer_id: customerId },
          payment_method_id: methods.items[0].payment_method_id,
          confirm: true,
          return_url: `${process.env.APP_URL}/upsell-success`,
          feature_flags: { redirect_immediately: true },
          metadata: { upsell: 'true', source: 'post_purchase' }
        });
        
        // Clear the upsell offer
        eligibleUpsells.delete(customerId);
        
        res.json({ success: true, sessionId: session.session_id });
      } catch (error) {
        console.error('Upsell failed:', error);
        res.status(500).json({ error: 'Upsell processing failed' });
      }
    });

    // Helper function to determine upsell product
    function getUpsellProduct(purchasedProductId: string): string | null {
      const upsellMap: Record<string, string> = {
        'pdt_basic_plan': 'pdt_pro_plan',
        'pdt_starter_course': 'pdt_complete_bundle',
        'pdt_single_license': 'pdt_team_license'
      };
      
      return upsellMap[purchasedProductId] || null;
    }

    app.listen(3000);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from flask import Flask, request, jsonify
    from dodopayments import DodoPayments

    client = DodoPayments(
        bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
        environment="live_mode",
    )

    app = Flask(__name__)

    # Store for tracking upsell eligibility (use your database in production)
    eligible_upsells = {}


    @app.route('/webhooks/dodo', methods=['POST'])
    def webhook_handler():
        event = request.json
        
        if event['type'] == 'payment.succeeded':
            # Check if customer is eligible for upsell
            customer_id = event['data']['customer_id']
            product_id = event['data']['product_id']
            
            # Define upsell rules
            upsell_product = get_upsell_product(product_id)
            
            if upsell_product:
                eligible_upsells[customer_id] = {
                    'customer_id': customer_id,
                    'product_id': upsell_product
                }
        
        elif event['type'] == 'payment.failed':
            print(f"Payment failed: {event['data']['payment_id']}")
        
        return jsonify({'received': True})


    @app.route('/api/upsell/<customer_id>', methods=['GET'])
    def check_upsell(customer_id):
        upsell = eligible_upsells.get(customer_id)
        
        if not upsell:
            return jsonify({'eligible': False})
        
        # Get payment methods
        methods = client.customers.retrieve_payment_methods(customer_id)
        
        if not methods.items:
            return jsonify({'eligible': False, 'reason': 'no_payment_method'})
        
        # Get product details for display
        product = client.products.retrieve(upsell['product_id'])
        
        return jsonify({
            'eligible': True,
            'product': {
                'id': product.product_id,
                'name': product.name,
                'price': product.price,
                'currency': product.price.currency
            },
            'payment_method_id': methods.items[0].payment_method_id
        })


    @app.route('/api/upsell/<customer_id>/accept', methods=['POST'])
    def accept_upsell(customer_id):
        upsell = eligible_upsells.get(customer_id)
        
        if not upsell:
            return jsonify({'error': 'No upsell available'}), 400
        
        try:
            methods = client.customers.retrieve_payment_methods(customer_id)
            
            # Create one-click purchase
            session = client.checkout_sessions.create(
                product_cart=[{'product_id': upsell['product_id'], 'quantity': 1}],
                customer={'customer_id': customer_id},
                payment_method_id=methods.items[0].payment_method_id,
                confirm=True,
                return_url=f"{os.environ['APP_URL']}/upsell-success",
                feature_flags={'redirect_immediately': True},
                metadata={'upsell': 'true', 'source': 'post_purchase'}
            )
            
            # Clear the upsell offer
            del eligible_upsells[customer_id]
            
            return jsonify({'success': True, 'session_id': session.session_id})
        
        except Exception as error:
            print(f"Upsell failed: {error}")
            return jsonify({'error': 'Upsell processing failed'}), 500


    def get_upsell_product(purchased_product_id: str) -> str:
        """Determine upsell product based on purchased product."""
        upsell_map = {
            'pdt_basic_plan': 'pdt_pro_plan',
            'pdt_starter_course': 'pdt_complete_bundle',
            'pdt_single_license': 'pdt_team_license'
        }
        return upsell_map.get(purchased_product_id)


    if __name__ == '__main__':
        app.run(port=3000)
    ```
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Time Your Upsells Strategically">
    The best time to offer an upsell is immediately after a successful purchase when customers are in a buying mindset. Other effective moments:

    * After feature usage milestones
    * When approaching plan limits
    * During onboarding completion
  </Accordion>

  <Accordion title="Validate Payment Method Eligibility">
    Before attempting a one-click charge, verify the payment method:

    * Is compatible with the product's currency
    * Hasn't expired
    * Belongs to the customer

    The API will validate these, but checking proactively improves UX.
  </Accordion>

  <Accordion title="Handle Failures Gracefully">
    When one-click charges fail:

    1. Fall back to standard checkout flow
    2. Notify the customer with clear messaging
    3. Offer to update payment method
    4. Don't repeatedly attempt failed charges
  </Accordion>

  <Accordion title="Provide Clear Value Proposition">
    Upsells convert better when customers understand the value:

    * Show what they're getting vs. current plan
    * Highlight the price difference, not total price
    * Use social proof (e.g., "Most popular upgrade")
  </Accordion>

  <Accordion title="Respect Customer Choice">
    * Always provide an easy way to decline
    * Don't show the same upsell repeatedly after decline
    * Track and analyze which upsells convert to optimize offers
  </Accordion>
</AccordionGroup>

## Webhooks to Monitor

Track these webhook events for upsell and downgrade flows:

| Event                       | Trigger                                    | Action                              |
| --------------------------- | ------------------------------------------ | ----------------------------------- |
| `payment.succeeded`         | Upsell/cross-sell payment completed        | Deliver product, update access      |
| `payment.failed`            | One-click charge failed                    | Show error, offer retry or fallback |
| `subscription.plan_changed` | Upgrade/downgrade completed                | Update features, send confirmation  |
| `subscription.active`       | Subscription reactivated after plan change | Grant access to new tier            |

<Card title="Webhook Integration Guide" icon="webhook" href="/developer-resources/webhooks">
  Learn how to set up and verify webhook endpoints.
</Card>

## Related Resources

<CardGroup>
  <Card title="Subscription Upgrade Guide" icon="arrows-rotate" href="/developer-resources/subscription-upgrade-downgrade">
    Detailed guide on plan changes, proration modes, and handling failures.
  </Card>

  <Card title="Checkout Sessions" icon="cart-shopping" href="/developer-resources/checkout-session">
    Complete reference for creating checkout sessions with all options.
  </Card>

  <Card title="Customer Payment Methods API" icon="credit-card" href="/api-reference/customers/get-customer-payment-methods">
    API reference for listing customer payment methods.
  </Card>

  <Card title="Add-ons" icon="puzzle-piece" href="/features/addons">
    Enhance subscriptions with flexible add-ons for additional revenue.
  </Card>
</CardGroup>


# Event Ingestion
Source: https://docs.dodopayments.com/features/usage-based-billing/event-ingestion

Send usage events from your application to track customer consumption and power billing.

Events are the foundation of usage-based billing. Send events when billable actions occur, and meters aggregate them into charges.

<Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
  Complete API documentation with examples and response codes.
</Card>

## Event Structure

<Accordion title="Required Fields">
  <ParamField type="string">
    Unique identifier. Use UUIDs or combine customer ID + timestamp + action.
  </ParamField>

  <ParamField type="string">
    Dodo Payments customer ID. Must be a valid existing customer.
  </ParamField>

  <ParamField type="string">
    Event type that matches your meter's event name (case-sensitive). Examples: `api.call`, `image.generated`
  </ParamField>
</Accordion>

<Accordion title="Optional Fields">
  <ParamField type="string">
    ISO 8601 timestamp (UTC). Defaults to the current server time if omitted. Include for accurate billing with delayed/batch events. Timestamps older than 1 hour, or more than 5 minutes in the future, are rejected.
  </ParamField>

  <ParamField type="object">
    Additional properties for aggregation and filtering:

    * Numeric values: `bytes`, `tokens`, `duration_ms`
    * Filters: `endpoint`, `method`, `quality`

    ```javascript theme={null}
    metadata: {
      endpoint: "/v1/orders",
      method: "POST",
      tokens: 1024
    }
    ```
  </ParamField>
</Accordion>

## Sending Events

<CodeGroup>
  ```javascript Single Event theme={null}
  await fetch('https://test.dodopayments.com/events/ingest', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      events: [{
        event_id: "api_call_1234",
        customer_id: "cus_abc123",
        event_name: "api.call",
        metadata: { endpoint: "/v1/orders" }
      }]
    })
  });
  ```

  ```javascript Batch Events theme={null}
  await fetch('https://test.dodopayments.com/events/ingest', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      events: [
        { event_id: "call_1", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_2", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_3", customer_id: "cus_abc", event_name: "api.call" }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      'https://test.dodopayments.com/events/ingest',
      headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'},
      json={'events': [{'event_id': 'call_1', 'customer_id': 'cus_abc', 'event_name': 'api.call'}]}
  )
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://test.dodopayments.com/events/ingest' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"events": [{"event_id": "call_1", "customer_id": "cus_abc", "event_name": "api.call"}]}'
  ```
</CodeGroup>

<Tip>
  Batch up to 1,000 events per request for better performance. The API enforces a hard limit of 1,000 events per call.
</Tip>

## Ingestion Blueprints

Ready-made event patterns for common use cases. Start with a proven blueprint instead of building from scratch.

<CardGroup>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Track AI token usage across OpenAI, Anthropic, Groq, Gemini, and more.
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    Meter API requests with endpoint filtering and rate limiting support.
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    Track file uploads and storage consumption for cloud storage services.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Measure streaming bandwidth for video, audio, and real-time data.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Bill by elapsed time for serverless functions and compute instances.
  </Card>

  <Card title="View All Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    See all available blueprints with detailed implementation guides.
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Unique Event IDs">
    Use deterministic IDs to prevent duplicates: `${customerId}_${action}_${timestamp}`
  </Accordion>

  <Accordion title="Implement Retries">
    Retry on 5xx errors with exponential backoff. Don't retry 4xx errors.
  </Accordion>

  <Accordion title="Include Timestamps">
    Omit for real-time events. Include for delayed/batch events for accuracy.
  </Accordion>

  <Accordion title="Monitor Delivery">
    Track success rates and queue failed events for retry.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not appearing">
    * Event name must exactly match meter (case-sensitive)
    * Customer ID must exist
    * Check meter filters aren't excluding events
    * Verify timestamps are recent
  </Accordion>

  <Accordion title="Authentication errors (401)">
    Verify API key is correct and use format: `Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Validation errors (400)">
    Ensure all required fields are present: `event_id`, `customer_id`, `event_name`
  </Accordion>

  <Accordion title="Metadata not aggregating">
    * Metadata keys must match meter's "Over Property" exactly
    * Use numbers, not strings: `tokens: 150` not `tokens: "150"`
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Create Meters" icon="sliders" href="/features/usage-based-billing/meters">
    Define how your events are aggregated into billable quantities with filters and aggregation functions.
  </Card>

  <Card title="Ingestion Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Use ready-made blueprints for common use cases like LLM tracking, API gateways, and storage.
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Build a full AI image generator with usage-based billing from scratch.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/usage-events/ingest-events">
    Complete API documentation with all parameters, response codes, and interactive testing.
  </Card>
</CardGroup>


# Ingestion Blueprints
Source: https://docs.dodopayments.com/features/usage-based-billing/ingestion-blueprints

Ready-made event ingestion patterns for common use cases with sample code.

Ingestion blueprints are pre-built patterns for tracking usage in common scenarios. Instead of figuring out event structures and meter configurations from scratch, start with a proven blueprint and customize it for your needs.

## What Are Blueprints?

Each blueprint includes:

* **Event structure recommendations**: Optimal event naming and metadata design
* **Meter configuration**: Suggested aggregation types and filters
* **Sample code**: Working implementation examples in multiple languages
* **Best practices**: Tips for accuracy, performance, and cost optimization

<Tip>
  Blueprints save hours of setup time and help you avoid common pitfalls. Start with a blueprint, then adapt it to your specific requirements.
</Tip>

## Why Use Blueprints?

<CardGroup>
  <Card title="Faster Setup" icon="rocket">
    Get usage tracking working in minutes instead of hours. Copy proven patterns instead of designing from scratch.
  </Card>

  <Card title="Best Practices Built In" icon="shield-check">
    Avoid common mistakes with tested event structures, proper metadata, and optimal aggregation choices.
  </Card>

  <Card title="Production Ready" icon="code">
    Sample code is based on real-world implementations. Just add your API keys and go.
  </Card>
</CardGroup>

## Available Blueprints

Choose the blueprint that matches your use case:

<CardGroup>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Track AI token usage across OpenAI, Anthropic, Groq, Gemini, Vercel AI SDK, and more.

    **Perfect for**: AI chatbots, code generators, content creation tools, AI-powered apps.

    **What you'll track**: Input tokens, output tokens, model usage, request counts.
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    Meter API requests at the gateway level with endpoint filtering and rate limiting support.

    **Perfect for**: REST APIs, GraphQL services, webhook providers, API-first platforms.

    **What you'll track**: Request counts, endpoint usage, HTTP methods, response times.
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    Track file uploads, storage consumption, and bandwidth for cloud storage services.

    **Perfect for**: File hosting, media platforms, backup services, document management.

    **What you'll track**: Bytes stored, file uploads, downloads, storage snapshots.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Measure streaming bandwidth for video, audio, and real-time data delivery.

    **Perfect for**: Video streaming, audio platforms, live broadcasts, real-time data feeds.

    **What you'll track**: Bandwidth consumed, stream duration, quality levels, concurrent streams.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Bill by elapsed time for compute resources, serverless functions, and long-running jobs.

    **Perfect for**: Serverless platforms, container hosting, compute instances, batch processing.

    **What you'll track**: Execution time, compute hours, function invocations, job duration.
  </Card>
</CardGroup>

## How to Use a Blueprint

<Steps>
  <Step title="Choose your blueprint">
    Select the blueprint that best matches your billing scenario. Each blueprint page includes detailed implementation guides.
  </Step>

  <Step title="Review the event structure">
    Understand the recommended event naming and metadata design. Copy the event structure for your use case.
  </Step>

  <Step title="Create the meter">
    Follow the blueprint's meter configuration instructions. Use the suggested aggregation type and filters.
  </Step>

  <Step title="Implement event sending">
    Copy the sample code for your language/framework. Replace placeholder values with your actual API keys and customer IDs.
  </Step>

  <Step title="Test and verify">
    Send test events and verify they appear in your meter dashboard with correct aggregation.
  </Step>

  <Step title="Customize as needed">
    Adapt the blueprint to your specific requirements—add custom metadata, adjust filters, or modify pricing.
  </Step>
</Steps>

## Blueprint Comparison

Not sure which blueprint fits your needs? Here's a quick comparison:

| Use Case       | Blueprint      | Aggregation     | Common Metadata                      |
| -------------- | -------------- | --------------- | ------------------------------------ |
| AI chat app    | LLM            | Sum (tokens)    | model, input\_tokens, output\_tokens |
| REST API       | API Gateway    | Count           | endpoint, method, status\_code       |
| File storage   | Object Storage | Sum (bytes)     | file\_size, file\_type, operation    |
| Video platform | Stream         | Sum (bandwidth) | duration, quality, bitrate           |
| Serverless     | Time Range     | Sum (duration)  | function\_name, execution\_time\_ms  |

## Custom Implementations

Don't see a blueprint for your exact use case? No problem:

1. **Start with the closest blueprint**: Pick the one most similar to your needs
2. **Adapt the event structure**: Modify metadata fields to match your requirements
3. **Adjust meter configuration**: Change aggregation type or filters as needed
4. **Test thoroughly**: Verify billing calculations with sample usage

<Info>
  All blueprints are starting points. Feel free to mix concepts from different blueprints or create entirely custom implementations.
</Info>

## Need Help?

If you're unsure which blueprint to use or need help customizing:

<CardGroup>
  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Follow our end-to-end tutorial building an AI image generator with usage billing.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/usage-based-billing-guide">
    Comprehensive guide covering all aspects of usage-based billing implementation.
  </Card>
</CardGroup>


# Usage Based Billing
Source: https://docs.dodopayments.com/features/usage-based-billing/introduction

Charge customers based on what they actually use with flexible metering and automated billing.

Usage-based billing lets you charge customers for what they actually use—API calls, storage, AI tokens, or any metric you define. Customers pay for consumption, not fixed fees.

<Info>
  **Perfect for**: APIs, AI services, infrastructure platforms, and any product where value scales with usage.
</Info>

## How It Works

<Steps>
  <Step title="Send Usage Events">
    Your application sends events when billable actions occur.

    ```javascript theme={null}
    {
      "event_id": "evt_123",
      "customer_id": "cus_abc",
      "event_name": "api.call",
      "metadata": { "endpoint": "/v1/users" }
    }
    ```
  </Step>

  <Step title="Meters Aggregate Usage">
    Meters aggregate events into billable quantities using Count, Sum, Max, or Last aggregation.
  </Step>

  <Step title="Automatic Billing">
    Set pricing per unit and free thresholds. Customers are billed automatically each cycle.
  </Step>
</Steps>

## Core Concepts

### Events

Events represent usage actions in your application. Each event includes:

* **Event Name**: Type of usage (e.g., `api.call`)
* **Customer ID**: Who used it
* **Metadata**: Additional properties for aggregation

### Meters

Meters aggregate events into billable quantities:

* **Count**: Total events (API calls)
* **Sum**: Add values (total bytes)
* **Max**: Highest value (peak users)
* **Last**: Most recent value

<Frame>
  <img alt="Create meter interface" />
</Frame>

### Products with Usage Pricing

Set pricing per unit and optional free thresholds:

<Frame>
  <img alt="Pricing configuration" />
</Frame>

**Example**: 2,500 calls - 1,000 free = 1,500 × $0.02 = $30.00

### Credit-Based Deduction

Instead of charging per-unit in dollars, you can configure meters to deduct from a customer's [credit balance](/features/credit-based-billing). Credits refresh each billing cycle and apply before any overage charges.

## Quick Start

<Steps>
  <Step title="Create a Meter">
    In your dashboard: **Meters** → **Create Meter**

    1. Set event name (e.g., `api.call`)
    2. Choose aggregation (Count, Sum, Max, Last)
    3. Add optional filters
  </Step>

  <Step title="Add to Product">
    Link meter to a product with pricing:

    <Frame>
      <img alt="Adding meter to product" />
    </Frame>

    1. Select **Usage-Based Billing**
    2. Choose your meter
    3. Set price per unit and free threshold
  </Step>

  <Step title="Send Events">
    ```javascript theme={null}
    await fetch('https://test.dodopayments.com/events/ingest', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        events: [{
          event_id: "unique_event_id",
          customer_id: "cus_abc123",
          event_name: "api.call",
          metadata: { endpoint: "/v1/users" }
        }]
      })
    });
    ```
  </Step>

  <Step title="Monitor Usage">
    <Frame>
      <img alt="Meter dashboard" />
    </Frame>

    Check your meter's dashboard to see events and usage aggregation. Customers are billed automatically each cycle.
  </Step>
</Steps>

## Use Cases

<CardGroup>
  <Card title="APIs & Infrastructure" icon="cloud">
    Track API calls, compute hours, bandwidth, storage. Example: \$0.001 per call after 10,000 free.
  </Card>

  <Card title="AI Usage Tracking" icon="brain">
    Track tokens, generations, processing time. Example: \$0.04 per standard image, \$0.08 per HD.
  </Card>

  <Card title="Data & Analytics" icon="chart-line">
    Bill by data processed, queries run, records analyzed. Example: \$5 per GB after 10 GB free.
  </Card>

  <Card title="Communication" icon="message">
    Count messages, minutes, data transferred. Example: \$0.01 per SMS sent.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Event Ingestion" icon="bolt" href="/features/usage-based-billing/event-ingestion">
    Learn how to structure and send usage events from your application.
  </Card>

  <Card title="Meters Guide" icon="sliders" href="/features/usage-based-billing/meters">
    Master meter configuration, aggregation types, and event filtering.
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Build a complete AI image generator with usage-based billing from scratch.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/usage-based-billing-guide">
    Comprehensive guide to implementing usage-based billing in your application.
  </Card>
</CardGroup>


# Meters
Source: https://docs.dodopayments.com/features/usage-based-billing/meters

Transform raw usage events into billable quantities with aggregation and filtering.

<Info>
  Meters convert raw events into billable quantities. They filter events and apply aggregation functions (Count, Sum, Max, Last) to calculate usage per customer.
</Info>

<Frame>
  <img alt="Meter creation interface showing event name, aggregation type, and filtering options" />
</Frame>

## API Resources

<AccordionGroup>
  <Accordion title="View Meter API References">
    <CardGroup>
      <Card title="Create Meter" icon="plus" href="/api-reference/meters/create-meter">
        Create meters programmatically via API.
      </Card>

      <Card title="List Meters" icon="list" href="/api-reference/meters/get-meters">
        Retrieve all meters in your account.
      </Card>

      <Card title="Get Meter" icon="eye" href="/api-reference/meters/retrieve-meter">
        Fetch details for a specific meter by ID.
      </Card>

      <Card title="Archive Meter" icon="arrow-rotate-right" href="/api-reference/meters/archive-meter">
        Archive a meter to stop tracking usage.
      </Card>

      <Card title="Unarchive Meter" icon="arrow-rotate-left" href="/api-reference/meters/unarchive-meter">
        Restore an archived meter to resume tracking.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Creating a Meter

<Steps>
  <Step title="Basic Information">
    <ParamField type="string">
      Descriptive name (e.g., "API Requests", "Token Usage")
    </ParamField>

    <ParamField type="string">
      Exact event name to match (case-sensitive). Examples: `api.call`, `image.generated`
    </ParamField>
  </Step>

  <Step title="Aggregation">
    <ParamField type="string">
      Choose how events are aggregated:

      * **Count**: Total number of events (API calls, uploads)
      * **Sum**: Add numeric values (tokens, bytes)
      * **Max**: Highest value in period (peak users)
      * **Last**: Most recent value
    </ParamField>

    <ParamField type="string">
      Metadata key to aggregate (required for all types except Count). Examples: `tokens`, `bytes`, `duration_ms`
    </ParamField>

    <ParamField type="string">
      Unit label for invoices. Examples: `calls`, `tokens`, `GB`, `hours`
    </ParamField>
  </Step>

  <Step title="Filtering (Optional)">
    <Frame>
      <img alt="Event filtering" />
    </Frame>

    Add conditions to filter which events are counted:

    * **AND logic**: All conditions must match
    * **OR logic**: Any condition can match

    **Comparators**: equals, not equals, greater than, greater than or equals, less than, less than or equals, contains, does not contain

    Enable filtering, choose logic, add conditions with property key, comparator, and value.
  </Step>

  <Step title="Create">
    Review configuration and click **Create Meter**.
  </Step>
</Steps>

## Viewing Analytics

<Frame>
  <img alt="Meter analytics" />
</Frame>

Your meter dashboard shows:

* **Overview**: Total usage and usage chart
* **Events**: Individual events received
* **Customers**: Per-customer usage and charges

## Billing in Credits Instead of Currency

By default, meters charge customers per-unit in dollars (or your configured currency). You can instead configure a meter to **deduct from a credit balance** - so usage consumes credits rather than generating a monetary charge.

<Info>
  Credit-based deduction requires a [Credit Entitlement](/features/credit-based-billing) attached to the same product. Create your credit first, then link it to the meter.
</Info>

### When to Use Credit-Based Deduction

| Scenario                                                        | Standard (currency)           | Credit-based                                         |
| --------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------- |
| Simple per-unit pricing (\$0.01/call)                           | ✅ Best fit                    | Unnecessary overhead                                 |
| Prepaid credit packs (buy 10K tokens, use over time)            | ❌ Can't express               | ✅ Best fit                                           |
| Bundled usage with subscriptions (Pro plan includes 100K calls) | Possible via free threshold   | ✅ Better - credits roll over, expire, show in portal |
| Multi-meter products sharing a credit pool                      | ❌ Each meter bills separately | ✅ All meters deduct from one balance                 |

### Configuring a Meter to Deduct Credits

<Steps>
  <Step title="Create a Credit Entitlement">
    First, create a credit in **Products → Credits**. Define the unit (e.g., "API Calls", "Tokens"), precision, and lifecycle settings (expiry, rollover, overage).

    See the [Credit-Based Billing guide](/features/credit-based-billing) for detailed instructions.
  </Step>

  <Step title="Create or Edit a Usage-Based Product">
    Go to your usage-based product and open the **Meter** configuration section.
  </Step>

  <Step title="Add a Meter">
    Click the **+** button to attach a meter. Configure the event name, aggregation type, and measurement unit as usual.
  </Step>

  <Step title="Enable 'Bill Usage in Credits'">
    Toggle **Bill usage in Credits** on the meter configuration. This reveals the credit settings:

    <Frame>
      <img alt="Meter configuration with Bill usage in Credits toggle enabled" />
    </Frame>

    <ParamField type="string">
      Select which credit entitlement this meter should deduct from.
    </ParamField>

    <ParamField type="number">
      The number of usage units required to deduct 1 credit. For example:

      * `1` = each meter event deducts 1 credit
      * `100` = 100 meter events deduct 1 credit
      * `1000` = 1,000 API calls consume 1 credit
    </ParamField>
  </Step>

  <Step title="Set the Free Threshold">
    The **Free Threshold** still applies - events below this threshold don't deduct credits.

    **Example**: With a free threshold of 1,000 and meter-units-per-credit of 1:

    * Customer uses 2,500 API calls
    * First 1,000 are free
    * Remaining 1,500 deduct 1,500 credits from their balance
  </Step>
</Steps>

### How Credit Deduction Works

Once configured, the deduction pipeline runs automatically:

1. **Events arrive** - Your application sends usage events via the [Event Ingestion API](/features/usage-based-billing/event-ingestion)
2. **Meter aggregates** - Events are aggregated per your meter configuration (Count, Sum, Max, Last)
3. **Background worker processes** - Every minute, a worker fetches new events since the last checkpoint
4. **Credits are deducted** - Aggregated usage is converted to credits using the `meter_units_per_credit` rate and deducted using **FIFO ordering** (oldest grants consumed first)
5. **Overage tracked** - If the balance hits zero and overage is enabled, usage continues and overage is handled according to the configured behavior (forgiven at reset, billed at next invoice, or carried forward as deficit)

```mermaid theme={null}
flowchart LR
    A[Usage Event] --> B[Meter Aggregation]
    B --> C{Credits Available?}
    C -->|Yes| D[Deduct from Balance]
    C -->|No| E{Overage Enabled?}
    E -->|Yes| F[Track Overage]
    E -->|No| G[Block Usage]
    D --> H[Update Ledger]
    F --> H
```

<Warning>
  Credit deduction runs asynchronously (every \~1 minute). There may be a brief delay between event ingestion and balance deduction. Design your application to handle this delay - don't rely on real-time balance checks for access control on individual requests.
</Warning>

### Multiple Meters, One Credit Pool

You can link multiple meters on the same product to the **same credit entitlement**. All meters deduct from one shared balance.

**Example**: An AI platform with two meters:

* `text.generation` - 1 credit per 1,000 tokens
* `image.generation` - 10 credits per image

Both deduct from the same "AI Credits" pool. The customer sees a single unified balance in their portal.

<Tip>
  Use different `meter_units_per_credit` rates across meters to express relative costs. Expensive operations (image generation) cost fewer meter units per credit than cheap ones (text completion).
</Tip>

<CardGroup>
  <Card title="List Customer Ledger" icon="scroll" href="/api-reference/credit-entitlements/list-customer-ledger">
    View the full credit deduction history for a customer.
  </Card>

  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    Check a customer's current credit balance via API.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not appearing">
    * Event name must match exactly (case-sensitive)
    * Check meter filters aren't excluding events
    * Verify customer IDs exist
    * Temporarily disable filters to test
  </Accordion>

  <Accordion title="Aggregation not working">
    * Verify Over Property matches metadata key exactly
    * Use numbers, not strings: `tokens: 150` not `"150"`
    * Include required properties in all events
  </Accordion>

  <Accordion title="Filters not working">
    * Match case exactly
    * Use correct operators for data type
    * Ensure events include filtered properties
  </Accordion>

  <Accordion title="Wrong usage totals">
    * Check Events tab to count actual events received
    * Verify aggregation type (Count vs Sum)
    * Ensure values are numeric for Sum/Max
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Send Events" icon="bolt" href="/features/usage-based-billing/event-ingestion">
    Start sending usage events from your application to your meters.
  </Card>

  <Card title="View Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Use ready-made meter configurations for common use cases.
  </Card>
</CardGroup>


# Welcome to Dodo Payments
Source: https://docs.dodopayments.com/introduction

The complete payments & billing platform for SaaS, AI, and digital products. Accept payments globally, set up flexible billing models, and monetize your product in minutes - all without building your own infrastructure.

<Frame>
  <img alt="Dodo Payments - Complete payments and billing platform for modern digital products" />
</Frame>

## What is Dodo Payments?

Dodo Payments is the **all-in-one engine** to launch, scale, and monetize worldwide. Designed for the new generation of digital SaaS and AI products, we handle everything from **payments to billing to distribution** - all without extra engineering.

<Info>
  **Built for SaaS and AI Products**: Handle one-time payments, subscriptions, credits, seats, tokens, or any usage metric with our optimized billing infrastructure.
</Info>

<Tip>
  <strong>Meet Sentra: Your AI-powered billing assistant</strong><br />
  Sentra is an AI agent that integrates, analyzes, and acts on billing and payments directly in your IDE. Ask questions, build integrations, or plan billing architectures - all by describing what you want.

  <a href="/developer-resources/sentra">
    Get started with Sentra →
  </a>
</Tip>

### Why Choose Dodo Payments?

<CardGroup>
  <Card title="All-in-One Platform" icon="box">
    One solution for payments, billing, and distribution—no more piecing tools together
  </Card>

  <Card title="Global Merchant of Record" icon="globe">
    Go global without complexity: built-in coverage in 190+ countries, 80+ currencies, and 30+ payment methods
  </Card>

  <Card title="Developer-First & No-Code" icon="code">
    Seamless APIs and SDKs for fast integration, plus <a href="/developer-resources/sentra">Sentra AI agent</a> to build integrations by just describing what you need
  </Card>

  <Card title="Faster Monetization" icon="bolt">
    Start collecting revenue in minutes, not weeks
  </Card>

  <Card title="Flexible Billing Models" icon="repeat">
    Usage-based, credit-based, subscriptions with addons, or one-time payments are built in
  </Card>

  <Card title="Optimized for AI Products" icon="brain" href="/features/credit-based-billing">
    Handle credits, seats, tokens, or any usage metric with credit-based billing
  </Card>
</CardGroup>

## Quick Start Guide

Get up and running with Dodo Payments in just a few steps.

<AccordionGroup>
  <Accordion title="For Humans">
    Prefer to drive the integration yourself? The steps below walk you through creating an account, adding a product, and picking an integration method in under five minutes. No code required for the no-code path; SDK samples are waiting in every major language if you want them.

    If you'd rather let your AI coding assistant do the heavy lifting - integration scaffolding, webhook handlers, subscription flows - install **[Sentra](/developer-resources/sentra)**, our AI billing assistant for VS Code, Cursor, and Windsurf. Describe what you want; Sentra plans, scaffolds, and ships it.
  </Accordion>

  <Accordion title="For AI Agents">
    Dodo Payments is built for agent-native workflows. If you're an LLM reading this - or a developer configuring one - start here.

    **Install**. For Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro, or OpenCode, the [Dodo Agent Plugin](/developer-resources/build-with-ai-coding-agents) wires both MCP servers and all skills in one step. Gemini CLI gets the MCP servers only. See the [AI Coding Agents guide](/developer-resources/build-with-ai-coding-agents) for per-agent install commands.

    **Discover**. The full docs index is served at [`docs.dodopayments.com/llms.txt`](https://docs.dodopayments.com/llms.txt), and every documentation page is available in plain markdown by appending `.md` to its URL (e.g. `/api-reference/introduction.md`).

    **Connect**. Two MCP servers give agents live access to the platform:

    * **[Dodo Knowledge MCP](/developer-resources/mcp-server#dodo-knowledge-mcp)** - semantic search across all Dodo documentation
    * **[Dodo Payments MCP](/developer-resources/mcp-server)** - execute API operations (create payments, manage subscriptions, issue refunds)

    See the [MCP Server guide](/developer-resources/mcp-server) for the full client configuration.

    **Extend**. Install official [Dodo Payments Skills](/developer-resources/agent-skills) to teach your agent how to handle checkout, subscriptions, usage-based billing, credit-based billing, webhooks, and more:

    ```bash theme={null}
    npx skills add dodopayments/skills
    ```

    Works with Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro, OpenCode, and any agent supporting the skills protocol.
  </Accordion>
</AccordionGroup>

<Steps>
  <Step title="Create Your Account">
    Sign up at [app.dodopayments.com](https://app.dodopayments.com/signup) using your email.

    <Check>
      You'll receive a confirmation email to verify your account.
    </Check>
  </Step>

  <Step title="Add Your First Product">
    Choose your billing model and add your product to start accepting payments.

    <CardGroup>
      <Card title="One-Time Payment" icon="box" href="/features/one-time-payment-products">
        Perfect for digital downloads, courses, or single purchases
      </Card>

      <Card title="Subscription Product" icon="repeat" href="/features/subscription">
        Ideal for SaaS, memberships, or recurring services
      </Card>

      <Card title="Usage-Based Billing" icon="chart-bar" href="/features/usage-based-billing/introduction">
        Bill customers for API calls, credits, tokens, or any usage metric - ideal for AI and SaaS
      </Card>

      <Card title="Credit-Based Billing" icon="coins" href="/features/credit-based-billing">
        Issue credits (API calls, tokens, compute units) and deduct as customers consume - with rollover and overage controls
      </Card>
    </CardGroup>
  </Step>

  <Step title="Choose Your Integration Method">
    Select the integration approach that best fits your needs and technical requirements.

    <Tabs>
      <Tab title="No-Code (Fastest)">
        **Perfect for getting started quickly:**

        * Create **Payment Links** from your dashboard
        * Share via email, social media, or embed in websites
        * Start accepting payments immediately
      </Tab>

      <Tab title="Overlay Checkout">
        **Best for seamless, on-brand payments:**

        * Launch checkout as an overlay on your site or app
        * Keep users on your page for a frictionless experience
        * Customize appearance to match your brand

        <Card title="Overlay Integration" icon="layer-group" href="/developer-resources/overlay-checkout">
          Add our overlay checkout with a single line of code
        </Card>
      </Tab>

      <Tab title="Inline Checkout">
        **Best for fully integrated, embedded checkout experiences:**

        * Embed checkout directly into your page layout
        * Build custom order summaries that sync with checkout
        * Maximum control over checkout design and flow

        <Card title="Inline Integration" icon="credit-card" href="/developer-resources/inline-checkout">
          Embed checkout directly into your website
        </Card>
      </Tab>

      <Tab title="Full SDK Integration">
        **Best for advanced, fully customized solutions:**

        * Use our TypeScript/Python/Go/PHP/Java/Kotlin/C#/Ruby/Rust SDK for seamless integration
        * Programmatic access to all payment, subscription, and customer portal APIs
        * Deep integration with your backend, workflows, and data models
        * Full support for webhooks, advanced features, and automation

        <Tip>
          <strong>Skip the manual work with Sentra</strong><br />
          Install our AI agent in VS Code, Cursor, or Windsurf. Describe what you want - SDK integration, webhook handlers, subscription flows - and Sentra generates the code for you.

          <a href="/developer-resources/sentra">
            Install Sentra →
          </a>
        </Tip>

        <Card title="SDK Quickstart" icon="code" href="/developer-resources/integration-guide">
          Learn how to install and use our official SDK
        </Card>

        <Card title="API Reference" icon="server" href="/api-reference/introduction">
          Explore the full API and SDK documentation
        </Card>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Developer Integration

<Frame>
  <iframe title="Developer Integration Tutorial" />
</Frame>

<Card title="Sentra: AI-Powered Integration Assistant" icon="wand-magic-sparkles" href="/developer-resources/sentra">
  **Build billing integrations by describing what you need.** Sentra is an AI agent for VS Code, Cursor, and Windsurf that generates SDK code, webhook handlers, subscription flows, and more. Use **Ask** mode to learn, **Build** mode to implement, or **Plan** mode to architect your billing system.
</Card>

### Build with AI Coding Agents

Connect your AI coding assistant directly to Dodo Payments. The Agent Plugin is a one-command setup for Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro, and OpenCode. Other MCP-compatible agents such as Windsurf, Claude Desktop, Cline, and Zed connect through the MCP servers manually.

<CardGroup>
  <Card title="Agent Plugin" icon="robot" href="/developer-resources/build-with-ai-coding-agents">
    One install bundles both MCP servers and all seventeen skills for Claude Code, Codex CLI, Cursor, VS Code, Kiro, and OpenCode
  </Card>

  <Card title="Dodo Knowledge MCP" icon="book-open" href="/developer-resources/mcp-server#dodo-knowledge-mcp">
    Semantic search across Dodo Payments documentation - get instant answers about features, APIs, and best practices
  </Card>

  <Card title="Dodo Payments MCP" icon="credit-card" href="/developer-resources/mcp-server">
    Execute API operations directly - create payments, manage subscriptions, and handle refunds through your AI assistant
  </Card>
</CardGroup>

<Accordion title="Quick MCP Setup for Cursor/Claude Desktop">
  Add both servers to your MCP configuration (`~/.cursor/mcp.json` or Claude Desktop config):

  ```json theme={null}
  {
    "mcpServers": {
      "dodo-knowledge": {
        "command": "npx",
        "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
      },
      "dodopayments": {
        "command": "npx",
        "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
      }
    }
  }
  ```

  <Info>
    Requires Node.js 18+. See the [MCP Server documentation](/developer-resources/mcp-server) for detailed setup instructions for all supported clients.
  </Info>
</Accordion>

### Agent Skills

Enhance your AI coding assistant with official Dodo Payments skills - reusable capabilities that teach agents how to implement payment integrations, webhook handlers, and billing flows correctly.

<Card title="Dodo Payments Skills" icon="wand-magic-sparkles" href="/developer-resources/agent-skills">
  Install skills for checkout integration, subscriptions, usage-based billing, credit-based billing, webhooks, and more. Works with Claude Code, OpenCode, Cursor, and any MCP-compatible agent.
</Card>

<Accordion title="Quick Skills Installation">
  ```bash theme={null}
  # Install all Dodo Payments skills
  npx skills add dodopayments/skills

  # Or install individual skills
  npx skills add dodopayments/skills/dodo-payments/dodo-best-practices
  npx skills add dodopayments/skills/dodo-payments/webhook-integration
  npx skills add dodopayments/skills/dodo-payments/subscription-integration
  npx skills add dodopayments/skills/dodo-payments/credit-based-billing
  ```

  <Info>
    See the [Agent Skills documentation](/developer-resources/agent-skills) for Claude Code, OpenCode, and other client setup instructions.
  </Info>
</Accordion>

### Framework Adapters

Integrate in under 10 lines of code with our framework adapters. Choose from our recommended frameworks or explore all supported options.

#### Recommended Frameworks

<CardGroup>
  <Card title="Next.js" icon="atom" href="/developer-resources/nextjs-adaptor">
    React-based full-stack framework with App Router support
  </Card>

  <Card title="Better Auth" icon="shield" href="/developer-resources/better-auth-adaptor">
    Authentication framework with built-in integrations
  </Card>

  <Card title="Supabase" icon="database" href="/developer-resources/supabase-boilerplate">
    Open source Firebase alternative with Postgres and Auth
  </Card>

  <Card title="Convex" icon="database" href="/developer-resources/convex-component">
    Backend-as-a-Service with real-time capabilities
  </Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="Show other 8+ supported frameworks">
    <CardGroup>
      <Card title="SvelteKit" icon="js" href="/developer-resources/sveltekit-adaptor" />

      <Card title="Nuxt" icon="vuejs" href="/developer-resources/nuxt-adaptor" />

      <Card title="Remix" icon="react" href="/developer-resources/remix-adaptor" />

      <Card title="Express" icon="js" href="/developer-resources/express-adaptor" />

      <Card title="Fastify" icon="bolt" href="/developer-resources/fastify-adaptor" />

      <Card title="Hono" icon="cloud" href="/developer-resources/hono-adaptor" />

      <Card title="Astro" icon="star" href="/developer-resources/astro-adaptor" />

      <Card title="TanStack" icon="chart-line" href="/developer-resources/tanstack-adaptor" />
    </CardGroup>
  </Accordion>
</AccordionGroup>

### Powerful SDKs

Speed up development with our official SDKs. Choose from our recommended languages or explore all supported options.

<CardGroup>
  <Card title="TypeScript" icon="code-simple" href="/developer-resources/dodo-payments-sdks#typescript" />

  <Card title="Python" icon="python" href="/developer-resources/dodo-payments-sdks#python" />

  <Card title="Go" icon="golang" href="/developer-resources/dodo-payments-sdks#go" />

  <Card title="PHP" icon="php" href="/developer-resources/dodo-payments-sdks#php" />

  <Card title="Java" icon="java" href="/developer-resources/dodo-payments-sdks#java" />

  <Card title="Kotlin" icon="android" href="/developer-resources/dodo-payments-sdks#kotlin" />

  <Card title="C#" icon="hashtag" href="/developer-resources/dodo-payments-sdks#c%23" />

  <Card title="Ruby" icon="gem" href="/developer-resources/dodo-payments-sdks#ruby" />

  <Card title="Rust" icon="rust" href="/developer-resources/dodo-payments-sdks#rust" />
</CardGroup>

### Dodo CLI

Drive Dodo Payments from your terminal. The Dodo CLI ships with an interactive TUI, a built-in AI assistant, and offline webhook testing — install it in one line:

```bash theme={null}
curl -fsSL https://dodopayments.com/install.sh | sh
```

<Card title="Dodo CLI" icon="terminal" href="/developer-resources/sdks/cli">
  Manage payments, customers, and webhooks from your terminal — with a TUI, AI assistant, and real-time webhook listener built in.
</Card>

### Billing SDK

Stop reinventing the wheel. Use production-ready, accessible billing components, from pricing cards to subscription dashboards, built for React and ShadCN.

<Card title="Billing Components" icon="credit-card" href="https://billingsdk.com">
  Beautiful, customizable billing components, pricing tables, subscription management, and usage meters - save development time with production-ready UI for billing and payments.
</Card>

<Info>
  **Open Source & Free**: BillingSDK is completely free to use and modify for personal and commercial projects. Built by the Dodo Payments team for developers.
</Info>

### In-App Purchases for Android and iOS

Build rich in-app payment experiences with our lightweight payment links and secure React Native SDKs optimized for iOS and Android.

<CardGroup>
  <Card title="Mobile Integration Guide" icon="book" href="/developer-resources/mobile-integration">
    Complete guide for integrating payments in mobile applications
  </Card>

  <Card title="Expo Boilerplate" icon="box-open" href="/developer-resources/expo-boilerplate">
    Jumpstart your React Native in-app payments with our open source Expo template
  </Card>
</CardGroup>

## External Integrations

Connect Dodo Payments with your favorite tools and platforms to automate workflows, send notifications, and enhance your payment operations.

<Info>
  **Automate Everything**: Set up real-time notifications, trigger workflows, sync customer data, and more with our growing library of integrations.
</Info>

### Popular Integrations

Quickly connect Dodo Payments to the most used design and productivity tools to streamline your workflow and automate payment operations.

<CardGroup>
  <Card title="Framer Plugin" icon="frame" href="/integrations/framer-plugin">
    Add payments to Framer websites
  </Card>

  <Card title="WooCommerce" icon="wordpress" href="/integrations/woocommerce-plugin">
    Accept payments on WooCommerce stores
  </Card>

  <Card title="Raycast Extension" icon="rocket" href="/integrations/raycast-extension">
    Manage payments from Raycast
  </Card>

  <Card title="Figma Plugin" icon="figma" href="/integrations/figma-plugin">
    Access Dodo Payments in Figma
  </Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="Communication & Notifications">
    Stay informed about payment events with real-time notifications in your team communication tools.

    <CardGroup>
      <Card title="Slack" icon="slack" href="/integrations/slack">
        Send payment notifications and alerts to Slack channels
      </Card>

      <Card title="Discord" icon="discord" href="/integrations/discord">
        Get instant payment updates in your Discord server
      </Card>

      <Card title="Microsoft Teams" icon="microsoft" href="/integrations/microsoft-teams">
        Receive payment notifications directly in Teams channels
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Email Marketing & Customer Communication">
    Sync customer data and trigger email campaigns based on payment events.

    <CardGroup>
      <Card title="Resend" icon="envelope" href="/integrations/resend">
        Send transactional emails with Resend
      </Card>

      <Card title="SendGrid" icon="paper-plane" href="/integrations/sendgrid">
        Automate email campaigns with SendGrid
      </Card>

      <Card title="Loops" icon="repeat" href="/integrations/loops">
        Trigger email sequences with Loops
      </Card>

      <Card title="Customer.io" icon="users" href="/integrations/customer-io">
        Sync customer data to Customer.io
      </Card>

      <Card title="AutoSend" icon="paper-plane" href="/integrations/autosend">
        Send automated transactional emails with AutoSend
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="CRM & Sales">
    Connect your payment data with CRM platforms to streamline sales and customer management.

    <CardGroup>
      <Card title="HubSpot" icon="hubspot" href="/integrations/hubspot">
        Sync customers and deals with HubSpot CRM
      </Card>

      <Card title="Close CRM" icon="briefcase" href="/integrations/close-crm">
        Automate sales workflows with Close CRM
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Automation & Workflows">
    Build powerful automations and data pipelines with workflow automation platforms.

    <CardGroup>
      <Card title="Zapier" icon="bolt" href="/integrations/zapier">
        Connect to 5,000+ apps with Zapier
      </Card>

      <Card title="N8N" icon="diagram-project" href="/integrations/n8n">
        Automate workflows with self-hosted or cloud N8N
      </Card>

      <Card title="Windmill" icon="wind" href="/integrations/windmill">
        Build custom workflows with Windmill
      </Card>

      <Card title="Inngest" icon="code" href="/integrations/inngest">
        Create event-driven workflows with Inngest
      </Card>

      <Card title="Segment" icon="chart-network" href="/integrations/segment">
        Stream payment data to Segment CDP
      </Card>

      <Card title="DataFast" icon="chart-bar" href="/integrations/datafast">
        Attribute revenue to marketing channels with DataFast analytics
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

<Card title="View All Integrations" icon="puzzle-piece" href="/integrations/introduction">
  Explore our complete library of integrations with detailed setup guides
</Card>

## Need Help?

<CardGroup>
  <Card title="Developer Documentation" icon="book" href="/developer-resources/integration-guide">
    Explore comprehensive guides and API references
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Full OpenAPI reference, endpoints, parameters, and example requests for all Dodo Payments APIs
  </Card>

  <Card title="Community Support" icon="users" href="https://discord.gg/bYqAp4ayYh">
    Join our Discord community for help and discussions
  </Card>

  <Card title="Contact Support" icon="headphones" href="mailto:support@dodopayments.com">
    Get direct help from our support team
  </Card>
</CardGroup>


# Migrate to Dodo Payments
Source: https://docs.dodopayments.com/migrate-to-dodo

Easily migrate your data from other payment providers to Dodo Payments using our CLI tool

**Switching from another payment provider to Dodo Payments?** Our migration tool makes it easy to move your **products, customers, discount codes, and license keys without losing any data.** The process is safe, guided, and can be done in just a few minutes.

We currently support migrations from **Lemon Squeezy, Stripe, Polar.sh, and Paddle**.

### Supported Migrations

<CardGroup>
  <Card title="Products & Pricing" icon="box">
    Migrate all your products and pricing details.
  </Card>

  <Card title="Customer Data" icon="users">
    Transfer your complete customer database, including contact details.
  </Card>

  <Card title="Discount Codes & Promotions" icon="tag">
    Move all discount codes and promotional offers seamlessly.
  </Card>

  <Card title="License Keys" icon="key">
    Import license keys with customer and product mappings. Supported for Polar.sh and Lemon Squeezy.
  </Card>
</CardGroup>

## Get Started

First, install the migration tool:

```bash theme={null}
npm install -g dodo-migrate
```

<Note>
  You'll need Node.js ≥ 18 installed on your computer.
</Note>

## Migrate Your Data

### If you're coming from Lemon Squeezy:

```bash theme={null}
dodo-migrate lemonsqueezy
```

### If you're coming from Stripe:

```bash theme={null}
dodo-migrate stripe
```

### If you're coming from Polar.sh:

```bash theme={null}
dodo-migrate polar
```

### If you're coming from Paddle:

```bash theme={null}
dodo-migrate paddle
```

The tool will walk you through everything step by step. You'll need:

* Your provider's API key (Lemon Squeezy, Stripe, Polar.sh, Paddle, etc.)
* Your Dodo Payments API key
* Whether you want to test first (recommended) or go live
* Which Dodo Payments brand to migrate to
* What data to migrate (products, customers, discounts, license keys)

## Why Use Our Migration Tool?

* **No data loss** - Everything transfers safely
* **Test first** - Try it in test mode before going live
* **Guided process** - We walk you through each step
* **Resume if needed** - If something goes wrong, you can pick up where you left off

## Advanced Usage

If you prefer to run the migration without prompts, you can provide all the details upfront:

### Lemon Squeezy migration:

```bash theme={null}
dodo-migrate lemonsqueezy \
  --provider-api-key=lsq_XXXXXXXXXXXXXXXX \
  --dodo-api-key=dp_XXXXXXXXXXXXXXXX \
  --mode=test_mode \
  --dodo-brand-id=brand_XXXXXX
```

### Stripe migration:

```bash theme={null}
dodo-migrate stripe \
  --provider-api-key=sk_test_XXXXXXXXXXXXXXXX \
  --dodo-api-key=dp_XXXXXXXXXXXXXXXX \
  --mode=test_mode \
  --dodo-brand-id=brand_XXXXXX \
  --migrate-types=products,coupons
```

### Polar.sh migration:

```bash theme={null}
dodo-migrate polar \
  --provider-api-key=polar_org_XXXXXXXXXXXXXXXX \
  --dodo-api-key=dp_XXXXXXXXXXXXXXXX \
  --mode=test_mode \
  --dodo-brand-id=brand_XXXXXX \
  --migrate-types=products,discounts,customers,license_keys
```

### Paddle migration:

```bash theme={null}
dodo-migrate paddle \
  --provider-api-key=paddle_XXXXXXXXXXXXXXXX \
  --dodo-api-key=dp_XXXXXXXXXXXXXXXX \
  --mode=test_mode \
  --dodo-brand-id=brand_XXXXXX
```

## License Key Migration

License key migration is supported for **Polar.sh** and **Lemon Squeezy**. When you select license keys in the interactive prompt (or pass `license_keys` in `--migrate-types`), the tool will import your existing license keys into Dodo Payments with the correct customer and product associations.

<Warning>
  License key migration requires **products and customers** to be migrated in the same session. The tool builds an in-memory mapping of provider IDs to Dodo IDs during the run — if products or customers are missing, license keys cannot be linked correctly.
</Warning>

### What gets migrated

* License key strings
* Activation limits
* Expiration dates
* Customer and product associations

### What doesn't migrate

* **License key activations** — customers will need to re-activate on their devices after migration
* **Revoked or disabled keys** — only active keys are migrated
* Keys without a matching product or customer are skipped with a warning

<Tip>
  Duplicate license keys are handled gracefully. If you re-run the migration, already-imported keys are detected and skipped, making the process safe to retry.
</Tip>

## Need Help?

* **Tool help**: `dodo-migrate --help`
* **Lemon Squeezy help**: `dodo-migrate lemonsqueezy --help`
* **Stripe help**: `dodo-migrate stripe --help`
* **Polar.sh help**: `dodo-migrate polar --help`
* **Paddle help**: `dodo-migrate paddle --help`
* **Community support**: [Discord](https://discord.gg/bYqAp4ayYh)
* **Report issues**: [GitHub](https://github.com/dodopayments/dodo-migrate)

## Update the Tool

```bash theme={null}
# Update to latest version
npm update -g dodo-migrate

# Remove the tool
npm uninstall -g dodo-migrate
```


# My Account
Source: https://docs.dodopayments.com/miscellaneous/accounts

Manage your personal account information, change your login email, and add multiple businesses to your Dodo Payments account.

## Business Profile

<Steps>
  <Step title="Access your Business Profile">
    Go to **Settings → Business**.
  </Step>

  <Step title="Edit and save business details">
    Update the business details, such as the business logo and Brand display name (used on invoices), then click **Save Changes**.
  </Step>
</Steps>

## User Account

<Steps>
  <Step title="Access your User Profile">
    Click the icon in the top right, then select **Profile**.
  </Step>

  <Step title="Edit and save personal details">
    Update your personal information (Contact Name, Profile Image, phone number) for a personalized experience, then click **Save Changes**.
  </Step>
</Steps>

## Change Your Login Email

You can change the email address you use to sign in to your Dodo Payments account. This change applies across all your businesses and requires verification of both your current and new email addresses.

<Steps>
  <Step title="Open your profile menu">
    Click the icon in the top right corner of the dashboard.
  </Step>

  <Step title="Go to Profile">
    Select **Profile** from the menu.
  </Step>

  <Step title="Open the Account tab">
    Click the **Account** tab.
  </Step>

  <Step title="Start the email change">
    Click **Change email**.
  </Step>

  <Step title="Verify your current email">
    Enter the one-time code sent to your current email address to confirm it's you.
  </Step>

  <Step title="Enter your new email">
    Type the new email address you want to use for sign-in.
  </Step>

  <Step title="Verify your new email">
    Enter the one-time code sent to your new email address to confirm you control it.
  </Step>
</Steps>

<Warning>
  After you change your login email, your old email address can no longer be used to sign in (whether by password, magic link, or emailed code). Any linked social sign-in methods, such as Google or GitHub, will be unlinked and must be reconnected if you want to use them again.
</Warning>

<Note>
  Your password, businesses, team access, and verification status remain unchanged. A confirmation email will be sent to your previous email address so you're notified of the change.
</Note>

## Managing Multiple Businesses

Merchants with more than one business can easily add and verify additional businesses through their Dodo Payments account.

**Workflow: Add a New Business**

<Steps>
  <Step title="Go to the Home page">
    Navigate to the **Home** page.
  </Step>

  <Step title="Open the Add New menu">
    In the top-left corner, next to your current business name, click the **+** icon.
  </Step>

  <Step title="Select Add New">
    An **Add New** pop-up will appear. Click **Add New**.
  </Step>

  <Step title="Open the Add New Business/Brand panel">
    A panel titled **Add New Business/Brand** will open on the right side of the screen. Click **Add New Business**.
  </Step>

  <Step title="Complete the business creation process">
    Follow the on-screen prompts to complete the business creation process.
  </Step>
</Steps>


# Account Verification
Source: https://docs.dodopayments.com/miscellaneous/verification-process

Complete account verification to activate payments and payouts. Learn about required forms, identity verification, business verification, compliance requirements, and ongoing monitoring.

At Dodo Payments, businesses can start using live mode immediately after sign-up. **Live mode is available from day 1.**

To receive live payments and activate payouts, you must complete **Account Verification**. This process includes:

1. Choosing your **Account Type** (Individual or Registered Entity)
2. Completing **Product & Payout Details**
3. Compliance team review of your submitted information

Once approved, your account will be enabled for live payments and payouts. This ensures compliance with regulatory guidelines, card-network rules, tax requirements, and our Merchant Acceptance Policy.

<Info>
  For the most up-to-date and comprehensive details on supported and prohibited product categories, as well as restricted and accepted business locations, please refer to our [Merchant Acceptance Policy](/miscellaneous/merchant-acceptance).
</Info>

## Account Verification

The Verification section is available in your dashboard.

### When Do You Need to Complete Verification?

Complete the verification process after sign-up to receive access to live payments and enable payouts as soon as possible.

### Choosing Your Account Type

Before starting verification, you must select whether you are an **Individual** or a **Registered Entity**.

| Individual                                               | Registered Entity                                     |
| -------------------------------------------------------- | ----------------------------------------------------- |
| You're a creator or sole proprietor                      | Your business is registered (Pvt Ltd, LLP, LLC, etc.) |
| Payments and payouts are tied to you personally          | You have a GST, EIN, or other business tax ID         |
| You don't have a company registration or business tax ID | Payouts are tied to your company bank account         |

<Frame>
  <img alt="Verification Dashboard" />
</Frame>

### Steps to Activate Payouts

<Steps>
  <Step title="Access the Verification section">
    Visit the **Verification** section in your dashboard.
  </Step>

  <Step title="Choose your Account Type">
    **Let's start with the basics.** Tell us how you operate so we can tailor verification for you. Choose the option that best matches your setup today — **Individual** or **Registered Entity**.
  </Step>

  <Step title="Submit Product Information Form">
    Complete and submit the **Product Information Form**. This short form helps us understand your business. Check that your website is ready first — see [Preparing Your Website](#preparing-your-website).
  </Step>

  <Step title="Complete Payout Details">
    Submit all required payout detail forms **sequentially** to complete the verification process. Forms are unlocked one at a time — you must complete and submit each form before the next one becomes available.
  </Step>
</Steps>

<Info>
  Complete verification to activate live payments and payouts. Most reviews finish within 72 hours.
</Info>

<Warning>
  Until verification is complete:

  * Live payments will not be available for your account.
  * Payouts will not be available for your account.
</Warning>

### Required Forms by Account Type

The forms you need to complete depend on your account type. Forms must be completed **in the order shown below** — each form unlocks only after the previous one is submitted.

| Account Type          | Required Forms (in order)                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------- |
| **Individual**        | Product Information Form → Identity Verification (KYC) → Bank Verification                               |
| **Registered Entity** | Product Information Form → Identity Verification (KYC) → Business Verification (KYB) → Bank Verification |

<Info>
  If you are a **UK registered entity**, you must also submit a [Tax Form W-8BEN-E](#5-additional-compliance) as part of the verification process.
</Info>

### Changing Your Account Type

You can change your account type (Individual ↔ Registered Entity) as long as all submitted forms are still **under review** (submitted status). Once any form's status changes to approved, failed, or on hold, your account type selection becomes permanent.

<Warning>
  **Important: If you change your account type after submitting the bank form:**

  * Your bank verification will be put on hold
  * You will need to resubmit your bank details
  * If switching from Individual to Registered Entity, you will also need to complete the Business Verification form
  * Your Product Information and Identity Verification will be preserved.
</Warning>

### 1. Product Information Form

Before collecting payout details, all merchants must complete a **Product Information Form**. This form helps us understand your business and ensure compliance with our [Merchant Acceptance Policy](/miscellaneous/merchant-acceptance).

<Info>
  This form is **required for both individuals and registered entities**.
</Info>

#### Save as Draft

Not ready to submit? You can save your progress using the **Save as Draft** button. Your form data will be saved and you can return to complete it later. This feature is available for Product Information, Bank Verification, and Business Verification forms.

### Information Required

The Product Information Form collects the following details:

* **Product website or landing page**

  The URL where customers learn about or purchase your product

* **Product description**

  A brief, one-sentence explanation of what your product does

* **Product category**

  Select from options such as SaaS, digital content, services, marketplace, or physical goods

* **Delivery method**

  How customers receive the product after payment (e.g., instant access, email delivery, subscriptions, manual fulfillment)

* **Level of automation**

  Whether product delivery is fully automated, partially automated, or human-driven

* **Compliance-sensitive areas**

  Disclosure of any regulated, restricted, or higher-risk product types (if applicable)

* **Dodo Payments integration method**

  How you plan to collect payments (e.g., payment links, checkout sessions, APIs, SDKs)

* **Product stage and customer acquisition**

  Information about your product's maturity and go-to-market approach

* **Social media presence**

  Links to your product or founder social media profiles

* **Confirmation and declaration**

  Acknowledgement that the information provided is accurate and policy-compliant

<Note>
  This information is used **only for compliance review** and does not impact your ability to integrate, test, or accept live payments.
</Note>

### Preparing Your Website

Your Product Information Form is reviewed against your live website, so publish your site before you submit. A product URL that the review team cannot open is one of the most common reasons a form is placed on hold — for example, a link that lands on a login screen, a closed waitlist, or a domain that is not live yet.

Before you submit, check that a visitor with no account can reach your site and find each of the following:

* **Pricing** — what you charge, including the billing interval for any recurring plan
* **Terms of Service** — the agreement your customers accept when they buy
* **Privacy Policy** — how you collect, store, and use customer data
* **Refund and Cancellation Policy** — how a customer requests a refund or cancels a subscription
* **Contact route** — a monitored support address or contact form your customers can use

Link these from a consistent place, such as your site footer, so they are reachable from every page.

<Tip>
  If you have not written these policies yet, you can generate a first draft with the [Policy Generator](https://dodopayments.com/tools/policy-generator) and then adapt it to your business.
</Tip>

<Warning>
  The details on your live site must match what you enter in the Product Information Form, including your product description, pricing, and delivery method. A mismatch between the two is a common cause of a form being placed on hold.
</Warning>

### 2. Identity Verification

We use **Persona**, a leading global verification provider following industry standard security measure and following global data privacy guidelines.

KYC ensures the authenticity of individual businesses through:

* **Government-issued ID verification** (passport, national ID, driver's license etc)
* **Selfie check** to confirm liveness and match with ID

Persona's AI-driven process completes verification within minutes while maintaining bank-grade security standards.

<Warning>
  The ID you verify with must be issued by a country on our [accepted countries list](/miscellaneous/accepted-countries-and-territories). This applies to you as an individual, and to every director and beneficial owner of a registered entity — regardless of where the entity itself is incorporated.
</Warning>

<Tip>
  For more information about Persona's security measures, visit [withpersona.com/security](https://withpersona.com/security).
</Tip>

<Note>
  **Camera Access Issues:** If you encounter a "Can't access your camera" error during identity verification, you'll need to enable camera permissions for your device and browser. The steps vary by browser and device:

  * **Chrome:** Enable camera permissions through your browser settings (Desktop, iPhone & iPad, or Android)
  * **Safari:** For desktop, enable through Safari preferences. For mobile devices, go to Settings → Safari → Camera and set permission to "Ask" or "Allow"
  * **iOS Apps:** Go to Settings → Apps → \[Your App] → Allow Camera permissions. Also ensure Lockdown Mode is not blocking the app
  * **Android Apps:** Go to Settings → Apps → \[Your App] → Allow Camera permissions

  For detailed, step-by-step troubleshooting instructions for your specific browser and device, refer to [Persona's camera access guide](https://help.withpersona.com/articles/3V9VoOoGLp6zRCwthpzpx4/).
</Note>

#### If Identity Verification Fails

Identity Verification can fail even when your documents are genuine, usually because the capture itself did not give Persona enough to work with.

Common causes:

* **The photo on your ID no longer resembles you.** An ID issued years ago may not match your current appearance closely enough for the selfie check.
* **The document was captured from a screen or a photocopy.** Use the original physical document.
* **The capture is blurry, cropped, or has glare.** Every edge of the document should be visible and all text readable.
* **The document has expired.**
* **The ID was issued by a country that is not supported.** Check the [accepted countries list](/miscellaneous/accepted-countries-and-territories).

<Warning>
  Identity Verification does not reopen on its own after a failed attempt. Your dashboard may show that resubmissions are temporarily paused, with a prompt to contact support.
</Warning>

To retry, email [support@dodopayments.com](mailto:support@dodopayments.com) from the email address your Dodo Payments account is registered under and ask for the Identity Verification form to be re-enabled. Our team will reopen the form on your dashboard so you can submit again.

<Tip>
  Before you retry, have a valid, unexpired, physical government-issued photo ID ready, and complete the check in a well-lit place with your camera permissions already granted. This is the same submission — a clear photo of the ID plus a selfie — so getting the capture right the first time avoids another round trip.
</Tip>

### 3. Business Verification (Registered Entity Only)

<Info>
  Business Verification is **required only for registered entities**. If you have an individual account, you can skip this section.
</Info>

For registered entities, verification ensures the legitimacy of the company and its authorised representatives.

For Registered Entity accounts, Business Verification must be completed before Bank Verification.

#### Required Details

<AccordionGroup>
  <Accordion title="Company Registration Number">
    Provide your **Company Registration Number** and supporting document (Certificate of Incorporation or similar as per your jurisdiction).
  </Accordion>

  <Accordion title="Tax ID (Optional)">
    If you want your tax number reflected on payout invoices for claiming tax benefits, please provide a valid Tax ID and documents.

    Examples of tax identifiers across regions: EIN, CRN, VAT ID, GSTIN
  </Accordion>

  <Accordion title="Director / UBO Information">
    Provide details about all Director's or UBO's of the company in the verification form.

    **Beneficial Owner(s)**

    The beneficial owner is any natural person who, whether acting alone or together, or through other companies, LLPs, or legal persons, owns or is entitled to 10% or more of the shares or capital or profits of the connected user, or who exercises control over the connected user through other means, including enjoying the right to appoint the majority of its directors or to control its management or policy decisions through shareholding or management rights or through shareholders agreements or voting agreements. If the connected user has more than 1 beneficial owner, please provide us with the requisite documents for all.

    **Business Director(s)**

    Individuals appointed and currently serving as directors on the board of directors for the connected user in accordance with your local laws. Please provide us with the government issued ID's of all Directors.
  </Accordion>
</AccordionGroup>

### 4. Bank Verification

The Bank Form collects your **bank account details** and **contact information**.

<Warning>
  * Bank account details must **match** the verified identity or registered entity name.
  * For individuals, the account holder's name should match the Identity Verification document.
  * For registered entities, it should match the company's legal name as per Business Verification.
  * Dodo Payments cannot process payouts to mismatched or third-party accounts.
</Warning>

### 5. Additional Compliance

<Info>
  <strong>W-8BEN-E:</strong> Only required for <strong>UK registered entities</strong>. Ensure you fill out this form if your company is based in the United Kingdom.
</Info>

Registered entities from the United Kingdom need to fill a **W-8BEN-E** form to comply with international tax reporting regulations. This ensures smooth payout processing and tax documentation accuracy.

<CardGroup>
  <Card title="Download W-8BEN-E Form" icon="download" href="https://www.irs.gov/pub/irs-pdf/fw8bene.pdf">
    Download the official IRS W-8BEN-E form (PDF) required for UK registered entities.<br />

    <small>
      <strong>Tip:</strong> Complete the form digitally before printing and signing for best results.
    </small>
  </Card>
</CardGroup>

#### What is Form W-8 BEN-E?

W-8 BEN-E forms are Internal Revenue Service (IRS) forms that foreign businesses must file to verify their country of residence for tax purposes, certifying that they qualify for a lower rate of tax withholding.

#### How to Fill Out Form W-8 BEN-E

<AccordionGroup>
  <Accordion title="Part I – Identification of Beneficial Owner">
    **1. Name of Organization That is the Beneficial Owner**

    This is your entity name.

    **2. Country of Incorporation or Organization**

    This is the country of residence (where the business is registered). For a corporation, it is the country of incorporation. If you are another type of entity, enter the country under whose laws you are created, organized, or governed.

    **3. Chapter 3 Status**

    In this section, the most commonly checked box is "Corporation". The majority of foreign entities that are doing business fall under "Corporation" or "Partnership" status. Other options include:

    * Foreign government – Controlled Entity
    * Foreign government – Integral Part
    * Estate
    * Simple trust (grantor and complex, too)
    * Central Bank of Issue
    * Tax-exempt organization
    * Private foundation
    * International organization
    * Disregarded entity

    For Private Limited company - check the Corporation box
    For Limited Liability Partnership - check the Partnership box

    **4. Chapter 4 Status (FATCA Status)**

    For SaaS/Digital Products, the most common choice here is Active NFFE. This means the business is an Active Non-Financial Foreign Entity. If none of the other categories fit, Active NFFE is the best option.

    **5. Permanent Residence Address**

    This is your business's permanent resident address. Your permanent residence address is the address in the country where you claim to be a resident for purposes of that country's income tax.

    **8-10. Tax Identification Information**

    You may provide the FTIN issued to you by your jurisdiction of tax residence on line 9b for purposes of claiming treaty benefits.
  </Accordion>

  <Accordion title="Part XXV – Active NFFE">
    In this part of the form, you simply need to check box 39 to certify that:

    * The entity in Part I is a foreign entity that is not a bank or financial institution.
    * Less than 50% of the gross income for the preceding calendar year is passive income.
    * Less than 50% of assets held are assets that produce or are held for the production of passive income (calculated as a weighted average of the % of quarterly passive assets).
  </Accordion>

  <Accordion title="Part XXX – Certification">
    The most important part of the document is the certification and signature. Here, in writing, there needs to be a first name, last name, and date (on which the form was signed). The person signing the W-8BEN-E form must be authorized to sign for the beneficial owner.
  </Accordion>
</AccordionGroup>

#### View Sample W-8 BEN-E Forms

<AccordionGroup>
  <Accordion title="Private Limited Company">
    <Note>
      **Sample Profile:**

      * Company: ABC Technologies PVT LTD
      * Type: SaaS / Digital Products
      * Country: India (example)
      * TIN: PAN or equivalent tax ID in your country
    </Note>

    **Page 1**

    <Frame>
      <img alt="W-8 BEN-E Private Limited Sample Page 1" />
    </Frame>

    **Page 2**

    <Frame>
      <img alt="W-8 BEN-E Private Limited Sample Page 2" />
    </Frame>

    **Page 8**

    <Frame>
      <img alt="W-8 BEN-E Private Limited Sample Page 8" />
    </Frame>
  </Accordion>

  <Accordion title="Limited Liability Partnership (LLP)">
    <Note>
      **Sample Profile:**

      * Company: ABC Technologies LLP
      * Type: SaaS / Digital Products
      * Country: India (example)
      * TIN: PAN or equivalent tax ID in your country
    </Note>

    **Page 1**

    <Frame>
      <img alt="W-8 BEN-E LLP Sample Page 1" />
    </Frame>

    **Page 2**

    <Frame>
      <img alt="W-8 BEN-E LLP Sample Page 2" />
    </Frame>

    **Page 8**

    <Frame>
      <img alt="W-8 BEN-E LLP Sample Page 8" />
    </Frame>
  </Accordion>
</AccordionGroup>

## Account Monitoring and Compliance Review

Once your Payout Details are reviewed and approved, our compliance team performs a manual **Monitoring Review** in accordance with our **[Review & Monitoring Policy](https://docs.dodopayments.com/miscellaneous/review-monitoring-policy)**. This is a standard compliance check for all merchants on Dodo Payments

### Why do we do this?

As a MoR platform, we handle payment processing, invoicing, taxes, and refunds on your behalf. To keep your business - and our entire merchant community protected, we follow  monitoring practices that check for:

* The type of products/services you’re selling and compliance with our [**Merchant Acceptance Policy**](https://docs.dodopayments.com/miscellaneous/merchant-acceptance).
* Card-network rules and AML regulations
* Potential fraud indicators or unusual activity patterns

### What does this mean for you?

💡 **If your business operates in line with our Merchant Acceptance Policy and general platform rules, you have nothing to worry about.**

This review is designed to ensure everything looks good before we enable payouts. Most merchants pass this step smoothly with no action required.

The process is quick, lightweight, and intended to safeguard *your* payouts and long-term account stability.

Once the review is complete and everything looks good, payouts will be enabled for your account

* You will be able to view your payout schedule, next payout date, payout threshold and eligible balance directly in the dashboard

<Frame>
  <img alt="Account Activated" />
</Frame>

### Live Payments Are Active but Payouts Are Inactive

Live payments and payouts are enabled by two different gates, so it is normal to be taking live payments while your dashboard still shows payouts as inactive.

Payouts additionally require:

* **Bank Verification approved** — and, for registered entities, Business Verification approved as well.
* **The Monitoring Review completed** — the compliance check described above runs after your payout details are approved.

If payouts are inactive, open the **Verification** section in your dashboard and check the status of each form. A form that is still in draft, under review, or on hold is the usual reason, and completing it is what moves your account forward.

<Info>
  Payouts being **active** is not the same as a payout being **sent**. Once payouts are enabled, a payout is initiated only when your eligible balance meets your payout threshold and your next payout date arrives. See [Payouts Process](/features/payouts/payout-structure) for cycles and thresholds.
</Info>

If every form is approved and payouts are still inactive after the review window above, contact [support@dodopayments.com](mailto:support@dodopayments.com) from your registered email address.

### Ongoing Monitoring

Dodo Payments also performs **ongoing monitoring periodically** so we can keep accounts compliant over time.

This is routine monitoring and if **your business remains compliant, you can continue operating without concern.** If we have any concern about your account during this check then necessary action will be taken in accordance with our [**Review & Monitoring Policy**](https://docs.dodopayments.com/miscellaneous/review-monitoring-policy)

## Additional Information Requests

As part of our **ongoing monitoring**, our compliance team may request additional information from time to time.

These requests can be completed directly from the dashboard and **do not block payments or payouts**, but failure to submit them may trigger pauses in payouts/payments processing, further compliance reviews or account restrictions.

<Tip>
  For more details, refer to our [Review Monitoring Policy](/miscellaneous/review-monitoring-policy).
</Tip>

## Timeline & Support

* Typical verification time: **1–3 business days (excludes weekends and public holidays)**
* If additional review is needed, you will be notified via email and dashboard.
* For help, reach out to [support@dodopayments.com](mailto:support@dodopayments.com)

## Resubmission of Documents

If there are issues with the documents submitted during the onboarding process, the Dodo Payments Verification Team may request that you resubmit specific documents.

You can resubmit documents using the **resubmit** option in your dashboard.

<Warning>
  Once you submit a form, you cannot edit it or submit it again on your own. The **Resubmit** option appears only after the Verification Team enables it for your account.
</Warning>

### If a Form Is Marked Failed

A **Failed** status is not the same as a resubmission request. When a form fails, resubmission is not reopened automatically, so there is usually no **Resubmit** option available to you.

For a failed form, the route forward is an **appeal** from the **Verification** section of your dashboard:

<Steps>
  <Step title="Read the failure reason">
    Open the **Verification** section in your dashboard to see why the form failed.
  </Step>

  <Step title="Fix the underlying issue first">
    Address what caused the failure before you appeal — for example, point your product URL at a public landing page rather than a login screen, or make sure your live website matches what you described in the form.
  </Step>

  <Step title="File your appeal">
    Submit the appeal from the **Verification** section with a detailed explanation. A one-line response is unlikely to change the outcome.
  </Step>
</Steps>

<Warning>
  You can appeal **only once**, and the appeal decision is final. Write your appeal carefully the first time. Appeals typically take more than **48 working hours** to review.
</Warning>

<Info>
  If your business could not be supported for reasons of location or product category, an appeal cannot change that outcome. Review [Countries Eligible for Merchant Acceptance](/miscellaneous/accepted-countries-and-territories) and the [Merchant Acceptance Policy](/miscellaneous/merchant-acceptance) to confirm your eligibility first.
</Info>

### When Can You Resubmit Documents?

* **Missing or Incomplete Information**: If essential details such as identification numbers, business name, or other key data are missing.
* **Document Mismatch**: When the documents submitted do not match the business or personal information provided.
* **Unreadable or Expired Documents**: If the uploaded documents are unclear, illegible, or have expired.
* **Additional Clarification Needed**: If the verification team requires further documentation to clarify your identity or business information.

### How to Resubmit Documents

<Steps>
  <Step title="Check your dashboard">
    Check your Dodo Payments Dashboard for a resubmission request (you will also receive an email notification if resubmission is required).
  </Step>

  <Step title="Access the resubmit option">
    The verification team will enable the **Resubmit** option, allowing you to upload new documents.
  </Step>

  <Step title="Upload correct documents">
    Navigate to the **Verification Section** in the dashboard and upload the correct documents.
  </Step>

  <Step title="Submit for review">
    Submit the documents for review by clicking **Submit for Review**.
  </Step>
</Steps>

<CardGroup>
  <Card title="Merchant Acceptance Policy" icon="shield-check" href="/miscellaneous/merchant-acceptance">
    Review our comprehensive acceptance standards, including supported and prohibited products, and ensure your business is eligible for onboarding.
  </Card>

  <Card title="Review Monitoring Policy" icon="magnifying-glass" href="/miscellaneous/review-monitoring-policy">
    Understand how ongoing compliance is monitored, learn about triggers for document review, and stay proactive with your account status.
  </Card>
</CardGroup>


# Create Checkout Session
Source: https://docs.dodopayments.com/api-reference/checkout-sessions/create

post /checkouts
Unified endpoint for creating checkout sessions for all types of billing requirements.



# Get Checkout Session
Source: https://docs.dodopayments.com/api-reference/checkout-sessions/get-checkouts

get /checkouts/{id}
Retrieve the status of a specific checkout session by its ID, including the resulting payment ID and payment status.



# Preview Checkout Session
Source: https://docs.dodopayments.com/api-reference/checkout-sessions/preview

post /checkouts/preview
Preview a checkout session to calculate pricing, taxes, and totals without creating an actual session.



# Create Discount
Source: https://docs.dodopayments.com/api-reference/discounts/create-discount

post /discounts
Create a discount for your account.



# Get Discount by Code
Source: https://docs.dodopayments.com/api-reference/discounts/get-discount-by-code

get /discounts/code/{code}
Validate and retrieve a discount by its code name (e.g., 'SAVE20') instead of using the internal discount ID.



# List Discounts
Source: https://docs.dodopayments.com/api-reference/discounts/list-discounts

get /discounts
Retrieve a list of all discounts associated with your account.



# Get Discount
Source: https://docs.dodopayments.com/api-reference/discounts/validate-discount

get /discounts/{discount_id}
Retrieve a discount by its unique discount_id.



# Error Codes
Source: https://docs.dodopayments.com/api-reference/error-codes

Reference for Dodo Payments API and business-logic error codes, grouped by category, with triggers, messages, and how to resolve them.

## Overview

Dodo Payments API uses standard HTTP status codes and custom error codes to indicate the success or failure of API requests. When an error occurs, the API returns an appropriate HTTP status code and a JSON response containing detailed information about the error.

Each error response includes:

* An HTTP status code indicating the general category of the error
* A specific error code that identifies the exact nature of the error
* A human-readable error message explaining what went wrong
* Additional details about the error when applicable

Understanding these error codes and their meanings is crucial for:

* Debugging integration issues
* Implementing proper error handling in your application
* Providing meaningful feedback to end users
* Maintaining a robust payment processing system

<Note>
  These are **API and business-logic** errors. For **card decline reasons** returned on a failed payment (such as `INSUFFICIENT_FUNDS` or `CARD_DECLINED`), see the [Transaction Failures](/api-reference/transaction-failures) reference instead.
</Note>

## Standard API Error Codes

| HTTP Status | Name                  | Description                                                          |
| ----------- | --------------------- | -------------------------------------------------------------------- |
| **400**     | Bad Request           | The request was malformed or contained invalid parameters            |
| **401**     | Unauthorized          | Authentication failed or API key is invalid                          |
| **403**     | Forbidden             | The API key doesn't have permission to access the requested resource |
| **404**     | Not Found             | The requested resource doesn't exist                                 |
| **409**     | Conflict              | The request conflicts with the current state of the resource         |
| **410**     | Gone                  | The resource has already been deleted or archived                    |
| **413**     | Payload Too Large     | The request body or uploaded file exceeds the maximum allowed size   |
| **422**     | Unprocessable Entity  | The request was well-formed but contained semantic errors            |
| **429**     | Too Many Requests     | Rate limit exceeded                                                  |
| **500**     | Internal Server Error | An unexpected error occurred on our servers                          |

## Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

```json theme={null}
{
  "code": "UNSUPPORTED_COUNTRY",
  "message": "Country AI currently not supported"
}
```

## Error Codes Reference

The error codes below are grouped by the area of the API they relate to. Each entry lists the condition that triggers it and the message the API returns.

### Authentication & Account

* `UNAUTHORIZED`
  * **Trigger:** No API key or invalid token / scope
  * **Message:** You are not authorised to perform this action

* `MERCHANT_NOT_LIVE`
  * **Trigger:** Business still in Test Mode
  * **Message:** Merchant is not live

### Payments & Checkout

* `CHECKOUT_SESSION_CONSUMED`
  * **Trigger:** Checkout session has already generated a payment
  * **Message:** Checkout session has already been consumed

* `NO_ELIGIBLE_PAYMENT_METHODS`
  * **Trigger:** After filtering, nothing left
  * **Message:** No eligible payment methods found

* `PAYMENT_NOT_SUCCEEDED`
  * **Trigger:** Attempt to refund/process unsuccessful payment
  * **Message:** The provided payment has not succeeded

* `PREVIOUS_PAYMENT_PENDING`
  * **Trigger:** Attempt to create charge while previous is in non-terminal state
  * **Message:** Cannot create new charge as previous payment is not successful yet

* `UNSUCCESSFUL_PAYMENT_ID`
  * **Trigger:** Payment ID references unsuccessful payment
  * **Message:** The Payment ID has an unsuccessful status.

### Connectors & BYOP

These errors relate to merchant-owned payment connectors (Bring Your Own Processor).

* `BYOP_CONNECTOR_DISABLED`
  * **Trigger:** Updating a payment method on a subscription routed through a disabled BYOP connector
  * **Message:** The subscription is routed through the merchant's own (BYOP) connector which is currently disabled

* `BYOP_CUSTOM_INVOICE_ADDRESS_MISSING`
  * **Trigger:** A merchant-routed (BYOP) payment is missing the required custom invoice address
  * **Message:** BYOP custom invoice address is required when a payment is routed through the merchant's connector

* `CONNECTOR_LABEL_ALREADY_EXISTS`
  * **Trigger:** Creating a connector with a label that already exists
  * **Message:** A connector with this label already exists. Please choose a different label.

### Refunds

* `EXISTING_REFUND_REQUEST_PROCESSING`
  * **Trigger:** Previous refund request still being processed
  * **Message:** A refund request with status "Pending" is still being processed

* `LINE_ITEM_FULLY_REFUNDED`
  * **Trigger:** Attempt to refund already fully refunded line item
  * **Message:** Line item  has been fully refunded cannot be refunded further.

* `LINE_ITEM_NOT_FOUND`
  * **Trigger:** Item ID not part of the referenced payment
  * **Message:** Line item  not found in payment

* `LINE_ITEM_PRORATED`
  * **Trigger:** Refund or update attempted on a prorated line
  * **Message:** Line item  cannot be refunded because its prorated

* `LINE_ITEM_REFUND_AMOUNT_TOO_HIGH`
  * **Trigger:** Refund amount > paid amount (tax incl.)
  * **Message:** Line item  requested refund amount including tax is  which is above the paid amount&#x20;

* `LINE_ITEM_REFUND_AMOUNT_TOO_LOW`
  * **Trigger:** Refund amount below minimum threshold
  * **Message:** Line item  requested refund amount is  which is too low

* `NOTHING_TO_REFUND`
  * **Trigger:** No refundable amount remains; all positive line items already fully refunded
  * **Message:** No refundable amount remaining. All positive line items have been fully refunded.

* `PARTIAL_REFUND_NOT_ALLOWED`
  * **Trigger:** Partial refund attempted on a payment method that only supports full refunds
  * **Message:** Partial refunds are not allowed for this payment method

* `PAYMENT_ALREADY_REFUNDED`
  * **Trigger:** Duplicate refund
  * **Message:** This payment has already been refunded

* `PAYMENT_HAS_BEEN_REFUNDED`
  * **Trigger:** Payment has been fully refunded
  * **Message:** The Payment ID has been fully refunded.

* `REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT`
  * **Trigger:** Aggregate refund amount > paid amount
  * **Message:** The calculated refund amount is larger than the paid amount

* `REFUND_WINDOW_EXPIRED`
  * **Trigger:** Outside allowable refund window
  * **Message:** Refunds cannot be initiated  days after payment creation. Contact [support@dodopayments.com](mailto:support@dodopayments.com).

* `ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED`
  * **Trigger:** Attempt to refund zero-amount payment
  * **Message:** Cannot refund a payment with zero currency amount

### Subscriptions & Add-ons

* `ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED`
  * **Trigger:** Attempt to add addons to usage-based billing subscriptions
  * **Message:** Addons in Subscriptions are not supported for Usage Based Billing

* `ADDONS_NOT_ALLOWED_FOR_ON_DEMAND`
  * **Trigger:** Attempt to add addons to on-demand subscriptions
  * **Message:** Addons are not allowed for on demand subscriptions

* `CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED`
  * **Trigger:** Customer Portal attempts to cancel a scheduled plan change while the business has disabled that action
  * **Message:** Cancelling scheduled plan change is disabled for customer portal.

* `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION`
  * **Trigger:** Attempt to charge subscription scheduled for cancellation
  * **Message:** Subscription scheduled for cancellation

* `CUSTOMER_HAS_EXISTING_SUBSCRIPTION`
  * **Trigger:** Creating a subscription for a customer who already has one, when multiple subscriptions per customer are not allowed
  * **Message:** Customer  has an existing subscription. To allow multiple subscriptions per customer, change business settings

* `DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL`
  * **Trigger:** `do_not_bill` proration mode used in a Customer Portal plan change
  * **Message:** do\_not\_bill proration mode is not allowed in the customer portal

* `DUPLICATE_ADDON_IDS_IN_REQUEST`
  * **Trigger:** Same `addon_id` appears more than once in the request
  * **Message:** Duplicate addon IDs are not allowed

* `INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED`
  * **Trigger:** Plan change on inactive subscription
  * **Message:** Changing plans is not supported for inactive subscriptions

* `INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE`
  * **Trigger:** A proration mode other than `full_immediately` used with `effective_at: next_billing_date`
  * **Message:** Only full\_immediately proration mode is allowed with effective\_at: next\_billing\_date

* `MISSING_ADDON_IDS`
  * **Trigger:** `addon_id` list empty or unknown IDs
  * **Message:** One or more product IDs do not exist:&#x20;

* `ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED`
  * **Trigger:** Plan swap not allowed for on-demand
  * **Message:** Changing plans is not supported for on demand subscriptions

* `ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED`
  * **Trigger:** Attempt to use on-demand with usage-based billing
  * **Message:** On Demand Subscriptions are not supported for Usage Based Billing

* `ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND`
  * **Trigger:** One-time product added to an on-demand subscription
  * **Message:** One-time products are not allowed for on demand subscriptions

* `PENDING_PLAN_CHANGE_EXISTS`
  * **Trigger:** New plan change requested while a previous one is still awaiting payment
  * **Message:** A pending plan change already exists for this subscription. Please wait for the current payment to complete.

* `PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED`
  * **Trigger:** Plan change via Customer Portal while the business has disabled it
  * **Message:** Subscription plan change for customer portal is disabled.

* `PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION`
  * **Trigger:** Plan change attempted on subscription scheduled for cancellation
  * **Message:** Subscription scheduled for cancellation

* `SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED`
  * **Trigger:** Scheduling a plan change via Customer Portal while the business has disabled it
  * **Message:** Scheduling plan changes is disabled for this business.

* `SCHEDULED_PLAN_CHANGE_EXISTS`
  * **Trigger:** Creating a scheduled plan change when one already exists
  * **Message:** A scheduled plan change already exists for this subscription. Please cancel the existing scheduled change before creating a new one.

* `SCHEDULED_PLAN_CHANGE_NOT_FOUND`
  * **Trigger:** Referencing or cancelling a scheduled plan change that does not exist
  * **Message:** No scheduled plan change found for this subscription.

* `SUBSCRIPTION_EXPIRED`
  * **Trigger:** Billing past `ends_at`
  * **Message:** Subscription expired cannot create new charges

* `SUBSCRIPTION_INACTIVE`
  * **Trigger:** Status ≠ `ACTIVE`
  * **Message:** Subscription is not active

* `SUBSCRIPTION_NOT_ON_DEMAND`
  * **Trigger:** Expected on-demand but got fixed interval
  * **Message:** Subscription is already not on demand

* `SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED`
  * **Trigger:** Subscription payment retries exceeded maximum attempts
  * **Message:** Maximum retry limit of 10 attempts exceeded for this subscription

### Products, Cart & Brands

* `BRAND_MISMATCH`
  * **Trigger:** Cart items belong to different brands
  * **Message:** All items in the product cart should belong to the same brand

* `BRAND_NOT_ENABLED`
  * **Trigger:** Brand is disabled or not active
  * **Message:** Brand provided is not enabled

* `BRAND_SUBMISSION_NOT_ENABLED`
  * **Trigger:** Brand verification resubmission feature not enabled
  * **Message:** Brand verificatin resubmission is not enabled

* `FILE_IN_USE`
  * **Trigger:** Deleting a digital product file still referenced by active entitlement grants
  * **Message:** Digital file is referenced by active grants

* `INVALID_SUGGESTED_PRICE`
  * **Trigger:** PWYW price \< minimum allowed price
  * **Message:** Suggested Price cannot be lower than minimum price. In case of pay what you want, price is considered as minimum accepted amount

* `LOCALIZED_PRICE_ALREADY_EXISTS`
  * **Trigger:** A localized price already exists for this product and country/currency
  * **Message:** A localized price for this product and country/currency already exists

* `LOCALIZED_PRICE_DUPLICATES_BASE`
  * **Trigger:** Localized price duplicates the product's base currency/country
  * **Message:** Localized price duplicates the product's base currency/country

* `LOCALIZED_PRICE_SHAPE_MISMATCH`
  * **Trigger:** Localized price shape does not match the product's `pricing_mode`
  * **Message:** Localized price shape does not match the product's pricing\_mode

* `MISSING_PRODUCT_INFORMATION`
  * **Trigger:** Product exists but mandatory info missing
  * **Message:** Product  exists but other mandatory information is missing or invalid

* `PAY_AS_YOU_WANT_AMOUNT_REQUIRED`
  * **Trigger:** Price missing for PWYW product
  * **Message:** Amount is mandatory for pay as you want product

* `PRODUCT_CART_EMTPY`
  * **Trigger:** Empty product cart submitted
  * **Message:** product\_cart is empty (the error code is intentionally spelled `EMTPY` to match the exact value the API returns)

* `PRODUCT_COLLECTION_IS_DELETED`
  * **Trigger:** Operating on a product collection that has been deleted
  * **Message:** *No message*

* `PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS`
  * **Trigger:** Removing the last product (or last group with products) from a collection
  * **Message:** Cannot delete the last product in a collection. Archive the collection instead.

* `PRODUCT_IS_DELETED`
  * **Trigger:** Product soft-deleted
  * **Message:** *No messages*

* `PRODUCT_PRICING_MODE_REQUIRED`
  * **Trigger:** Adding localized prices before the product's `pricing_mode` is set
  * **Message:** Product pricing\_mode must be set before adding localized prices

* `SLUG_ALREADY_TAKEN`
  * **Trigger:** The requested product slug / short URL is already in use
  * **Message:** Slug is already taken

* `UNABLE_TO_EDIT_PRIMARY_BRAND`
  * **Trigger:** Attempt to update primary brand via regular API
  * **Message:** Primary brand cannot be updated via this API endpoint.

### Discounts

* `DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION`
  * **Trigger:** Re-applying a discount that has already been used on this subscription
  * **Message:** This discount has already been used on this subscription

* `DISCOUNT_CODE_ALREADY_EXISTS`
  * **Trigger:** Duplicate discount code creation
  * **Message:** Discount Code already exists

* `DISCOUNT_CODE_EXPIRED`
  * **Trigger:** Discount code past its `expires_at` date
  * **Message:** Discount code expired

* `DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED`
  * **Trigger:** Discount reused after `usage_limit` reached
  * **Message:** Usage limit cannot be less than times\_used / Discount code hit usage limit
  * **Note:** Terminal — the code is exhausted. Do not retry.

* `DISCOUNT_CONCURRENT_REDEMPTION`
  * **Trigger:** Another redemption of the same code held the usage-limit row lock too long
  * **Message:** Discount is being redeemed concurrently; please retry
  * **Note:** Transient. The code may still have capacity, so the request is safe to retry. Do not surface this to the customer as "code exhausted".

* `DISCOUNT_CURRENCY_OPTION_INVALID`
  * **Trigger:** Invalid `currency_options` on create or update
  * **Message:** A flat discount requires at least one currency option with a resolvable default / Duplicate currency options are not allowed / Only one currency option may be marked as default

* `DISCOUNT_CUSTOMER_NOT_ELIGIBLE`
  * **Trigger:** Customer does not satisfy the code's `customer_eligibility` (`first_time`, `existing`, or not on a `specific` code's allow list)
  * **Message:** Customer is not eligible for this discount code

* `DISCOUNT_MINIMUM_SUBTOTAL_NOT_MET`
  * **Trigger:** Cart subtotal is below the `minimum_subtotal` configured for the checkout currency
  * **Message:** Cart subtotal is below the discount's minimum required subtotal

* `DISCOUNT_NOT_YET_ACTIVE`
  * **Trigger:** Code used before its `starts_at` date
  * **Message:** Discount code is not yet active (starts\_at is in the future)

* `DISCOUNT_PER_CUSTOMER_USAGE_LIMIT_EXCEEDED`
  * **Trigger:** Customer has already redeemed the code `per_customer_usage_limit` times
  * **Message:** Per-customer usage limit exceeded for this discount code

* `DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT`
  * **Trigger:** Plan change to a product the existing discount does not apply to
  * **Message:** Discount not applicable to the new plan's product

* `DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND`
  * **Trigger:** Code applied to on-demand subscription
  * **Message:** Discount coupon not available for on demand subscriptions

* `DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT`
  * **Trigger:** Code applied to unrelated product(s)
  * **Message:** Discount coupon not available for this product

* `INVALID_DISCOUNT_CODE`
  * **Trigger:** Code does not exist / not applicable
  * **Message:** Invalid Discount Code / Discount Code cannot be applied to any product in the cart

* `INVALID_PERCENTAGE`
  * **Trigger:** Percent amount > 100% (or 10,000 basis points)
  * **Message:** Percentage amount cannot be more than 10000 / Discount code amount cannot be more than 100%

* `UNSUPPORTED_DISCOUNT_TYPE`
  * **Trigger:** A discount type that is not supported. `percentage` and `flat` are both supported; per-unit amount discounts are not.
  * **Message:** Only percentage and flat discount codes are supported

### License Keys

* `ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT`
  * **Trigger:** License-key activations: new limit \< existing instance count
  * **Message:** New activation limit cannot be less than current instances count

* `INACTIVE_LICENSE_KEY`
  * **Trigger:** Key status ≠ `ACTIVE`
  * **Message:** License key is not active

* `LICENSE_KEY_LIMIT_REACHED`
  * **Trigger:** Activations = limit
  * **Message:** License key activation limit reached

* `LICENSE_KEY_NOT_FOUND`
  * **Trigger:** Instance ID or key ID invalid
  * **Message:** License key instance not found or does not belong to this license key

* `NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS`
  * **Trigger:** Attempt to set expiry on sub-based key
  * **Message:** Cannot set expiry date for subscription-based license key

### Usage-Based Billing & Meters

* `DUPLICATE_METER_IDS_IN_REQUEST`
  * **Trigger:** Same meter ID appears multiple times in request
  * **Message:** Duplicate Meter Ids are not allowed

* `INVALID_QUANTITY`
  * **Trigger:** Invalid quantity specified for usage-based pricing
  * **Message:** Only 1 quantity allowed in usage based price products

* `METER_IS_DELETED`
  * **Trigger:** Attempt to use deleted meter
  * **Message:** The Meter is already been deleted

* `MISSING_METER_IDS`
  * **Trigger:** Meter ID list empty or contains invalid IDs
  * **Message:** One or more meter IDs do not exist:&#x20;

### Credit-Based Billing

* `CREDIT_ENTITLEMENT_IS_DELETED`
  * **Trigger:** Operating on a credit entitlement that has been deleted
  * **Message:** The credit entitlement has already been deleted

* `CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS`
  * **Trigger:** Creating a credit entitlement with a name that already exists
  * **Message:** A credit entitlement with this name already exists

* `OVERAGE_LIMIT_EXCEEDED`
  * **Trigger:** A usage or credit deduction would exceed the configured overage limit
  * **Message:** Overage limit exceeded

### Wallet

* `INSUFFICIENT_WALLET_FUNDS`
  * **Trigger:** Wallet balance \< debit amount
  * **Message:** Insufficient funds in wallet

* `NEGATIVE_BALANCE_ADJUSTMENT`
  * **Trigger:** Attempt to make wallet balance negative
  * **Message:** Wallet balance is not allowed to be made negative

### Currency, Tax & Region

* `EXCHANGE_RATE_NOT_FOUND`
  * **Trigger:** No FX rate for `from → to` currency pair
  * **Message:** Exchange rate not found to convert from Currency to Currency

* `INVALID_TAX_ID`
  * **Trigger:** VAT/GST/TIN failed validation
  * **Message:** Tax Id is invalid

* `REQUEST_AMOUNT_BELOW_MINIMUM`
  * **Trigger:** Amount \< product minimum
  * **Message:** Amount cannot be less than minimum amount specified for the product

* `TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT`
  * **Trigger:** Combined cart total \< gateway minimum
  * **Message:** Minimum amount of  is required to process payment

* `UNSUPPORTED_BILLING_CURRENCY`
  * **Trigger:** The requested billing currency is not supported for this subscription
  * **Message:** Non USD billing currency is not supported for subscriptions

* `UNSUPPORTED_COUNTRY`
  * **Trigger:** Geo not yet supported
  * **Message:** Country  currently not supported

* `UNSUPPORTED_CURRENCY`
  * **Trigger:** Product or addon currency is not a currency Dodo Payments can charge in. Base prices can be set in any chargeable currency, so this usually means the currency code is invalid or not yet supported.
  * **Message:** Currency is not currently supported / Only USD and INR products supported currently / Only USD and INR supported for addon price / Can only request USD or INR for billing\_currency / Currency Not Supported / Unexpected currency for Indian card subscriptions

* `UNSUPPORTED_TAX_CATEGORY`
  * **Trigger:** Tax category string not in enum
  * **Message:** Category  currently not supported

### Validation & Requests

* `DUPLICATE_LINE_ITEMS_IN_REQUEST`
  * **Trigger:** Same `item_id` appears twice in `items[]`
  * **Message:** Duplicate item\_ids specified in items array

* `INVALID_QUERY_PARAMS`
  * **Trigger:** Mutually exclusive / malformed query parameters
  * **Message:** Query params should only contain either time\_frame or (start, end)

* `INVALID_REQUEST_BODY`
  * **Trigger:** Malformed JSON or schema violation
  * **Message:** Your request body is invalid. Please check your request headers and object.

* `INVALID_REQUEST_PARAMETERS`
  * **Trigger:** Semantics wrong (e.g. date in past)
  * **Message:** Cannot change next\_billing\_date to past time

* `MAXIMUM_KEYS_REACHED`
  * **Trigger:** Metadata / custom-fields exceeded 50 pairs
  * **Message:** Exceeds 50 key-value pairs

### General & System

* `INTEGER_CONVERSION_FAILURE`
  * **Trigger:** Any integer ↔ string/decimal conversion that fails server-side
  * **Message:** Integer Conversion Failure

* `INTERNAL_SERVER_ERROR`
  * **Trigger:** Uncaught exceptions; you should log details server-side
  * **Message:** *No public message (generic 500)*

* `NOT_FOUND`
  * **Trigger:** Generic 404 for any missing resource
  * **Message:** Item not found *(or more specific)*

* `TOO_MANY_REQUESTS`
  * **Trigger:** 429 rate-limit
  * **Message:** *No messages*

* `UNSUPPORTED_ACTION`
  * **Trigger:** Unsupported action for resource type
  * **Message:** Changing plans for usage based subscriptions is not supported

## Best Practices

1. Always handle errors gracefully in your application
2. Implement proper error logging
3. Use appropriate error messages for end users
4. Implement retry logic for transient errors
5. Contact support for unresolved issues

## Support

For additional help with error codes or integration issues, please contact our support team at [support@dodopayments.com](mailto:support@dodopayments.com).


# Introduction
Source: https://docs.dodopayments.com/api-reference/introduction

The Dodo Payments API provides comprehensive endpoints for payment processing, subscription management, and digital product delivery. Our RESTful API follows industry standards with detailed responses for all operations.

<CardGroup>
  <Card title="SDKs & Libraries" icon="code" href="/developer-resources/dodo-payments-sdks">
    Official backend SDKs for <strong>TypeScript</strong>, <strong>Python</strong>, <strong>Go</strong>, <strong>PHP</strong>, <strong>Java</strong>, <strong>Kotlin</strong>, <strong>C#</strong>, <strong>Ruby</strong>, and <strong>Rust</strong>. These libraries simplify API requests, authentication, and error handling, letting you focus on building great payment experiences.
  </Card>

  <Card title="Mobile Checkout SDKs" icon="mobile" href="/developer-resources/mobile-integration">
    Building a native app? Open Dodo's hosted checkout and get a typed result back in one call, on <strong>Android</strong>, <strong>iOS</strong>, <strong>React Native</strong>, and <strong>Flutter</strong>. These hold no API key.
  </Card>
</CardGroup>

## Environment URLs

* **Test Mode**: [`https://test.dodopayments.com`](https://test.dodopayments.com)
* **Live Mode**: [`https://live.dodopayments.com`](https://live.dodopayments.com)

<Note>
  Learn more about [Test Mode vs Live Mode](/miscellaneous/test-mode-vs-live-mode).
</Note>

## API Key Management and Authentication

<Steps>
  <Step title="Access API Keys">
    Navigate to **Developer → API Keys** in your dashboard to manage your keys.
  </Step>

  <Step title="Generate a New Key">
    Select **Add API Key**, provide a descriptive name, and configure write access:

    * **Enable write access** (checked): Full read and write permissions for all API operations
    * **Enable write access** (unchecked): Read-only access - can only fetch data (payments, subscriptions, customers, products). Cannot create or modify resources.

    <Tip>
      Uncheck "Enable write access" for dashboard integrations, analytics tools, and any system that only needs to view data without making changes.
    </Tip>
  </Step>

  <Step title="Store Your Key Securely">
    Copy the generated key immediately and ensure it is stored securely.
  </Step>

  <Step title="Authenticate Your API Requests">
    Use your API keys to authenticate all requests. Apply the following authorization format:

    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    <Warning>
      Never expose your secret API keys in client-side code or public repositories.
    </Warning>
  </Step>
</Steps>

## Response Format

<CodeGroup>
  ```json Success Response theme={null}
  {
    "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
    "status": "succeeded",
    "total_amount": 2999,
    "currency": "USD",
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json Error Response theme={null}
  {
    "code": "INVALID_REQUEST",
    "message": "The request contains invalid parameters"
  }
  ```
</CodeGroup>

## Rate Limits

Our API uses a dual-window rate limiting system with burst protection. Limits are applied based on your authentication method and business tier.

### Default Limits (Tier 0)

| Window                 | Limit        |
| ---------------------- | ------------ |
| Per Second (Burst)     | 40 requests  |
| Per Minute (Sustained) | 240 requests |

### Business Tiers

Higher rate limits are available for businesses with increased API needs:

| Tier             | Burst (per second) | Sustained (per minute) |
| ---------------- | ------------------ | ---------------------- |
| Tier 0 (Default) | 40                 | 240                    |
| Tier 1           | 100                | 1,000                  |
| Tier 2           | 500                | 5,000                  |

<Tip>
  Contact support to upgrade your business to a higher rate limit tier.
</Tip>

### Unauthenticated Requests

Requests without valid authentication headers are rate limited by IP address:

| Window                 | Limit        |
| ---------------------- | ------------ |
| Per Second (Burst)     | 20 requests  |
| Per Minute (Sustained) | 100 requests |

### Rate Limit Headers

Monitor your usage with these response headers:

* `X-RateLimit-Limit` - Maximum requests allowed
* `X-RateLimit-Remaining` - Requests remaining in current window
* `X-RateLimit-Reset` - Time when the rate limit resets

<Note>
  When you exceed rate limits, the API returns a `429 Too Many Requests` response. Implement exponential backoff in your retry logic.
</Note>

## Error Handling

To effectively manage errors, consult the *Error Codes* and *Transaction Failures* sections for detailed guidance.

<CardGroup>
  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    Delve into comprehensive error details and their resolutions.
  </Card>

  <Card title="Transaction Failures" icon="circle-exclamation" href="/api-reference/transaction-failures">
    Gain insights into common transaction issues and their solutions.
  </Card>
</CardGroup>

## Webhooks

Receive real-time notifications about payment events. See our [Webhook Guide](/developer-resources/webhooks) for setup instructions.

<Card title="Webhook Guide" icon="webhook" href="/developer-resources/webhooks">
  Set up webhooks for real-time notifications and event handling.
</Card>

## Related Developer Guides

Explore our comprehensive guides to understand how to implement key features using the API:

<CardGroup>
  <Card title="One-time Payments Integration" icon="code-merge" href="/developer-resources/integration-guide">
    Learn how to integrate one-time payments, checkout sessions, and payment links into your application
  </Card>

  <Card title="Subscription Integration" icon="credit-card" href="/developer-resources/subscription-integration-guide">
    Complete guide to implementing subscriptions, managing plans, and handling subscription lifecycle events
  </Card>

  <Card title="Usage-Based Billing" icon="arrow-trend-up" href="/developer-resources/usage-based-billing-guide">
    Set up meters and usage events for metered billing and consumption-based pricing models
  </Card>

  <Card title="Webhooks" icon="box" href="/developer-resources/webhooks">
    Receive real-time notifications and automate workflows with webhook events
  </Card>

  <Card title="Checkout Sessions" icon="cart-shopping" href="/developer-resources/checkout-session">
    Create secure, hosted checkout experiences with full customization and advanced features
  </Card>
</CardGroup>


# Metadata Guide
Source: https://docs.dodopayments.com/api-reference/metadata

Learn how to use metadata to store additional information about your Dodo Payments objects

## Introduction

Metadata allows you to store additional, structured information about your objects in Dodo Payments. You can attach metadata to most Dodo Payments objects, including payments, subscriptions, and more.

## Overview

* Metadata keys can be up to 40 characters long
* Metadata values can be a string, integer, number, or boolean; strings can be up to 500 characters long
* Objects, arrays, and `null` are not accepted as metadata values
* You can have up to 50 metadata key-value pairs per object
* Keys should only contain alphanumeric characters, dashes, and underscores
* Metadata is not searchable using our API but is returned in API responses and webhooks

## Use Cases

Metadata is useful for:

* Storing external IDs or references
* Adding internal annotations
* Linking Dodo Payments objects to your system
* Categorizing transactions
* Adding custom attributes for reporting

## Adding Metadata

You can add metadata when creating or updating objects through the API. For products, you also have the option to add metadata directly from the dashboard UI.

### Via API

```javascript theme={null}
// 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'
    }
});
```

### Via Dashboard UI (Products Only)

For products, you can also add metadata directly from the Dodo Payments dashboard when creating or editing a product. The metadata section allows you to easily add custom key-value pairs without writing code.

<Frame>
  <img alt="Product metadata interface in Dodo Payments dashboard" />
</Frame>

<Tip>
  Using the dashboard UI for product metadata is particularly useful for non-technical team members who need to manage product information and categories.
</Tip>

## Retrieving Metadata

Metadata is included in API responses when retrieving objects:

```javascript theme={null}
// 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'
```

<Note>
  Retrieving a checkout session (`GET /checkouts/{id}`) does not return `metadata`. The session status response contains only `id`, `created_at`, `payment_id`, `payment_status`, `customer_email`, and `customer_name`. Read the metadata you attached at session creation from the resulting payment instead, using the `payment_id` returned by that endpoint.
</Note>

## Searching and Filtering

While metadata is not directly searchable via our API, you can:

1. Store important identifiers in metadata
2. Retrieve objects using their primary IDs
3. Filter the results in your application code

```javascript theme={null}
// 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;
  }
}
```

## Best Practices

### Do:

* Use consistent naming conventions for metadata keys
* Document your metadata schema internally
* Keep values short and meaningful
* Use metadata for static data only
* Consider using prefixes for different systems (e.g., `crm_id`, `inventory_sku`)

### Don't:

* Store sensitive data in metadata
* Use metadata for frequently changing values
* Rely on metadata for critical business logic
* Store duplicate information that's available elsewhere in the object
* Use special characters in metadata keys

## Supported Objects

Metadata is supported on the following objects:

| Object Type              | Support |
| ------------------------ | ------- |
| Payments                 | ✓       |
| Subscriptions            | ✓       |
| Subscription Change Plan | ✓       |
| Subscription Charges     | ✓       |
| Products                 | ✓       |
| Refunds                  | ✓       |
| Checkout Sessions        | ✓       |
| Customers                | ✓       |
| Discounts                | ✓       |
| Entitlements             | ✓       |
| Credit Ledger Entries    | ✓       |
| Usage Events             | ✓       |
| Webhooks                 | ✓       |

## Webhooks and Metadata

Metadata is included in webhook events, making it easy to handle notifications with your custom data:

```javascript theme={null}
// 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
  }
});
```


# Get Invoice
Source: https://docs.dodopayments.com/api-reference/payments/get-invoice

get /invoices/payments/{payment_id}
Get an invoice by Payment ID.



# List Payments
Source: https://docs.dodopayments.com/api-reference/payments/get-payments

get /payments
Get a list of all payments associated with your account.



# Get Payment Detail
Source: https://docs.dodopayments.com/api-reference/payments/get-payments-1

get /payments/{payment_id}
Get detailed information about a specific payment.



# Create One-Time Payment
Source: https://docs.dodopayments.com/api-reference/payments/post-payments

post /payments
Create a one-time payment for a customer.

<Warning>
  **Deprecated API**: This API will be deprecated soon. We recommend using [Checkout Sessions](/api-reference/checkout-sessions/create) instead, which provides a more powerful and customizable API to create payment links for one-time payments and subscriptions.
</Warning>


# Retrieve Line Items
Source: https://docs.dodopayments.com/api-reference/payments/retrieve-line-items

get /payments/{payment_id}/line-items
Retrieve line items for a specific payment.



# Cancel Scheduled Plan Change
Source: https://docs.dodopayments.com/api-reference/subscriptions/cancel-change-plan

delete /subscriptions/{subscription_id}/change-plan/scheduled
Cancel a scheduled plan change for a subscription.



# Change Plan
Source: https://docs.dodopayments.com/api-reference/subscriptions/change-plan

post /subscriptions/{subscription_id}/change-plan
Modify an existing subscription's plan, enabling both upgrades and downgrades to different pricing tiers.<br/><br/>Note&colon; This will use the existing payment information of the customer to upgrade/downgrade the plan.

## Scheduled Plan Changes

Use the `effective_at` parameter to control when the plan change takes effect:

| Value               | Behavior                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `immediately`       | Apply the plan change right away. This is the default.                                                                          |
| `next_billing_date` | Schedule the change for the next billing date. The customer retains access to their current plan until the billing period ends. |

<Info>
  Scheduled plan changes are ideal for downgrades — customers keep their current plan benefits until the end of the billing period, then automatically switch to the new plan.
</Info>

To cancel a scheduled plan change before it takes effect, use the [Cancel Scheduled Plan Change](/api-reference/subscriptions/cancel-change-plan) endpoint.

## Payment Failure Handling

Use the `on_payment_failure` parameter to control what happens when the plan change payment fails:

| Value            | Behavior                                                                               |
| ---------------- | -------------------------------------------------------------------------------------- |
| `prevent_change` | Keep subscription on current plan until payment succeeds. Plan change remains pending. |
| `apply_change`   | Apply plan change immediately regardless of payment outcome. This is the default.      |

<Info>
  If `on_payment_failure` is not specified, the behavior defaults to your business-level setting configured in the dashboard.
</Info>

## Discount Codes

You can apply one or more **stacked discount codes** when changing plans by passing the `discount_codes` array (max 20 entries, applied in array order). The singular `discount_code` field is deprecated but still works for existing integrations; it cannot be combined with `discount_codes` in the same request.

| `discount_codes` value          | Behavior                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Not provided (`null` / omitted) | Existing discounts with `preserve_on_plan_change=true` are preserved if applicable to the new product. |
| `[]` (empty array)              | **All** existing discounts are removed from the subscription.                                          |
| `["CODE_A", "CODE_B", ...]`     | Replaces any existing discounts with this stacked set, validated and applied in array order.           |

<Tip>
  Use discount codes during plan changes to offer promotional pricing on upgrades, or pass codes when migrating customers to a new plan tier.
</Tip>

<Tip>
  Use `prevent_change` for critical upgrades where you want to ensure payment before granting access to premium features.
</Tip>


# Create Charge (On-Demand)
Source: https://docs.dodopayments.com/api-reference/subscriptions/create-charge

post /subscriptions/{subscription_id}/charge
Create a charge for a subscription. This is useful for on-demand billing.



# Get Subscription Detail
Source: https://docs.dodopayments.com/api-reference/subscriptions/get-subscriptions

get /subscriptions/{subscription_id}
Get detailed information about a specific subscription.



# List Subscriptions
Source: https://docs.dodopayments.com/api-reference/subscriptions/get-subscriptions-1

get /subscriptions
Get a list of all subscriptions associated with your account.



# Get Subscription Usage History
Source: https://docs.dodopayments.com/api-reference/subscriptions/get-usage-history

get /subscriptions/{subscription_id}/usage-history
Retrieve the complete usage history for a subscription with usage-based billing.



# Update Subscription
Source: https://docs.dodopayments.com/api-reference/subscriptions/patch-subscriptions

patch /subscriptions/{subscription_id}
Update a subscription's details.



# Create Subscription
Source: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

post /subscriptions
Create a subscription for a customer.

<Warning>
  **Deprecated API**: This API will be deprecated soon. We recommend using [Checkout Sessions](/api-reference/checkout-sessions/create) instead, which provides a more powerful and customizable API to create payment links for one-time payments and subscriptions.
</Warning>


# Preview Plan Change
Source: https://docs.dodopayments.com/api-reference/subscriptions/preview-change-plan

post /subscriptions/{subscription_id}/change-plan/preview
Preview the effects of a subscription plan change before committing to it. Returns the immediate charge amount and the new subscription details without making any actual changes.

<Info>
  Use this endpoint to show customers exactly what they'll be charged when upgrading or downgrading their subscription, improving transparency and reducing support requests.
</Info>

## Use Cases

* **Checkout confirmation**: Display the prorated charge before customers confirm a plan change
* **Pricing calculators**: Build upgrade/downgrade calculators in your application
* **Customer self-service**: Let customers explore plan options with accurate pricing
* **Discount validation**: Preview how stacked discount codes affect the plan change pricing

<Info>
  You can include `discount_codes` (an array of up to 20 codes, applied in order) in the preview request to see how the stacked discounts affect the immediate charge and new plan pricing before committing to the change. The singular `discount_code` field is deprecated but still supported for backward compatibility; we recommend `discount_codes` going forward.
</Info>

## Response Fields

The preview response includes:

| Field              | Description                                                                    |
| ------------------ | ------------------------------------------------------------------------------ |
| `immediate_charge` | The charge that would be created immediately, including line items and summary |
| `new_plan`         | The full subscription object showing how it would look after the plan change   |

<Tip>
  The `immediate_charge.summary` contains the total amount that would be charged. Use this to display pricing to your customers before they confirm the plan change.
</Tip>


# Retrieve Credit Usage
Source: https://docs.dodopayments.com/api-reference/subscriptions/retrieve-credit-usage

get /subscriptions/{subscription_id}/credit-usage
Retrieve the credit usage for a subscription.



# Update Payment Method
Source: https://docs.dodopayments.com/api-reference/subscriptions/update-payment-method

post /subscriptions/{subscription_id}/update-payment-method
Update the payment method for an existing subscription. You can either add a new payment method or use an existing one from the customer's saved payment methods.

Update the payment method for a subscription. This endpoint supports both active subscriptions and subscriptions in `on_hold` state.

<Info>
  For subscriptions in `on_hold` state, updating the payment method automatically creates a charge for remaining dues, generates an invoice, and reactivates the subscription to `active` state upon successful payment.
</Info>

### Use Cases

* **Active subscriptions**: Update payment method when a card expires or customer wants to use a different payment method
* **On hold subscriptions**: Reactivate subscriptions that went on hold due to failed payments by updating the payment method
* **Payment method management**: Switch between saved payment methods or add new ones

<Info>
  To list existing payment methods for a customer, use the [List Payment Methods API](/api-reference/customers/get-customer-payment-methods). This helps you retrieve available payment method IDs when using `type: "existing"` to update a subscription's payment method.
</Info>

### Behavior for Active Subscriptions

When updating the payment method for an active subscription:

* The payment method is updated immediately
* No charge is created
* The subscription remains active
* Future renewals will use the new payment method

### Behavior for On Hold Subscriptions

When updating the payment method for a subscription in `on_hold` state:

1. A charge is automatically created for remaining dues
2. An invoice is generated for the charge
3. The payment is processed using the new payment method
4. Upon successful payment, the subscription is reactivated to `active` state
5. You'll receive webhook events: `payment.succeeded` followed by `subscription.active`

<Warning>
  If the payment fails after updating the payment method for an `on_hold` subscription, the subscription will remain in `on_hold` state. Monitor webhook events to track payment status.
</Warning>

### Webhook Events

When updating a payment method for an `on_hold` subscription, you'll receive the following webhook events:

1. **`payment.succeeded`** - The charge for remaining dues was successful
2. **`subscription.active`** - The subscription has been reactivated


# Transaction Failures
Source: https://docs.dodopayments.com/api-reference/transaction-failures

Understand every Dodo Payments transaction failure code, whether it is a soft or hard decline, and the recommended action to recover the payment.

## Overview

Dodo Payments returns a detailed failure reason whenever a payment attempt is unsuccessful. These reasons are standardized across payment methods and providers, so you can implement consistent handling in your application.

When a payment fails, the `payment.failed` webhook and the payment object expose:

* `error_code` — a standardized failure reason from the table below.
* `error_message` — a human-readable explanation written for **you**, the merchant. When `error_code` is one of the standardized codes below, this is a headline plus the recommended action rather than the raw text from the payment processor.
* `retry_attempt` — `0` for the original charge, `1` or higher for each scheduled subscription renewal retry.

Understanding these failure reasons lets you give customers clear feedback, decide whether a retry is worthwhile, and recover more revenue.

### Merchant Copy vs. Customer Copy

Every standardized failure code maps to two different messages, so the right audience sees the right level of detail:

| Audience          | Where it appears                                                                                                                             | What it says                                                                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **You**           | `error_message` on the payment, the dashboard payment details page, and the merchant payment-failed email                                    | The real reason plus a recommended action, for example *"The card hasn't been activated by the cardholder. Ask the customer to activate it with their bank, then retry."* |
| **Your customer** | The checkout failure screen, the [Customer Portal](/features/customer-portal), and [dunning](/features/recovery/subscription-dunning) emails | A short, plain-language explanation they can act on, for example *"Your card hasn't been activated yet. Please activate it with your bank and try again."*                |

<Note>
  The Customer Portal returns the customer-facing wording in `error_message`, while the merchant API returns the merchant wording for the same payment. The `error_code` is identical in both.
</Note>

<Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
  A step-by-step developer guide for reading these codes from webhooks and the API, surfacing them to customers, and deciding when to retry.
</Card>

## Soft vs. Hard Declines

Every failure code falls into one of two categories. This distinction drives whether you should retry the same payment method or ask the customer for a new one.

| Decline type     | What it means                                                                                                   | What to do                                                                                                | Examples                                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Soft decline** | Temporary or correctable — the same card can succeed on a later attempt or once the customer fixes their input. | Safe to retry (after a delay, or once the customer corrects their details).                               | `INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER` |
| **Hard decline** | Terminal — retrying the same card will not change the outcome.                                                  | Do **not** retry the same card. Ask the customer to use a different payment method or contact their bank. | `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`                                                   |

For subscription renewals, Dodo Payments applies this distinction automatically: soft declines are re-attempted by [Subscription Payment Retries](/features/recovery/payment-retries), while hard declines end the retry chain immediately and are best handled with [Subscription Dunning](/features/recovery/subscription-dunning).

<Warning>
  **Never reveal the real reason for `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, or `FRAUDULENT` to the customer.** Surfacing these can tip off a fraudulent actor. Always show the customer a generic decline message (for example, *"Your card was declined. Please contact your bank or use another card."*) and only log the specific code internally.

  Dodo Payments already enforces this on the surfaces it controls: for these four codes, checkout, the Customer Portal, and dunning emails always fall back to a generic decline message, while your own copy keeps the true reason. Apply the same rule anywhere you render `error_message` from the merchant API to a customer.
</Warning>

## Transaction Failure Reasons

The following table lists every failure code, its decline type, whether the customer can resolve it, a description, and the recommended action.

| Failure Code                       | Type | User Error | Description                                                                                                            | Recommended Action                                                                                                         |
| ---------------------------------- | ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `AUTHENTICATION_FAILURE`           | Soft | Yes        | Authentication failed during the transaction                                                                           | Ask the customer to retry and complete 3DS authentication, or use another card                                             |
| `AUTHENTICATION_REQUIRED`          | Soft | Yes        | Additional authentication is needed to complete the transaction                                                        | Prompt the customer to complete 3DS authentication. For subscription renewals, ask the customer to return and authenticate |
| `AUTHENTICATION_TIMEOUT`           | Soft | Yes        | The authentication process timed out                                                                                   | Ask the customer to retry and complete authentication promptly                                                             |
| `CARD_DECLINED`                    | Soft | No         | The card was declined by the issuing bank without a specific reason (generic decline)                                  | Ask the customer to retry, contact their bank, or use another card                                                         |
| `CARD_NOT_ACTIVATED`               | Soft | Yes        | The card has not been activated by the cardholder                                                                      | Ask the customer to activate the card with their bank, then retry                                                          |
| `CARD_VELOCITY_EXCEEDED`           | Soft | Yes        | Too many transactions attempted in a short period                                                                      | Ask the customer to wait and retry later, or contact their bank about limits                                               |
| `CUSTOMER_CANCELLED`               | Soft | Yes        | The customer cancelled the transaction                                                                                 | Let the customer restart checkout when they are ready                                                                      |
| `DO_NOT_HONOR`                     | Hard | No         | The issuing bank explicitly refused the transaction (ISO 8583 code 05 — do not honor); networks treat this as terminal | Ask the customer to contact their bank; do not retry the same card                                                         |
| `EXPIRED_CARD`                     | Hard | Yes        | The card has expired                                                                                                   | Ask the customer to use a card with a valid expiry date                                                                    |
| `FRAUDULENT`                       | Hard | Yes        | The transaction was flagged as potentially fraudulent                                                                  | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `GENERIC_DECLINE`                  | Soft | No         | The transaction was declined for an unspecified reason                                                                 | Ask the customer to contact their bank or try another card                                                                 |
| `INCORRECT_CVC`                    | Soft | Yes        | The provided CVC code was incorrect                                                                                    | Ask the customer to re-enter the correct CVC                                                                               |
| `INCORRECT_NUMBER`                 | Soft | Yes        | The card number was entered incorrectly                                                                                | Ask the customer to re-enter the correct card number                                                                       |
| `INSUFFICIENT_FUNDS`               | Soft | Yes        | The account has insufficient funds to complete the transaction                                                         | Ask the customer to use another payment method or retry once funds are available                                           |
| `INVALID_ACCOUNT`                  | Hard | Yes        | The account details provided are invalid                                                                               | Ask the customer to contact their bank or use another card                                                                 |
| `INVALID_AMOUNT`                   | Soft | Yes        | The transaction amount is invalid                                                                                      | Verify the amount and any purchase limits with the customer                                                                |
| `INVALID_CARD_NUMBER`              | Soft | Yes        | The card number format is invalid                                                                                      | Ask the customer to re-enter a valid card number                                                                           |
| `INVALID_CARD_OWNER`               | Soft | Yes        | The card owner information is invalid                                                                                  | Ask the customer to correct the cardholder name                                                                            |
| `INVALID_CVC`                      | Soft | Yes        | The CVC format is invalid                                                                                              | Ask the customer to re-enter a valid CVC                                                                                   |
| `INVALID_EXPIRY_YEAR`              | Soft | Yes        | The card expiry year is invalid                                                                                        | Ask the customer to enter a valid expiry date                                                                              |
| `INVALID_PIN`                      | Soft | Yes        | The provided PIN is incorrect                                                                                          | Ask the customer to re-enter the correct PIN                                                                               |
| `INVALID_REQUEST`                  | Soft | Yes        | The transaction request contains invalid data                                                                          | Check the payment request fields and resubmit with valid data                                                              |
| `INVALID_UPI_ID`                   | Soft | Yes        | The UPI ID provided is invalid                                                                                         | Ask the customer to enter a valid UPI ID                                                                                   |
| `LIMIT_EXCEEDED`                   | Soft | Yes        | The transaction exceeds the card or account limit                                                                      | Ask the customer to contact their bank about limits, or use another method                                                 |
| `LIVE_MODE_TEST_CARD`              | Hard | Yes        | A test card was used in live mode                                                                                      | Use a real card — retrying the test card will always fail in live mode                                                     |
| `LOST_CARD`                        | Hard | Yes        | The card has been reported as lost                                                                                     | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `MANDATE_INVALID`                  | Soft | Yes        | The payment mandate is invalid                                                                                         | Ask the customer to set up the payment mandate again                                                                       |
| `MANDATE_REQUIRED`                 | Soft | Yes        | A mandate is required for this transaction                                                                             | Set up a mandate and ask the customer to authorize it before charging                                                      |
| `MANDATE_REQUIRED_SYSTEM`          | Hard | No         | The system requires a mandate for this transaction type                                                                | Ensure the mandate setup flow is completed before charging                                                                 |
| `NETWORK_ERROR`                    | Soft | No         | A network error occurred during the transaction                                                                        | Transient — retry the payment after a short delay                                                                          |
| `NETWORK_TIMEOUT`                  | Soft | No         | The network request timed out                                                                                          | Transient — retry the payment after a short delay                                                                          |
| `ORDER_ALREADY_EXISTS`             | Soft | No         | An order already exists for this transaction (duplicate order creation)                                                | Check the status of the existing order before retrying; contact support if it persists                                     |
| `ORDER_CREATION_FAILED`            | Soft | No         | Failed to create the order for the transaction                                                                         | Transient/system error — retry the payment; contact support if it persists                                                 |
| `PAYMENT_METHOD_PROVIDER_DECLINED` | Hard | Yes        | The payment method provider declined the transaction                                                                   | Ask the customer to contact their provider or use another payment method                                                   |
| `PAYMENT_METHOD_UNSUPPORTED`       | Hard | Yes        | The payment method is not supported for this transaction                                                               | Ask the customer to use a supported payment method                                                                         |
| `PICKUP_CARD`                      | Hard | Yes        | The card has been reported as lost or stolen and flagged for pickup                                                    | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `PROCESSING_ERROR`                 | Soft | No         | An error occurred while processing the transaction                                                                     | Transient — retry the payment; if it persists, ask the customer to contact their bank                                      |
| `PROVIDER_UNSUPPORTED`             | Hard | No         | The payment provider does not support this transaction type                                                            | Ask the customer to use another payment method                                                                             |
| `REENTER_TRANSACTION`              | Soft | Yes        | The transaction needs to be re-entered                                                                                 | Ask the customer to retry the payment                                                                                      |
| `REVOCATION_OF_AUTHORIZATION`      | Hard | Yes        | The authorization for the transaction was revoked                                                                      | Ask the customer to use another payment method                                                                             |
| `STOLEN_CARD`                      | Hard | Yes        | The card has been reported as stolen                                                                                   | Show the customer a generic decline message — do not reveal the reason. Ask them to use another card                       |
| `SUBSCRIPTION_NOT_ACTIVE`          | Hard | No         | The subscription is not active, so the recurring charge could not be processed                                         | Reactivate the subscription (for example, by updating the payment method) before attempting the charge again               |
| `TRANSACTION_NOT_ALLOWED`          | Hard | Yes        | The transaction is not allowed for this card or account                                                                | Ask the customer to contact their bank to allow this transaction type, or use another card                                 |
| `TRANSACTION_NOT_APPROVED`         | Hard | Yes        | The transaction was not approved                                                                                       | Ask the customer to contact their bank or try another card                                                                 |
| `TRY_AGAIN_LATER`                  | Soft | No         | The transaction should be retried later                                                                                | Transient — retry the payment later                                                                                        |
| `UNKNOWN_ERROR`                    | Soft | No         | An unknown error occurred                                                                                              | Retry the payment; if it persists, contact support                                                                         |

<Note>
  **User Error** indicates whether the payment decline can be resolved by the customer. When `Yes`, the customer can take action to fix the issue (for example, entering correct card details). When `No`, the decline is due to system-level issues or bank restrictions that the customer cannot resolve directly.
</Note>

<Info>
  A card can also be declined when the issuing bank's own risk engine flags the cardholder as a high-risk customer — independent of the merchant or the transaction details. These declines typically surface as generic codes such as `DO_NOT_HONOR`, `GENERIC_DECLINE`, `CARD_DECLINED`, `TRANSACTION_NOT_APPROVED`, or `FRAUDULENT`. In these cases the bank does not share the specific reason, and neither Dodo Payments nor the merchant can override the decision. Ask the customer to contact their bank to resolve the flag, or use a different card or payment method.
</Info>

## Handling Failures Programmatically

Read `error_code` from the `payment.failed` webhook or the payment object, map it to the recommended action above, and decide whether to retry. For subscription renewals, soft declines are retried for you automatically — see [Subscription Payment Retries](/features/recovery/payment-retries).

For API-level and business-logic errors (such as `PAYMENT_NOT_SUCCEEDED` or `REFUND_WINDOW_EXPIRED`) that are not card declines, see the [Error Codes](/api-reference/error-codes) reference.

## Related

<CardGroup>
  <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
    End-to-end guide to detecting, surfacing, and retrying failed payments.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    API and business-logic error codes for non-decline failures.
  </Card>

  <Card title="Subscription Payment Retries" icon="arrow-rotate-right" href="/features/recovery/payment-retries">
    Automatic retries that recover soft declines on subscription renewals.
  </Card>

  <Card title="Subscription Dunning" icon="repeat" href="/features/recovery/subscription-dunning">
    Email sequences that recover hard declines by prompting a payment method update.
  </Card>
</CardGroup>

## Support

For additional help with transaction failures or integration issues, please contact our support team at [support@dodopayments.com](mailto:support@dodopayments.com).


# Agent Skills
Source: https://docs.dodopayments.com/developer-resources/agent-skills

Enhance your AI coding assistants with official Dodo Payments skills for seamless payment integrations, webhook handling, and billing flows.

## Overview

Agent Skills are reusable capabilities that enhance what AI coding assistants can do when working with Dodo Payments. They provide procedural knowledge and best practices that help agents accomplish specific tasks more effectively - from integrating checkout flows to setting up usage-based billing.

<Info>
  **Think of skills as plugins for your AI assistant.** They teach your agent how to implement Dodo Payments features correctly, following our recommended patterns and best practices.
</Info>

Skills work with any AI agent that supports the skills protocol, including:

* **Claude Code** - Anthropic's CLI coding assistant
* **Codex CLI** - OpenAI's CLI coding agent
* **Cursor** - AI-first code editor
* **VS Code / GitHub Copilot** - via the Agent Plugin
* **Kiro** - loads skills as a Power
* **OpenCode** - open source AI coding agent
* **Other clients** - any agent supporting the skills protocol

<Note>
  **Gemini CLI is the exception.** It has no agent-skill primitive, so skills are not available there — only the two [MCP servers](/developer-resources/mcp-server) are.
</Note>

## Available Skills

Seventeen skills covering the full integration surface, grouped by the task you're working on.

### Getting Started

| Skill                                                                                                     | Description                                                                                                                             |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| [dodo-best-practices](https://github.com/dodopayments/skills/tree/main/dodo-payments/dodo-best-practices) | SDK setup, environments, API keys, and the canonical checkout-to-webhook architecture                                                   |
| [framework-adapters](https://github.com/dodopayments/skills/tree/main/dodo-payments/framework-adapters)   | Official `@dodopayments/*` route handlers for Next.js, Express, Hono, Astro, Remix, SvelteKit, Nuxt, Fastify, TanStack, Bun, and Convex |
| [testing-and-go-live](https://github.com/dodopayments/skills/tree/main/dodo-payments/testing-and-go-live) | Test mode, test payment methods, webhook testing, and the production launch checklist                                                   |

### Accepting Payments

| Skill                                                                                                               | Description                                                                    |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [checkout-integration](https://github.com/dodopayments/skills/tree/main/dodo-payments/checkout-integration)         | Checkout Sessions, payment links, and overlay or inline checkout               |
| [subscription-integration](https://github.com/dodopayments/skills/tree/main/dodo-payments/subscription-integration) | Subscription lifecycle, trials, plan changes, proration, and on-demand charges |
| [mobile-checkout](https://github.com/dodopayments/skills/tree/main/dodo-payments/mobile-checkout)                   | In-app checkout for React Native, Flutter, iOS, and Android                    |
| [webhook-integration](https://github.com/dodopayments/skills/tree/main/dodo-payments/webhook-integration)           | Receiving and verifying webhooks using the Standard Webhooks specification     |

### Billing Models

| Skill                                                                                                       | Description                                                                         |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [credit-based-billing](https://github.com/dodopayments/skills/tree/main/dodo-payments/credit-based-billing) | Credit entitlements, balances, ledger, rollover, overage, and meter-based deduction |
| [usage-based-billing](https://github.com/dodopayments/skills/tree/main/dodo-payments/usage-based-billing)   | Meters, event ingestion, aggregation, and per-unit pricing                          |
| [license-keys](https://github.com/dodopayments/skills/tree/main/dodo-payments/license-keys)                 | License key activation, validation, and instance management                         |

### Catalog and Pricing

| Skill                                                                                                                   | Description                                                                   |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [product-catalog-management](https://github.com/dodopayments/skills/tree/main/dodo-payments/product-catalog-management) | Products, pricing, add-ons, collections, images, and digital product delivery |
| [discounts-and-promotions](https://github.com/dodopayments/skills/tree/main/dodo-payments/discounts-and-promotions)     | Discount codes, eligibility rules, stacking, and subscription-cycle limits    |
| [localized-pricing](https://github.com/dodopayments/skills/tree/main/dodo-payments/localized-pricing)                   | Localized pricing, adaptive currency, and purchasing power parity             |

### Customers and Operations

| Skill                                                                                                       | Description                                                                |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [customer-management](https://github.com/dodopayments/skills/tree/main/dodo-payments/customer-management)   | Customers, the self-service portal, saved payment methods, and wallets     |
| [refunds-and-disputes](https://github.com/dodopayments/skills/tree/main/dodo-payments/refunds-and-disputes) | Issuing refunds, handling disputes and chargebacks, and reconciling access |

### UI and Integrations

| Skill                                                                                                             | Description                                                                           |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [billing-sdk](https://github.com/dodopayments/skills/tree/main/dodo-payments/billing-sdk)                         | BillingSDK React components for pricing tables and billing UI                         |
| [better-auth-integration](https://github.com/dodopayments/skills/tree/main/dodo-payments/better-auth-integration) | The `@dodopayments/better-auth` plugin for customer sync, checkout, and portal access |

## Installation

Choose your preferred installation method based on your AI coding assistant.

<Tabs>
  <Tab title="Agent Plugin (recommended)">
    If you're using Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro, or OpenCode, the [Dodo Agent Plugin](/developer-resources/build-with-ai-coding-agents) installs all seventeen skills plus both MCP servers in one step. Skills load automatically when your agent detects a relevant task.

    See the [AI Coding Agents guide](/developer-resources/build-with-ai-coding-agents) for per-agent install commands.
  </Tab>

  <Tab title="Skills CLI">
    Install skills using the universal skills CLI that works with any MCP-compatible agent:

    ```bash theme={null}
    # Install all Dodo Payments skills
    npx skills add dodopayments/skills
    ```

    Or install individual skills as needed:

    ```bash expandable theme={null}
    # Getting started
    npx skills add dodopayments/skills/dodo-payments/dodo-best-practices
    npx skills add dodopayments/skills/dodo-payments/framework-adapters
    npx skills add dodopayments/skills/dodo-payments/testing-and-go-live

    # Accepting payments
    npx skills add dodopayments/skills/dodo-payments/checkout-integration
    npx skills add dodopayments/skills/dodo-payments/subscription-integration
    npx skills add dodopayments/skills/dodo-payments/mobile-checkout
    npx skills add dodopayments/skills/dodo-payments/webhook-integration

    # Billing models
    npx skills add dodopayments/skills/dodo-payments/credit-based-billing
    npx skills add dodopayments/skills/dodo-payments/usage-based-billing
    npx skills add dodopayments/skills/dodo-payments/license-keys

    # Catalog and pricing
    npx skills add dodopayments/skills/dodo-payments/product-catalog-management
    npx skills add dodopayments/skills/dodo-payments/discounts-and-promotions
    npx skills add dodopayments/skills/dodo-payments/localized-pricing

    # Customers and operations
    npx skills add dodopayments/skills/dodo-payments/customer-management
    npx skills add dodopayments/skills/dodo-payments/refunds-and-disputes

    # UI and integrations
    npx skills add dodopayments/skills/dodo-payments/billing-sdk
    npx skills add dodopayments/skills/dodo-payments/better-auth-integration
    ```

    <Tip>
      Install only the skills you need to keep your agent focused and reduce context overhead.
    </Tip>
  </Tab>

  <Tab title="Claude Code">
    Add the Dodo Payments skills marketplace to Claude Code:

    ```bash theme={null}
    /plugin marketplace add dodopayments/skills
    ```

    Then install individual plugins:

    ```bash expandable theme={null}
    # Getting started
    /plugin install dodo-best-practices
    /plugin install framework-adapters
    /plugin install testing-and-go-live

    # Accepting payments
    /plugin install checkout-integration
    /plugin install subscription-integration
    /plugin install mobile-checkout
    /plugin install webhook-integration

    # Billing models
    /plugin install credit-based-billing
    /plugin install usage-based-billing
    /plugin install license-keys

    # Catalog and pricing
    /plugin install product-catalog-management
    /plugin install discounts-and-promotions
    /plugin install localized-pricing

    # Customers and operations
    /plugin install customer-management
    /plugin install refunds-and-disputes

    # UI and integrations
    /plugin install billing-sdk
    /plugin install better-auth-integration
    ```
  </Tab>

  <Tab title="OpenCode">
    OpenCode loads skills from directories you point it at. It does **not** scan installed packages, so an explicit `skills.paths` entry is required.

    Using the Agent Plugin package:

    ```bash theme={null}
    npm install --save-dev @dodopayments/opencode-plugin
    ```

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "plugin": ["@dodopayments/opencode-plugin"],
      "skills": {
        "paths": ["node_modules/@dodopayments/opencode-plugin/skills"]
      }
    }
    ```

    Relative paths resolve against the **project directory**, so the package must be present in that project's `node_modules`. An absolute path works too, and avoids the local-install requirement.

    <Warning>
      A skills path that does not exist is ignored **silently** — no error, no warning. Confirm the skills actually loaded:

      ```bash theme={null}
      opencode run "List every skill available to you by name."
      ```

      You should see all seventeen.
    </Warning>
  </Tab>
</Tabs>

## Using Skills

Once installed, your AI assistant loads the relevant skill automatically when you ask it to implement a Dodo Payments feature. You don't need to name the skill - just describe the task.

| Example prompt                                                               | Skill that loads             |
| ---------------------------------------------------------------------------- | ---------------------------- |
| Help me integrate Dodo Payments into my Next.js app following best practices | `dodo-best-practices`        |
| Add a Dodo Payments checkout route handler to my Hono app                    | `framework-adapters`         |
| Walk me through testing payments and going live                              | `testing-and-go-live`        |
| Create a checkout session for my SaaS product                                | `checkout-integration`       |
| Implement a subscription flow with a free trial and multiple pricing tiers   | `subscription-integration`   |
| Add in-app checkout to my React Native app                                   | `mobile-checkout`            |
| Set up webhook handlers for payment and subscription events                  | `webhook-integration`        |
| Set up credit entitlements and metered credit deduction for my AI product    | `credit-based-billing`       |
| Add usage-based billing to track API calls for my AI product                 | `usage-based-billing`        |
| Implement license key validation for my desktop app                          | `license-keys`               |
| Create a product catalog with add-ons and tiered pricing                     | `product-catalog-management` |
| Add a promo code that gives 20% off the first three billing cycles           | `discounts-and-promotions`   |
| Show prices in the visitor's local currency with purchasing power parity     | `localized-pricing`          |
| Give customers a self-service portal to manage their payment methods         | `customer-management`        |
| Issue a partial refund and revoke access when a dispute is opened            | `refunds-and-disputes`       |
| Add a pricing page using BillingSDK components                               | `billing-sdk`                |
| Wire Dodo Payments into my Better Auth setup                                 | `better-auth-integration`    |

## How Skills Work

Skills provide your AI assistant with:

1. **Procedural Knowledge** - Step-by-step instructions for implementing features
2. **Code Templates** - Production-ready code patterns and snippets
3. **Best Practices** - Recommended approaches for security, error handling, and UX
4. **Context Awareness** - Understanding of how different Dodo Payments features work together

When you ask your AI assistant to implement a feature, it uses the relevant skill to:

* Understand the correct implementation approach
* Generate accurate, working code
* Follow Dodo Payments conventions
* Handle edge cases and errors properly

<Note>
  Skills complement the [MCP Server](/developer-resources/mcp-server) and [Sentra](/developer-resources/sentra). Use MCP for API operations, Sentra for guided integration, and Skills for enhanced AI assistant capabilities.
</Note>

## Comparison with Other Tools

| Tool             | Purpose                        | Best For                                    |
| ---------------- | ------------------------------ | ------------------------------------------- |
| **Agent Skills** | Enhance AI assistant knowledge | AI-assisted development with any MCP client |
| **MCP Server**   | Execute API operations         | Direct API access from AI assistants        |
| **Sentra**       | Guided integration assistant   | Interactive billing integration in IDE      |

## Resources

<CardGroup>
  <Card title="Skills Repository" icon="github" href="https://github.com/dodopayments/skills">
    Browse the source code and contribute to Dodo Payments skills
  </Card>

  <Card title="MCP Server" icon="server" href="/developer-resources/mcp-server">
    Enable AI assistants to execute Dodo Payments API operations
  </Card>

  <Card title="Sentra" icon="wand-magic-sparkles" href="/developer-resources/sentra">
    AI-powered billing assistant for your IDE
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and share feedback with the community
  </Card>
</CardGroup>


# Astro Minimal Boilerplate
Source: https://docs.dodopayments.com/developer-resources/astro-boilerplate

Get started quickly with our minimal Astro boilerplate for integrating Dodo Payments into your Astro application

## Overview

The Astro minimal boilerplate provides a ready-to-use starting point for integrating Dodo Payments with your Astro application. This template includes checkout sessions, webhook handling, customer portal, and modern UI components to help you start accepting payments quickly.

<Info>
  This boilerplate uses Astro 5 with TypeScript, Tailwind CSS 4, and the `@dodopayments/astro` adapter.
</Info>

### Features

* **Quick Setup** - Get started in under 5 minutes
* **Payment Integration** - Pre-configured checkout flow using `@dodopayments/astro`
* **Modern UI** - Clean, dark-themed pricing page with Tailwind CSS
* **Webhook Handler** - Ready-to-use webhook endpoint for payment events
* **Customer Portal** - One-click subscription management
* **TypeScript** - Fully typed with minimal, focused types
* **Pre-filled Checkout** - Demonstrates passing customer data to improve UX

## Prerequisites

Before you begin, make sure you have:

* **Node.js LTS version** (required for Astro 5)
* **Dodo Payments account** (to access API and Webhook Keys from dashboard)

## Quick Start

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
    cd dodo-astro-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    Sign up at [Dodo Payments](https://dodopayments.com/) and get your credentials from the dashboard:

    * **API Key:** [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Make sure you're in **Test Mode** while developing!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the root directory:

    ```bash theme={null}
    cp .env.example .env
    ```

    Update the values with your Dodo Payments credentials:

    ```env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_RETURN_URL=http://localhost:4321/
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Never commit your `.env` file to version control. It's already included in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Update `src/lib/products.ts` with your actual product IDs from Dodo Payments:

    ```typescript theme={null}
    export const products: Product[] = [
      {
        product_id: "pdt_001", // Replace with your product ID
        name: "Basic Plan",
        description: "Get access to basic features and support",
        price: 9999, // in cents
        features: [
          "Access to basic features",
          "Email support",
          "1 Team member",
          "Basic analytics",
        ],
      },
      // ... add more products
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    Open [http://localhost:4321](http://localhost:4321) to see your pricing page!
  </Step>
</Steps>

## Project Structure

```text theme={null}
src/
├── components/
│   ├── Footer.astro           # Reusable footer
│   ├── Header.astro           # Navigation header
│   └── ProductCard.astro      # Product pricing card
├── layouts/
│   └── Layout.astro           # Root layout
├── lib/
│   └── products.ts            # Product definitions
├── pages/
│   ├── index.astro            # Pricing page (home)
│   └── api/
│       ├── checkout.ts        # Checkout session handler
│       ├── customer-portal.ts # Customer portal redirect
│       └── webhook.ts         # Webhook event handler
└── styles/
    └── global.css             # Global styles with Tailwind
```

## Customization

### Update Product Information

Edit `src/lib/products.ts` to modify:

* Product IDs (from your Dodo dashboard)
* Pricing
* Features
* Descriptions

### Pre-fill Customer Data

In `src/components/ProductCard.astro`, replace the hardcoded values with your actual user data:

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### Update Customer Portal

In `src/components/Header.astro`, replace the hardcoded customer ID with the actual customer ID from your auth system or database:

```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```

You can complete a test purchase to get the customer ID for testing.

## Webhook Events

The boilerplate demonstrates handling webhook events in `src/pages/api/webhook.ts`:

* `onSubscriptionActive` - Triggered when a subscription becomes active
* `onSubscriptionCancelled` - Triggered when a subscription is cancelled

Add your business logic inside these handlers:

```typescript theme={null}
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
```

Add more webhook events as needed.

For local development, you can use tools like [ngrok](https://ngrok.com/) to create a secure tunnel to your local server and use it as your webhook URL.

## Deployment

This boilerplate uses static output with on-demand rendering for API routes. You'll need to install an adapter for your deployment platform:

| Platform   | Guide                                                                         |
| ---------- | ----------------------------------------------------------------------------- |
| Vercel     | [Deploy to Vercel](https://docs.astro.build/en/guides/deploy/vercel/)         |
| Netlify    | [Deploy to Netlify](https://docs.astro.build/en/guides/deploy/netlify/)       |
| Cloudflare | [Deploy to Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/) |

See [Astro's deployment guides](https://docs.astro.build/en/guides/deploy/) for all platforms.

### Update Webhook URL

After deploying, update your webhook URL in the [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks):

```text theme={null}
https://your-domain.com/api/webhook
```

Also remember to update the `DODO_PAYMENTS_WEBHOOK_KEY` environment variable in your production environment to match the webhook signing key for your deployed domain.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Delete `node_modules` and reinstall dependencies:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Checkout redirect fails">
    **Common causes:**

    * Invalid product ID - verify it exists in your Dodo dashboard
    * Wrong API key or environment setting in `.env`
    * Check browser console and terminal for errors
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    For local testing, use [ngrok](https://ngrok.com) to expose your server:

    ```bash theme={null}
    ngrok http 4321
    ```

    Update the webhook URL in your [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) to the ngrok URL. Remember to update your .env file with the correct webhook verification key.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Replace the hardcoded `CUSTOMER_ID` in `src/components/Header.astro` with an actual customer ID from your Dodo dashboard.

    Or integrate your authentication system and database to fetch the customer ID dynamically.
  </Accordion>

  <Accordion title="Build fails with adapter error">
    This boilerplate uses static output with on-demand API routes. You need to install an adapter for deployment:

    See [Astro's deployment guides](https://docs.astro.build/en/guides/deploy/) for details.
  </Accordion>
</AccordionGroup>

## Learn More

* [Dodo Payments Documentation](https://docs.dodopayments.com/)
* [Checkout Sessions Documentation](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Webhooks Documentation](https://docs.dodopayments.com/developer-resources/webhooks)

## Support

Need help with the boilerplate?

* Join our [Discord community](https://discord.gg/bYqAp4ayYh) for questions and discussions
* Check the [GitHub repository](https://github.com/dodopayments/dodo-astro-minimal-boilerplate) for issues and updates
* Contact our [support team](mailto:support@dodopayments.com) for assistance


# Cursor Billing Model
Source: https://docs.dodopayments.com/developer-resources/billing-deconstructions/cursor

Deconstruct Cursor's model-weighted credit system and build the same hybrid subscription-plus-credits model using Dodo Payments.

## How Cursor Bills

Cursor uses a hybrid model that combines a monthly subscription with a depleting credit pool. This approach provides a predictable price for users while managing the variable costs of different AI models.

**Pricing Tiers**: Cursor offers tiers from Hobby to Ultra, balancing premium and standard access to fit different workflows.

| Plan  | Price       | Premium Requests  | Slow Requests |
| :---- | :---------- | :---------------- | :------------ |
| Hobby | Free        | 50/month          | Unlimited     |
| Pro   | \$20/month  | 500/month         | Unlimited     |
| Pro+  | \$60/month  | Unlimited premium | -             |
| Ultra | \$200/month | Unlimited premium | -             |

**Model-Weighted Depletion**: Different requests consume different amounts of credits based on the underlying model's cost. This allows Cursor to offer a single subscription that covers multiple providers while ensuring expensive operations are accounted for.

| Request Type   | Model             | Credit Cost |
| :------------- | :---------------- | :---------- |
| Tab Completion | Default           | 0           |
| Chat           | GPT-4o Mini       | 1           |
| Chat           | Claude 3.5 Sonnet | 1           |
| Composer       | GPT-4o            | 5           |
| Agent          | Claude 3.5 Sonnet | 10          |
| Agent          | o1-preview        | 25          |

**Credit Exhaustion and Overages**: When credits run out, users move to a "Slow" queue with cheaper models instead of being cut off. Alternatively, they can enable usage-based overages to maintain premium access at a fixed per-request cost.

```mermaid theme={null}
flowchart TD
    A[User Makes Request] --> B[Determine Model and Type]
    B --> C[Calculate Credit Cost]
    C --> D{Credits Remaining?}
    D -->|Yes| E[Deduct Credits]
    E --> F[Process with Premium Model]
    D -->|No| G{Overage Enabled?}
    G -->|Yes| H[Bill Overage at End of Cycle]
    H --> F
    G -->|No| I[Route to Slow Queue]
    I --> J[Process with Basic Model]
```

4. **Enterprise and Business**: Teams use pooled usage where the entire organization shares a single credit bucket. This simplifies management and ensures heavy users don't hit individual limits while others have unused capacity.

## What Makes It Unique

Cursor's model balances user experience with infrastructure costs by solving problems that traditional SaaS billing models struggle with.

* **Provider Abstraction**: A single subscription wraps multiple LLM providers like OpenAI and Anthropic, handling complex pricing and API keys behind the scenes.
* **Weighted Depletion**: Costs align with value by charging more for powerful models, making the pricing feel fair and transparent for all users.
* **Graceful Degradation**: The "Slow" queue prevents hard cutoffs, keeping users in the product and encouraging upgrades without being punitive.
* **Pooled Credits**: Team-level buckets reduce friction for enterprise customers by allowing efficient resource sharing across the entire organization.

## Build This with Dodo Payments

You can replicate this exact model using Dodo Payments' credit entitlements and usage-based billing. The following steps will guide you through the implementation.

<Steps>
  <Step title="Create a Custom Unit Credit Entitlement">
    First, define the credit system in the Dodo dashboard. This entitlement will represent the "Premium Requests" that users get with their subscription.

    * **Credit Type:** Custom Unit
    * **Unit Name:** "Premium Requests"
    * **Precision:** 0 (since you can't use half a request)
    * **Credit Expiry:** 30 days (this ensures credits reset each billing cycle)
    * **Rollover:** Disabled (unused requests don't carry over to the next month)
    * **Overage:** Enabled
    * **Price Per Unit:** \$0.04 (the cost for each request after the initial pool is exhausted)
    * **Overage Behavior:** Bill overage at billing (this adds the overage cost to the next invoice)

    This configuration ensures that users have a fixed pool of requests each month, with the option to pay for more if they need them. It's the foundation of the hybrid billing model.
  </Step>

  <Step title="Create Subscription Products">
    Create separate products for each tier. Attach the same credit entitlement to each product, but with different amounts. This allows you to manage all tiers with a single credit system, making it easy to upgrade or downgrade users.

    * **Hobby:** \$0/month, 50 credits/cycle
    * **Pro:** \$20/month, 500 credits/cycle
    * **Pro+:** \$60/month, 5000 credits/cycle (effectively unlimited for most)
    * **Ultra:** \$200/month, 50000 credits/cycle (effectively unlimited)

    When a user subscribes to one of these products, Dodo automatically allocates the corresponding number of credits to their account. This happens instantly, providing a seamless onboarding experience.
  </Step>

  <Step title="Create a Usage Meter Linked to Credits">
    Create a meter named `ai.request` with **Sum** aggregation on the `credit_cost` property. Link this meter to your credit entitlement by enabling the "Bill usage in Credits" toggle. Set the meter units per credit to 1.

    To handle model-weighted depletion, you'll manage the credit cost at the application level. When a user makes a request, your app determines the cost based on the model or action type.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    /**
     * Determines the credit cost for a given request type and model.
     * This logic lives in your application and can be updated without
     * changing your billing configuration.
     */
    function getCreditCost(requestType: string, model: string): number {
      const costs: Record<string, Record<string, number>> = {
        'tab_completion': { 'default': 0 },
        'chat': { 'gpt-4o-mini': 1, 'gpt-4o': 1, 'claude-sonnet': 1 },
        'composer': { 'gpt-4o-mini': 2, 'gpt-4o': 5, 'claude-sonnet': 5 },
        'agent': { 'gpt-4o': 10, 'claude-sonnet': 10, 'o1': 25 }
      };
      
      // Default to 1 credit if the combination isn't found
      return costs[requestType]?.[model] ?? 1;
    }

    /**
     * Ingests usage events into Dodo Payments.
     * For weighted requests, we send multiple events or use a sum aggregation.
     */
    async function trackRequest(customerId: string, requestType: string, model: string) {
      const creditCost = getCreditCost(requestType, model);
      
      // Tab completions are free, so we don't need to track them for billing
      if (creditCost === 0) return;
      
      const client = new DodoPayments({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      });
      
      await client.usageEvents.ingest({
        events: [{
          event_id: `req_${Date.now()}_${Math.random().toString(36).slice(2)}`,
          customer_id: customerId,
          event_name: 'ai.request',
          timestamp: new Date().toISOString(),
          metadata: {
            request_type: requestType,
            model: model,
            credit_cost: creditCost
          }
        }]
      });
    }
    ```

    <Tip>
      If you want to use a single event for weighted requests, set your meter aggregation to **Sum** and use a property like `credit_cost` as the value to sum. This is often more efficient for high-volume ingestion and simplifies your application logic.
    </Tip>
  </Step>

  <Step title="Handle Credit Exhaustion (Slow Queue)">
    Listen for the `credit.balance_low` webhook from Dodo. When a user's credits are near zero, you can switch them to a slow queue in your application. This is where you implement the "graceful degradation" logic.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';
    import express from 'express';

    const app = express();
    app.use(express.raw({ type: 'application/json' }));

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    });

    app.post('/webhooks/dodo', async (req, res) => {
      try {
        const event = client.webhooks.unwrap(req.body.toString(), {
          headers: {
            'webhook-id': req.headers['webhook-id'] as string,
            'webhook-signature': req.headers['webhook-signature'] as string,
            'webhook-timestamp': req.headers['webhook-timestamp'] as string,
          },
        });
        
        if (event.type === 'credit.balance_low') {
          const customerId = event.data.customer_id;
          await updateUserTier(customerId, 'slow');
          await notifyUser(customerId, 'You have used most of your premium requests. Switching to standard models.');
        }
        
        res.json({ received: true });
      } catch (error) {
        res.status(401).json({ error: 'Invalid signature' });
      }
    });

    /**
     * Routes a request based on the user's current tier.
     * This function is called before every AI request to determine the model and queue.
     */
    async function routeRequest(customerId: string, requestType: string) {
      const tier = await getUserTier(customerId);
      
      if (tier === 'slow') {
        // Route to a cheaper model and a lower priority queue
        // This saves costs while keeping the user active in the product
        return { model: 'gpt-4o-mini', queue: 'standard' };
      }
      
      // Premium routing for users with remaining credits
      // This provides the best possible performance and model quality
      return { model: 'claude-sonnet', queue: 'priority' };
    }
    ```
  </Step>

  <Step title="Create Checkout">
    Finally, generate a checkout session for the user to subscribe to a plan. Dodo handles the payment processing, tax compliance, and credit allocation automatically.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    });

    /**
     * Creates a checkout session for a new subscription.
     * This is typically called when a user clicks an "Upgrade" button.
     */
    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_cursor_pro', quantity: 1 }
      ],
      customer: { email: 'developer@example.com' },
      return_url: 'https://yourapp.com/dashboard'
    });
    ```
  </Step>
</Steps>

## Accelerate with the LLM Ingestion Blueprint

The credit-weighted billing above handles your core monetization. For deeper analytics on actual token consumption across providers, the [LLM Ingestion Blueprint](/developer-resources/ingestion-blueprints/llm) can run alongside your credit system.

```bash theme={null}
npm install @dodopayments/ingestion-blueprints
```

```typescript theme={null}
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';
import Anthropic from '@anthropic-ai/sdk';

// Track raw token usage for analytics alongside credit-weighted billing
const openaiTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'analytics.openai_tokens',
});

const anthropicTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'analytics.anthropic_tokens',
});

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

// Wrap each provider separately
const trackedOpenAI = openaiTracker.wrap({ client: openai, customerId: 'customer_123' });
const trackedAnthropic = anthropicTracker.wrap({ client: anthropic, customerId: 'customer_123' });

// Token tracking is automatic, credit deduction still uses your weighted system
const response = await trackedOpenAI.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});
```

This gives you two layers of data: credit-weighted billing for monetization and raw token counts for cost analysis and margin tracking.

<Tip>
  The LLM Blueprint supports OpenAI, Anthropic, Groq, Google Gemini, and more. See the [full blueprint documentation](/developer-resources/ingestion-blueprints/llm) for all supported providers.
</Tip>

## Pooled Team Credits (Enterprise)

Cursor's Business and Enterprise plans pool credits across a team. You can implement this with Dodo by creating a single subscription for the organization rather than individual users. This ensures that the team's usage is consolidated and managed as a single entity, which is a major requirement for larger customers.

### Implementation Strategy

1. **Organization-Level Customer:** Create a single `customer_id` in Dodo for the entire organization. This customer represents the billing entity for the team and holds the shared credit pool. All invoices and credit allocations are tied to this ID.
2. **Seat-Based Billing:** Use Dodo's add-ons to charge a per-user platform fee. When a team adds a new member, you update the quantity of the "Seat" add-on. This ensures your revenue scales with the number of users while keeping the credit pool separate. It's a clean way to handle multi-dimensional billing.
3. **Shared Usage Tracking:** All team members' requests are ingested using the organization's `customer_id`. This ensures that every request from any team member depletes the same central credit pool. You can still track individual user usage by including a `user_id` in the event metadata for internal reporting and analytics.

This approach gives you the best of both worlds: a predictable per-user fee for the platform and a shared pool of credits for the expensive AI resources. It also simplifies the user experience for team members, as they don't have to manage their own individual limits.

## Comparison with Traditional SaaS Billing

Traditional SaaS billing usually involves flat-rate tiers (e.g., \$10/month for 100 units). If a user needs 101 units, they often have to jump to a \$50/month tier. This creates "cliff" effects that can frustrate users and lead to churn. It also doesn't account for the variable cost of different types of usage, which is critical in the AI space.

Cursor's model, powered by Dodo, is much more flexible and fair:

* **No "Cliff" Effects:** Users don't have to upgrade just because they hit a limit. They can pay for overages or accept slower performance. This keeps them in the product and reduces friction, leading to higher customer satisfaction and lower churn.
* **Cost Alignment:** Your revenue scales directly with your infrastructure costs. If a user uses expensive models, they pay more (either through credits or overages). This protects your margins and allows you to offer high-cost features sustainably without risking your business model.
* **Better Retention:** By not cutting users off, you keep them engaged with your product even when they've reached their limit. They can continue to work, which builds long-term loyalty and increases the lifetime value of the customer. It's a win-win for both the user and the provider.

## Handling Model Updates and Evolution

One of the challenges with AI billing is that models are constantly being updated or replaced. New models might have different cost structures or performance characteristics. With Dodo's credit system, you can handle this gracefully at the application level without needing to migrate your billing data.

If you introduce a new, more expensive model, you simply update your `getCreditCost` function to assign it a higher cost. You don't need to change your billing configuration or update existing subscriptions. This decoupling of billing and application logic is a major advantage, as it allows you to iterate on your product at the speed of AI without being constrained by your billing system.

## User Notifications and Transparency

To provide a great user experience, it's important to keep users informed about their credit usage. Transparency builds trust and helps users manage their costs effectively. You can use Dodo's webhooks to trigger notifications at various thresholds (e.g., 50%, 80%, and 100% usage).

These notifications can be sent via email, in-app alerts, or Slack messages. By providing real-time feedback on usage, you encourage users to manage their consumption or upgrade their plan before they hit the "slow queue". This proactive approach reduces support tickets and improves the overall user experience, making your product feel more professional and user-centric.

## Security and Fraud Prevention

When implementing a credit-based system, it's important to consider security and fraud prevention. Since credits have a direct monetary value, they can be a target for abuse.

* **Idempotency:** Always use unique `event_id`s when ingesting usage events to prevent double-counting. Dodo's ingestion API handles idempotency automatically if you provide a unique ID, ensuring that a network retry doesn't charge the user twice.
* **Rate Limiting:** Implement rate limiting at the application level to prevent a single user from exhausting their credits (or your API budget) too quickly. This protects your infrastructure and the user's wallet.
* **Monitoring:** Monitor usage patterns for anomalies that might indicate account sharing or automated abuse. Dodo's analytics can help you identify these patterns, allowing you to take action before they become a major problem.

## Best Practices for Credit Systems

When building a credit-based billing system, keep these best practices in mind:

1. **Keep it Simple:** Don't make your credit system too complex. Users should be able to easily understand how much a request costs and how many credits they have left.
2. **Provide Value:** Ensure that the credits provide real value to the user. If the cost of a request is too high, users will feel like they're being nickel-and-dimed.
3. **Be Transparent:** Always show the user their current credit balance and usage history. This builds trust and reduces confusion.
4. **Automate Everything:** Use Dodo's webhooks and APIs to automate as much of the billing process as possible. This reduces manual work and ensures that your billing is always accurate.

## Key Dodo Features Used

<CardGroup>
  <Card title="Credit-Based Billing" icon="coins" href="/features/credit-based-billing">
    Manage depleting credit pools and overages with custom units.
  </Card>

  <Card title="Subscriptions" icon="calendar" href="/features/subscription">
    Set up recurring billing for different tiers with integrated credits.
  </Card>

  <Card title="Usage-Based Billing" icon="chart-line" href="/features/usage-based-billing/introduction">
    Track events and bill based on consumption in real-time.
  </Card>

  <Card title="Event Ingestion" icon="bolt" href="/features/usage-based-billing/event-ingestion">
    Send high-volume usage data to Dodo with low latency.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/credit">
    React to credit balance changes and automate user tiering.
  </Card>

  <Card title="LLM Ingestion Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Automatic token tracking across multiple LLM providers.
  </Card>
</CardGroup>


# ElevenLabs Billing Model
Source: https://docs.dodopayments.com/developer-resources/billing-deconstructions/elevenlabs

Deconstruct ElevenLabs' character-based billing with rollover credits and tiered overage pricing, then build the same model using Dodo Payments.

ElevenLabs has built a dominant position in the AI voice space by making their billing as fluid as their speech synthesis. Their model centers on a single unit of value: the character. Whether you are generating text-to-speech, cloning a voice, or dubbing a video, you consume from a unified pool of character credits.

## How ElevenLabs Bills

The ElevenLabs pricing structure uses fixed monthly quotas tied to subscription tiers. As users move to higher tiers, they get more characters and access to more advanced features like professional voice cloning or commercial rights.

| Plan    | Price       | Characters/Month | Overage Rate      |
| :------ | :---------- | :--------------- | :---------------- |
| Free    | \$0         | 10,000           | Not available     |
| Starter | \$5/month   | 30,000           | \~\$0.30/1K chars |
| Creator | \$22/month  | 100,000          | \~\$0.24/1K chars |
| Pro     | \$99/month  | 500,000          | \~\$0.15/1K chars |
| Scale   | \$330/month | 2,000,000        | \~\$0.10/1K chars |

1. **Character-based pricing**: Characters are the universal currency across the platform. Text-to-Speech, Dubbing, and Voice Cloning all draw from this same balance, simplifying usage tracking.
2. **Rollover mechanics**: Unused characters roll over to the next billing cycle instead of expiring. ElevenLabs applies a cap to prevent infinite accumulation, ensuring users retain value from their subscription.
3. **Tiered overages**: Overages are handled based on the subscription tier. Lower plans have overages disabled by default for safety, while higher tiers allow opt-in charges to maintain service continuity.

## What Makes It Unique

Several strategic choices make the ElevenLabs billing model particularly effective for retaining users and encouraging upgrades.

* **Character Rollover**: Rollover credits reduce "use it or lose it" anxiety by carrying forward unused investment. This maintains subscription value even during periods of lower activity.
* **Tiered Overage Pricing**: Overage rates decrease as plan sizes increase, creating a strong incentive to upgrade. Users often find higher tiers more attractive due to the lower cost of additional usage.
* **Unified Consumption**: A single character pool for all services removes the cognitive burden of managing separate quotas. Users only need to track one number to understand their remaining capacity.
* **Opt-in Overages**: Professional users can enable overages for continuity, while casual users benefit from the safety of a hard cap.

```mermaid theme={null}
flowchart TD
    A[New Billing Cycle] --> B[Fresh Credits + Rolled Over]
    B --> C[User Generates Audio]
    C --> D{Characters Left?}
    D -->|Yes| C
    D -->|No| E{Overage Enabled?}
    E -->|Yes| F[Bill at Tier Rate]
    F --> C
    E -->|No| G[Generation Blocked]
    D -->|Cycle Ends| H[Unused Credits Roll Over]
    H --> A
```

## Build This with Dodo Payments

You can replicate this sophisticated model using Dodo Payments' credit-based billing and usage metering.

<Steps>
  <Step title="Create a Custom Unit Credit Entitlement">
    First, define the "Characters" unit that will serve as your platform's currency.

    1. Go to **Entitlements** in your Dodo dashboard.
    2. Create a new **Credit Entitlement**.
    3. Set the **Credit Type** to **Custom Unit**.
    4. Name the unit "Characters".
    5. Set **Precision** to 0, as characters are always whole units.
    6. Set **Credit Expiry** to 30 days to match the monthly billing cycle.
    7. Enable **Rollover** with these settings:
       * **Max Rollover Percentage**: 100% (allows all unused characters to carry over).
       * **Rollover Timeframe**: 1 Month.
       * **Max Rollover Count**: 1 (credits can roll over once, then they expire).
  </Step>

  <Step title="Create Tiered Subscription Products">
    Create five subscription products. You will attach the same "Characters" entitlement to each, but with different configurations for each tier.

    | Product | Price    | Credits/Cycle | Overage Enabled | Overage Price (per 1K chars) |
    | :------ | :------- | :------------ | :-------------- | :--------------------------- |
    | Free    | \$0/mo   | 10,000        | No              | -                            |
    | Starter | \$5/mo   | 30,000        | Yes (opt-in)    | \$0.30                       |
    | Creator | \$22/mo  | 100,000       | Yes             | \$0.24                       |
    | Pro     | \$99/mo  | 500,000       | Yes             | \$0.15                       |
    | Scale   | \$330/mo | 2,000,000     | Yes             | \$0.10                       |

    When you attach the credit entitlement to each product, uncheck **Import Default Credit Settings**. This allows you to set the specific **Price Per Unit** for overages on that specific tier. Set the **Overage Behavior** to **Bill overage at billing** and configure a **Low Balance Threshold** at 10% of the tier's quota.
  </Step>

  <Step title="Create a Usage Meter">
    The usage meter connects your application's activity to the credit system.

    1. Create a new meter named `tts.characters`.
    2. Set the **Aggregation** to **Sum**. This will add up the `characters` property from every event you send.
    3. Link this meter to your "Characters" credit entitlement.
    4. Set **Meter units per credit** to 1. This ensures that one character used in your app equals one credit deducted from the balance.
  </Step>

  <Step title="Send Usage Events">
    Integrate the usage tracking into your application code. Every time a user generates audio, send an event to Dodo.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    async function trackGeneration(
      customerId: string,
      text: string, 
      service: 'tts' | 'dubbing' | 'cloning'
    ) {
      const characterCount = text.length;

      const client = new DodoPayments({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      });

      await client.usageEvents.ingest({
        events: [{
          event_id: `gen_${Date.now()}_${Math.random().toString(36).slice(2)}`,
          customer_id: customerId,
          event_name: 'tts.characters',
          timestamp: new Date().toISOString(),
          metadata: {
            characters: characterCount,
            service: service,
            voice_id: 'voice_abc123'
          }
        }]
      });
    }
    ```
  </Step>

  <Step title="Handle Low Balance and Overage">
    Use webhooks to keep your users informed about their character usage.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';
    import express from 'express';

    const app = express();
    app.use(express.raw({ type: 'application/json' }));

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    });

    app.post('/webhooks/dodo', async (req, res) => {
      try {
        const event = client.webhooks.unwrap(req.body.toString(), {
          headers: {
            'webhook-id': req.headers['webhook-id'] as string,
            'webhook-signature': req.headers['webhook-signature'] as string,
            'webhook-timestamp': req.headers['webhook-timestamp'] as string,
          },
        });

        switch (event.type) {
          case 'credit.balance_low':
            await notifyUser(event.data.customer_id, 
              'You are running low on characters. Consider upgrading your plan for more characters and lower overage rates.'
            );
            break;
          case 'credit.deducted':
            await logUsage(event.data);
            break;
          case 'credit.overage_charged':
            await notifyUser(event.data.customer_id,
              'You have exceeded your character quota. Overage charges will appear on your next invoice.'
            );
            break;
        }

        res.json({ received: true });
      } catch (error) {
        res.status(401).json({ error: 'Invalid signature' });
      }
    });
    ```
  </Step>

  <Step title="Create Checkout">
    When a user is ready to subscribe, create a checkout session for the chosen tier.

    ```typescript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_elevenlabs_pro', quantity: 1 }
      ],
      customer: { email: 'creator@example.com' },
      return_url: 'https://yourapp.com/dashboard'
    });
    ```
  </Step>
</Steps>

## Accelerate with the Stream Ingestion Blueprint

For tracking audio output alongside character-based billing, the [Stream Ingestion Blueprint](/developer-resources/ingestion-blueprints/stream) provides a streamlined way to meter bandwidth consumption.

```bash theme={null}
npm install @dodopayments/ingestion-blueprints
```

```typescript theme={null}
import { Ingestion, trackStreamBytes } from '@dodopayments/ingestion-blueprints';

const ingestion = new Ingestion({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'tts.audio_bytes',
});

// After generating audio, track the output size
const audioBuffer = await generateSpeech(text, voiceId);

await trackStreamBytes(ingestion, {
  customerId: customerId,
  bytes: audioBuffer.byteLength,
  metadata: {
    voice_id: voiceId,
    service: 'tts',
    format: 'mp3',
  },
});
```

Use the Stream Blueprint to track audio bandwidth alongside your character-based credit system. This gives you visibility into actual infrastructure costs per generation.

<Tip>
  The Stream Blueprint also supports batching for high-volume scenarios. See the [full blueprint documentation](/developer-resources/ingestion-blueprints/stream) for advanced usage patterns.
</Tip>

## Upgrade Incentive: Tiered Overage Pricing

The most brilliant part of the ElevenLabs model is how it uses overage rates to drive upgrades. By making the cost per character cheaper on higher tiers, they change the conversation from "how much do I need?" to "how much can I save?".

| Tier    | Included Chars | Overage (per 1K) | Effective Cost at 500K Chars   |
| :------ | :------------- | :--------------- | :----------------------------- |
| Creator | 100,000        | \$0.24           | \$22 + (400 \* \$0.24) = \$118 |
| Pro     | 500,000        | \$0.15           | \$99 (No overage)              |

A user who regularly consumes 500,000 characters on the Creator plan pays \$118 per month in subscription plus overages. Upgrading to the Pro plan covers the same usage for \$99, saving \$19 per month. The lower overage rate on higher tiers means that as usage grows, upgrading becomes the obvious financial decision.

With Dodo Payments, you implement this by unchecking the **Import Default Credit Settings** box when attaching credits to your subscription products. This gives you full control over the **Price Per Unit** for each specific tier, allowing you to reward your highest-paying customers with the best rates.

## Key Dodo Features Used

<CardGroup>
  <Card title="Credit-Based Billing" icon="coins" href="/features/credit-based-billing">
    Manage character quotas, rollovers, and expirations.
  </Card>

  <Card title="Subscriptions" icon="calendar" href="/features/subscription">
    Set up the recurring tiers that deliver monthly character allowances.
  </Card>

  <Card title="Usage-Based Billing" icon="chart-line" href="/features/usage-based-billing/introduction">
    Track real-time character consumption across your services.
  </Card>

  <Card title="Event Ingestion" icon="bolt" href="/features/usage-based-billing/event-ingestion">
    Send high-volume usage data to Dodo with minimal latency.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/credit">
    React to low balances and overage events in real-time.
  </Card>

  <Card title="Stream Ingestion Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Track audio streaming bandwidth for usage-based billing.
  </Card>
</CardGroup>


# Billing Deconstructions
Source: https://docs.dodopayments.com/developer-resources/billing-deconstructions/introduction

Learn how to build sophisticated billing models by studying how top AI companies charge their users, then replicate each model with Dodo Payments.

## Overview

| App        | Primary Metric            | Unique Innovation                                           | Dodo Feature                                      |
| :--------- | :------------------------ | :---------------------------------------------------------- | :------------------------------------------------ |
| OpenAI     | Tokens (fiat-denominated) | Prepaid fiat credits with never-expiring balance            | Credit-Based Billing (Fiat Credits)               |
| Cursor     | Premium Requests          | Model-weighted credit depletion (different costs per model) | Credit-Based Billing (Custom Unit)                |
| ElevenLabs | Characters                | Character quotas with rollover + tiered overage pricing     | Credit-Based Billing (Rollover + Overage)         |
| Midjourney | GPU Time                  | "Relax Mode" unlimited fallback after quota                 | Subscription + Usage Meters                       |
| Replicate  | Execution Seconds         | Per-second hardware-specific pure metering                  | Pure Usage-Based Billing                          |
| Lovable    | Messages (credits)        | Daily bonus drip + team-wide shared credit pool             | Credit-Based Billing (Custom Unit) + Subscription |

Each deconstruction breaks down the billing model of a real company and shows you how to replicate it with Dodo Payments.

Pick the app closest to what you are building:

<CardGroup>
  <Card title="OpenAI" icon="https://mintcdn.com/dodopayments/LYWHtNbGSpS1P01t/images/logos/openai.svg?fit=max&auto=format&n=LYWHtNbGSpS1P01t&q=85&s=f08aceb692b25e49fd5e0a4e86d760ed" href="/developer-resources/billing-deconstructions/openai">
    Replicate the token-based prepaid credit model.
  </Card>

  <Card title="Cursor" icon="https://mintcdn.com/dodopayments/QMrmQEutc1DEUdTz/images/logos/cursor.svg?fit=max&auto=format&n=QMrmQEutc1DEUdTz&q=85&s=7e16fe8cba52f3f509c54be8e1ae15da" href="/developer-resources/billing-deconstructions/cursor">
    Build model-weighted usage limits.
  </Card>

  <Card title="ElevenLabs" icon="https://mintcdn.com/dodopayments/LYWHtNbGSpS1P01t/images/logos/elevenlabs.svg?fit=max&auto=format&n=LYWHtNbGSpS1P01t&q=85&s=87aa61a0985fcecc109bb442e0e4795e" href="/developer-resources/billing-deconstructions/elevenlabs">
    Implement character quotas with rollover and overages.
  </Card>

  <Card title="Midjourney" icon="https://mintcdn.com/dodopayments/LYWHtNbGSpS1P01t/images/logos/midjourney.svg?fit=max&auto=format&n=LYWHtNbGSpS1P01t&q=85&s=f8d9144eb2f6afb0bbada40c2d5cddf1" href="/developer-resources/billing-deconstructions/midjourney">
    Combine subscriptions with usage-based fallback.
  </Card>

  <Card title="Replicate" icon="https://mintcdn.com/dodopayments/LYWHtNbGSpS1P01t/images/logos/replicate.svg?fit=max&auto=format&n=LYWHtNbGSpS1P01t&q=85&s=7e3ac9c3c3df1773b9fd375d2bf39784" href="/developer-resources/billing-deconstructions/replicate">
    Set up pure per-second consumption metering.
  </Card>

  <Card title="Lovable" icon="https://mintcdn.com/dodopayments/LYWHtNbGSpS1P01t/images/logos/lovable.svg?fit=max&auto=format&n=LYWHtNbGSpS1P01t&q=85&s=2313952f22719a239ceb1f5b01a9b24f" href="/developer-resources/billing-deconstructions/lovable">
    Replicate message-credit subscriptions with daily bonus drip.
  </Card>
</CardGroup>

## Dodo Features

<CardGroup>
  <Card title="Credit-Based Billing" icon="coins" href="/features/credit-based-billing">
    Manage prepaid credits and virtual units.
  </Card>

  <Card title="Usage-Based Billing" icon="chart-line" href="/features/usage-based-billing/introduction">
    Meter consumption in real-time.
  </Card>

  <Card title="Subscriptions" icon="calendar" href="/features/subscription">
    Handle recurring billing and plan management.
  </Card>

  <Card title="Hybrid Billing" icon="shuffle" href="/features/hybrid-billing">
    Combine multiple billing models for maximum flexibility.
  </Card>
</CardGroup>

## Ingestion Blueprints

Each deconstruction includes integration with Dodo's [Ingestion Blueprints](/features/usage-based-billing/ingestion-blueprints), pre-built SDKs that handle event tracking automatically. Instead of manually constructing usage events, use a blueprint to get production-ready metering in minutes.

<CardGroup>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Automatic token tracking for OpenAI, Anthropic, Groq, and more.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Track audio and video streaming bandwidth.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Bill by compute duration down to the millisecond.
  </Card>
</CardGroup>


# Lovable Billing Model
Source: https://docs.dodopayments.com/developer-resources/billing-deconstructions/lovable

Deconstruct Lovable's message-credit subscription with daily bonus drip, team-wide sharing, and separate cloud metering, then build the same model using Dodo Payments.

Lovable (lovable.dev) is an AI web app builder that uses a credit-based subscription model. Unlike token-based systems, Lovable simplifies the user experience by charging one credit per message. This model combines a monthly credit pool with a daily bonus drip to encourage consistent engagement while allowing for burst usage.

## Lovable's Billing Model

Lovable's pricing is built around message credits and separate metered billing for cloud infrastructure.

| Plan       | Price      | Monthly Credits | Daily Bonus                   | Key Features                                              |
| :--------- | :--------- | :-------------- | :---------------------------- | :-------------------------------------------------------- |
| Free       | \$0/month  | 0               | 5/day (up to 30/month)        | Public projects only                                      |
| Pro        | \$25/month | 100             | 5/day (up to 150/month total) | On-demand top-ups, usage-based Cloud + AI, custom domains |
| Business   | \$50/month | 100             | 5/day                         | SSO, team workspace, design templates, security center    |
| Enterprise | Custom     | Custom          | Custom                        | SCIM, dedicated support, audit logs                       |

* **Credit-based subscription**: 1 credit = 1 message/prompt to the AI.
* **Credits are shared across unlimited users**: Team-wide pool, not per-seat.
* **Credits reset each billing cycle**: Monthly credits refresh on renewal.
* **On-demand credit top-ups**: Users can buy more credits if they run out.
* **Separate usage-based Cloud + AI billing**: Metered billing for hosting and compute.
* **Daily bonus credits reset each day**: A use-it-or-lose-it daily drip of 5 credits.

## What Makes It Unique

* **Message-based simplicity**: 1 credit = 1 message regardless of complexity. No token counting or model weighting.
* **Daily drip + monthly pool hybrid**: The 5 daily bonus credits create a daily engagement incentive, while the 100 monthly credits allow burst usage.
* **Team-wide shared pool**: Credits shared across unlimited users for a flat team price, not per-seat.
* **Two-layer billing**: Credits for AI interactions + separate metered billing for cloud infrastructure.

## Build This with Dodo Payments

You can replicate Lovable's hybrid model using Dodo Payments' credit entitlements and usage-based meters.

<Steps>
  <Step title="Create a Custom Unit Credit Entitlement">
    Define the message credit system in your Dodo Payments dashboard. This entitlement handles the monthly credit pool.

    * **Credit Type**: Custom Unit
    * **Unit Name**: "Messages"
    * **Precision**: 0
    * **Credit Expiry**: 30 days
    * **Overage**: Disabled (hard cap when credits hit 0)
  </Step>

  <Step title="Create Subscription Products">
    Create your plans and attach the credit entitlement. For the Free plan, you'll handle the daily bonus via application logic.

    * **Free**: \$0/mo, 0 credits (daily bonus handled by app logic)
    * **Pro**: \$25/mo, 100 credits/cycle, attach credit entitlement
    * **Business**: \$50/mo, 100 credits/cycle, attach credit entitlement

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    });

    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_lovable_pro', quantity: 1 }
      ],
      customer: { email: 'user@example.com' },
      return_url: 'https://lovable.dev/dashboard'
    });
    ```
  </Step>

  <Step title="Create a Usage Meter for Cloud + AI">
    Lovable bills separately for cloud infrastructure. Create a meter to track these costs.

    * **Meter name**: `cloud.compute_seconds`
    * **Aggregation**: Sum on `compute_seconds` property

    Attach this meter to your subscription products with per-unit pricing. When you ingest usage, Dodo calculates the cost based on your rates.

    ```typescript theme={null}
    await client.usageEvents.ingest({
      events: [{
        event_id: `compute_${Date.now()}`,
        customer_id: 'cust_123',
        event_name: 'cloud.compute_seconds',
        timestamp: new Date().toISOString(),
        metadata: {
          compute_seconds: 3600,
          project_id: 'proj_abc'
        }
      }]
    });
    ```
  </Step>

  <Step title="Implement Daily Bonus Credits (Application Logic)">
    The daily bonus drip is handled at the application level. You can use a cron job to grant these credits or track them separately in your database.

    To track the usage of these bonus credits in Dodo without depleting the main entitlement balance immediately, you can use a separate event name or handle the logic in your app to check the bonus pool first.

    ```typescript theme={null}
    // Example cron job logic (pseudo-code)
    // Every day at midnight UTC:
    // 1. Reset 'daily_bonus_used' to 0 for all users in your DB

    // When a user sends a message:
    async function handleMessage(userId: string) {
      const user = await db.users.findUnique({ where: { id: userId } });
      
      if (user.daily_bonus_used < 5) {
        // Use daily bonus
        await db.users.update({
          where: { id: userId },
          data: { daily_bonus_used: { increment: 1 } }
        });
        // Track for analytics but don't deduct from Dodo credits yet
        await client.usageEvents.ingest({
          events: [{
            event_id: `msg_bonus_${Date.now()}`,
            customer_id: userId,
            event_name: 'ai.message.bonus',
            timestamp: new Date().toISOString(),
            metadata: { type: 'daily_bonus' }
          }]
        });
      } else {
        // Deduct from Dodo credit entitlement
        await client.usageEvents.ingest({
          events: [{
            event_id: `msg_${Date.now()}`,
            customer_id: userId,
            event_name: 'ai.message',
            timestamp: new Date().toISOString(),
            metadata: { type: 'subscription_credit' }
          }]
        });
      }
    }
    ```
  </Step>

  <Step title="Send Usage Events for Messages">
    Track each AI message as a usage event. Link the `ai.message` event to your "Messages" credit entitlement in the Dodo dashboard.

    ```typescript theme={null}
    await client.usageEvents.ingest({
      events: [{
        event_id: `msg_${Date.now()}`,
        customer_id: 'cust_123',
        event_name: 'ai.message',
        timestamp: new Date().toISOString(),
        metadata: {
          content_length: 450,
          project_id: 'proj_abc',
          feature_type: 'editor'
        }
      }]
    });
    ```
  </Step>

  <Step title="Handle Webhooks for Low Balance">
    Notify users when they are running low on credits so they can top up or upgrade.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';
    import express from 'express';

    const app = express();
    app.use(express.raw({ type: 'application/json' }));

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    });

    app.post('/webhooks/dodo', async (req, res) => {
      try {
        const event = client.webhooks.unwrap(req.body.toString(), {
          headers: {
            'webhook-id': req.headers['webhook-id'] as string,
            'webhook-signature': req.headers['webhook-signature'] as string,
            'webhook-timestamp': req.headers['webhook-timestamp'] as string,
          },
        });

        if (event.type === 'credit.balance_low') {
          const { customer_id, available_balance } = event.data;
          await notifyUser(customer_id, `Your balance is low: ${available_balance} messages left.`);
        }

        res.json({ received: true });
      } catch (error) {
        res.status(401).json({ error: 'Invalid signature' });
      }
    });
    ```
  </Step>
</Steps>

## Accelerate with the LLM Ingestion Blueprint

The [LLM Ingestion Blueprint](/developer-resources/ingestion-blueprints/llm) simplifies tracking by wrapping your AI client.

```typescript theme={null}
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'ai.message',
});

const trackedClient = tracker.wrap({
  client: new OpenAI(),
  customerId: 'cust_123',
});

// Automatically tracks the message and deducts 1 credit (if configured)
await trackedClient.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Build a landing page' }],
});
```

<Tip>
  Check out the [full blueprint documentation](/developer-resources/ingestion-blueprints/llm) for more details on automatic tracking.
</Tip>

## Architecture Overview

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant A as Your App
    participant D as Dodo Payments
    participant L as LLM Provider
    participant C as Cloud Infrastructure

    U->>A: Send Message
    A->>A: Check Daily Bonus Pool
    alt Daily Bonus Available
        A->>A: Deduct Daily Bonus
    else No Daily Bonus
        A->>D: Check Credit Balance
        D-->>A: Balance Available
        A->>D: Ingest Message Event
    end
    A->>L: Call LLM
    L-->>A: AI Response
    A->>C: Execute Compute/Hosting
    A->>D: Ingest Cloud Usage Event
    A-->>U: Return Response
```

## Key Dodo Features Used

Explore the features that make this implementation possible.

<CardGroup>
  <Card title="Credit-Based Billing" icon="coins" href="/features/credit-based-billing">
    Manage message credits and shared team pools.
  </Card>

  <Card title="Subscriptions" icon="calendar" href="/features/subscription">
    Set up recurring plans for Pro and Business tiers.
  </Card>

  <Card title="Usage-Based Billing" icon="chart-line" href="/features/usage-based-billing/introduction">
    Meter cloud infrastructure usage separately from AI credits.
  </Card>

  <Card title="Event Ingestion" icon="bolt" href="/features/usage-based-billing/event-ingestion">
    Send high-volume message and compute events to Dodo.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/credit">
    Automate notifications for low credit balances.
  </Card>

  <Card title="LLM Ingestion Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Simplify AI usage tracking with pre-built integrations.
  </Card>
</CardGroup>


# Midjourney Billing Model
Source: https://docs.dodopayments.com/developer-resources/billing-deconstructions/midjourney

Deconstruct Midjourney's GPU-time subscription with Relax Mode fallback and build the same model using Dodo Payments.

Midjourney is a generative AI platform that uses a unique billing model based on GPU time rather than a simple per-image count. This approach ensures that complex, high-resolution renders cost more than quick, low-resolution drafts.

## How Midjourney Bills

Midjourney's subscription plans grant users a specific number of "Fast GPU Hours" each month. These hours represent the actual computational time spent on your generations.

| Plan     | Price       | Fast GPU Hours | Relax Mode | Stealth Mode |
| :------- | :---------- | :------------- | :--------- | :----------- |
| Basic    | \$10/month  | \~3.3 hrs      | No         | No           |
| Standard | \$30/month  | 15 hrs         | Unlimited  | No           |
| Pro      | \$60/month  | 30 hrs         | Unlimited  | Yes          |
| Mega     | \$120/month | 60 hrs         | Unlimited  | Yes          |

1. **Pricing Tiers**: Midjourney offers four subscription levels ranging from \$10 to \$120 per month, each providing a set amount of Fast GPU hours.
2. **Relax Mode**: Standard and higher plans include unlimited generations through a low-priority queue once Fast hours are exhausted, ensuring users never hit a hard usage wall.
3. **Extra GPU Hours**: Users can purchase additional Fast GPU time for approximately \$4 per hour if they need immediate results after depleting their monthly allocation.
4. **Metering in GPU Seconds**: Usage is tracked by the actual computational time spent on generations, meaning complex renders cost more than simple drafts.
5. **Community Loop**: Active users can earn bonus GPU hours by rating images in the gallery, which helps train models while rewarding the community.

## What Makes It Unique

The Midjourney model is effective because it aligns cost with value and resource usage.

* **GPU-time billing** aligns cost with resource usage, ensuring complex renders are priced fairly compared to simple drafts.
* **Relax Mode** offers an unlimited fallback that reduces churn by maintaining service access even after monthly limits are reached.
* **The Fast vs Relax split** incentivizes upgrades by offering priority processing for users who value speed and instant results.
* **Extra GPU Hours** provide a flexible top-up option for power users who need additional high-priority capacity mid-month.

## Build This with Dodo Payments

You can replicate this model using Dodo Payments by combining subscriptions with usage meters and application-level logic.

<Steps>
  <Step title="Create a Usage Meter">
    First, create a meter to track the GPU seconds used by each customer.

    * **Meter name**: `gpu.fast_seconds`
    * **Aggregation**: **Sum** (sum the `gpu_seconds` property from each event)

    You will only track events where the generation mode is "fast". Relax mode generations are not metered for billing purposes.
  </Step>

  <Step title="Create Subscription Products with Usage Pricing">
    Create your subscription products and attach the usage meter with a free threshold.

    | Product  | Base Price  | Free Threshold (seconds) | Overage Rate        |
    | :------- | :---------- | :----------------------- | :------------------ |
    | Basic    | \$10/month  | 12,000 (3.3 hrs)         | N/A (Hard Cap)      |
    | Standard | \$30/month  | 54,000 (15 hrs)          | \$0.00 (Relax Mode) |
    | Pro      | \$60/month  | 108,000 (30 hrs)         | \$0.00 (Relax Mode) |
    | Mega     | \$120/month | 216,000 (60 hrs)         | \$0.00 (Relax Mode) |

    For the Basic plan, you will disable overage to enforce a hard cap. For the other plans, the "Relax Mode" is handled by your application logic when the meter shows the threshold is exceeded.
  </Step>

  <Step title="Implement Application-Level Relax Mode">
    The key insight is that Relax Mode is not a billing feature. It is your application routing requests to a slower queue when the Dodo usage meter shows the threshold is reached.

    ```typescript theme={null}
    async function handleGenerationRequest(customerId: string, prompt: string) {
      const usage = await getCustomerUsage(customerId, 'gpu.fast_seconds');
      const subscription = await getSubscription(customerId);
      const threshold = getThresholdForPlan(subscription.product_id);
      
      if (usage.current >= threshold) {
        if (subscription.product_id === 'pdt_basic') {
          throw new Error('Fast GPU hours exhausted. Upgrade to Standard for Relax Mode.');
        }
        
        // Relax Mode. Route to low-priority queue
        return await queueGeneration(customerId, prompt, {
          priority: 'low',
          mode: 'relax',
          model: 'standard'
        });
      }
      
      // Fast Mode. Priority processing
      return await queueGeneration(customerId, prompt, {
        priority: 'high',
        mode: 'fast',
        model: 'premium'
      });
    }
    ```
  </Step>

  <Step title="Send Usage Events (Fast Mode Only)">
    Only send usage events to Dodo when a generation is performed in Fast mode.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    async function trackFastGeneration(customerId: string, gpuSeconds: number, jobId: string) {
      // Only track Fast mode generations. Relax mode is free and unlimited
      const client = new DodoPayments({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      });

      await client.usageEvents.ingest({
        events: [{
          event_id: `gen_${jobId}`,
          customer_id: customerId,
          event_name: 'gpu.fast_seconds',
          timestamp: new Date().toISOString(),
          metadata: {
            gpu_seconds: gpuSeconds,
            resolution: '1024x1024',
            mode: 'fast'
          }
        }]
      });
    }
    ```
  </Step>

  <Step title="Sell Extra Fast Hours (One-Time Top-Up)">
    Create a one-time payment product for "Extra Fast GPU Hour" at \$4. When a customer purchases this, you can grant additional threshold or credits in your application.

    ```typescript theme={null}
    // After customer purchases extra hours
    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_extra_gpu_hour', quantity: 5 }
      ],
      customer: { customer_id: customerId },
      return_url: 'https://yourapp.com/dashboard'
    });
    ```
  </Step>

  <Step title="Create Checkout for Subscription">
    Finally, create a checkout session for the subscription plan.

    ```typescript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_mj_standard', quantity: 1 }
      ],
      customer: { email: 'artist@example.com' },
      return_url: 'https://yourapp.com/studio'
    });
    ```
  </Step>
</Steps>

## Accelerate with the Time Range Ingestion Blueprint

The [Time Range Ingestion Blueprint](/developer-resources/ingestion-blueprints/time-range) simplifies GPU time tracking by providing dedicated helpers for duration-based billing.

```bash theme={null}
npm install @dodopayments/ingestion-blueprints
```

```typescript theme={null}
import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

const ingestion = new Ingestion({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'gpu.fast_seconds',
});

// Track generation time after a Fast mode job completes
const startTime = Date.now();
const result = await runGeneration(prompt, settings);
const durationMs = Date.now() - startTime;

await trackTimeRange(ingestion, {
  customerId: customerId,
  durationMs: durationMs,
  metadata: {
    mode: 'fast',
    resolution: '1024x1024',
  },
});
```

The blueprint handles duration conversion and event formatting. You only need to provide the customer ID and the elapsed time.

<Tip>
  The Time Range Blueprint supports milliseconds, seconds, and minutes. See the [full blueprint documentation](/developer-resources/ingestion-blueprints/time-range) for all duration options and best practices.
</Tip>

## The Fast vs Relax Architecture

The dual-queue system works by routing requests based on the current usage state.

```mermaid theme={null}
flowchart TD
    A[Generation Request] --> B{GPU Usage < Threshold?}
    B -->|Yes| C[Fast Queue]
    C --> D[Priority Processing]
    D --> E[Meter GPU Seconds]
    B -->|No| F{Plan Has Relax Mode?}
    F -->|Yes| G[Relax Queue]
    G --> H[Low Priority, Unmetered]
    F -->|No| I[Request Blocked]
```

1. All requests go through your application.
2. The application checks the Dodo usage meter against the plan's free threshold.
3. If the usage is under the threshold, the request goes to the Fast queue and is metered.
4. If the usage is over the threshold, the request goes to the Relax queue, which is unmetered and has lower priority.
5. The Basic plan has no Relax fallback, so requests are blocked once the limit is reached.

<Info>
  Relax Mode is an application-level pattern, not a Dodo billing feature. Dodo tracks your Fast GPU usage and tells you when the threshold is exceeded. Your application decides whether to block the user or route them to a slower queue.
</Info>

## Key Dodo Features Used

<CardGroup>
  <Card title="Subscriptions" icon="calendar" href="/features/subscription">
    Manage recurring billing and plan tiers.
  </Card>

  <Card title="Usage-Based Billing" icon="bolt" href="/features/usage-based-billing/introduction">
    Track and bill based on actual resource consumption.
  </Card>

  <Card title="Event Ingestion" icon="input-pipe" href="/features/usage-based-billing/event-ingestion">
    Send high-volume usage events to the Dodo API.
  </Card>

  <Card title="Meters" icon="gauge" href="/features/usage-based-billing/meters">
    Define how usage events are aggregated and billed.
  </Card>

  <Card title="One-Time Payments" icon="credit-card" href="/features/one-time-payment-products">
    Sell extra hours or top-ups as one-time purchases.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Simplified GPU time tracking with duration-based helpers.
  </Card>
</CardGroup>


# OpenAI Billing Model
Source: https://docs.dodopayments.com/developer-resources/billing-deconstructions/openai

Deconstruct OpenAI's token-based billing with prepaid fiat credits and build the same model using Dodo Payments Credit-Based Billing. This guide covers everything from credit entitlements to usage meters and rate tiers.

OpenAI's billing model is the gold standard for AI companies. It combines prepaid fiat credits for API usage with flat-rate subscriptions for consumer products. This hybrid approach ensures predictable revenue while allowing developers to scale their usage without friction.

## Why OpenAI's Model is the Standard

The AI industry faces unique challenges that traditional SaaS billing doesn't always address. OpenAI's model solves several of these problems simultaneously.

1. **Predictable Revenue and Low Risk**: By requiring prepaid credits for API usage, OpenAI eliminates the risk of users running up massive bills they can't pay. You get the money upfront, and the user gets the service as they use it.
2. **Scalability for Developers**: A \$5 top-up is a low barrier to entry. As their application grows, developers can automate top-ups or buy larger packs. The friction to start is almost zero, but the ceiling for growth is unlimited.
3. **User Psychology**: Denominating credits in fiat currency (USD) instead of abstract "tokens" or "points" makes the value clear. It feels like a bank account for AI services, which builds trust and makes budgeting easier for companies.

## How OpenAI Bills

OpenAI operates two distinct billing models that cater to different user needs.

1. **API (Pay-as-you-go)**: The API uses prepaid fiat-denominated credits. Users top up their accounts with \$5, \$10, \$50, or more. These credits show a dollar value but have no monetary value outside OpenAI. OpenAI bills per-token with different rates for input and output tokens. Credits never expire, and when a user's balance hits \$0, their API calls fail immediately.
2. **ChatGPT Plus, Team, and Enterprise**: These are flat-rate subscriptions. ChatGPT Plus costs \$20 per month, while the Team plan is \$25 per user per month. These plans have soft usage caps where users get downgraded to a smaller model instead of being blocked.
3. **Spend-based rate tiers**: As you spend more total money over time, you unlock higher API rate limits. This is a trust-based access scaling system tied directly to your billing history.

| Model       | Pricing     | Input Tokens | Output Tokens |
| :---------- | :---------- | :----------- | :------------ |
| GPT-4o      | Usage-based | \$2.50 / 1M  | \$10.00 / 1M  |
| GPT-4o-mini | Usage-based | \$0.15 / 1M  | \$0.60 / 1M   |
| o1          | Usage-based | \$15.00 / 1M | \$60.00 / 1M  |

| Plan       | Price            | Type                        |
| :--------- | :--------------- | :-------------------------- |
| Free       | \$0              | Limited access              |
| Plus       | \$20 / mo        | Subscription with soft caps |
| Team       | \$25 / user / mo | Per-seat subscription       |
| Enterprise | Custom           | Invoiced billing            |

## What Makes It Unique

OpenAI's billing strategy has several key characteristics that make it effective for AI services.

* **Fiat-denominated credits**: Credits feel like money because they're denominated in USD. This makes pricing transparent and easy to understand for developers.
* **No expiry**: Never-expiring balances reduce the "use it or lose it" pressure. Users feel comfortable topping up larger amounts because they know the value won't disappear.
* **Multi-dimensional metering**: Input and output tokens are tracked separately but deduct from the same credit balance. This allows OpenAI to price expensive output tokens differently from cheaper input tokens.
* **Trust tiers**: Linking rate limits to total spend encourages users to stay on the platform and rewards long-term customers with better performance.

## Strategic Advantages

This model creates a powerful flywheel. Low entry costs bring in developers. Prepaid credits provide immediate cash flow. Usage-based scaling ensures that as the developers succeed, OpenAI succeeds. The subscription side provides a steady, predictable baseline of revenue from non-developers.

## Build This with Dodo Payments

You can replicate OpenAI's billing model using Dodo Payments. We'll use Credit-Based Billing for the API and standard subscriptions for the ChatGPT Plus side.

<Steps>
  <Step title="Create a Fiat Credit Entitlement">
    Start by creating a credit entitlement in your Dodo Payments dashboard. This will act as the central balance for your users.

    * **Credit Type:** Fiat Credits (USD)
    * **Credit Expiry:** Never
    * **Rollover:** Not needed (since they never expire)
    * **Overage:** Disabled

    Disabling overage ensures that API calls fail when the balance hits \$0, exactly like OpenAI.
  </Step>

  <Step title="Create Top-Up Products">
    Create one-time payment products for different credit packs. You might offer \$5, \$10, \$50, and \$100 options. Attach your fiat credit entitlement to each product.

    Set the credits issued per product in cents. For a \$50 pack, you'll issue 5000 credits.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    });

    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_credit_pack_50', quantity: 1 }
      ],
      customer: { email: 'developer@example.com' },
      return_url: 'https://yourapp.com/dashboard'
    });
    ```
  </Step>

  <Step title="Create Usage Meters">
    Create two separate meters to track token usage.

    * `llm.input_tokens`: Sum aggregation on the `tokens` property.
    * `llm.output_tokens`: Sum aggregation on the `tokens` property.

    Link both meters to your fiat credit entitlement. You'll need to configure the "Meter units per credit" for each.

    ### Calculating Meter Units per Credit

    To match OpenAI's GPT-4o pricing (\$2.50 per 1M input tokens), you need to calculate how many tokens equal \$1 (100 cents).

    * **Input Tokens:** 1,000,000 tokens / \$2.50 = 400,000 tokens per \$1.
    * **Output Tokens:** 1,000,000 tokens / \$10.00 = 100,000 tokens per \$1.

    In the Dodo dashboard, you would set the "Meter units per credit" to 400,000 for input and 100,000 for output.
  </Step>

  <Step title="Send Usage Events">
    After each LLM request, send the usage data to Dodo Payments. You can send both input and output events in a single request.

    ```typescript theme={null}
    await client.usageEvents.ingest({
      events: [{
        event_id: `req_${requestId}`,
        customer_id: customerId,
        event_name: 'llm.input_tokens',
        timestamp: new Date().toISOString(),
        metadata: {
          model: 'gpt-4o',
          tokens: 1500
        }
      }, {
        event_id: `req_${requestId}_out`,
        customer_id: customerId,
        event_name: 'llm.output_tokens',
        timestamp: new Date().toISOString(),
        metadata: {
          model: 'gpt-4o',
          tokens: 800
        }
      }]
    });
    ```
  </Step>

  <Step title="Handle Balance Depletion">
    You should check the user's balance before processing an API request. If the balance is zero or negative, return a 402 error.

    ```typescript theme={null}
    async function checkCreditsBeforeRequest(customerId: string) {
      const balance = await client.creditEntitlements.balances.retrieve(customerId, {
        credit_entitlement_id: 'credit_entitlement_id',
      });

      if (Number(balance.balance) <= 0) {
        throw new Error('Insufficient credits. Please top up your account.');
      }
    }
    ```

    ### Handling Low Balance Webhooks

    Don't wait until the user hits \$0 to notify them. Use webhooks to trigger an email or in-app notification when their balance drops below a certain threshold.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';
    import express from 'express';

    const app = express();
    app.use(express.raw({ type: 'application/json' }));

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    });

    app.post('/webhooks/dodo', async (req, res) => {
      try {
        const event = client.webhooks.unwrap(req.body.toString(), {
          headers: {
            'webhook-id': req.headers['webhook-id'] as string,
            'webhook-signature': req.headers['webhook-signature'] as string,
            'webhook-timestamp': req.headers['webhook-timestamp'] as string,
          },
        });

        if (event.type === 'credit.balance_low') {
          const { customer_id, available_balance } = event.data;
          await sendLowBalanceEmail(customer_id, available_balance);
        }

        res.json({ received: true });
      } catch (error) {
        res.status(401).json({ error: 'Invalid signature' });
      }
    });
    ```

    <Tip>
      OpenAI sends these emails when a user's balance is nearly exhausted, giving them time to top up without service interruption.
    </Tip>
  </Step>

  <Step title="Build the ChatGPT Subscription Side (Optional)">
    If you want to offer a subscription plan like ChatGPT Plus, create a separate subscription product in Dodo Payments. These don't need credit entitlements.

    For a Team plan, use seat-based billing by adding add-ons for each additional user.

    ```typescript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_plus_subscription', quantity: 1 }
      ],
      customer: { email: 'user@example.com' },
      return_url: 'https://yourapp.com/billing'
    });
    ```

    ### Implementing Soft Caps

    To replicate OpenAI's soft caps, you can track usage for your subscription users using the same meters but without linking them to a credit entitlement. In your application logic, check the usage for the current billing period.

    ```typescript theme={null}
    async function checkSubscriptionUsage(customerId: string) {
      const usage = await getUsageForCurrentPeriod(customerId);
      
      if (usage > SOFT_CAP_THRESHOLD) {
        // Route to a smaller model instead of blocking
        return 'gpt-4o-mini';
      }
      
      return 'gpt-4o';
    }
    ```
  </Step>
</Steps>

## Accelerate with the LLM Ingestion Blueprint

The steps above show how to manually construct and send usage events. For production deployments, the [LLM Ingestion Blueprint](/developer-resources/ingestion-blueprints/llm) provides automatic token tracking that wraps your OpenAI client directly.

```bash theme={null}
npm install @dodopayments/ingestion-blueprints
```

```typescript theme={null}
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'llm.chat_completion',
});

const trackedClient = tracker.wrap({
  client: openai,
  customerId: customerId,
});

// Every API call now automatically tracks token usage
const response = await trackedClient.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: prompt }],
});

// inputTokens, outputTokens, and totalTokens are sent automatically
console.log('Tokens used:', response.usage);
```

The blueprint captures `inputTokens`, `outputTokens`, and `totalTokens` from every API response and sends them as event metadata. Configure your meter to aggregate on the appropriate token property.

<Tip>
  The LLM Blueprint supports OpenAI, Anthropic, Groq, Google Gemini, OpenRouter, and the Vercel AI SDK. See the [full blueprint documentation](/developer-resources/ingestion-blueprints/llm) for provider-specific examples and advanced configuration.
</Tip>

## Implementing Spend-Based Rate Tiers

OpenAI's rate tiers are a powerful way to manage capacity. You can implement this by tracking the total lifetime spend of a customer.

1. **Track Lifetime Spend:** Listen for `payment.succeeded` webhooks and update a `total_spend` field in your database for that customer.
2. **Define Tiers:** Create a mapping of spend amounts to rate limits.
   * Tier 1: \$0 - \$50 spend -> 3 RPM
   * Tier 2: \$50 - \$250 spend -> 10 RPM
   * Tier 3: \$250+ spend -> 50 RPM
3. **Enforce Limits:** In your API middleware, check the customer's tier and enforce the corresponding rate limit.

```typescript theme={null}
async function getRateLimitForCustomer(customerId: string) {
  const customer = await db.customers.findUnique({ where: { id: customerId } });
  const totalSpend = customer.total_spend;

  if (totalSpend >= 25000) return TIER_3_LIMITS; // $250.00
  if (totalSpend >= 5000) return TIER_2_LIMITS;  // $50.00
  return TIER_1_LIMITS;
}
```

## Full Implementation Example: The API Proxy

In a real-world scenario, you'll likely have an API proxy that sits between your users and the LLM provider. This proxy handles authentication, credit checks, and usage reporting.

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant P as Your API Proxy
    participant D as Dodo Payments
    participant O as OpenAI
    U->>P: API Request
    P->>D: Check Credit Balance
    D-->>P: Balance Available
    P->>O: Forward Request
    O-->>P: Response + Token Count
    P->>D: Ingest Usage Events
    D-->>P: Events Accepted
    P-->>U: Return Response
```

```typescript theme={null}
import DodoPayments from 'dodopayments';
import OpenAI from 'openai';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export async function handleApiRequest(req, res) {
  const { customerId, prompt, model } = req.body;

  try {
    // 1. Check credit balance
    const balance = await client.creditEntitlements.balances.retrieve(customerId, {
      credit_entitlement_id: 'credit_entitlement_id',
    });

    if (Number(balance.balance) <= 0) {
      return res.status(402).json({ error: 'Insufficient credits. Please top up.' });
    }

    // 2. Call OpenAI
    const completion = await openai.chat.completions.create({
      model: model,
      messages: [{ role: 'user', content: prompt }],
    });

    const { prompt_tokens, completion_tokens } = completion.usage;

    // 3. Ingest usage events to Dodo
    await client.usageEvents.ingest({
      events: [
        {
          event_id: `req_${completion.id}_in`,
          customer_id: customerId,
          event_name: 'llm.input_tokens',
          timestamp: new Date().toISOString(),
          metadata: { model, tokens: prompt_tokens }
        },
        {
          event_id: `req_${completion.id}_out`,
          customer_id: customerId,
          event_name: 'llm.output_tokens',
          timestamp: new Date().toISOString(),
          metadata: { model, tokens: completion_tokens }
        }
      ]
    });

    // 4. Return response to user
    res.json(completion);

  } catch (error) {
    console.error('API Error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
}
```

## Handling Edge Cases

When building a billing system as complex as OpenAI's, you'll encounter several edge cases that need careful handling.

### Race Conditions

If a user has a very low balance and sends multiple requests simultaneously, they might exceed their credit limit before the first event is processed. To prevent this, you can implement a small "buffer" or use a distributed lock on the customer's balance during the request.

### Event Ingestion Latency

Dodo Payments processes events asynchronously. This means there might be a slight delay between an API call and the credit deduction. For most use cases, this is acceptable. If you need strict real-time enforcement, you can maintain a local cache of the user's balance and update it optimistically.

### Refund Handling

If you refund a credit pack purchase, Dodo Payments will automatically handle the credit entitlement if configured. However, you should ensure your application logic reflects this change immediately to prevent users from using credits they no longer have.

### Multi-Model Support

If you support multiple models with different pricing, you have two options:

1. **Separate Meters:** Create separate meters for each model (e.g., `gpt-4o.input_tokens`, `gpt-4o-mini.input_tokens`).
2. **Weighted Events:** Use a single meter but multiply the `tokens` value by a weight before sending it to Dodo. For example, if GPT-4o is 10x more expensive than GPT-4o-mini, you could send 10x the tokens for GPT-4o requests.

OpenAI uses the separate meter approach internally to maintain clear records of usage per model.

## Architecture Overview

```mermaid theme={null}
flowchart LR
    A[Buy Credit Pack] --> B[Credits Added to Balance]
    B --> C[API Request]
    C --> D[Count Tokens]
    D --> E[Deduct Credits]
    E --> F{Balance > 0?}
    F -->|Yes| C
    F -->|No| G[Block API Calls]
    G --> A
```

The meters track tokens and deduct the corresponding value from the user's credit balance based on your configured rates.

## Conclusion

Replicating OpenAI's billing model with Dodo Payments gives you the best of both worlds: the flexibility of usage-based billing and the predictability of prepaid credits. By following this guide, you can build a billing system that scales with your users while protecting your margins.

Whether you're building the next big LLM or a niche AI tool, these patterns will help you create a professional, developer-friendly experience. This approach ensures that your billing infrastructure is as scalable and reliable as the AI models you're delivering to your customers.

## Key Dodo Features Used

Explore the features that make this implementation possible.

<CardGroup>
  <Card title="Credit-Based Billing" icon="coins" href="/features/credit-based-billing">
    Manage prepaid fiat credits and entitlements for your users.
  </Card>

  <Card title="Usage-Based Billing" icon="chart-line" href="/features/usage-based-billing/introduction">
    Track granular usage like tokens and bill for it in real-time.
  </Card>

  <Card title="One-Time Payments" icon="credit-card" href="/features/one-time-payment-products">
    Sell credit packs and top-ups with a simple checkout flow.
  </Card>

  <Card title="Event Ingestion" icon="bolt" href="/features/usage-based-billing/event-ingestion">
    Send high-volume usage data to Dodo Payments with ease.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/credit">
    Stay updated on credit balance changes and low balance alerts.
  </Card>

  <Card title="LLM Ingestion Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Automatic token tracking for OpenAI and other LLM providers.
  </Card>
</CardGroup>


# Replicate Billing Model
Source: https://docs.dodopayments.com/developer-resources/billing-deconstructions/replicate

Deconstruct Replicate's per-second hardware-specific billing and build the same pure usage-based model using Dodo Payments.

Replicate is a platform for running open-source machine learning models in the cloud. Their billing model is one of the purest examples of usage-based pricing in the AI industry. There is no monthly subscription fee and no flat rate per model run. Instead, they bill for the exact amount of compute time consumed, down to the second, with rates that vary based on the underlying hardware.

This approach works well for AI workloads because execution times are unpredictable. A single user might run a lightweight model for a few seconds or a massive generative model for several minutes. By tying cost to compute resources rather than the model itself, Replicate keeps pricing transparent and scalable.

## How Replicate Bills

Replicate's pricing is decoupled from the specific model being run. Whether you're generating an image with SDXL or running Llama 3, the billing is determined by the hardware tier and the duration of execution. This lets them host thousands of open-source models without needing a separate pricing plan for each one.

| Hardware               | Price per Second | Price per Hour |
| :--------------------- | :--------------- | :------------- |
| NVIDIA CPU             | \$0.000100       | \$0.36         |
| NVIDIA T4 GPU          | \$0.000225       | \$0.81         |
| NVIDIA A40 GPU         | \$0.000575       | \$2.07         |
| NVIDIA A40 (Large) GPU | \$0.000725       | \$2.61         |
| NVIDIA A100 (40GB) GPU | \$0.001150       | \$4.14         |
| NVIDIA A100 (80GB) GPU | \$0.001400       | \$5.04         |

```mermaid theme={null}
flowchart TD
    A[Model Execution Completes] --> B[Measure Execution Time]
    B --> C{Which Hardware?}
    C -->|CPU| D[CPU Meter]
    C -->|T4 GPU| E[T4 GPU Meter]
    C -->|A40 GPU| F[A40 GPU Meter]
    C -->|A40 Large GPU| G[A40 Large GPU Meter]
    C -->|A100 40GB GPU| H[A100 40GB GPU Meter]
    C -->|A100 80GB GPU| I[A100 80GB GPU Meter]
    D --> J[Bill per Second at Tier Rate]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
```

1. **Hardware-Specific Rates**: The cost per second varies based on the compute resources required. Each hardware tier has a different price point.
2. **Pure Usage-Based Model**: There are no monthly fees, no overages, and no limits. Users are billed for exact compute time (e.g., "12.4 seconds on an A100") rather than per-generation.
3. **Per-Second Granularity**: Traditional cloud providers bill by the hour or minute, leading to waste on short-lived tasks. Per-second billing eliminates this inefficiency for both small experiments and large production workloads.

<Info>
  Cold starts are also billable. The first request to a model often takes 10-30 seconds to load the model into memory. This loading time is billed at the same rate as execution time.
</Info>

## What Makes It Unique

* **Hardware-specific metering:** The same model costs more on better hardware. Users choose between speed and cost. A T4 GPU works for non-time-sensitive tasks, while an A100 handles real-time applications.
* **Per-second granularity:** Billing is calculated to the second, so users are never overcharged for short tasks.
* **No subscription:** Zero commitment to start. It scales infinitely with usage, making it ideal for startups and developers experimenting with different models.
* **Model-agnostic:** The billing logic stays the same regardless of task type (image generation, text processing, audio transcription, or video synthesis). This lets the platform support a vast model ecosystem without complex pricing tables.

## Build This with Dodo Payments

You can replicate this billing model using Dodo Payments' usage-based billing features. The key is to use multiple meters to track different hardware tiers and attach them to a single product.

<Steps>
  <Step title="Create Usage Meters (One Per Hardware Class)">
    Create separate meters for each hardware tier. Each hardware type has a different cost per second, so independent metering lets Dodo price each tier differently and provide itemized billing.

    | Meter Name            | Event Name              | Aggregation | Property            |
    | :-------------------- | :---------------------- | :---------- | :------------------ |
    | CPU Compute           | `compute.cpu`           | Sum         | `execution_seconds` |
    | GPU T4 Compute        | `compute.gpu_t4`        | Sum         | `execution_seconds` |
    | GPU A40 Compute       | `compute.gpu_a40`       | Sum         | `execution_seconds` |
    | GPU A40 Large Compute | `compute.gpu_a40_large` | Sum         | `execution_seconds` |
    | GPU A100 40GB Compute | `compute.gpu_a100_40`   | Sum         | `execution_seconds` |
    | GPU A100 80GB Compute | `compute.gpu_a100_80`   | Sum         | `execution_seconds` |

    The `Sum` aggregation on the `execution_seconds` property calculates total compute time per hardware tier over the billing period.
  </Step>

  <Step title="Create a Usage-Based Product">
    Create a new product in the Dodo Payments dashboard:

    * **Pricing type:** Usage Based Billing
    * **Base Price:** \$0/month (no subscription fee)
    * **Billing frequency:** Monthly

    Attach all meters with their per-unit pricing:

    | Meter                   | Price Per Unit (per second) |
    | :---------------------- | :-------------------------- |
    | compute.cpu             | \$0.000100                  |
    | compute.gpu\_t4         | \$0.000225                  |
    | compute.gpu\_a40        | \$0.000575                  |
    | compute.gpu\_a40\_large | \$0.000725                  |
    | compute.gpu\_a100\_40   | \$0.001150                  |
    | compute.gpu\_a100\_80   | \$0.001400                  |

    Set the **Free Threshold** to 0 for all meters. Every second of execution is billable.
  </Step>

  <Step title="Send Usage Events">
    Send usage events to Dodo whenever a model execution completes. Include a unique `event_id` for each prediction to ensure idempotency.

    ```typescript theme={null}
    import DodoPayments from 'dodopayments';

    type HardwareTier = 'cpu' | 'gpu_t4' | 'gpu_a40' | 'gpu_a40_large' | 'gpu_a100_40' | 'gpu_a100_80';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    });

    async function trackModelExecution(
      customerId: string,
      modelId: string,
      hardware: HardwareTier,
      executionSeconds: number,
      predictionId: string
    ) {
      const eventName = `compute.${hardware}`;

      await client.usageEvents.ingest({
        events: [{
          event_id: `pred_${predictionId}`,
          customer_id: customerId,
          event_name: eventName,
          timestamp: new Date().toISOString(),
          metadata: {
            execution_seconds: executionSeconds,
            model_id: modelId,
            hardware: hardware
          }
        }]
      });
    }

    // Example: SDXL image generation on A100
    await trackModelExecution(
      'cus_abc123',
      'stability-ai/sdxl',
      'gpu_a100_80',
      8.3,  // 8.3 seconds of A100 time
      'pred_xyz789'
    );
    ```
  </Step>

  <Step title="Measure Execution Time Precisely">
    Wrap your model execution with precise timing using `performance.now()`. Round to the nearest tenth of a second for billing.

    ```typescript theme={null}
    async function runModelWithMetering(
      customerId: string,
      modelId: string,
      hardware: HardwareTier,
      input: Record<string, unknown>
    ) {
      const predictionId = `pred_${Date.now()}`;
      const startTime = performance.now();

      try {
        const result = await executeModel(modelId, input, hardware);
        const executionSeconds = (performance.now() - startTime) / 1000;
        const billedSeconds = Math.round(executionSeconds * 10) / 10;

        await trackModelExecution(
          customerId,
          modelId,
          hardware,
          billedSeconds,
          predictionId
        );

        return result;
      } catch (error) {
        // Still bill for compute time even on failure
        const executionSeconds = (performance.now() - startTime) / 1000;
        if (executionSeconds > 1) {
          await trackModelExecution(
            customerId,
            modelId,
            hardware,
            Math.round(executionSeconds * 10) / 10,
            predictionId
          );
        }
        throw error;
      }
    }
    ```
  </Step>

  <Step title="Create Checkout">
    When a user signs up, create a checkout session for the usage-based product. Dodo handles recurring billing and invoicing automatically.

    ```typescript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [
        { product_id: 'pdt_compute_payg', quantity: 1 }
      ],
      customer: { email: 'ml-engineer@company.com' },
      return_url: 'https://yourplatform.com/dashboard'
    });
    ```
  </Step>
</Steps>

## Accelerate with the Time Range Ingestion Blueprint

The [Time Range Ingestion Blueprint](/developer-resources/ingestion-blueprints/time-range) simplifies per-second compute tracking. Create one ingestion instance per hardware tier and use `trackTimeRange` for cleaner event submission.

```bash theme={null}
npm install @dodopayments/ingestion-blueprints
```

```typescript theme={null}
import { Ingestion, trackTimeRange } from '@dodopayments/ingestion-blueprints';

// Create one ingestion instance per hardware tier
function createHardwareIngestion(hardware: string) {
  return new Ingestion({
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'live_mode',
    eventName: `compute.${hardware}`,
  });
}

const ingestions: Record<string, Ingestion> = {
  cpu: createHardwareIngestion('cpu'),
  gpu_t4: createHardwareIngestion('gpu_t4'),
  gpu_a40: createHardwareIngestion('gpu_a40'),
  gpu_a40_large: createHardwareIngestion('gpu_a40_large'),
  gpu_a100_40: createHardwareIngestion('gpu_a100_40'),
  gpu_a100_80: createHardwareIngestion('gpu_a100_80'),
};

// Track execution after a model run completes
const startTime = performance.now();
const result = await executeModel(modelId, input, hardware);
const durationMs = performance.now() - startTime;

await trackTimeRange(ingestions[hardware], {
  customerId: customerId,
  durationMs: durationMs,
  metadata: {
    model_id: modelId,
    hardware: hardware,
  },
});
```

The blueprint handles duration formatting and event construction. Combined with per-hardware ingestion instances, this pattern cleanly maps to Replicate's multi-tier metering.

<Tip>
  For long-running jobs, combine the Time Range Blueprint with interval-based heartbeat tracking. See the [full blueprint documentation](/developer-resources/ingestion-blueprints/time-range) for advanced patterns.
</Tip>

## Cost Estimation for Users

Since usage-based billing can be unpredictable, provide users with cost estimates before they run a model. This reduces surprise bills and builds trust.

### Example Cost Calculations

| Model           | Hardware  | Avg Time | Cost Per Run |
| :-------------- | :-------- | :------- | :----------- |
| SDXL (image)    | A100 80GB | \~8 sec  | \~\$0.0112   |
| Llama 3 (text)  | A100 40GB | \~3 sec  | \~\$0.0035   |
| Whisper (audio) | GPU T4    | \~15 sec | \~\$0.0034   |

### Building a Cost Calculator

```typescript theme={null}
function estimateCost(hardware: HardwareTier, estimatedSeconds: number): number {
  const rates: Record<HardwareTier, number> = {
    'cpu': 0.000100,
    'gpu_t4': 0.000225,
    'gpu_a40': 0.000575,
    'gpu_a40_large': 0.000725,
    'gpu_a100_40': 0.001150,
    'gpu_a100_80': 0.001400
  };

  return Number((rates[hardware] * estimatedSeconds).toFixed(4));
}

// Show the user before running: "This will cost approximately $0.0098"
const estimate = estimateCost('gpu_a100_80', 8.5);
```

## Enterprise: Reserved Capacity

For enterprise customers who need guaranteed availability and no cold starts, Replicate offers "Private Instances" at a fixed hourly rate.

With Dodo Payments, model this as a subscription product:

* **Product Type:** Subscription
* **Price:** Fixed monthly price (e.g., "Reserved A100 Instance - \$500/month")
* **Billing Cycle:** Monthly

You can still send usage events for monitoring and analytics, but the subscription covers the cost. As a user's volume grows, switching from pay-as-you-go to reserved capacity often becomes more cost-effective.

## Advanced: Heartbeat Metering

For tasks that take several minutes or hours, sending a single event at the end is risky. If the process crashes, you lose the usage data. A better approach is to send usage events every 30-60 seconds during execution.

```typescript theme={null}
async function runLongTaskWithHeartbeat(
  customerId: string,
  modelId: string,
  hardware: HardwareTier
) {
  const predictionId = `pred_${Date.now()}`;
  let totalSeconds = 0;

  const heartbeatInterval = setInterval(async () => {
    try {
      await trackModelExecution(
        customerId,
        modelId,
        hardware,
        30,
        `${predictionId}_${totalSeconds}`
      );
      totalSeconds += 30;
    } catch (error) {
      console.error('Heartbeat tracking failed:', error, { predictionId, totalSeconds });
    }
  }, 30000);

  try {
    await executeLongTask();
  } finally {
    clearInterval(heartbeatInterval);
  }
}
```

## Key Dodo Features Used

<CardGroup>
  <Card title="Usage-Based Billing" icon="chart-line" href="/features/usage-based-billing/introduction">
    Set up products that bill based on consumption.
  </Card>

  <Card title="Meters" icon="gauge" href="/features/usage-based-billing/meters">
    Define the metrics you want to track and bill for.
  </Card>

  <Card title="Event Ingestion" icon="bolt" href="/features/usage-based-billing/event-ingestion">
    Send usage data to Dodo in real-time.
  </Card>

  <Card title="Subscriptions" icon="calendar" href="/features/subscription">
    Manage recurring billing for reserved capacity and enterprise plans.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Per-second compute tracking with duration helpers.
  </Card>
</CardGroup>


# Billing SDK
Source: https://docs.dodopayments.com/developer-resources/billingsdk

Complete billing infrastructure for modern web applications with React components, CLI tooling, and full-stack integration

<Frame>
  <iframe title="Billing SDK | Dodo Payments" />
</Frame>

Billing SDK is a comprehensive open-source solution that provides complete billing infrastructure for modern web applications. It includes React components, CLI tooling, and full-stack integration support for multiple frameworks with Dodo Payments.

## Overview

Billing SDK offers:

* **React Components**: Pre-built, customizable billing components for React applications
* **CLI Tooling**: Command-line interface for project initialization and component management
* **Framework Support**: Integration with Next.js, Express.js, Hono, Fastify, and React
* **Payment Provider**: Full integration with Dodo Payments

## Quick Start

Get started with Billing SDK in minutes:

<Steps>
  <Step title="Install the CLI">
    Use npx to run the CLI without installation:

    ```bash theme={null}
    npx @billingsdk/cli --help
    ```

    Or install it globally for frequent use:

    ```bash theme={null}
    npm install -g @billingsdk/cli
    ```
  </Step>

  <Step title="Initialize a Project">
    Run the interactive setup to create a new billing project:

    ```bash theme={null}
    npx @billingsdk/cli init
    ```

    You'll be prompted to select:

    * Your preferred framework (Next.js, Express.js, Hono, Fastify, React)
    * Your payment provider (Dodo Payments)
  </Step>

  <Step title="Add Components">
    Add individual billing components to your project:

    ```bash theme={null}
    npx @billingsdk/cli add pricing-table-one
    npx @billingsdk/cli add subscription-management
    ```
  </Step>
</Steps>

## Supported Frameworks

Billing SDK supports multiple frameworks with comprehensive Dodo Payments integration:

| Framework  | Dodo Payments |
| ---------- | ------------- |
| Next.js    | ✅ Yes         |
| Express.js | ✅ Yes         |
| Hono       | ✅ Yes         |
| React      | ✅ Yes         |
| Fastify    | ✅ Yes         |

## CLI Commands

### `@billingsdk/cli init`

Initialize a new billing project with complete setup including framework configuration, Dodo Payments integration, and essential dependencies.

**What it does:**

1. **Framework Selection**: Choose your preferred framework
2. **Template Installation**: Downloads and installs framework-specific templates with Dodo Payments integration
3. **Dependency Management**: Automatically installs required dependencies
4. **File Generation**: Creates necessary configuration files and boilerplate code

**Example:**

```bash theme={null}
npx @billingsdk/cli init
```

### `@billingsdk/cli add`

Add individual billing components to your existing project using the shadcn/ui registry system.

**Examples:**

```bash theme={null}
# Add a pricing table
npx @billingsdk/cli add pricing-table-one

# Add subscription management
npx @billingsdk/cli add subscription-management

# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle
```

**What happens:**

1. Downloads the component configuration from the registry
2. Installs the component files in your `components/billingsdk/` directory
3. Updates your project configuration if needed
4. Installs any additional dependencies

## Generated Files Structure

After running `init`, you'll get a complete project structure with:

* **API Routes**: Comprehensive endpoints for checkout, customers, products, subscriptions, and webhooks
* **Hooks**: React hooks for billing operations (if using React/Next.js)
* **Library Files**: Payment provider client initialization and utilities
* **Environment Configuration**: Example environment variable files

### Next.js Example Structure

```
your-project/
├── app/api/
│   └── (dodopayments)/
│       ├── checkout/route.ts
│       ├── customer/route.ts
│       ├── customer/payments/route.ts
│       ├── customer/subscriptions/route.ts
│       ├── product/route.ts
│       ├── products/route.ts
│       └── webhook/route.ts
├── hooks/
│   └── useBilling.ts
├── lib/
│   └── dodopayments.ts
└── .env.example
```

## Environment Configuration

Configure your environment variables after initialization:

```bash theme={null}
# DodoPayments
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

<Warning>
  Always store your API keys securely using environment variables. Never commit them to version control.
</Warning>

## Available Components

Billing SDK provides a comprehensive collection of React components:

* **Pricing Tables**: Multiple variants for displaying product pricing
* **Subscription Management**: Components for managing customer subscriptions
* **Usage Monitoring**: Visual components for tracking usage-based billing
* **Checkout Components**: Pre-built checkout flows
* **Customer Portal**: Components for customer self-service

## Open Source

Billing SDK is built on open-source principles:

* 🔍 **Transparency**: Full visibility into how components work
* 🤝 **Community**: Built by developers, for developers
* 🔒 **Security**: Open code means better security through peer review
* 📈 **Innovation**: Faster iteration through community contributions

<Info>
  Billing SDK is released under the GNU General Public License (GPL), ensuring the project remains open and free.
</Info>

## Getting Help

Need assistance with Billing SDK?

* **GitHub Issues**: [Open an issue](https://github.com/dodopayments/billingsdk/issues)
* **Documentation**: Visit [billingsdk.com/docs](https://billingsdk.com/docs)
* **LLMs Full Documentation**: [billingsdk.com/llms-full.txt](https://billingsdk.com/llms-full.txt)

## Contributing

We welcome contributions! See our [contribution guide](https://billingsdk.com/docs/contribution-open-source) for details on:

* Reporting bugs
* Requesting features
* Submitting pull requests
* Adding new components
* Improving documentation

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://billingsdk.com/docs">
    Complete guide to Billing SDK with examples and best practices
  </Card>

  <Card title="CLI Reference" icon="terminal" href="https://billingsdk.com/docs/cli">
    Detailed CLI documentation for all commands and options
  </Card>

  <Card title="Component Library" icon="boxes-stacked" href="https://billingsdk.com/docs/components">
    Browse all available components with live examples
  </Card>
</CardGroup>


# Build a Prepaid Email Service with Credit-Based Billing
Source: https://docs.dodopayments.com/developer-resources/build-a-prepaid-email-service-with-credit-based-billing

Build MailKit, a transactional email platform with prepaid email credits. A monthly subscription plan, one-time top-up packs, instant credit deduction on every send, and proactive low-balance alerts powered by Resend and Dodo Payments.

<Tip>
  <strong>Let Sentra write your integration code for you.</strong><br />
  Use our AI assistant in VS Code, Cursor, or Windsurf to generate SDK/API code, webhook handlers, and more, just by describing what you want.

  <a href="https://dodopayments.com/sentra">
    Try Sentra: AI-Powered Integration →
  </a>
</Tip>

In this tutorial, you'll build **MailKit**, a transactional email platform where customers pay upfront for a pool of email credits. The plan grants a monthly email allowance; when customers run low, they can buy a top-up pack instead of waiting for the next cycle. Every send deducts one credit automatically.

<Note>
  This tutorial uses [Resend](https://resend.com) as the email provider. Its free tier (3,000 emails/month) is enough to build and test the entire flow without a paid account. The pattern works with any provider; swap `resend.emails.send` for SendGrid, Postmark, SES, or your own SMTP relay.
</Note>

By the end of this tutorial, you'll know how to:

* Create a custom credit entitlement (emails) in your dashboard
* Attach credits to a subscription plan and a one-time top-up product
* Send real emails via Resend and debit one credit per send via a ledger entry
* Query a live credit balance from your frontend
* Verify Dodo webhooks correctly and handle `credit.balance_low` to nudge customers before they hit zero

## What We're Building

Here's the pricing model for MailKit:

| Product      | Price        | Emails             |
| ------------ | ------------ | ------------------ |
| MailKit Plan | \$19/month   | 5,000 emails/cycle |
| Top-Up Pack  | \$9 one-time | +5,000 emails      |

The unit is **one email = one credit**. Customers don't have to think about tokens, batches, or weighted units. They just see "you have 4,231 emails left this month."

<Info>
  Before you start, make sure you have:

  * A Dodo Payments account (test mode is fine)
  * A free [Resend](https://resend.com) account and API key
  * Node.js 18+ and basic TypeScript familiarity
</Info>

## Step 1: Create Your Email Credit Entitlement

The credit entitlement defines the unit your platform sells: in this case, one email send.

<Frame>
  <img alt="Credits listing page" />
</Frame>

<Steps>
  <Step title="Open the Credits section">
    1. Log into your Dodo Payments dashboard
    2. Click **Products** in the left sidebar
    3. Select the **Credits** tab
    4. Click **Create Credit**
  </Step>

  <Step title="Configure the credit unit">
    Fill in the credit details:

    **Credit Name**: `Email Credits`

    **Credit Type**: Select **Custom Unit**

    **Unit Name**: `email`

    **Precision**: `0` (an email is always a whole unit; you can't send half an email)

    **Credit Expiry**: `30 days` (each cycle's allowance resets)

    <Warning>
      Precision cannot be changed after creation. For discrete units like emails, messages, or sessions, `0` is correct.
    </Warning>
  </Step>

  <Step title="Leave the other defaults as-is">
    We won't enable rollover or overage in this cookbook; the goal is the simplest possible CBB flow. You can revisit these on the credit attachment later.
  </Step>

  <Step title="Save and copy the credit ID">
    Click **Create Credit**. Open the credit and copy its ID. You'll need it for backend balance queries. It looks like `cent_xxxxxxxxxxxx`.

    <Check>
      Your `Email Credits` entitlement is ready. Next: the products that grant credits to customers.
    </Check>
  </Step>
</Steps>

## Step 2: Create the Plan and Top-Up Pack

You'll create two products: a recurring **Subscription** plan and a **Single Payment** top-up. The plan grants 5,000 emails each cycle; the top-up adds another 5,000 on demand. Both attach the same `Email Credits` entitlement.

<Tip>
  This cookbook deducts credits with direct ledger entries instead of usage-based meters. Ledger entries are immediate (the balance updates in milliseconds), need no extra setup, and are the right fit when one user action equals exactly one credit. If you'd prefer auto-deduction from ingested usage events (handy for weighted units like "tokens" or "MB processed"), see [Credit-Based Billing → Usage Billing with Credits](/features/credit-based-billing) for the meter-based pattern.
</Tip>

### MailKit Plan (\$19/month, 5,000 emails)

<Steps>
  <Step title="Create the subscription">
    1. Go to **Products → Create Product**
    2. Fill in the product details:

    **Product Name**: `MailKit Plan`

    **Description**: `5,000 transactional emails per month.`

    3. Select **Subscription** as the product type
    4. Set the recurring price:

    **Recurring Price**: `19.00`

    **Billing Cycle**: `Monthly`

    **Currency**: `USD`
  </Step>

  <Step title="Attach the email credit entitlement">
    Scroll to **Entitlements → Credits → Attach** and configure:

    **Credit Entitlement**: `Email Credits`

    **Credits issued per billing cycle**: `5000`

    **Low Balance Threshold**: `20` (percent; fires `credit.balance_low` when the balance drops below 20% of the cycle allowance, i.e. 1,000 emails)

    **Import Default Credit Settings**: enabled (uses the 30-day expiry from Step 1)

    Click **Add to Product**, then **Save** the product. Copy the product ID (`pdt_xxxxxxxxxxxx`).

    <Check>
      Plan: \$19/month → 5,000 emails refreshed each cycle.
    </Check>
  </Step>
</Steps>

### Top-Up Pack (\$9 one-time, 5,000 emails)

<Steps>
  <Step title="Create a one-time product">
    1. Go to **Products → Create Product**
    2. Fill in the product details:

    **Product Name**: `Email Top-Up Pack`

    **Description**: `Add 5,000 emails to your MailKit balance instantly.`

    3. Select **Single Payment** as the product type
    4. Set the pricing:

    **Price**: `9.00`

    **Currency**: `USD`
  </Step>

  <Step title="Attach the credit grant">
    In **Entitlements → Credits → Attach**:

    * Credit Entitlement: `Email Credits`
    * Credits issued: `5000`

    <Info>
      One-time products grant credits with their own expiry (30 days from purchase, per Step 1). Top-ups stack on top of subscription credits; they don't replace them.
    </Info>

    Save and copy the product ID.

    <Check>
      Top-Up Pack: \$9 → +5,000 emails, available immediately.
    </Check>
  </Step>
</Steps>

## Step 3: Set Up the Backend

Now build the Express server that handles checkout, sending, balance queries, and webhooks.

<Steps>
  <Step title="Initialize the project">
    ```bash theme={null}
    mkdir mailkit && cd mailkit
    npm init -y
    npm install dodopayments resend express dotenv
    npm install -D tsx @types/node @types/express
    ```

    Add a dev script to `package.json`:

    ```json theme={null}
    {
      "scripts": {
        "dev": "tsx watch server.ts"
      }
    }
    ```

    <Tip>
      [`tsx`](https://tsx.is) runs TypeScript directly without a build step or `tsconfig.json`, which is perfect for a tutorial. For production, add a `tsconfig.json` and a `build` script.
    </Tip>
  </Step>

  <Step title="Configure environment variables">
    Create `.env`:

    ```bash .env theme={null}
    # Dodo Payments
    DODO_PAYMENTS_API_KEY=your_dodo_test_api_key
    DODO_WEBHOOK_KEY=your_dodo_webhook_signing_key
    CREDIT_ENTITLEMENT_ID=cent_xxxxxxxxxxxx
    PLAN_PRODUCT_ID=pdt_xxxxxxxxxxxx
    TOPUP_PRODUCT_ID=pdt_xxxxxxxxxxxx

    # Resend
    RESEND_API_KEY=re_xxxxxxxxxxxx

    # App
    BASE_URL=http://localhost:3000
    PORT=3000
    ```

    You'll fill in the `DODO_WEBHOOK_KEY` in Step 4 after creating the endpoint. The Resend API key comes from [resend.com/api-keys](https://resend.com/api-keys).

    <Warning>
      Add `.env` to `.gitignore` immediately. Never commit API keys.
    </Warning>
  </Step>

  <Step title="Build the server">
    Create `server.ts` in the project root:

    <CodeGroup>
      ```typescript server.ts expandable theme={null}
      import 'dotenv/config';
      import express, { Request, Response } from 'express';
      import DodoPayments from 'dodopayments';
      import { Resend } from 'resend';

      const app = express();

      const dodo = new DodoPayments({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
        webhookKey: process.env.DODO_WEBHOOK_KEY!,
        environment: 'test_mode',
      });

      const resend = new Resend(process.env.RESEND_API_KEY!);

      const CREDIT_ENTITLEMENT_ID = process.env.CREDIT_ENTITLEMENT_ID!;
      const BASE_URL = process.env.BASE_URL!;

      // ---------------------------------------------------------------
      // Webhook endpoint MUST receive the raw body for signature
      // verification. Register it BEFORE express.json().
      // ---------------------------------------------------------------
      app.post(
        '/webhooks/dodo',
        express.raw({ type: 'application/json' }),
        async (req: Request, res: Response) => {
          const headers = {
            'webhook-id': req.headers['webhook-id'] as string,
            'webhook-signature': req.headers['webhook-signature'] as string,
            'webhook-timestamp': req.headers['webhook-timestamp'] as string,
          };

          let event: any;
          try {
            event = await dodo.webhooks.unwrap(req.body.toString('utf8'), { headers });
          } catch (err) {
            console.error('Webhook signature verification failed:', err);
            return res.status(401).json({ error: 'invalid signature' });
          }

          switch (event.type) {
            case 'credit.balance_low': {
              const { customer_id, credit_entitlement_name, available_balance, threshold_percent } =
                event.data;
              console.log(
                `[low-balance] ${customer_id} has ${available_balance} ${credit_entitlement_name} ` +
                  `left (under ${threshold_percent}%)`
              );
              await notifyCustomerLowBalance(customer_id, Number(available_balance));
              break;
            }
            case 'credit.added':
              console.log('[credit.added]', event.data);
              break;
            case 'credit.rolled_over':
              console.log('[rolled_over]', event.data);
              break;
          }

          res.json({ received: true });
        }
      );

      // JSON parsing for everything else.
      app.use(express.json());

      // ---------------------------------------------------------------
      // POST /checkout/subscribe → start the MailKit subscription.
      // ---------------------------------------------------------------
      app.post('/checkout/subscribe', async (req, res) => {
        const { email, name } = req.body as { email: string; name: string };

        const session = await dodo.checkoutSessions.create({
          product_cart: [{ product_id: process.env.PLAN_PRODUCT_ID!, quantity: 1 }],
          customer: { email, name },
          return_url: `${BASE_URL}/?subscribed=1`,
        });

        res.json({ checkout_url: session.checkout_url });
      });

      // ---------------------------------------------------------------
      // POST /checkout/topup → buy a 5,000-email top-up for an existing
      // customer. In a real app, customer_id is resolved from the
      // authenticated session, never trusted from request input.
      // ---------------------------------------------------------------
      app.post('/checkout/topup', async (req, res) => {
        const { customer_id } = req.body as { customer_id: string };

        const session = await dodo.checkoutSessions.create({
          product_cart: [{ product_id: process.env.TOPUP_PRODUCT_ID!, quantity: 1 }],
          customer: { customer_id },
          return_url: `${BASE_URL}/?topped_up=1`,
        });

        res.json({ checkout_url: session.checkout_url });
      });

      // ---------------------------------------------------------------
      // GET /credits/:customerId → live balance for the dashboard widget.
      // ---------------------------------------------------------------
      app.get('/credits/:customerId', async (req, res) => {
        const balance = await dodo.creditEntitlements.balances.retrieve(req.params.customerId, {
          credit_entitlement_id: CREDIT_ENTITLEMENT_ID,
        });

        res.json({ balance: balance.balance });
      });

      // ---------------------------------------------------------------
      // POST /send → send an email via Resend, then write a ledger entry
      // to debit 1 credit from the customer's balance. The deduction is
      // instant; the next /credits call reflects it.
      // ---------------------------------------------------------------
      app.post('/send', async (req, res) => {
        const { customer_id, to, subject, html } = req.body as {
          customer_id: string;
          to: string;
          subject: string;
          html: string;
        };

        // 1. Pre-flight balance check: refuse to send if the balance is at zero.
        const balance = await dodo.creditEntitlements.balances.retrieve(customer_id, {
          credit_entitlement_id: CREDIT_ENTITLEMENT_ID,
        });

        if (Number(balance.balance) <= 0) {
          return res.status(402).json({
            error: 'No email credits remaining. Buy a top-up pack or upgrade your plan.',
          });
        }

        // 2. Send via Resend.
        const { data, error } = await resend.emails.send({
          from: 'MailKit <onboarding@resend.dev>', // swap for your verified domain
          to: [to],
          subject,
          html,
        });

        if (error) {
          return res.status(500).json({ error: error.message });
        }

        // 3. Debit 1 credit. Resend's message id is the idempotency key, so if
        //    the client retries this request, Dodo deduplicates and the
        //    customer is only debited once for that send.
        await dodo.creditEntitlements.balances.createLedgerEntry(customer_id, {
          credit_entitlement_id: CREDIT_ENTITLEMENT_ID,
          amount: '1',
          entry_type: 'debit',
          reason: `email send ${data!.id}`,
          idempotency_key: data!.id,
        });

        res.json({ id: data!.id });
      });

      async function notifyCustomerLowBalance(customerId: string, available: number) {
        // In production: send an email to the account owner, push a banner,
        // open an in-app modal, etc. For the demo we just log.
        console.log(`[NOTIFY] ${customerId}: ${available} emails left. Consider topping up.`);
      }

      app.use(express.static('public'));

      const port = Number(process.env.PORT) || 3000;
      app.listen(port, () => {
        console.log(`MailKit running on http://localhost:${port}`);
      });
      ```
    </CodeGroup>

    <Warning>
      **Webhook body must be raw.** `express.json()` parses and re-serializes the body, which breaks signature verification. Define `/webhooks/dodo` with `express.raw()` *before* the `app.use(express.json())` line.
    </Warning>

    <Check>
      Backend ready: subscribe, top-up, balance, send, and webhook handler all wired up.
    </Check>
  </Step>

  <Step title="Add a demo UI">
    Create `public/index.html`:

    <CodeGroup>
      ```html public/index.html expandable theme={null}
      <!doctype html>
      <html>
        <head>
          <title>MailKit Demo</title>
          <style>
            body {
              font-family: system-ui, -apple-system, sans-serif;
              max-width: 720px;
              margin: 40px auto;
              padding: 0 20px;
              color: #1a1a2e;
            }
            h1 { font-size: 28px; margin-bottom: 4px; }
            h2 { font-size: 16px; margin-top: 32px; padding-bottom: 6px; border-bottom: 1px solid #eee; }
            label { display: block; font-size: 13px; font-weight: 600; margin: 12px 0 4px; }
            input, select, textarea {
              width: 100%;
              padding: 10px;
              border: 1px solid #ddd;
              border-radius: 6px;
              font-family: inherit;
              font-size: 14px;
              box-sizing: border-box;
            }
            button {
              background: #1a1a2e;
              color: white;
              padding: 10px 18px;
              border: none;
              border-radius: 6px;
              cursor: pointer;
              font-size: 14px;
              margin-top: 12px;
            }
            button:hover { background: #2d2d4a; }
            .out {
              background: #f6f6fa;
              padding: 12px;
              border-radius: 6px;
              margin-top: 12px;
              font-size: 13px;
              font-family: ui-monospace, monospace;
              white-space: pre-wrap;
              word-break: break-all;
            }
            .balance { font-size: 36px; font-weight: 700; color: #4f46e5; }
            .balance-sub { color: #888; font-size: 13px; margin-top: 4px; }
          </style>
        </head>
        <body>
          <h1>MailKit</h1>
          <p>Prepaid transactional email, billed per send.</p>

          <h2>1. Subscribe to MailKit ($19/mo, 5,000 emails)</h2>
          <label>Email</label>
          <input id="subEmail" type="email" placeholder="you@example.com" />
          <label>Name</label>
          <input id="subName" type="text" placeholder="Your name" />
          <button onclick="subscribe()">Get checkout link</button>
          <div id="subOut" class="out" hidden></div>

          <h2>2. Check your balance</h2>
          <label>Customer ID</label>
          <input id="balCust" type="text" placeholder="cus_xxxxxxxxxxxx" />
          <button onclick="checkBalance()">Refresh</button>
          <div id="balOut" class="out" hidden></div>

          <h2>3. Send a transactional email</h2>
          <label>Customer ID</label>
          <input id="sendCust" type="text" placeholder="cus_xxxxxxxxxxxx" />
          <label>To (Resend's sandbox accepts delivered@resend.dev)</label>
          <input id="sendTo" type="email" value="delivered@resend.dev" />
          <label>Subject</label>
          <input id="sendSubj" type="text" value="Hello from MailKit" />
          <label>HTML body</label>
          <textarea id="sendBody" rows="3">&lt;strong&gt;It works!&lt;/strong&gt;</textarea>
          <button onclick="sendEmail()">Send</button>
          <div id="sendOut" class="out" hidden></div>

          <h2>4. Run low? Buy a top-up pack</h2>
          <label>Customer ID</label>
          <input id="topCust" type="text" placeholder="cus_xxxxxxxxxxxx" />
          <button onclick="topup()">Buy 5,000 emails ($9)</button>
          <div id="topOut" class="out" hidden></div>

          <script>
            const show = (id, content) => {
              const el = document.getElementById(id);
              el.hidden = false;
              el.innerHTML = content;
            };

            async function subscribe() {
              const r = await fetch('/checkout/subscribe', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                  email: document.getElementById('subEmail').value,
                  name: document.getElementById('subName').value,
                }),
              });
              const data = await r.json();
              show('subOut', r.ok
                ? `<a href="${data.checkout_url}" target="_blank">Open checkout →</a>`
                : `Error: ${data.error}`);
            }

            async function checkBalance() {
              const id = document.getElementById('balCust').value;
              const r = await fetch(`/credits/${id}`);
              const data = await r.json();
              show('balOut', r.ok
                ? `<div class="balance">${Number(data.balance).toLocaleString()}</div>
                   <div class="balance-sub">emails available</div>`
                : `Error: ${data.error}`);
            }

            async function sendEmail() {
              const r = await fetch('/send', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                  customer_id: document.getElementById('sendCust').value,
                  to: document.getElementById('sendTo').value,
                  subject: document.getElementById('sendSubj').value,
                  html: document.getElementById('sendBody').value,
                }),
              });
              const data = await r.json();
              show('sendOut', r.ok ? `Sent. Message id: ${data.id}` : `Error: ${data.error}`);
            }

            async function topup() {
              const r = await fetch('/checkout/topup', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ customer_id: document.getElementById('topCust').value }),
              });
              const data = await r.json();
              show('topOut', r.ok
                ? `<a href="${data.checkout_url}" target="_blank">Open top-up checkout →</a>`
                : `Error: ${data.error}`);
            }
          </script>
        </body>
      </html>
      ```
    </CodeGroup>
  </Step>
</Steps>

## Step 4: Wire Up the Webhook Endpoint

The `credit.balance_low` event is what lets you nudge customers *before* they run out. Without it, the first time they notice the problem is when an email fails to send.

<Steps>
  <Step title="Expose your local server">
    Webhooks need a public URL. Use [ngrok](https://ngrok.com) (or any tunnel) while developing:

    ```bash theme={null}
    ngrok http 3000
    ```

    Copy the HTTPS forwarding URL (e.g. `https://1234abcd.ngrok-free.app`).
  </Step>

  <Step title="Register the endpoint in Dodo">
    1. Go to **Developers → Webhooks → Add Endpoint**
    2. **URL**: `https://1234abcd.ngrok-free.app/webhooks/dodo`
    3. **Events**: subscribe to `credit.added`, `credit.balance_low`, and `credit.rolled_over`
    4. Save, then copy the **signing key** into your `.env` as `DODO_WEBHOOK_KEY`
    5. Restart your server
  </Step>
</Steps>

## Step 5: Test the Full Flow

<Steps>
  <Step title="Start the server">
    ```bash theme={null}
    npm run dev
    ```

    You should see `MailKit running on http://localhost:3000`. Open it in your browser.
  </Step>

  <Step title="Subscribe a test customer">
    1. In section 1, enter a test email and name, click **Get checkout link**
    2. Open the link, complete checkout with a [test card](/miscellaneous/testing-process)
    3. After payment, find the `customer_id` in your dashboard under **Customers**

    <Check>
      The customer should now have **5,000 emails** in their balance. Check **Customers → \[Customer] → Credits**.
    </Check>
  </Step>

  <Step title="Send a real email">
    1. Paste the `customer_id` into section 3
    2. Leave `to` set to `delivered@resend.dev` (Resend's sandbox inbox that accepts everything)
    3. Click **Send**

    You'll get a Resend message id back. Refresh the balance in section 2 and the count immediately drops to 4,999. Each ledger debit is reflected in the live balance the moment it's written.
  </Step>

  <Step title="Trigger the low-balance webhook">
    The threshold is 20% (1,000 of the 5,000-email allowance). To trigger it without sending 4,000 real emails, **manually debit the balance** from the dashboard:

    1. Go to **Customers → \[Customer] → Credits → Email Credits**
    2. Click **Adjust Balance** and debit `4000`
    3. Send one more email through the demo

    Your server should log within a few seconds:

    ```
    [low-balance] cus_xxx has 999 Email Credits left (under 20%)
    [NOTIFY] cus_xxx: 999 emails left. Consider topping up.
    ```

    <Check>
      Your server received and verified the webhook. In production this is where you'd email the customer or show an in-app banner.
    </Check>
  </Step>

  <Step title="Buy a top-up pack">
    1. Paste the `customer_id` into section 4
    2. Click **Buy 5,000 emails**, complete the test checkout
    3. Refresh the balance, and it jumps by 5,000

    <Check>
      A `credit.added` event fires with `grant_source: one_time`. The top-up stacks on top of the subscription credits; both pools are consumed FIFO (oldest non-expired grant first).
    </Check>
  </Step>

  <Step title="Test the hard stop">
    Manually debit the balance to zero, then try to send one more email. You'll get:

    ```json theme={null}
    { "error": "No email credits remaining. Buy a top-up pack or upgrade your plan." }
    ```

    That 402 is your application-level enforcement. The Dodo balance API is the source of truth; never cache it on the client.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook signature verification fails (401)">
    The signature is computed over the raw HTTP body. `express.json()` parses and re-serializes the payload, which breaks the HMAC. Make sure `/webhooks/dodo` is registered with `express.raw({ type: 'application/json' })` *above* the `app.use(express.json())` line, and that `DODO_WEBHOOK_KEY` matches the signing key shown on the endpoint detail page.
  </Accordion>

  <Accordion title="Balance is 0, customer not found, or credits don't deduct">
    Three things to verify, in this order:

    1. The customer **completed checkout** (credits are issued on successful payment, not on session creation)
    2. `CREDIT_ENTITLEMENT_ID` in your `.env` matches the credit attached to the product (mismatched IDs silently write to the wrong credit)
    3. The `customer_id` you're passing came from Dodo (the `customers` table in the dashboard), not your own database
  </Accordion>

  <Accordion title="Resend rejects the recipient">
    The sandbox sender `onboarding@resend.dev` only delivers to the email on your Resend account or to `delivered@resend.dev`. To send to anyone else, [verify a domain](https://resend.com/docs/dashboard/domains/introduction) and use a `from` address on it.
  </Accordion>
</AccordionGroup>

## What You Built

<CardGroup>
  <Card title="One reusable credit unit" icon="envelope">
    `Email Credits`, defined once and attached to both the subscription plan and the top-up pack.
  </Card>

  <Card title="Subscription with prepaid allowance" icon="layer-group">
    \$19/month grants 5,000 emails per cycle. Customers know what they're paying for, you know your worst-case cost.
  </Card>

  <Card title="Top-up pack" icon="circle-plus">
    A one-time product that grants 5,000 emails. Stacks on subscription credits with no plan change required.
  </Card>

  <Card title="Instant ledger debits" icon="bolt">
    A single `createLedgerEntry` call after each send. No meter, no aggregation lag, idempotent on retry via Resend's message id.
  </Card>
</CardGroup>

<Card title="Credit-Based Billing Reference" icon="book" href="/features/credit-based-billing">
  Read the full CBB documentation for rollover, overage modes, ledger management, and the complete API surface.
</Card>

Need help?

* [Discord Community](https://discord.gg/bYqAp4ayYh)
* [support@dodopayments.com](mailto:support@dodopayments.com)


# Build an AI API Platform with Credit-Based Billing
Source: https://docs.dodopayments.com/developer-resources/build-an-ai-api-platform-with-credit-based-billing

Build a tiered AI API service with token credits — issue credits via subscription plans and one-time top-up packs, and auto-deduct as customers call your API.

<Tip>
  <strong>Let Sentra write your integration code for you.</strong><br />
  Use our AI assistant in VS Code, Cursor, or Windsurf to generate SDK/API code, webhook handlers, credit grants, and more — just by describing what you want.

  <a href="https://dodopayments.com/sentra">
    Try Sentra: AI-Powered Integration →
  </a>
</Tip>

In this tutorial, you'll build **NeuralAPI** — a tiered AI platform where each subscription plan comes with a monthly token credit allowance, customers can buy top-up packs when they run low, and your backend automatically deducts credits as requests are processed by OpenAI.

<Note>
  This tutorial uses Node.js/Express + the OpenAI SDK. The Dodo Payments concepts (credits, meters, webhooks) apply to any framework or AI provider — adapt freely.
</Note>

By the end of this tutorial, you'll know how to:

* Create a custom credit entitlement (tokens) and a meter that auto-deducts from it
* Attach credits to subscription plans (with and without overage) and a one-time top-up product
* Wire a real OpenAI completion endpoint that bills tokens through Dodo Payments
* Query a customer's live credit balance via the SDK
* Verify webhook signatures and route Dodo Payments credit events

## What We're Building

Here's the pricing model for NeuralAPI:

| Product           | Price         | Tokens                  | Overage               |
| ----------------- | ------------- | ----------------------- | --------------------- |
| Starter Plan      | \$29/month    | 10,000,000 tokens/cycle | Blocked at zero       |
| Pro Plan          | \$99/month    | 40,000,000 tokens/cycle | \$0.005 per 1K tokens |
| Token Top-Up Pack | \$19 one-time | +5,000,000 tokens       | —                     |

<Info>
  Before you start, make sure you have:

  * A Dodo Payments account (test mode is fine)
  * An OpenAI API key
  * Node.js 18+
  * Basic familiarity with TypeScript/Node.js
</Info>

## Step 1: Create Your Token Credit Entitlement

First, create the credit entitlement that both subscription plans and the top-up pack will share. Think of this as defining the "token" unit your platform uses.

<Frame>
  <img alt="Credits listing page showing created credit entitlements" />
</Frame>

<Steps>
  <Step title="Navigate to Credits">
    1. Log into your Dodo Payments dashboard
    2. Click **Products** in the left sidebar
    3. Select the **Credits** tab
    4. Click **Create Credit**
  </Step>

  <Step title="Configure the credit unit">
    Fill in the basic details for your token credit:

    **Credit Name**: `API Tokens`

    **Credit Type**: Select **Custom Unit**

    **Unit Name**: `token`

    **Precision**: `0` (tokens are always whole numbers)

    **Credit Expiry**: `30 days` (credits reset each billing cycle)

    <Warning>
      Precision cannot be changed after a credit is created. For token counts, `0` (whole numbers) is almost always correct.
    </Warning>
  </Step>

  <Step title="Skip overage at the credit level">
    Leave overage **disabled** here — you'll configure it per-plan when attaching the credit to products. This lets the Starter plan block usage at zero while the Pro plan allows overage.

    <Tip>
      Overage settings configured here are *defaults*. Each product attachment can override them — which is exactly what we'll do in Step 3.
    </Tip>
  </Step>

  <Step title="Save and copy the credit ID">
    Click **Create Credit**. Once saved, open the credit and copy its ID — it looks like `cent_xxxxxxxxxxxx`.

    <Check>
      Your `API Tokens` credit entitlement is ready. Next, create a meter so usage events can drive deductions automatically.
    </Check>
  </Step>
</Steps>

## Step 2: Create a Meter for Token Usage

A meter aggregates incoming usage events and converts them into credit deductions. You need this *before* creating the plan products, since you'll attach it during product creation in Step 3.

<Steps>
  <Step title="Open the Meters section">
    1. In the dashboard sidebar, go to **Products** → **Meters**
    2. Click **Create Meter**
  </Step>

  <Step title="Configure the meter">
    Fill in:

    **Meter Name**: `Token Usage Meter`

    **Event Name**: `api.tokens_used` *(this must match exactly what your app sends)*

    **Aggregation Type**: `Sum` — we sum the token count from each event

    **Over Property**: `tokens` — the metadata key on each event whose value will be summed

    **Measurement Unit**: `tokens`

    <Warning>
      Event names are case-sensitive. `api.tokens_used` ≠ `Api.Tokens.Used` — pick one and stick to it.
    </Warning>

    Save the meter and copy its ID — you'll reference it when attaching to products.

    <Check>
      Meter is created. Now we can wire it to the credit when we configure products.
    </Check>
  </Step>
</Steps>

## Step 3: Create the Plan Products

Both plans need to be **Usage Based Billing** products, not plain Subscriptions — meters can only attach to UBB products, and you need the meter to auto-deduct credits as customers call your API. UBB products still support a recurring base fee (the `$29` / `$99`); usage on top of that gets billed in credits.

<Frame>
  <img alt="Usage Based Billing pricing configuration" />
</Frame>

### Starter Plan (\$29/month — 10M tokens, no overage)

<Steps>
  <Step title="Create the Starter UBB product">
    1. Go to **Products → Create Product**
    2. Select **Usage Based Billing** as the pricing type
    3. Fill in:

    **Product Name**: `NeuralAPI Starter`

    **Description**: `10 million API tokens per month. Perfect for individual developers and small projects.`

    **Fixed Price**: `29.00` (the recurring base fee — billed monthly even before any usage)

    **Billing Cycle**: `Monthly`

    **Currency**: `USD`
  </Step>

  <Step title="Attach the meter">
    In the **Select meter** section, click **+** and add `Token Usage Meter`. Then on the meter:

    1. Toggle **Bill usage in Credits** on
    2. **Credit Entitlement**: select `API Tokens`
    3. **Meter units per credit**: `1` — each token in the event maps to 1 credit deducted
    4. **Free Threshold**: `0` — the credit allocation itself is the customer's "free tier"; we don't need an extra free band

    <Frame>
      <img alt="Meter with Bill usage in Credits enabled and API Tokens selected" />
    </Frame>

    This is the wiring that makes incoming `api.tokens_used` events actually deduct from the customer's balance.
  </Step>

  <Step title="Configure credit issuance for Starter">
    Still on the product, scroll to the credit configuration section that appears once a credit-billed meter is attached:

    **Credits issued per billing cycle**: `10000000`

    **Allow Overage**: **Disabled** — Starter customers are blocked when tokens run out

    **Import Default Credit Settings**: Enabled — use the 30-day expiry from the credit entitlement

    <Frame>
      <img alt="Credit configuration form with per-cycle amount and overage settings" />
    </Frame>

    Click **Save** and copy the product ID.

    <Check>
      Starter Plan: \$29/month base fee, 10M tokens/cycle, blocked at zero, auto-deducts via meter.
    </Check>
  </Step>
</Steps>

### Pro Plan (\$99/month — 40M tokens, overage enabled)

<Steps>
  <Step title="Create the Pro UBB product">
    Same flow as Starter, with bigger numbers:

    **Product Name**: `NeuralAPI Pro`

    **Description**: `40 million API tokens per month with overage. Built for production applications.`

    **Fixed Price**: `99.00`

    **Billing Cycle**: `Monthly`

    **Currency**: `USD`
  </Step>

  <Step title="Attach the meter">
    Identical to Starter: add `Token Usage Meter`, toggle **Bill usage in Credits** on, select `API Tokens`, **Meter units per credit** `1`, **Free Threshold** `0`.
  </Step>

  <Step title="Configure credit issuance with overage">
    Configure the credit issuance, this time enabling overage:

    **Credits issued per billing cycle**: `40000000`

    **Import Default Credit Settings**: **Disable** — we need to customize overage settings per product

    **Allow Overage**: **Enabled**

    **Price Per Unit**: `0.000005` USD per token (i.e., $0.005 per 1K tokens, or $5 per 1M tokens — above the plan's effective per-token rate to discourage spillover)

    **Overage Behavior**: `Bill overage at billing` — overage is charged on the next invoice, then the balance resets

    Save the product and copy the product ID.

    <Check>
      Pro Plan: $99/month base fee, 40M tokens/cycle, overage at $0.005/1K tokens, auto-deducts via meter.
    </Check>
  </Step>
</Steps>

## Step 4: Create the Token Top-Up Pack

The top-up pack is a one-time purchase that grants 5,000,000 tokens to an existing customer's balance.

<Frame>
  <img alt="Product pricing section with Single Payment selected" />
</Frame>

<Steps>
  <Step title="Create a one-time product">
    1. Go to **Products → Create Product**
    2. Select **Single Payment** as the pricing type
    3. Fill in:

    **Product Name**: `Token Top-Up Pack`

    **Description**: `Instantly add 5 million tokens to your NeuralAPI balance.`

    **Price**: `19.00`

    **Currency**: `USD`
  </Step>

  <Step title="Attach the token credit">
    1. In the **Entitlements** section, click **Attach** next to **Credits**
    2. Select `API Tokens`
    3. Set **Credits issued**: `5000000`
    4. **Disable** *Import Default Credit Settings* — we want to override the default 30-day expiry
    5. Set **Credit Expiry**: `365 days`
    6. Save the product

    Copy the product ID.

    <Tip>
      Why a longer expiry on top-ups? Subscription credits reset every 30 days because that's the cycle. Top-ups are *prepaid purchases* — the customer paid \$19 upfront and reasonably expects those tokens to last beyond a month. 365 days matches how real prepaid credits work at OpenAI, AWS, and Anthropic, while still capping your liability so customers can't stockpile indefinitely.
    </Tip>

    <Check>
      Top-Up Pack configured — purchasing it grants 5,000,000 tokens that remain valid for 365 days.
    </Check>
  </Step>
</Steps>

## Step 5: Build the Backend

Now let's build the Express server that handles subscription checkout, top-up checkout, real OpenAI completions with token billing, balance queries, and credit webhook events.

<Steps>
  <Step title="Set up your project">
    ```bash theme={null}
    mkdir neural-api-billing
    cd neural-api-billing
    npm init -y
    npm install dodopayments openai express dotenv
    npm install -D @types/node @types/express typescript tsx
    ```

    Create a `tsconfig.json`:

    ```json tsconfig.json theme={null}
    {
      "compilerOptions": {
        "target": "ES2022",
        "module": "commonjs",
        "outDir": "./dist",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true
      }
    }
    ```

    Update `package.json` scripts:

    ```json package.json theme={null}
    {
      "scripts": {
        "dev": "tsx watch src/server.ts",
        "build": "tsc",
        "start": "node dist/server.js"
      }
    }
    ```
  </Step>

  <Step title="Set up environment variables">
    Create `.env` with your credentials and IDs from the previous steps:

    ```bash .env theme={null}
    DODO_PAYMENTS_API_KEY=your_dodo_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_secret_here
    DODO_ENVIRONMENT=test_mode
    OPENAI_API_KEY=sk-...
    CREDIT_ENTITLEMENT_ID=cent_xxxxxxxxxxxx
    STARTER_PLAN_PRODUCT_ID=pdt_xxxxxxxxxxxx
    PRO_PLAN_PRODUCT_ID=pdt_xxxxxxxxxxxx
    TOPUP_PRODUCT_ID=pdt_xxxxxxxxxxxx
    BASE_URL=http://localhost:3000
    ```

    <Warning>
      Never commit `.env` to version control. Add it to `.gitignore` immediately.
    </Warning>

    You'll fill in `DODO_PAYMENTS_WEBHOOK_KEY` in Step 7 after registering your webhook endpoint.
  </Step>

  <Step title="Implement the server">
    Create `src/server.ts`:

    <CodeGroup>
      ```typescript src/server.ts expandable theme={null}
      import 'dotenv/config';
      import DodoPayments from 'dodopayments';
      import OpenAI from 'openai';
      import express, { Request, Response } from 'express';

      const app = express();

      // IMPORTANT: webhook route needs the raw body for signature verification.
      // We register the raw parser ONLY on /webhooks/dodo, then JSON for everything else.
      app.use('/webhooks/dodo', express.raw({ type: 'application/json' }));
      app.use(express.json());
      app.use(express.static('public'));

      const dodo = new DodoPayments({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
        webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
        environment: (process.env.DODO_ENVIRONMENT as 'test_mode' | 'live_mode') ?? 'test_mode',
      });

      const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });

      const CREDIT_ENTITLEMENT_ID = process.env.CREDIT_ENTITLEMENT_ID!;
      const BASE_URL = process.env.BASE_URL!;
      const PLAN_PRODUCTS: Record<string, string> = {
        starter: process.env.STARTER_PLAN_PRODUCT_ID!,
        pro: process.env.PRO_PLAN_PRODUCT_ID!,
      };

      // ────────────────────────────────────────────────────────────────────────────
      // Subscription checkout
      // Body: { plan: 'starter' | 'pro', email: string, name: string }
      // ────────────────────────────────────────────────────────────────────────────
      app.post('/checkout/subscribe', async (req: Request, res: Response) => {
        const { plan, email, name } = req.body;
        if (!PLAN_PRODUCTS[plan]) {
          return res.status(400).json({ error: `Unknown plan: ${plan}` });
        }
        try {
          const session = await dodo.checkoutSessions.create({
            product_cart: [{ product_id: PLAN_PRODUCTS[plan], quantity: 1 }],
            customer: { email, name },
            return_url: `${BASE_URL}/?subscribed=1`,
          });
          res.json({ checkout_url: session.checkout_url, session_id: session.session_id });
        } catch (err) {
          console.error('Subscription checkout error:', err);
          res.status(500).json({ error: 'Failed to create subscription checkout' });
        }
      });

      // ────────────────────────────────────────────────────────────────────────────
      // Top-up checkout — buyer must already be a customer
      // Body: { customer_id: string }
      // ────────────────────────────────────────────────────────────────────────────
      app.post('/checkout/topup', async (req: Request, res: Response) => {
        const { customer_id } = req.body;
        if (!customer_id) return res.status(400).json({ error: 'customer_id required' });
        try {
          const session = await dodo.checkoutSessions.create({
            product_cart: [{ product_id: process.env.TOPUP_PRODUCT_ID!, quantity: 1 }],
            customer: { customer_id },
            return_url: `${BASE_URL}/?topup=1`,
          });
          res.json({ checkout_url: session.checkout_url });
        } catch (err) {
          console.error('Top-up checkout error:', err);
          res.status(500).json({ error: 'Failed to create top-up checkout' });
        }
      });

      // ────────────────────────────────────────────────────────────────────────────
      // Live token balance for a customer
      // ────────────────────────────────────────────────────────────────────────────
      app.get('/credits/:customerId', async (req: Request, res: Response) => {
        try {
          const result = await dodo.creditEntitlements.balances.retrieve(req.params.customerId, {
            credit_entitlement_id: CREDIT_ENTITLEMENT_ID,
          });
          res.json({
            balance: result.balance,
            overage: result.overage,
            last_transaction_at: result.last_transaction_at,
          });
        } catch (err) {
          console.error('Balance fetch error:', err);
          res.status(500).json({ error: 'Failed to fetch credit balance' });
        }
      });

      // ────────────────────────────────────────────────────────────────────────────
      // AI completion — calls OpenAI, then ingests a usage event with the real
      // token count. The meter aggregates these and deducts credits automatically.
      // Body: { customer_id: string, prompt: string }
      // ────────────────────────────────────────────────────────────────────────────
      app.post('/api/generate', async (req: Request, res: Response) => {
        const { customer_id, prompt } = req.body;
        if (!customer_id || !prompt) {
          return res.status(400).json({ error: 'customer_id and prompt required' });
        }

        // Best-effort balance gate for Starter (no overage). Note: balance updates
        // are eventually consistent (~1 min lag from event ingestion), so a Starter
        // customer can technically squeeze through a few extra requests right after
        // running out. Use a stricter rate-limiter on top if you need hard cutoffs.
        try {
          const balance = await dodo.creditEntitlements.balances.retrieve(customer_id, {
            credit_entitlement_id: CREDIT_ENTITLEMENT_ID,
          });
          if (Number(balance.balance) <= 0 && Number(balance.overage) <= 0) {
            return res.status(402).json({
              error: 'Out of tokens. Top up or upgrade to continue.',
            });
          }
        } catch {
          // Fall through — if the balance lookup fails, don't block; rely on metering.
        }

        let completion;
        try {
          completion = await openai.chat.completions.create({
            model: 'gpt-5-mini',
            messages: [{ role: 'user', content: prompt }],
          });
        } catch (err) {
          console.error('OpenAI error:', err);
          return res.status(502).json({ error: 'Upstream AI provider failed' });
        }

        const tokensUsed = completion.usage?.total_tokens ?? 0;

        // Fire-and-forget — don't block the response on metering.
        ingestTokenUsage(customer_id, tokensUsed, completion.model).catch((err) =>
          console.error('Usage ingest failed:', err),
        );

        res.json({
          text: completion.choices[0]?.message?.content ?? '',
          tokens_used: tokensUsed,
          model: completion.model,
        });
      });

      async function ingestTokenUsage(customerId: string, tokens: number, model: string) {
        await dodo.usageEvents.ingest({
          events: [
            {
              // event_id is the idempotency key. Use a stable, unique value per request.
              event_id: `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
              customer_id: customerId,
              event_name: 'api.tokens_used',
              timestamp: new Date().toISOString(),
              metadata: { tokens, model },
            },
          ],
        });
      }

      // ────────────────────────────────────────────────────────────────────────────
      // Webhook handler — verifies signature using the SDK, then routes events.
      // ────────────────────────────────────────────────────────────────────────────
      app.post('/webhooks/dodo', async (req: Request, res: Response) => {
        const rawBody = (req.body as Buffer).toString('utf8');
        const headers = {
          'webhook-id': req.header('webhook-id') ?? '',
          'webhook-signature': req.header('webhook-signature') ?? '',
          'webhook-timestamp': req.header('webhook-timestamp') ?? '',
        };

        let event: { type: string; data: any };
        try {
          event = dodo.webhooks.unwrap(rawBody, { headers }) as any;
        } catch (err) {
          console.error('Webhook verification failed:', err);
          return res.status(401).json({ error: 'Invalid signature' });
        }

        switch (event.type) {
          case 'credit.added':
            console.log(`[credit.added] customer=${event.data.customer_id} amount=${event.data.amount}`);
            break;
          case 'credit.deducted':
            console.log(`[credit.deducted] customer=${event.data.customer_id} amount=${event.data.amount}`);
            break;
          case 'credit.overage_charged':
            console.log(`[credit.overage_charged] customer=${event.data.customer_id}`);
            break;
          default:
            // Ignore other event types
            break;
        }

        res.json({ received: true });
      });

      app.listen(3000, () => {
        console.log('NeuralAPI billing server running on http://localhost:3000');
      });
      ```

      ```json package.json theme={null}
      {
        "name": "neural-api-billing",
        "version": "1.0.0",
        "scripts": {
          "dev": "tsx watch src/server.ts",
          "build": "tsc",
          "start": "node dist/server.js"
        },
        "dependencies": {
          "dodopayments": "latest",
          "openai": "^4.0.0",
          "express": "^4.18.0",
          "dotenv": "^16.0.0"
        },
        "devDependencies": {
          "@types/node": "^20.0.0",
          "@types/express": "^4.17.0",
          "typescript": "^5.0.0",
          "tsx": "^4.0.0"
        }
      }
      ```
    </CodeGroup>

    <Check>
      Backend done: subscription checkout, top-up checkout, OpenAI completion with metered token billing, balance query, and a verified webhook handler.
    </Check>

    <Tip>
      [`@dodopayments/ingestion-blueprints`](/features/usage-based-billing/ingestion-blueprints) provides drop-in trackers that automate the `usageEvents.ingest` call for you — including the [LLM Blueprint](/developer-resources/ingestion-blueprints/llm), [API gateway](/developer-resources/ingestion-blueprints/api-gateway), [object storage](/developer-resources/ingestion-blueprints/object-storage), [streams](/developer-resources/ingestion-blueprints/stream), and [time-range](/developer-resources/ingestion-blueprints/time-range) usage.
    </Tip>
  </Step>

  <Step title="A note on how deductions actually happen">
    You may have noticed there's no explicit "deduct N credits" call. That's by design:

    1. Your handler calls OpenAI and gets back `usage.total_tokens` (e.g., 1532).
    2. You ingest a single usage event: `event_name: api.tokens_used`, `metadata: { tokens: 1532 }`.
    3. The `Token Usage Meter` aggregates events by customer.
    4. Because the meter is wired to the `API Tokens` credit with **Bill usage in Credits**, Dodo Payments deducts 1532 credits from the customer's oldest non-expired grant (FIFO).
    5. If overage is enabled and the customer goes below zero, the deficit is tracked and billed on the next invoice.

    The meter handles all of that. Your code only ingests events.
  </Step>
</Steps>

## Step 6: Add a Demo Frontend

Create `public/index.html` to test all the flows in your browser. We persist the customer ID to `localStorage` so subscribe → generate → top-up all share the same identity, mimicking a logged-in app:

<CodeGroup>
  ```html public/index.html expandable theme={null}
  <!DOCTYPE html>
  <html>
  <head>
    <title>NeuralAPI Demo</title>
    <style>
      body { font-family: system-ui, sans-serif; max-width: 760px; margin: 40px auto; padding: 20px; color: #1a1a2e; }
      h1 { font-size: 24px; }
      h2 { margin-top: 36px; border-bottom: 1px solid #eee; padding-bottom: 8px; font-size: 18px; }
      .panel { padding: 16px; background: #fafafe; border: 1px solid #e6e6f0; border-radius: 8px; margin: 12px 0; }
      .form-group { margin: 12px 0; }
      label { display: block; margin-bottom: 4px; font-weight: 600; font-size: 13px; }
      input, select, textarea { width: 100%; padding: 10px; border: 1px solid #ddd; border-radius: 6px; box-sizing: border-box; font-family: inherit; font-size: 14px; }
      textarea { min-height: 80px; resize: vertical; }
      button { background: #6366f1; color: white; padding: 10px 18px; border: none; border-radius: 6px; cursor: pointer; font-size: 14px; font-weight: 600; }
      button:hover { background: #4f46e5; }
      button:disabled { background: #c7c7d4; cursor: not-allowed; }
      .balance { font-size: 32px; font-weight: 700; color: #6366f1; }
      .muted { color: #777; font-size: 13px; margin-top: 4px; }
      .result { margin-top: 12px; padding: 12px; background: #fff; border: 1px solid #e6e6f0; border-radius: 6px; font-size: 14px; white-space: pre-wrap; }
      .row { display: flex; gap: 12px; align-items: center; }
      .row > * { flex: 1; }
    </style>
  </head>
  <body>
    <h1>NeuralAPI Demo</h1>

    <div class="panel">
      <label>Logged-in customer ID (paste once after subscribing)</label>
      <div class="row">
        <input id="customerId" placeholder="cus_xxxxxxxxxxxx" />
        <button onclick="saveCustomerId()" style="flex:0">Save</button>
      </div>
      <div class="muted">After completing checkout, copy the customer ID from your Dodo Payments dashboard (Customers → most recent) and paste here.</div>
    </div>

    <h2>1. Subscribe to a Plan</h2>
    <div class="form-group"><label>Plan</label>
      <select id="plan">
        <option value="starter">Starter — $29/mo, 10M tokens</option>
        <option value="pro">Pro — $99/mo, 40M tokens + overage</option>
      </select>
    </div>
    <div class="form-group"><label>Email</label><input type="email" id="email" placeholder="you@example.com" /></div>
    <div class="form-group"><label>Name</label><input id="name" placeholder="Your name" /></div>
    <button onclick="subscribe(event)">Get Checkout Link</button>
    <div id="subscribeResult" class="result" style="display:none"></div>

    <h2>2. Generate AI Response (deducts tokens)</h2>
    <div class="form-group"><label>Prompt</label><textarea id="prompt" placeholder="Explain quantum computing in one sentence"></textarea></div>
    <button onclick="generate(event)">Generate</button>
    <div id="generateResult" class="result" style="display:none"></div>

    <h2>3. Live Token Balance</h2>
    <button onclick="checkBalance(event)">Refresh Balance</button>
    <div id="balanceResult" class="result" style="display:none"></div>

    <h2>4. Buy a Top-Up Pack</h2>
    <button onclick="topup(event)">Buy 5M Tokens — $19</button>
    <div id="topupResult" class="result" style="display:none"></div>

    <script>
      const $ = (id) => document.getElementById(id);
      document.addEventListener('DOMContentLoaded', () => {
        $('customerId').value = localStorage.getItem('customerId') || '';
      });

      function getCustomerId() {
        const id = $('customerId').value.trim();
        if (!id) { alert('Save a customer ID first'); throw new Error('no customer'); }
        return id;
      }

      function saveCustomerId() {
        localStorage.setItem('customerId', $('customerId').value.trim());
        alert('Saved');
      }

      async function withLoading(btn, loadingLabel, fn) {
        const original = btn.textContent;
        btn.disabled = true;
        btn.textContent = loadingLabel;
        try { await fn(); } finally {
          btn.disabled = false;
          btn.textContent = original;
        }
      }

      async function subscribe(ev) {
        await withLoading(ev.target, 'Loading…', async () => {
          const res = await fetch('/checkout/subscribe', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ plan: $('plan').value, email: $('email').value, name: $('name').value }),
          });
          const data = await res.json();
          const el = $('subscribeResult');
          el.style.display = 'block';
          el.innerHTML = res.ok
            ? `<a href="${data.checkout_url}" target="_blank">Open Checkout →</a>`
            : `Error: ${data.error}`;
        });
      }

      async function generate(ev) {
        const customer_id = getCustomerId();
        await withLoading(ev.target, 'Generating…', async () => {
          const res = await fetch('/api/generate', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ customer_id, prompt: $('prompt').value }),
          });
          const data = await res.json();
          const el = $('generateResult');
          el.style.display = 'block';
          el.innerHTML = res.ok
            ? `<strong>Response:</strong>\n${data.text}\n\n<em>Tokens used: ${data.tokens_used} (${data.model})</em>`
            : `Error: ${data.error}`;
          if (res.ok) refreshBalanceSilently();
        });
      }

      async function checkBalance(ev) {
        const customer_id = getCustomerId();
        await withLoading(ev.target, 'Refreshing…', async () => {
          const res = await fetch('/credits/' + customer_id);
          const data = await res.json();
          const el = $('balanceResult');
          el.style.display = 'block';
          el.innerHTML = res.ok
            ? `<div class="balance">${Number(data.balance).toLocaleString()} tokens</div>
               <div class="muted">Overage used: ${Number(data.overage).toLocaleString()} · Last activity: ${data.last_transaction_at ?? 'never'}</div>`
            : `Error: ${data.error}`;
        });
      }

      async function refreshBalanceSilently() {
        const customer_id = $('customerId').value.trim();
        if (!customer_id) return;
        const res = await fetch('/credits/' + customer_id);
        const data = await res.json();
        const el = $('balanceResult');
        el.style.display = 'block';
        el.innerHTML = res.ok
          ? `<div class="balance">${Number(data.balance).toLocaleString()} tokens</div>
             <div class="muted">Overage used: ${Number(data.overage).toLocaleString()} · Last activity: ${data.last_transaction_at ?? 'never'}</div>`
          : `Error: ${data.error}`;
      }

      async function topup(ev) {
        const customer_id = getCustomerId();
        await withLoading(ev.target, 'Loading…', async () => {
          const res = await fetch('/checkout/topup', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ customer_id }),
          });
          const data = await res.json();
          const el = $('topupResult');
          el.style.display = 'block';
          el.innerHTML = res.ok
            ? `<a href="${data.checkout_url}" target="_blank">Open Top-Up Checkout →</a>`
            : `Error: ${data.error}`;
        });
      }
    </script>
  </body>
  </html>
  ```
</CodeGroup>

## Step 7: Wire Up the Webhook

Webhooks let your server react to balance changes — you'll use them to send "running low" emails before customers hit zero.

<Steps>
  <Step title="Expose your local server">
    Webhooks need a public URL. For local development, use [ngrok](https://ngrok.com) or any tunnel:

    ```bash theme={null}
    ngrok http 3000
    ```

    Copy the `https://...ngrok-free.app` URL.
  </Step>

  <Step title="Register the webhook in Dodo Payments">
    1. In the dashboard, go to **Developers → Webhooks → Add Endpoint**
    2. **URL**: `https://your-tunnel.ngrok-free.app/webhooks/dodo`
    3. Subscribe to (at minimum):
       * `credit.added`
       * `credit.deducted`
       * `credit.overage_charged`
    4. Save and copy the **Signing Secret**
    5. Paste it into `.env` as `DODO_PAYMENTS_WEBHOOK_KEY`, then restart `npm run dev`

    <Tip>
      The SDK's `dodo.webhooks.unwrap()` validates the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers using your signing secret. You don't need to hand-roll HMAC verification — and you shouldn't, because Dodo Payments uses [Standard Webhooks](https://www.standardwebhooks.com/), which signs `id.timestamp.body` rather than just the body.
    </Tip>
  </Step>
</Steps>

## Step 8: Test the Full Flow

<Steps>
  <Step title="Subscribe a test customer">
    1. Run `npm run dev`
    2. Open `http://localhost:3000`
    3. Pick **Pro Plan**, enter a test email + name, click **Get Checkout Link**, complete checkout with [test card details](/miscellaneous/testing-process)
    4. In the dashboard, go to **Customers → most recent** and copy the `cus_...` ID
    5. Paste it into the "Logged-in customer ID" field on the demo and click **Save**

    <Check>
      The customer should have 40,000,000 tokens. Click **Refresh Balance** to confirm.
    </Check>
  </Step>

  <Step title="Generate a real AI response">
    Type a prompt and click **Generate**. The server calls OpenAI, gets back the actual `total_tokens`, ingests a usage event, and returns the response.

    <Info>
      Usage events are processed by a background worker every \~minute. The balance won't tick down instantly — wait 30–90 seconds and click **Refresh Balance** again. Don't conclude it's broken if the first refresh doesn't show movement.
    </Info>
  </Step>

  <Step title="Test the top-up flow">
    Click **Buy 5M Tokens — \$19** and complete checkout. After the payment succeeds, refresh the balance — it should jump by 5,000,000 tokens. Your server log should show a `credit.added` event.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Credits not deducting after usage events">
    **Possible causes:**

    * The meter's event name doesn't match the `event_name` you're sending (`api.tokens_used` is case-sensitive)
    * The meter isn't linked to the `API Tokens` credit on the product — go to the product's meter configuration and confirm **Bill usage in Credits** is on
    * The `metadata.tokens` key doesn't match the meter's "Over Property" field
    * The customer's grant has expired (check the customer's credit history)

    **What to check:**

    1. **Products → Meters**: open the meter and confirm it shows the linked credit name on the product attachment
    2. The **Events** tab on the meter — ingested events should appear there even before deduction
    3. **Customers → \[Customer] → Credits**: ledger entries should appear within a minute or two
  </Accordion>

  <Accordion title="Balance always shows 0 or 'customer not found'">
    **Possible causes:**

    * The customer hasn't completed checkout yet — credits are only issued after a successful payment
    * You're querying with the wrong `customer_id` (use the `cus_...` ID from the dashboard, not your own DB ID)
    * The `CREDIT_ENTITLEMENT_ID` in `.env` doesn't match the credit attached to the product

    **What to check:**
    Open **Customers → \[Customer] → Credits**. If no credits appear there, the product entitlement wasn't attached or the payment didn't complete.
  </Accordion>

  <Accordion title="Overage not working for Pro plan customers">
    **Possible causes:**

    * Overage wasn't enabled on the **Pro product's credit attachment** (the credit-level setting is just a default)
    * The customer is actually on Starter, not Pro
    * Overage limit was set to 0

    **What to check:**
    Edit Pro → Entitlements → Credits → confirm **Allow Overage** is on and **Price Per Unit** is `0.000005` (= \$5 per million tokens; double-check the leading zeros — the field takes per-token price, not per-1K).
  </Accordion>

  <Accordion title="`Webhook verification failed` in logs">
    **Possible causes:**

    * Body parsing order: `express.json()` was applied to `/webhooks/dodo` before `express.raw()` — the SDK needs the **raw bytes** of the request, not parsed JSON
    * Wrong signing secret in `DODO_PAYMENTS_WEBHOOK_KEY`
    * Reverse proxy is rewriting headers

    **What to check:**
    Confirm the `app.use('/webhooks/dodo', express.raw(...))` line comes *before* `app.use(express.json())` in `server.ts`.
  </Accordion>
</AccordionGroup>

## Need help?

* [Discord Community](https://discord.gg/bYqAp4ayYh)
* [support@dodopayments.com](mailto:support@dodopayments.com)

## Congratulations! You've Built Credit-Based Billing for NeuralAPI

Your platform now has a complete, production-ready credit billing system:

<CardGroup>
  <Card title="Token Credit Entitlement" icon="coins">
    A reusable `API Tokens` credit with 30-day expiry, shared across all plans and the top-up pack
  </Card>

  <Card title="Tiered Plans, One Credit" icon="layer-group">
    Starter (10M, hard limit) and Pro (40M + overage) configured per-product without duplicating the credit
  </Card>

  <Card title="One-Time Top-Up Pack" icon="circle-plus">
    Customers add 5M tokens for \$19 without changing their subscription
  </Card>

  <Card title="Auto-Deduction via Meter" icon="bolt">
    Real OpenAI token counts ingested as events; the meter deducts credits FIFO with no manual tracking
  </Card>

  <Card title="Live Balance API" icon="gauge">
    Real-time balance via the SDK to gate access, display usage, or warn customers in-app
  </Card>

  <Card title="Verified Webhook Pipeline" icon="bell">
    Credit ledger events (`credit.added`, `credit.deducted`, `credit.overage_charged`) routed through a signature-verified handler using the SDK's Standard Webhooks helper
  </Card>
</CardGroup>

<Info>
  **Going to production?** Tighten these:

  * **Auth on `/credits/:customerId` and `/api/generate`** — currently anyone can hit these with any customer ID. Authenticate users and look up *their* customer ID server-side.
  * **Stable `event_id`s** — the example uses `Date.now() + random`. In production, use your request ID so retries are idempotent (Dodo Payments deduplicates by `event_id`).
  * **Persist the customer↔user mapping** — store `customer_id` in your DB after the first checkout so you don't need a manual paste step.
  * **Decide what happens when a subscription ends.** Plan credits remain in the customer's ledger until their natural expiry (30 days from issuance) and top-up credits stay valid for 365 days — but the cookbook's `/api/generate` only checks *balance*, not subscription status. So a cancelled customer can still consume their remaining tokens. That's the consumer-friendly default. If you want stricter access control, either (a) listen to the `subscription.cancelled` webhook and gate `/api/generate` on subscription status, or (b) call Dodo's ledger API to debit unused plan credits on cancel while leaving top-up credits intact.
  * **Monitor the Usage Billing dashboard** to catch metering anomalies early.
</Info>

<CardGroup>
  <Card title="Credit-Based Billing Reference" icon="book" href="/features/credit-based-billing">
    Full CBB documentation: rollover, overage modes, ledger management, all API endpoints.
  </Card>

  <Card title="Credit Webhook Events" icon="bell" href="/developer-resources/webhooks/intents/credit">
    Payload schemas for every credit event your server might receive.
  </Card>
</CardGroup>


# Build an AI Chat App with AI SDK & LLM Blueprint
Source: https://docs.dodopayments.com/developer-resources/build-an-ai-chat-app-with-usage-based-billing

Follow along as we build an AI chat app with automatic token tracking and usage-based billing

<Tip>
  <strong>Let Sentra write your integration code for you.</strong><br />
  Use our AI assistant in VS Code, Cursor, or Windsurf to generate SDK/API code, LLM Blueprint integration code, webhooks, and more - just by describing what you want.

  <a href="https://dodopayments.com/sentra">
    Try Sentra: AI-Powered Integration →
  </a>
</Tip>

In this tutorial, you'll build an **AI chat application** with automatic usage-based billing. We'll create everything from scratch: the billing meter, product configuration, and application code that powers conversations and tracks token usage in real-time.

<Note>
  This tutorial provides a complete working application with both backend and frontend. The chat app uses Google's Gemini AI and automatically tracks token usage without any manual counting required.
</Note>

By the end of this tutorial, you'll have a working chat application that:

* Powers AI conversations using Google Gemini (AI SDK)
* Automatically tracks token usage (no manual code)
* Charges customers based on actual token consumption
* Includes a beautiful chat interface

<Frame>
  <img alt="AI Chat Demo" />
</Frame>

## What We're Building

Let's start by understanding our AI chat service:

* **Service**: AI-powered chat using Google Gemini (AI SDK)
* **Pricing Model**: Pay-per-token (\$0.01 per 1,000 tokens)
* **Free Tier**: 10,000 free tokens per customer per month
* **Features**: Conversation history, automatic token tracking

<Info>
  Before we start, make sure you have:

  * A Dodo Payments account
  * A Google AI API key ([Get one from aistudio](https://aistudio.google.com/api-keys))
  * Node.js v16+ installed
</Info>

***

## Step 1: Create Your Usage Meter

We'll start by creating a meter in your Dodo Payments dashboard that will track AI token usage.

<Tip>
  **What we're building**: A meter named "AI Token Usage Meter" that sums up all tokens consumed in chat conversations.
</Tip>

<Steps>
  <Step title="Open the Meters section">
    1. Log into your Dodo Payments dashboard
    2. Click on Products in the left sidebar
    3. Click on **Meters**
    4. Click the **Create Meter** button

    <Frame>
      <img alt="Create Meter" />
    </Frame>

    You should see a form where we'll configure our token tracking.
  </Step>

  <Step title="Fill in the basic meter information">
    Now we'll enter the specific details for our AI chat service:

    **Meter Name** → `AI Token Usage Meter`

    **Description** → `Tracks token consumption from AI chat conversations using AI SDK`

    **Event Name** → `ai_chat_usage`

    <Warning>
      The event name `ai_chat_usage` must match exactly what we'll send from our application code later. Event names are case-sensitive!
    </Warning>
  </Step>

  <Step title="Configure how we count tokens">
    Set up the aggregation (how the meter counts our events):

    **Aggregation Type**: Select **Sum** from the dropdown

    **Aggregate Over**: Type → `totalTokens`

    **Measurement Unit**: Type → `tokens`

    <Info>
      We're using "Sum" because we want to add up all tokens consumed across multiple chat messages. The SDK automatically sends `totalTokens` in each event.
    </Info>
  </Step>

  <Step title="Create your meter">
    1. Double-check all your settings match the values above
    2. Click **Create Meter**

    <Frame>
      <img alt="Meter Configuration" />
    </Frame>

    <Check>
      **Meter created!** Your "AI Token Usage Meter" is now ready to start counting tokens. Next, we'll connect it to a billing product.
    </Check>
  </Step>
</Steps>

## Step 2: Get Your API Keys

Before we build the app, let's gather the API keys we'll need.

<Steps>
  <Step title="Get Dodo Payments API Key">
    1. In your Dodo Payments dashboard, go to **Developers** → **API Keys**
    2. Click **Create API Key**
    3. Copy the API key - it will look like `test_abc123...`

    <Note>
      Save this API key - we'll add it to our `.env` file later.
    </Note>
  </Step>

  <Step title="Get Google AI API Key">
    1. Visit [aistudio.google.com](https://aistudio.google.com/api-keys)
    2. Click **Get API Key**
    3. Create a new API key or use an existing one
    4. Copy the key

    <Note>
      Keep this key safe - we'll also add it to our `.env` file.
    </Note>
  </Step>
</Steps>

***

## Step 3: Create Your Billing Product

Now we need to create a product that defines our pricing (\$0.01 per 1,000 tokens with 10,000 free tokens). This connects our meter to actual billing.

<Tip>
  **What we're building**: A product called "AI Chat Service" that charges based on token consumption with a generous free tier.
</Tip>

<Steps>
  <Step title="Navigate to Products">
    1. In your Dodo Payments dashboard, click **Products** in the left sidebar
    2. Click **Create Product**
    3. Select **Usage-Based** as the product type

    This tells Dodo Payments that billing will be based on meter usage, not a fixed subscription.
  </Step>

  <Step title="Enter product details">
    Fill in the required details:

    **Product Name**: → `AI Chat Service`

    **Description**: → `AI-powered chat service with automatic token-based billing`

    **Product Image**: Upload a relevant image

    <Info>
      These will appear on customer invoices, so make them clear and professional.
    </Info>
  </Step>

  <Step title="Connect your meter">
    Before connecting your meter, make sure you have selected **Usage Based Billing** as the price type for your product.

    Additionally, set the **Fixed Price** to `0` to ensure customers are only charged based on their usage, with no base fee.

    Now, link the meter you just created:

    1. Scroll down to the **Associated Meter** section
    2. Click **Add Meters**
    3. From the dropdown, select **"AI Token Usage Meter"** (the one you created earlier)
    4. Confirm that it appears in your product configuration

    <Check>
      Your meter is now successfully connected to this product.
    </Check>
  </Step>

  <Step title="Set your pricing">
    Here's where we define our business model:

    **Price Per Unit**: Enter → `0.00001` (this is $0.01 per 1,000 tokens or $0.00001 per token)

    **Free Threshold**: Enter → `10000` (customers get 10,000 free tokens per month)

    <Frame>
      <img alt="Product Pricing" />
    </Frame>

    <Tip>
      **How billing works**: If a customer uses 25,000 tokens in a month, they'll be charged for 15,000 tokens (25,000 - 10,000 free) = 15,000 × $0.00001 = $0.15
    </Tip>
  </Step>

  <Step title="Save your product">
    1. Review all your settings:
       * Name: AI Chat Service
       * Meter: AI Token Usage Meter
       * Price: \$0.01 per 1,000 tokens
       * Free tier: 10,000 tokens
    2. Click **Save Changes**

    <Check>
      **Product created!** Your billing is now configured. Customers will automatically be charged based on their token usage.
    </Check>
  </Step>
</Steps>

## Step 4: Make a Test Purchase

Before we start building the app, let's create a test customer by making a purchase.

<Steps>
  <Step title="Get your payment link">
    1. In your Dodo Payments dashboard, go to **Products**
    2. Find your "AI Chat Service" product
    3. Click the **Share** button next to your product
    4. Copy the payment link that appears
  </Step>

  <Step title="Complete a test purchase">
    1. Open the payment link in a new browser tab
    2. Enter test payment details and complete purchase

    <Check>
      After successful payment, you'll have a customer ID that we'll use in our application code.
    </Check>
  </Step>

  <Step title="Find your customer ID">
    1. Go back to your Dodo Payments dashboard
    2. Navigate to **Sales** -> **Customers** in the left sidebar
    3. Find the customer you just created (with the test email)
    4. Copy the customer ID - it will look like `cus_123`

    <Note>
      Save this customer ID - we'll use it when testing our chat application.
    </Note>
  </Step>
</Steps>

## Step 5: Build the Chat Application

Now we have our billing setup complete and a test customer created. Let's build the AI chat application with automatic token tracking.

<Steps>
  <Step title="Set up your project">
    Create a new directory and initialize the project:

    ```bash theme={null}
    mkdir ai-chat-app
    cd ai-chat-app
    npm init -y
    ```
  </Step>

  <Step title="Install dependencies">
    Install the packages we need:

    ```bash theme={null}
    npm install express ai @ai-sdk/google @dodopayments/ingestion-blueprints dotenv
    npm install --save-dev typescript @types/express @types/node tsx
    ```
  </Step>

  <Step title="Configure TypeScript">
    Create `tsconfig.json`:

    ```json tsconfig.json theme={null}
    {
      "compilerOptions": {
        "target": "ES2020",
        "module": "ESNext",
        "moduleResolution": "node",
        "esModuleInterop": true,
        "strict": true,
        "skipLibCheck": true,
        "outDir": "./dist",
        "rootDir": "./src"
      },
      "include": ["src/**/*"],
      "exclude": ["node_modules"]
    }
    ```

    Update `package.json` to add the module type and scripts:

    ```json package.json theme={null}
    {
      "type": "module",
      "scripts": {
        "dev": "tsx src/server.ts",
        "build": "tsc",
        "start": "node dist/server.js"
      }
    }
    ```
  </Step>

  <Step title="Create project structure">
    Create the folders and files:

    ```bash theme={null}
    mkdir src public
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a `.env` file in your project root:

    ```bash .env theme={null}
    DODO_PAYMENTS_API_KEY=your_dodo_api_key_here
    DODO_ENVIRONMENT=test_mode
    GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
    PORT=3000
    ```

    Replace the placeholder values with your actual API keys from Step 2.
  </Step>

  <Step title="Create the backend server">
    Create `src/server.ts` and copy this complete server code:
  </Step>
</Steps>

Here's the complete AI chat server with integrated billing:

<CodeGroup>
  ```typescript src/server.ts expandable theme={null}
  import express, { Request, Response } from 'express';
  import { generateText } from 'ai';
  import { google } from '@ai-sdk/google';
  import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
  import 'dotenv/config';

  const app = express();
  app.use(express.json());
  app.use(express.static('public'));

  // Replace with your test customer ID
  const CUSTOMER_ID = 'cus_123';

  // Create tracker once with your meter event name
  const llmTracker = createLLMTracker({
    apiKey: process.env.DODO_PAYMENTS_API_KEY!,
    environment: process.env.DODO_ENVIRONMENT as 'test_mode' | 'live_mode',
    eventName: 'ai_chat_usage', // Must match your meter configuration
  });

  // Chat endpoint with conversation support
  app.post('/chat', async (req: Request, res: Response) => {
    try {
      const { messages } = req.body;

      if (!messages || !Array.isArray(messages)) {
        return res.status(400).json({ 
          error: 'Missing required field: messages (array)' 
        });
      }

      // Wrap AI SDK with automatic token tracking
      const trackedClient = llmTracker.wrap({
        client: { generateText },
        customerId: CUSTOMER_ID
      });

      // Generate AI response - tokens are automatically tracked!
      const response = await trackedClient.generateText({
        model: google('gemini-2.5-flash'),
        messages: messages
      });

      res.json({
        message: response.text,
        usage: {
          totalTokens: response.usage.totalTokens
        }
      });

    } catch (error: any) {
      console.error('Chat error:', error);
      res.status(500).json({ 
        error: 'Failed to process chat',
        details: error.message 
      });
    }
  });

  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`🚀 Server running at http://localhost:${PORT}`);
    console.log(`📊 Tracking event: ai_chat_usage`);
    console.log(`👤 Customer ID: ${CUSTOMER_ID}`);
    console.log(`🔧 Environment: ${process.env.DODO_ENVIRONMENT}`);
  });
  ```

  ```bash .env theme={null}
  # Add your API keys here
  DODO_PAYMENTS_API_KEY=your_dodo_api_key_here
  DODO_ENVIRONMENT=test_mode
  GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
  PORT=3000
  ```

  ```json package.json expandable theme={null}
  {
    "name": "ai-chat-app",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
      "dev": "tsx src/server.ts",
      "build": "tsc",
      "start": "node dist/server.js"
    },
    "dependencies": {
      "express": "^4.18.2",
      "ai": "^3.0.0",
      "@ai-sdk/google": "^0.0.15",
      "@dodopayments/ingestion-blueprints": "latest",
      "dotenv": "^16.0.3"
    },
    "devDependencies": {
      "typescript": "^5.0.0",
      "@types/express": "^4.17.17",
      "@types/node": "^20.0.0",
      "tsx": "^3.12.7"
    }
  }
  ```
</CodeGroup>

***

## Step 6: Add the Chat Interface

Now let's add a beautiful chat interface with full conversation history! Create `public/index.html`:

```html public/index.html expandable theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>AI Chat with Usage Billing</title>
    <style>
      * {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }

      body {
        font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI",
          Roboto, sans-serif;
        background: #0f0f1e;
        background-image: radial-gradient(
            at 0% 0%,
            rgba(102, 126, 234, 0.15) 0px,
            transparent 50%
          ),
          radial-gradient(
            at 100% 100%,
            rgba(118, 75, 162, 0.15) 0px,
            transparent 50%
          ),
          radial-gradient(
            at 50% 50%,
            rgba(102, 126, 234, 0.05) 0px,
            transparent 50%
          );
        height: 100vh;
        display: flex;
        justify-content: center;
        align-items: center;
        padding: 0;
        position: relative;
        overflow: hidden;
        margin: 0;
      }

      .chat-container {
        background: rgba(22, 22, 35, 0.95);
        border: 1px solid rgba(102, 126, 234, 0.2);
        border-radius: 0;
        box-shadow: 0 10px 40px rgba(0, 0, 0, 0.5);
        width: 100%;
        max-width: 100%;
        height: 100vh;
        display: flex;
        flex-direction: column;
        overflow: hidden;
        position: relative;
        z-index: 1;
      }

      .chat-header {
        background: linear-gradient(
          135deg,
          rgba(102, 126, 234, 0.15) 0%,
          rgba(118, 75, 162, 0.15) 100%
        );
        border-bottom: 1px solid rgba(102, 126, 234, 0.2);
        color: white;
        padding: 24px 28px;
        position: relative;
        overflow: hidden;
      }

      .chat-header h1 {
        font-size: 26px;
        margin-bottom: 6px;
        font-weight: 700;
        letter-spacing: -0.5px;
        color: #fff;
      }

      .chat-header p {
        font-size: 13px;
        opacity: 0.6;
        font-weight: 500;
        letter-spacing: 0.3px;
      }

      .chat-messages {
        flex: 1;
        overflow-y: auto;
        padding: 32px 10%;
        background: transparent;
        will-change: scroll-position;
        scroll-behavior: smooth;
      }

      .chat-messages::-webkit-scrollbar {
        width: 6px;
      }

      .chat-messages::-webkit-scrollbar-track {
        background: rgba(255, 255, 255, 0.05);
      }

      .chat-messages::-webkit-scrollbar-thumb {
        background: rgba(102, 126, 234, 0.3);
        border-radius: 3px;
      }

      .chat-messages::-webkit-scrollbar-thumb:hover {
        background: rgba(102, 126, 234, 0.5);
      }

      .message {
        margin-bottom: 20px;
        display: flex;
        gap: 12px;
        animation: slideIn 0.2s ease-out;
      }

      @keyframes slideIn {
        from {
          opacity: 0;
          transform: translateY(10px);
        }

        to {
          opacity: 1;
          transform: translateY(0);
        }
      }

      .message.user {
        flex-direction: row-reverse;
      }

      .message-avatar {
        width: 40px;
        height: 40px;
        border-radius: 12px;
        display: flex;
        align-items: center;
        justify-content: center;
        font-size: 20px;
        flex-shrink: 0;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
      }

      .message.user .message-avatar {
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      }

      .message.assistant .message-avatar {
        background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
      }

      .message-content {
        max-width: 65%;
      }

      .message-bubble {
        padding: 14px 18px;
        border-radius: 18px;
        line-height: 1.6;
        word-wrap: break-word;
        font-size: 15px;
        position: relative;
      }

      .message.user .message-bubble {
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        color: white;
        border-bottom-right-radius: 6px;
        box-shadow: 0 2px 8px rgba(102, 126, 234, 0.3);
      }

      .message.assistant .message-bubble {
        background: rgba(255, 255, 255, 0.05);
        color: rgba(255, 255, 255, 0.95);
        border: 1px solid rgba(255, 255, 255, 0.1);
        border-bottom-left-radius: 6px;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
      }

      .message-meta {
        display: flex;
        gap: 10px;
        margin-top: 8px;
        font-size: 11px;
        color: rgba(255, 255, 255, 0.4);
        font-weight: 500;
      }

      .message.user .message-meta {
        justify-content: flex-end;
      }

      .token-badge {
        background: rgba(102, 126, 234, 0.2);
        color: #a8b9ff;
        padding: 4px 10px;
        border-radius: 12px;
        font-weight: 600;
        border: 1px solid rgba(102, 126, 234, 0.3);
      }

      .chat-input-area {
        padding: 24px 10% 32px;
        background: rgba(22, 22, 35, 0.95);
        border-top: 1px solid rgba(102, 126, 234, 0.2);
      }

      .input-wrapper {
        display: flex;
        gap: 12px;
        align-items: flex-end;
      }

      #messageInput {
        flex: 1;
        background: rgba(255, 255, 255, 0.05);
        border: 2px solid rgba(102, 126, 234, 0.2);
        border-radius: 16px;
        padding: 14px 20px;
        font-size: 15px;
        font-family: inherit;
        resize: none;
        max-height: 120px;
        transition: border-color 0.2s ease, background 0.2s ease;
        color: white;
        will-change: border-color;
        overflow: hidden;
        scrollbar-width: none;
        /* Firefox */
      }

      #messageInput::-webkit-scrollbar {
        display: none;
      }

      #messageInput::placeholder {
        color: rgba(255, 255, 255, 0.3);
      }

      #messageInput:focus {
        outline: none;
        border-color: #667eea;
        background: rgba(255, 255, 255, 0.08);
      }

      #sendBtn {
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        color: white;
        border: none;
        width: 52px;
        height: 52px;
        border-radius: 16px;
        cursor: pointer;
        display: flex;
        align-items: center;
        justify-content: center;
        font-size: 22px;
        transition: transform 0.1s ease, box-shadow 0.1s ease;
        flex-shrink: 0;
        box-shadow: 0 2px 8px rgba(102, 126, 234, 0.4);
        position: relative;
      }

      #sendBtn:hover:not(:disabled) {
        transform: translateY(-1px);
        box-shadow: 0 4px 12px rgba(102, 126, 234, 0.5);
      }

      #sendBtn:active:not(:disabled) {
        transform: translateY(0);
      }

      #sendBtn:disabled {
        opacity: 0.4;
        cursor: not-allowed;
        box-shadow: none;
      }

      .typing-indicator {
        display: none;
        padding: 14px 18px;
        background: rgba(255, 255, 255, 0.05);
        border: 1px solid rgba(255, 255, 255, 0.1);
        border-radius: 18px;
        border-bottom-left-radius: 6px;
        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
        width: fit-content;
      }

      .typing-indicator.show {
        display: block;
      }

      .typing-dots {
        display: flex;
        gap: 6px;
      }

      .typing-dots span {
        width: 10px;
        height: 10px;
        border-radius: 50%;
        background: #667eea;
        animation: typing 1.4s infinite ease-in-out;
        will-change: transform, opacity;
      }

      .typing-dots span:nth-child(2) {
        animation-delay: 0.2s;
      }

      .typing-dots span:nth-child(3) {
        animation-delay: 0.4s;
      }

      @keyframes typing {
        0%,
        60%,
        100% {
          transform: translateY(0) scale(1);
          opacity: 0.6;
        }

        30% {
          transform: translateY(-12px) scale(1.1);
          opacity: 1;
        }
      }

      .error-message {
        background: rgba(239, 68, 68, 0.15);
        color: #fca5a5;
        padding: 14px 18px;
        border-radius: 12px;
        margin-bottom: 12px;
        display: none;
        border: 1px solid rgba(239, 68, 68, 0.3);
        font-size: 14px;
        font-weight: 500;
      }

      .error-message.show {
        display: block;
        animation: slideIn 0.3s ease;
      }

      .empty-state {
        text-align: center;
        padding: 80px 20px;
        color: rgba(255, 255, 255, 0.5);
      }

      .empty-state-icon {
        font-size: 72px;
        margin-bottom: 20px;
        animation: float 3s ease-in-out infinite;
      }

      @keyframes float {
        0%,
        100% {
          transform: translateY(0px);
        }

        50% {
          transform: translateY(-10px);
        }
      }

      .empty-state h2 {
        font-size: 24px;
        margin-bottom: 10px;
        color: rgba(255, 255, 255, 0.9);
        font-weight: 700;
        letter-spacing: -0.5px;
      }

      .empty-state p {
        font-size: 15px;
        color: rgba(255, 255, 255, 0.4);
        font-weight: 500;
      }
    </style>
  </head>

  <body>
    <div class="chat-container">
      <div class="chat-header">
        <h1>🤖 AI Chat Assistant</h1>
        <p>Powered by AI-SDK & Dodo Payments</p>
      </div>

      <div class="chat-messages" id="chatMessages">
        <div class="empty-state" id="emptyState">
          <div class="empty-state-icon">💬</div>
          <h2>Start a Conversation</h2>
          <p>Ask me anything! Your token usage is automatically tracked.</p>
        </div>
      </div>

      <div class="chat-input-area">
        <div class="error-message" id="errorMessage"></div>
        <div class="input-wrapper">
          <textarea
            id="messageInput"
            placeholder="Type your message here..."
            rows="1"
          ></textarea>
          <button id="sendBtn" onclick="sendMessage()">➤</button>
        </div>
      </div>
    </div>

    <script>
      let conversationHistory = [];

      const messageInput = document.getElementById("messageInput");
      let resizeTimeout;
      messageInput.addEventListener("input", function () {
        clearTimeout(resizeTimeout);
        resizeTimeout = setTimeout(() => {
          this.style.height = "auto";
          this.style.height = Math.min(this.scrollHeight, 120) + "px";
        }, 10);
      });

      // Send message on Enter (Shift+Enter for new line)
      messageInput.addEventListener("keydown", function (e) {
        if (e.key === "Enter" && !e.shiftKey) {
          e.preventDefault();
          sendMessage();
        }
      });

      async function sendMessage() {
        const input = document.getElementById("messageInput");
        const message = input.value.trim();

        if (!message) return;

        // Hide empty state
        document.getElementById("emptyState").style.display = "none";

        // Hide error
        document.getElementById("errorMessage").classList.remove("show");

        // Add user message to UI
        addMessage("user", message);

        // Add to conversation history
        conversationHistory.push({
          role: "user",
          content: message,
        });

        // Clear input
        input.value = "";
        input.style.height = "auto";

        // Show typing indicator
        showTypingIndicator();

        // Disable send button
        const sendBtn = document.getElementById("sendBtn");
        sendBtn.disabled = true;

        try {
          const response = await fetch("/chat", {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              messages: conversationHistory,
            }),
          });

          const data = await response.json();

          if (!response.ok) {
            throw new Error(data.error || "Failed to get response");
          }

          // Hide typing indicator
          hideTypingIndicator();

          // Add assistant response to UI
          addMessage("assistant", data.message, data.usage);

          // Add to conversation history
          conversationHistory.push({
            role: "assistant",
            content: data.message,
          });
        } catch (error) {
          hideTypingIndicator();
          showError(error.message);
          // Remove the last user message from history since it failed
          conversationHistory.pop();
        } finally {
          sendBtn.disabled = false;
        }
      }

      function addMessage(role, content, usage = null) {
        const messagesDiv = document.getElementById("chatMessages");

        const messageDiv = document.createElement("div");
        messageDiv.className = `message ${role}`;

        const avatar = role === "user" ? "👤" : "🤖";

        let metaHTML = "";
        if (usage) {
          metaHTML = `
                    <div class="message-meta">
                        <span class="token-badge">📊 ${usage.totalTokens} tokens</span>
                    </div>
                `;
        }

        messageDiv.innerHTML = `
                <div class="message-avatar">${avatar}</div>
                <div class="message-content">
                    <div class="message-bubble">${escapeHtml(content)}</div>
                    ${metaHTML}
                </div>
            `;

        messagesDiv.appendChild(messageDiv);
        requestAnimationFrame(() => {
          messagesDiv.scrollTop = messagesDiv.scrollHeight;
        });
      }

      function showTypingIndicator() {
        const messagesDiv = document.getElementById("chatMessages");

        const typingDiv = document.createElement("div");
        typingDiv.className = "message assistant";
        typingDiv.id = "typingIndicator";
        typingDiv.innerHTML = `
                <div class="message-avatar">🤖</div>
                <div class="typing-indicator show">
                    <div class="typing-dots">
                        <span></span>
                        <span></span>
                        <span></span>
                    </div>
                </div>
            `;

        messagesDiv.appendChild(typingDiv);
        requestAnimationFrame(() => {
          messagesDiv.scrollTop = messagesDiv.scrollHeight;
        });
      }

      function hideTypingIndicator() {
        const typingIndicator = document.getElementById("typingIndicator");
        if (typingIndicator) {
          typingIndicator.remove();
        }
      }

      function showError(message) {
        const errorDiv = document.getElementById("errorMessage");
        errorDiv.textContent = "❌ " + message;
        errorDiv.classList.add("show");
      }

      function escapeHtml(text) {
        const div = document.createElement("div");
        div.textContent = text;
        return div.innerHTML.replace(/\n/g, "<br>");
      }
    </script>
  </body>
</html>
```

***

## Step 7: Test Your Chat Application

Time to test our AI chat app and see the billing in action! Let's make sure everything works end-to-end.

<Tip>
  **What we're testing**: We'll have some conversations with the AI, verify the token events reach Dodo Payments, and confirm billing calculations are correct.
</Tip>

<Steps>
  <Step title="Start the server">
    First, make sure everything is set up:

    1. Verify your `.env` file has all the API keys from Step 2
    2. Start the development server:

    ```bash theme={null}
    npm run dev
    ```

    You should see:

    ```
    🚀 Server running at http://localhost:3000
    📊 Tracking event: ai_chat_usage
    👤 Customer ID: {YOUR CUSTOMER_ID}
    🔧 Environment: test_mode
    ```

    <Check>
      Server is running! Time to chat.
    </Check>
  </Step>

  <Step title="Open the chat interface">
    1. Open your browser
    2. Navigate to `http://localhost:3000`
    3. You should see the beautiful chat interface

    <Note>
      Make sure you update the `CUSTOMER_ID` in `server.ts` with your actual test customer ID from Step 4.
    </Note>
  </Step>

  <Step title="Have your first conversation">
    Let's test it out! Try these messages:

    1. **"What is artificial intelligence?"**
    2. **"How does machine learning work?"**
    3. **"Can you explain neural networks?"**

    Watch the token usage display update after each response!

    <Check>
      If you see the AI responding and token counts appearing, your app is working!
    </Check>
  </Step>

  <Step title="Check your Dodo Payments dashboard">
    Now let's verify the events are being received:

    1. Open your Dodo Payments dashboard
    2. Go to **Usage Billing** → **AI Token Usage Meter**
    3. Click on the **Events** tab
    4. You should see your chat events listed

    **What to look for:**

    * Event names: `ai_chat_usage`
    * Customer ID: Your test customer id

    <Frame>
      <img alt="Meter Events" />
    </Frame>

    <Check>
      You should see one event for each message you sent!
    </Check>
  </Step>

  <Step title="Verify token counting">
    Let's send some more messages and check if the token aggregation is working:

    1. In your meter, go to the **Customers** tab
    2. Find your test customer
    3. Check the "Consumed Units" column - it should show the total tokens used

    <Frame>
      <img alt="Meter Customer Tokens" />
    </Frame>

    <Info>
      The meter is summing up all `totalTokens` values automatically!
    </Info>
  </Step>

  <Step title="Test the free tier">
    Let's use enough tokens to exceed the free tier:

    1. Have several more conversations (aim for \~15,000+ total tokens)
    2. Check your **Customers** tab in meter dashboard again
    3. You should now see:
       * Consumed Units: 15,000+ tokens
       * Chargeable Units: 5,000 (10,000 free tokens applied)
       * Total Price: \~\$0.05

    <Frame>
      <img alt="Free Tier Test" />
    </Frame>

    <Check>
      **Success!** Your usage-based billing is working perfectly. Customers will be automatically charged based on their actual token consumption.
    </Check>
  </Step>
</Steps>

***

## Troubleshooting

Common issues and their solutions:

<AccordionGroup>
  <Accordion title="Events not appearing in dashboard">
    **Possible causes:**

    * Event name doesn't match meter configuration exactly
    * Customer ID doesn't exist in your account
    * API key is invalid or expired
    * Network connectivity issues

    **Solutions:**

    1. Verify event name matches meter configuration exactly (case-sensitive: `ai_chat_usage`)
    2. Check that customer ID exists in Dodo Payments dashboard
    3. Test API key with a simple API call
    4. Check server logs for error messages
  </Accordion>

  <Accordion title="Token counts showing zero">
    **Possible causes:**

    * Model not returning usage information
    * Incorrect SDK version

    **Solutions:**

    1. Test if model returns usage:

    ```typescript theme={null}
    const response = await generateText({...});
    console.log('Usage:', response.usage);
    ```

    2. Update to latest Blueprints SDK: `npm install @dodopayments/ingestion-blueprints@latest`
  </Accordion>

  <Accordion title="API key invalid error">
    **Possible causes:**

    * Wrong API key for environment
    * Extra spaces or quotes in `.env` file

    **Solutions:**

    * Ensure test key starts with `test_`, live key starts with `live_`
    * Remove any quotes around keys in `.env` file
    * Generate a new key if needed
  </Accordion>
</AccordionGroup>

Need help?

* [Discord Community](https://discord.gg/bYqAp4ayYh)
* [support@dodopayments.com](mailto:support@dodopayments.com)

***

## Congratulations! You Built an AI Chat App

You now have a fully functional AI chat application with automatic token usage tracking and billing powered by Dodo Payments. 🎉

### Learn More

<CardGroup>
  <Card title="LLM Blueprint" icon="robot" href="/developer-resources/ingestion-blueprints/llm">
    Learn more about LLM Ingestion Blueprint
  </Card>

  <Card title="Ingestion Blueprints SDK" icon="github" href="https://github.com/dodopayments/ingestion-blueprints">
    Check out the GitHub repository for more examples
  </Card>

  <Card title="Join Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Get help and share your projects on Discord
  </Card>
</CardGroup>


# Bun Adaptor
Source: https://docs.dodopayments.com/developer-resources/bun-adaptor

Learn how to integrate Dodo Payments with your Bun server project using our Bun Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your Bun server.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    bun add @dodopayments/bun
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    DODO_PAYMENTS_RETURN_URL=your-return-url
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using Bun's native server with <code>Bun.serve()</code>.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Bun server. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript Bun Server Handler expandable theme={null}
      import { Checkout } from '@dodopayments/bun';

      const staticCheckoutHandler = Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "static"
      });

      const sessionCheckoutHandler = Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "session"
      });

      const dynamicCheckoutHandler = Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "dynamic"
      });

      Bun.serve({
        port: 3000,
        fetch(request) {
          const url = new URL(request.url);
          
          if (url.pathname === "/api/checkout") {
            if (request.method === "GET") {
              return staticCheckoutHandler(request);
            }
            if (request.method === "POST") {
              return sessionCheckoutHandler(request);
              // or return dynamicCheckoutHandler(request);
            }
          }
          
          return new Response("Not Found", { status: 404 });
        },
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_xxx' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_xxx",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_xxx",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Bun Server Handler expandable theme={null}
      import { CustomerPortal } from "@dodopayments/bun";

      const customerPortalHandler = CustomerPortal({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      });

      Bun.serve({
        port: 3000,
        fetch(request) {
          const url = new URL(request.url);
          
          if (url.pathname === "/api/customer-portal" && request.method === "GET") {
            return customerPortalHandler(request);
          }
          
          return new Response("Not Found", { status: 404 });
        },
      });
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_123&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Bun server.
    </Info>

    <CodeGroup>
      ```typescript Bun Server Handler expandable theme={null}
      import { Webhooks } from "@dodopayments/bun";

      const webhookHandler = Webhooks({
        webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
        onPayload: async (payload) => {
          // handle the payload
        },
        // ... other event handlers for granular control
      });

      Bun.serve({
        port: 3000,
        fetch(request) {
          const url = new URL(request.url);
          
          if (url.pathname === "/api/webhook/dodo-payments" && request.method === "POST") {
            return webhookHandler(request);
          }
          
          return new Response("Not Found", { status: 404 });
        },
      });
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_xxx</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Bun server application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

````

You are an expert Bun developer assistant. Your task is to guide a user through integrating the @dodopayments/bun adapter into their existing Bun project.

The @dodopayments/bun adapter provides handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Bun's native server with Bun.serve().

First, install the necessary package:

bun add @dodopayments/bun

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/bun adapter would you like to integrate into your project? You can choose one or more of the following:
1. Checkout (static, dynamic, or session-based)
2. Customer Portal
3. Webhooks"

    Based on the user's selection, provide step-by-step integration instructions.

For each selected functionality, show:

    The environment variables required
    The exact code to add to their server file
    Where to place the code in their Bun.serve() configuration

Provide complete, working examples that the user can copy and paste directly into their project.

    Environment Variables Setup

Always include instructions for setting up the .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Remind the user to never commit their .env file to version control.

    For Checkout Integration

If the user selects Checkout, ask which type they need:

    Static checkout (GET requests with query parameters)
    Dynamic checkout (POST requests with JSON body)
    Checkout sessions (POST requests with product cart)

Provide the appropriate handler code for their selection.

    For Customer Portal Integration

Provide a complete example showing how to integrate the customer portal handler into their Bun server.

    For Webhook Integration

Provide a complete example showing how to integrate the webhook handler with available event handlers for granular control.

    Full Example

If the user wants to integrate all three functionalities, provide a complete Bun server example that combines all handlers.

```typescript
import { Checkout, CustomerPortal, Webhooks } from "@dodopayments/bun";

const staticCheckoutHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static",
});

const sessionCheckoutHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session",
});

const customerPortalHandler = CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
});

const webhookHandler = Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPaymentSucceeded: async (payload) => {
    console.log("Payment succeeded:", payload);
    // Your business logic here
  },
  onSubscriptionActive: async (payload) => {
    console.log("Subscription activated:", payload);
    // Your business logic here
  },
});

Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);
    
    // Checkout routes
    if (url.pathname === "/api/checkout") {
      if (request.method === "GET") {
        return staticCheckoutHandler(request);
      }
      if (request.method === "POST") {
        return sessionCheckoutHandler(request);
      }
    }
    
    // Customer portal route
    if (url.pathname === "/api/customer-portal" && request.method === "GET") {
      return customerPortalHandler(request);
    }
    
    // Webhook route
    if (url.pathname === "/api/webhook/dodo-payments" && request.method === "POST") {
      return webhookHandler(request);
    }
    
    return new Response("Not Found", { status: 404 });
  },
});

console.log("Server running on http://localhost:3000");

Additional Guidance:
• Explain that the handlers are Bun-native and work seamlessly with Bun.serve()
• Highlight the use of Web Standard Request and Response objects
• Mention that error handling is built-in and returns appropriate HTTP status codes
• Provide links to the Dodo Payments documentation for more details
````


# Checkout Sessions
Source: https://docs.dodopayments.com/developer-resources/checkout-session

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

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="#creating-your-first-checkout-session">
    Get your first checkout session running in under 5 minutes
  </Card>

  <Card title="API Reference & Live Testing" icon="code" href="/api-reference/checkout-sessions/create">
    Explore the full API documentation and interactively test Checkout Session requests and responses.
  </Card>

  <Card title="Preview Checkout" icon="eye" href="/api-reference/checkout-sessions/preview">
    Calculate pricing, taxes, and totals before creating a session.
  </Card>
</CardGroup>

<Info>
  **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.
</Info>

<Warning>
  **Single-Use Links**: The `checkout_url` returned by the API is not reusable and expires within 24 hours (or 15 minutes when `confirm=true`). It is intended for a single customer to complete one payment. Generate a fresh checkout session for each customer and each payment attempt rather than sharing or reusing a link.
</Warning>

## Prerequisites

<Steps>
  <Step title="Dodo Payments Account">
    You'll need an active Dodo Payments merchant account with API access.
  </Step>

  <Step title="API Credentials">
    Generate your API credentials from the Dodo Payments dashboard:
  </Step>

  <Step title="Products Setup">
    Create your products in the Dodo Payments dashboard before implementing checkout sessions.
  </Step>
</Steps>

## Creating Your First Checkout Session

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript expandable theme={null}
    import DodoPayments from 'dodopayments';

    // Initialize the Dodo Payments client
    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: 'test_mode', // defaults to 'live_mode'
    });

    async function createCheckoutSession() {
      try {
        const session = await client.checkoutSessions.create({
          // Products to sell - use IDs from your Dodo Payments dashboard
          product_cart: [
            {
              product_id: 'pdt_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' });
      }
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python expandable theme={null}
    import os
    from dodopayments import DodoPayments

    # Initialize the Dodo Payments client
    client = DodoPayments(
        bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
        environment="test_mode",  # defaults to "live_mode"
    )

    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": "pdt_123",  # Replace with your actual product ID
                        "quantity": 1
                    }
                ],
                
                # Pre-fill customer information to reduce checkout 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
            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
    ```
  </Tab>

  <Tab title="REST API">
    ```javascript expandable theme={null}
    // 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: 'pdt_123', // Replace with your actual product ID
                quantity: 1
              }
            ],
            
            // Pre-fill customer information to reduce checkout 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'
            }
          })
        });

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

### API Response

All methods above return the same response structure:

```json theme={null}
{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
```

Only `session_id` is guaranteed to be present. Two cases return additional or fewer fields:

* **`payment_method_id` was provided** — the charge is processed immediately and `checkout_url` is `null`. Use the returned `payment_id` instead.
* **`confirm: true` created the payment at session-creation time** — the response also includes `payment_id`, `client_secret`, and `publishable_key` for use with the Dodo Payments checkout SDK.

<Note>
  The generated `checkout_url` is single-use and expires within 24 hours. Don't cache or reuse it across customers or payment attempts — create a new checkout session whenever you need a fresh link.
</Note>

<Steps>
  <Step title="Get the checkout URL">
    Extract the `checkout_url` from the API response.
  </Step>

  <Step title="Redirect your customer">
    Direct your customer to the checkout URL to complete their purchase.

    ```javascript theme={null}
    // Redirect immediately
    window.location.href = session.checkout_url;

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

    <Tip>
      **Alternative Integration Options**: Instead of redirecting, you can embed the checkout directly in your page using [Overlay Checkout](/developer-resources/overlay-checkout) (modal overlay) or [Inline Checkout](/developer-resources/inline-checkout) (fully embedded). In a native mobile app, hand the same URL to the [Mobile Checkout SDKs](/developer-resources/mobile-integration) for Android, iOS, React Native, or Flutter. All of these consume the same checkout session URL.
    </Tip>
  </Step>

  <Step title="Handle the return">
    After payment, customers are redirected to your `return_url` with query parameters including payment/subscription ID, status, customer email, and any license keys. See the [`return_url` parameter docs](#request-body) for the full list.
  </Step>
</Steps>

## Request Body

<CardGroup>
  <Card title="Required Fields" icon="asterisk">
    Essential fields needed for every checkout session
  </Card>

  <Card title="Optional Fields" icon="gear">
    Additional configuration to customize your checkout experience
  </Card>
</CardGroup>

### Required Fields

<ParamField type="array">
  Array of products to include in the checkout session. Each product must have a valid `product_id` from your Dodo Payments dashboard.

  <Tip>
    **Mixed Checkout**: You can combine one-time payment products and subscription products in the same checkout session. This enables powerful use cases like setup fees with subscriptions, hardware bundles with SaaS, and more.
  </Tip>

  <Expandable title="Product Cart Item Properties">
    <ParamField type="string">
      The unique identifier of the product from your Dodo Payments dashboard.

      **Example:** `"pdt_123abc456def"`
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.

      **Example:** `1` for single item, `3` for multiple quantities
    </ParamField>

    <ParamField type="array">
      Array of addons to attach to the product. Only valid if the product is a subscription.

      <Expandable title="Addon item properties">
        <ParamField type="string" />

        <ParamField type="integer" />
      </Expandable>
    </ParamField>

    <ParamField type="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`.
    </ParamField>

    <ParamField type="array">
      Per-checkout-session overrides for credit entitlements already attached to this product. Use this to grant a different number of credits for this single session — e.g., a promotional bundle that grants 1,000 API credits instead of the product-default 500 — without creating a separate product.

      <Info>
        Each `credit_entitlement_id` must already be attached to the product. This field overrides only the `credits_amount` granted when this session is fulfilled; product-level credit entitlement settings (expiration, rollover, etc.) still apply.
      </Info>

      <Expandable title="Credit entitlement override properties">
        <ParamField type="string">
          ID of the credit entitlement to override. Must already be attached to the product.
        </ParamField>

        <ParamField type="string">
          Number of credits to grant for this checkout session, overriding the product-level `credits_amount`. Must be greater than zero.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<Tip>
  **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](/api-reference/products/get-products).
</Tip>

### Optional Fields

Configure these fields to customize the checkout experience and add business logic to your payment flow.

<AccordionGroup>
  <Accordion title="Customer Information">
    <ParamField type="object">
      Customer information. You can either attach an existing customer using their ID or create a new customer record during checkout.

      <Tabs>
        <Tab title="Attach Existing Customer">
          Attach an existing customer to the checkout session using their ID.

          <Expandable title="Existing Customer Properties">
            <ParamField type="string">
              The unique identifier of an existing customer. Use this to attach the checkout session to an existing customer instead of creating a new one.
            </ParamField>
          </Expandable>
        </Tab>

        <Tab title="New Customer">
          Create a new customer record during checkout.

          <Expandable title="New Customer Properties">
            <ParamField type="string">
              Customer's email address. Required when creating a new customer.
            </ParamField>

            <ParamField type="string">
              Customer's full name as it should appear on receipts and invoices.

              **Example**: `"John Doe"` or `"Jane Smith"`
            </ParamField>

            <ParamField type="string">
              Customer's phone number in international format. Required for some payment methods and fraud prevention.

              **Format**: Include country code, e.g., `"+1234567890"` for US numbers
            </ParamField>
          </Expandable>
        </Tab>
      </Tabs>
    </ParamField>

    <ParamField type="object">
      Billing address information for accurate tax calculation, fraud prevention, and regulatory compliance.

      <Info>
        When `confirm` is set to `true`, all billing address fields become required for successful session creation.
      </Info>

      <Expandable title="Billing address object properties">
        <ParamField type="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"`
        </ParamField>

        <ParamField type="string">
          City or municipality name.

          **Example**: `"San Francisco"`, `"New York"`, `"London"`
        </ParamField>

        <ParamField type="string">
          State, province, or region name. Use full names or standard abbreviations.

          **Example**: `"California"` or `"CA"`, `"Ontario"` or `"ON"`
        </ParamField>

        <ParamField type="string">
          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)

          <Card title="Country Code Reference" icon="globe" href="/api-reference/misc/supported-countries">
            View complete list of supported countries and their ISO codes
          </Card>
        </ParamField>

        <ParamField type="string">
          Postal code, ZIP code, or equivalent based on country requirements.

          **Examples**: `"94102"` (US), `"M5V 3A8"` (Canada), `"SW1A 1AA"` (UK)
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Payment Configuration">
    <ParamField type="array">
      Control which payment methods are available to customers during checkout. This helps optimize for specific markets or business requirements.

      **Common options**: `credit`, `debit`, `upi_collect`, `apple_pay`, `google_pay`, `amazon_pay`, `klarna`, `affirm`, `afterpay_clearpay`, `cashapp`, `ach`, `multibanco`, `bancontact_card`, `eps`, `ideal`, `blik`, `paypal`. This is not the full set — see the [Create Checkout Session API reference](/api-reference/checkout-sessions/create) for every accepted value.

      <Warning>
        **Critical**: Always include `credit` and `debit` as fallback options to prevent checkout failures when preferred payment methods are unavailable.
      </Warning>

      **Example**:

      ```json expandable theme={null}
      ["apple_pay", "google_pay", "credit", "debit"]
      ```
    </ParamField>

    <ParamField type="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

      <Note>
        This field is only effective when adaptive pricing is enabled. If adaptive pricing is disabled, the product's default currency will be used.
      </Note>
    </ParamField>

    <ParamField type="boolean">
      Display previously saved payment methods for returning customers, improving checkout speed and user experience.
    </ParamField>
  </Accordion>

  <Accordion title="Session Management">
    <ParamField type="string">
      URL to redirect customers after payment completion. Dodo Payments appends the following query parameters to your URL on redirect:

      | Parameter         | Type     | Condition                                                                         |
      | ----------------- | -------- | --------------------------------------------------------------------------------- |
      | `payment_id`      | `string` | Always present for one-time payments                                              |
      | `subscription_id` | `string` | Always present for subscription payments                                          |
      | `status`          | `string` | Always present                                                                    |
      | `license_key`     | `string` | Present if the product has license keys enabled. Comma-separated if multiple keys |
      | `email`           | `string` | Present if the customer has an email on record                                    |

      **Example redirect URLs:**

      ```text theme={null}
      # One-time payment with license key
      https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

      # Subscription payment with multiple license keys
      https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com

      # Payment without license keys
      https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&email=customer%40example.com
      ```

      <Tip>
        Use the `license_key` and `email` query parameters to display license keys or send a confirmation immediately on your return page, without needing an extra API call.
      </Tip>
    </ParamField>

    <ParamField type="string">
      URL to redirect customers when they click the back button or cancel the checkout session. If not provided, the back button will not be displayed.

      <Tip>
        Set a `cancel_url` to give customers a clear way to return to your site without completing the purchase. This improves the checkout experience and reduces friction.
      </Tip>
    </ParamField>

    <ParamField type="boolean">
      If true, finalizes all session details immediately. API will throw an error if required data is missing.
    </ParamField>

    <ParamField type="array">
      Apply one or more stacked discount codes to the checkout session. Codes are applied **in array order** (the first code reduces the base price, the second reduces the already-discounted price, and so on), up to a maximum of **20** codes per session.

      ```typescript theme={null}
      discount_codes: ['WELCOME10', 'BLACKFRIDAY20']
      ```

      <Info>
        The singular `discount_code` field below is **deprecated** but still fully supported — existing integrations continue to work without changes. It cannot be combined with `discount_codes` in the same request. Migrate to `discount_codes` when convenient to take advantage of stacking.
      </Info>
    </ParamField>

    <ParamField type="string">
      **Deprecated** — prefer `discount_codes` for new integrations. This field still works for backward compatibility, but cannot be combined with `discount_codes` in the same request.
    </ParamField>

    <ParamField type="object">
      Custom key-value pairs to store additional information about the session.
    </ParamField>

    <ParamField type="boolean">
      Override merchant default 3DS behaviour for this session.
    </ParamField>

    <ParamField type="boolean">
      Enable minimal address collection mode. When enabled, the checkout only collects:

      * **Country**: Always required for tax determination
      * **ZIP/Postal code**: Only in regions where it's necessary for sales tax, VAT, or GST calculation

      This significantly reduces checkout friction by eliminating unnecessary form fields.

      <Tip>
        Enable minimal address for faster checkout completion. Full address collection remains available for businesses that require complete billing details.
      </Tip>
    </ParamField>

    <ParamField type="string">
      A saved payment method belonging to the attached customer. Requires `confirm: true` and an existing `customer.customer_id`. When set, the charge is processed immediately and `checkout_url` is returned as `null` — use the returned `payment_id` instead.
    </ParamField>

    <ParamField type="boolean">
      If true, returns a shortened checkout URL instead of the full session URL.
    </ParamField>

    <ParamField type="string">
      Product collection ID for the collection-based checkout flow.
    </ParamField>

    <ParamField type="string">
      Tax ID for the customer (for example, a VAT number). Requires `billing_address` with a `country`.
    </ParamField>

    <ParamField type="string">
      Optional business or legal name associated with the tax ID. When provided together with a valid `tax_id`, it is rendered on the invoice instead of the customer's personal name.
    </ParamField>

    <ParamField type="integer">
      Override the merchant-level mandate floor (in INR paise) for INR e-mandates on Indian cards.
    </ParamField>
  </Accordion>

  <Accordion title="UI Customization & Features">
    <ParamField type="object">
      Customize the appearance and behavior of the checkout interface.

      <Expandable title="Customization object properties">
        <ParamField type="string">
          Theme for the checkout interface. Options: `light`, `dark`, or `system`.
        </ParamField>

        <ParamField type="boolean">
          Display order details section in the checkout interface.
        </ParamField>

        <ParamField type="boolean">
          Show the "on-demand" tag for applicable products.
        </ParamField>

        <ParamField type="string">
          Force the checkout interface to render in a specific language. By default, the checkout auto-detects the customer's browser language.

          **Supported language codes:**
          `ar` (Arabic), `ca` (Catalan), `de` (German), `en` (English), `es` (Spanish), `fr` (French), `he` (Hebrew), `id` (Indonesian), `it` (Italian), `ja` (Japanese), `ko` (Korean), `ms` (Malay), `nl` (Dutch), `pl` (Polish), `pt` (Portuguese), `ro` (Romanian), `ru` (Russian), `sv` (Swedish), `th` (Thai), `tr` (Turkish), `zh` (Chinese)

          **Example**: `"es"` for Spanish, `"ja"` for Japanese
        </ParamField>

        <ParamField type="object">
          Custom theme configuration with colors for light and dark modes, fonts, and button styling. This is the server-side replacement for the deprecated client-side `themeConfig` option.

          <Expandable title="Theme config properties">
            <ParamField type="object">
              Light mode color configuration.
            </ParamField>

            <ParamField type="object">
              Dark mode color configuration.
            </ParamField>

            <ParamField type="string">
              URL for the primary font. Must be a valid `https://` URL.
            </ParamField>

            <ParamField type="string">
              URL for the secondary font. Must be a valid `https://` URL.
            </ParamField>

            <ParamField type="string">
              Font size for the checkout UI. Options: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`.
            </ParamField>

            <ParamField type="string">
              Font weight for the checkout UI. Options: `normal`, `medium`, `bold`, `extraBold`.
            </ParamField>

            <ParamField type="string">
              Custom text for the pay button (for example, `"Complete Purchase"` or `"Subscribe Now"`). Max 100 characters.
            </ParamField>

            <ParamField type="string">
              Border radius for UI elements. A number followed by `px`, `rem`, or `em` (for example, `"4px"`, `"0.5rem"`, `"1em"`).
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="object">
      Configure specific features and behaviors for the checkout session.

      <Expandable title="Feature flags object properties">
        <ParamField type="boolean">
          Allow customers to select their preferred currency during checkout.
        </ParamField>

        <ParamField type="boolean">
          Show discount code input field in the checkout interface.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to add or remove addons on a subscription product during checkout. Only applies to subscription products.
        </ParamField>

        <ParamField type="boolean">
          Collect customer phone numbers during checkout.
        </ParamField>

        <ParamField type="boolean">
          Require the customer to provide a phone number to complete checkout. Requires `allow_phone_number_collection` to also be true.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to enter tax identification numbers.
        </ParamField>

        <ParamField type="boolean">
          Force creation of a new customer record instead of updating existing ones.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to edit their email address during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to edit their name during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to edit the street address during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to edit the city during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to edit the state during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to edit the country during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to edit the zipcode during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow customers to enter or edit their tax ID during checkout.
        </ParamField>

        <ParamField type="boolean">
          Allow the customer to supply or edit the business name associated with the tax ID. Works independently of `allow_customer_editing_tax_id` — either flag (or `allow_tax_id`) is sufficient. Typically set together with `allow_customer_editing_tax_id`.
        </ParamField>

        <ParamField type="boolean">
          Skip the default payment success page and redirect customers immediately to your `return_url` after payment completion.

          <Tip>
            Use this when you have a custom success page that provides a better user experience, or for [mobile apps](/developer-resources/mobile-integration) and embedded checkout flows.
          </Tip>
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Custom Fields">
    <ParamField type="array">
      Collect additional information from customers during checkout with custom form fields. You can define up to 5 custom fields per checkout session. Customer responses are included in webhook payloads and available via the API.

      <Expandable title="Custom field object properties">
        <ParamField type="string">
          Unique identifier for this field. Used as the key in webhook payloads and API responses.

          **Example**: `"company_name"`, `"referral_source"`, `"team_size"`
        </ParamField>

        <ParamField type="string">
          Display label shown to the customer on the checkout form.

          **Example**: `"Company Name"`, `"How did you hear about us?"`, `"Team Size"`
        </ParamField>

        <ParamField type="string">
          Type of field determining input validation rules.

          **Available types**:

          * `text` - Single-line text input
          * `number` - Numeric input
          * `email` - Email address with validation
          * `url` - URL with validation
          * `date` - Date picker
          * `dropdown` - Select from predefined options
          * `boolean` - Yes/No toggle
        </ParamField>

        <ParamField type="boolean">
          Whether this field must be filled before checkout can complete.
        </ParamField>

        <ParamField type="string">
          Placeholder text displayed in the input field.
        </ParamField>

        <ParamField type="array">
          List of options for `dropdown` field type. Required when `field_type` is `dropdown`, ignored for other types.

          **Example**: `["Google", "Twitter", "Friend referral", "Other"]`
        </ParamField>
      </Expandable>
    </ParamField>

    <Info>
      Customer responses to custom fields are included in:

      * **Webhooks**: `payment.succeeded`, `subscription.active`, and other relevant event payloads contain the `custom_field_responses` array
      * **API responses**: Payment and subscription objects include `custom_field_responses`
    </Info>
  </Accordion>

  <Accordion title="Subscription Configuration">
    <ParamField type="object">
      Additional configuration for checkout sessions containing subscription products.

      <Expandable title="Subscription data object properties">
        <ParamField type="integer">
          Number of days for the trial period before the first charge. Must be between 0 and 10000 days.

          A paid trial amount cannot be set per session — configure `trial_amount` on the product's recurring price instead. See [Paid Trials](/features/subscription#paid-trials).
        </ParamField>

        <ParamField type="object">
          On-demand subscription configuration for usage-based or metered billing.

          <Expandable title="On-demand object properties">
            <ParamField type="boolean">
              If set to true, does not perform any charge and only authorizes payment method details for future use.
            </ParamField>

            <ParamField type="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`.
            </ParamField>

            <ParamField type="string">
              Optional currency of the product price. If not specified, defaults to the currency of the product.
            </ParamField>

            <ParamField type="string">
              Optional product description override for billing and line items. If not specified, the stored description of the product will be used.
            </ParamField>

            <ParamField type="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.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

## Usage Examples

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

### 1. Simple Single Product Checkout

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

### 2. Multi-Product Cart

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_laptop',
      quantity: 1
    },
    {
      product_id: 'pdt_mouse',
      quantity: 2
    },
    {
      product_id: 'pdt_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

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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

<Note>
  When `confirm` is set to `true`, the customer will be taken directly to the checkout page, bypassing any confirmation steps.
</Note>

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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

<Note>
  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.
</Note>

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 Stacked Discount Codes

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_gaming_chair',
      quantity: 1
    }
  ],
  discount_codes: ['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)

For detailed information about UPI configuration and testing, see the <a href="/features/payment-methods/india">India Payment Methods</a> page.

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    '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

For detailed information about BNPL configuration and testing, see the <a href="/features/payment-methods/bnpl">Buy Now Pay Later (BNPL)</a> page.

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    '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'
  }
});
```

### 11. Using Existing Payment Methods for Instant Checkout

Use a customer's saved payment method to create a checkout session that processes immediately, skipping payment method collection:

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_premium_plan',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_123'  // Required when using payment_method_id
  },
  payment_method_id: 'pm_abc123',  // Use customer's saved payment method
  confirm: true,  // Required when using payment_method_id
  return_url: 'https://yourapp.com/success'
});
```

<Warning>
  When using `payment_method_id`, `confirm` must be set to `true` and an existing `customer_id` must be provided. The payment method will be validated for eligibility with the payment's currency. Because the charge is processed immediately, `checkout_url` is returned as `null` — use the returned `payment_id` instead.
</Warning>

<Info>
  The payment method must belong to the customer and be compatible with the payment currency. This enables one-click purchases for returning customers.
</Info>

### 12. Short Links for Cleaner Payment URLs

Generate shortened, shareable payment links with custom slugs:

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  }
});

// The checkout_url will be a shortened, cleaner link
console.log(session.checkout_url);  // e.g., https://checkout.dodopayments.com/buy/abc123
```

<Tip>
  Short links are perfect for SMS, email, or social media sharing. They're easier to remember and build more customer trust than long URLs.
</Tip>

### 13. Skip Payment Success Page with Immediate Redirect

Redirect customers immediately after payment completion, bypassing the default success page:

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_digital_product',
      quantity: 1
    }
  ],
  feature_flags: {
    redirect_immediately: true  // Skip success page, redirect immediately
  },
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'Jane Smith'
  }
});
```

<Tip>
  Use `redirect_immediately: true` when you have a custom success page that provides better user experience than the default payment success page. This is especially useful for [mobile apps](/developer-resources/mobile-integration) and embedded checkout flows.
</Tip>

<Note>
  When `redirect_immediately` is enabled, customers are redirected to your `return_url` immediately after payment completion, skipping the default success page entirely.
</Note>

### 14. Forcing a Language

Force the checkout to display in a specific language, overriding the customer's browser language detection:

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ],
  customization: {
    force_language: 'ja'  // Force Japanese language
  },
  customer: {
    email: 'customer@example.jp',
    name: 'Tanaka Yuki'
  },
  return_url: 'https://yourapp.com/success'
});
```

<Tip>
  Use `force_language` when you know your customer's preferred language (e.g., from their account settings) or when targeting specific regional markets.
</Tip>

**Supported languages:** Arabic (`ar`), Catalan (`ca`), Chinese (`zh`), Dutch (`nl`), English (`en`), French (`fr`), German (`de`), Hebrew (`he`), Indonesian (`id`), Italian (`it`), Japanese (`ja`), Korean (`ko`), Malay (`ms`), Polish (`pl`), Portuguese (`pt`), Romanian (`ro`), Russian (`ru`), Spanish (`es`), Swedish (`sv`), Thai (`th`), Turkish (`tr`)

### 15. Collecting Custom Fields

Collect additional information from customers during checkout using custom fields:

```javascript expandable theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_saas_plan',
      quantity: 1
    }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true,
      placeholder: 'Acme Inc.'
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '201-500', '500+']
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      required: false,
      options: ['Google', 'Twitter', 'Friend referral', 'Blog post', 'Other']
    },
    {
      key: 'website',
      label: 'Company Website',
      field_type: 'url',
      required: false,
      placeholder: 'https://example.com'
    }
  ],
  customer: {
    email: 'buyer@company.com',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});
```

<Info>
  Custom field responses are automatically included in webhook payloads (`payment.succeeded`, `subscription.active`, etc.) and can be retrieved via the API. Use them to enrich your CRM, trigger onboarding flows, or customize the customer experience.
</Info>

**Available field types:** `text`, `number`, `email`, `url`, `date`, `dropdown`, `boolean`

## Previewing Checkout Sessions

Before creating a checkout session, you can preview the pricing breakdown including taxes, discounts, and totals. This is useful for displaying accurate pricing to customers before they proceed to checkout.

<Note>
  When the cart contains a subscription product, the preview response also returns a `next_billing_date` — a preview of the upcoming billing date, so you can show it before the subscription is created. It is computed relative to now: `now + trial period` when a trial applies, otherwise `now + one payment frequency`. The field is omitted for one-time-only carts. This is an estimate anchored on the preview time; the authoritative `next_billing_date` is set when the subscription activates.
</Note>

<Note>
  The preview also returns `trial_period_days` (the effective trial length, free or paid) and `trial_amount` (the per-unit trial charge after discounts, in the price currency's minor units). `trial_amount` is only present for a [paid trial](/features/subscription#paid-trials) and is `null` for a free trial or no trial. Use `current_breakup` for the taxed total actually due today.
</Note>

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    const preview = await client.checkoutSessions.preview({
      product_cart: [
        { product_id: 'pdt_123', quantity: 1 }
      ],
      billing_address: {
        country: 'US',
        state: 'CA',
        zipcode: '94102'
      },
      discount_codes: ['SAVE20']
    });

    console.log('Subtotal:', preview.current_breakup.subtotal);
    console.log('Tax:', preview.current_breakup.tax);
    console.log('Discount:', preview.current_breakup.discount);
    console.log('Total:', preview.current_breakup.total_amount);

    // Present only when the cart contains a subscription product
    console.log('Next billing date:', preview.next_billing_date);
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    preview = client.checkout_sessions.preview(
        product_cart=[
            {"product_id": "pdt_123", "quantity": 1}
        ],
        billing_address={
            "country": "US",
            "state": "CA",
            "zipcode": "94102"
        },
        discount_codes=["SAVE20"]
    )

    print(f"Subtotal: {preview.current_breakup.subtotal}")
    print(f"Tax: {preview.current_breakup.tax}")
    print(f"Discount: {preview.current_breakup.discount}")
    print(f"Total: {preview.current_breakup.total_amount}")

    # Present only when the cart contains a subscription product
    print(f"Next billing date: {preview.next_billing_date}")
    ```
  </Tab>
</Tabs>

<Card title="Preview API Reference" icon="code" href="/api-reference/checkout-sessions/preview">
  View the complete preview endpoint documentation.
</Card>

## 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:

<Steps>
  <Step title="Update your integration">
    Update your integration to use the new API or SDK method.
  </Step>

  <Step title="Adjust request payload">
    Adjust the request payload according to the Checkout Sessions format.
  </Step>

  <Step title="That's it!">
    Yes. No additional handling or special migration steps are needed on your side.
  </Step>
</Steps>

## Related API Reference

<CardGroup>
  <Card title="Create Checkout Session" icon="code" href="/api-reference/checkout-sessions/create">
    Complete API reference for creating checkout sessions with all available parameters and options
  </Card>

  <Card title="Preview Checkout Session" icon="eye" href="/api-reference/checkout-sessions/preview">
    API reference for previewing pricing, taxes, and totals before creating a session
  </Card>
</CardGroup>


# Sync with your Database
Source: https://docs.dodopayments.com/developer-resources/dodo-sync

Automatically sync your Dodo Payments data to your own database for analytics, reporting, and integrations.

Dodo Payments provides a built-in database sync feature that automatically synchronizes your payment data with your own database. You can sync **payments**, **customers**, **subscriptions**, and **licenses** to maintain a local copy of your data for analytics, reporting, or integration with other systems.

<Info>
  **Implementation**: Available via [npm package](https://www.npmjs.com/package/dodo-sync) | **Source Code**: [GitHub](https://github.com/dodopayments/dodo-sync)
</Info>

## What Can You Sync?

Our database sync feature supports synchronizing the following Dodo Payments entities to your database:

<CardGroup>
  <Card title="Payments" icon="credit-card">
    Sync all payment transactions, including one-time payments, refunds, and payment status updates.
  </Card>

  <Card title="Customers" icon="users">
    Keep your customer data in sync, including customer profiles, contact information, and metadata.
  </Card>

  <Card title="Subscriptions" icon="repeat">
    Synchronize subscription data, including active subscriptions, billing cycles, and subscription status changes.
  </Card>

  <Card title="Licenses" icon="key">
    Sync license information, including license keys, activations, and license status updates.
  </Card>
</CardGroup>

You can sync any combination of these entities by specifying them in the `scopes` parameter. All sync operations are incremental and only transfer new or updated records for optimal performance.

## Database Support

We currently support **MongoDB**, **PostgreSQL**, **MySQL**, and **ClickHouse**.

We are actively working on expanding support for:

* **Databases**: Snowflake and others.
* **Pipelines**: ETL pipelines, Realtime sync.

<Tip>
  We're continuously expanding database support. If you'd like to contribute a new database integration, please submit a Pull Request to our [GitHub repository](https://github.com/dodopayments/dodo-sync).
</Tip>

## Getting Started

You can use our database sync feature via the **CLI** or programmatically in your **code**. Both methods provide the same functionality—choose the one that best fits your workflow.

### Using the CLI

The CLI tool provides a quick way to set up and run database synchronization. Install it globally to use it from anywhere in your terminal:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g dodo-sync
  ```

  ```bash bun theme={null}
  bun add -g dodo-sync
  ```
</CodeGroup>

#### Running the CLI

The CLI supports two modes: **Interactive Mode** for guided setup, and **Manual Mode** for direct configuration.

**Interactive Mode**: Simply run the command without arguments to start the interactive setup wizard.

```bash theme={null}
dodo-sync
```

**Manual Mode**: Pass arguments directly to skip the wizard.

```bash theme={null}
dodo-sync -i [interval] -d [database] -u [database_uri] --scopes [scopes] --api-key [api_key] --env [environment]
```

**Examples:**

```bash theme={null}
# MongoDB
dodo-sync -i 600 -d mongodb -u mongodb://mymongodb.url --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# PostgreSQL
dodo-sync -i 600 -d postgres -u postgresql://user:password@localhost:5432/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# MySQL
dodo-sync -i 600 -d mysql -u mysql://user:password@localhost:3306/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# ClickHouse
dodo-sync -i 600 -d clickhouse -u http://localhost:8123 --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode
```

#### CLI Arguments

<ParamField type="number">
  Sync interval in seconds. Determines how frequently the sync operation runs. If not provided, the sync will run once and exit.
</ParamField>

<ParamField type="string">
  Database type to use. Supported values: `"mongodb"`, `"postgres"`, `"mysql"`, or `"clickhouse"`.
</ParamField>

<ParamField type="string">
  Connection URI for your database:

  * **MongoDB**: `mongodb://localhost:27017` or `mongodb+srv://user:pass@cluster.mongodb.net/`
  * **PostgreSQL**: `postgresql://user:password@localhost:5432/mydb`
  * **MySQL**: `mysql://user:password@localhost:3306/mydb`
  * **ClickHouse**: `http://localhost:8123`
</ParamField>

<ParamField type="string">
  Comma-separated list of data entities to sync. Available scopes: `licences`, `payments`, `customers`, `subscriptions`. Example: `"payments,customers"`.
</ParamField>

<ParamField type="string">
  Your Dodo Payments API key. Should start with `dp_live_` for live mode or `dp_test_` for test mode.
</ParamField>

<ParamField type="string">
  Environment target. Must be either `"live_mode"` or `"test_mode"`. This determines which Dodo Payments environment to sync from.
</ParamField>

<ParamField type="number">
  Rate limit in requests per second. Controls how fast the sync engine makes API requests to avoid overwhelming the Dodo Payments API.
</ParamField>

### Using in Your Code

For programmatic control, integrate the sync feature directly into your application. Install it as a dependency in your project:

<CodeGroup>
  ```bash npm theme={null}
  npm install dodo-sync
  ```

  ```bash bun theme={null}
  bun add dodo-sync
  ```
</CodeGroup>

#### Automatic Sync (Interval-based)

Use automatic sync when you want the sync to run continuously at regular intervals:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60, // Sync every 60 seconds
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI, // e.g., 'mongodb://localhost:27017'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode' // or 'live_mode'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Start the sync loop
syncDodoPayments.start();
```

<Tip>
  The `interval` option is required when using `.start()` for automatic syncing. The sync will run continuously at the specified interval until the process is stopped.
</Tip>

#### Manual Sync

Use manual sync when you want to trigger sync operations on-demand (e.g., from a cron job or API endpoint):

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI,
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Trigger a single sync operation
await syncDodoPayments.run();
```

<Tip>
  When using manual sync, the `interval` option is not required. You can call `.run()` whenever you need to perform a sync operation.
</Tip>

#### PostgreSQL Example

Here's how to use `dodo-sync` with PostgreSQL:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'postgres',
  databaseURI: process.env.POSTGRES_URI, // e.g., 'postgresql://user:password@localhost:5432/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();
```

#### MySQL Example

Here's how to use `dodo-sync` with MySQL:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'mysql',
  databaseURI: process.env.MYSQL_URI, // e.g., 'mysql://user:password@localhost:3306/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();
```

#### ClickHouse Example

Here's how to use `dodo-sync` with ClickHouse:

```typescript theme={null}
import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'clickhouse',
  databaseURI: process.env.CLICKHOUSE_URI, // e.g., 'http://localhost:8123'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();
```

#### Constructor Options

<ParamField type="string">
  Name of the database to use. Supported values: `"mongodb"`, `"postgres"`, `"mysql"`, or `"clickhouse"`.
</ParamField>

<ParamField type="string">
  Connection string for your database:

  * **MongoDB**: `mongodb://localhost:27017` or `mongodb+srv://...`
  * **PostgreSQL**: `postgresql://user:password@localhost:5432/mydb`
  * **MySQL**: `mysql://user:password@localhost:3306/mydb`
  * **ClickHouse**: `http://localhost:8123`
</ParamField>

<ParamField type="string[]">
  Array of entities to sync. Available options: `"licences"`, `"payments"`, `"customers"`, `"subscriptions"`. You can include any combination of these.
</ParamField>

<ParamField type="object">
  Dodo Payments API configuration for authentication and environment selection. See the [TypeScript SDK types](https://github.com/dodopayments/dodopayments-typescript/blob/main/src/client.ts) for complete options.

  **Required properties:**

  * `bearerToken`: Your Dodo Payments API key
  * `environment`: Either `"test_mode"` or `"live_mode"`
</ParamField>

<ParamField type="number">
  Time in seconds between automatic syncs. Required when using `.start()` for automatic syncing. Optional when using `.run()` for manual syncing.
</ParamField>

<ParamField type="number">
  Number of requests per second. Controls how fast the sync engine makes API requests to avoid overwhelming the Dodo Payments API.
</ParamField>

## Important Information

<Warning>
  **MongoDB**: A database named `dodopayments_sync` will be automatically created on your database server. All sync data will be stored there. This database name is currently fixed and cannot be changed.

  **PostgreSQL**: Tables (`Subscriptions`, `Payments`, `Licenses`, `Customers`) will be created in the database specified in your connection URI. Data is stored as JSONB.

  **MySQL**: Tables (`Subscriptions`, `Payments`, `Licenses`, `Customers`) will be created in the database specified in your connection URI. Data is stored as JSON.

  **ClickHouse**: Tables (`Subscriptions`, `Payments`, `Licenses`, `Customers`) will be created using the ReplacingMergeTree engine. When querying, use the `FINAL` keyword to ensure deduplicated results.
</Warning>

<Info>
  The sync engine tracks changes and only syncs new or updated records, making subsequent syncs efficient even with large datasets.
</Info>

## Additional Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-sync">
    View source code, report issues, or contribute improvements
  </Card>

  <Card title="npm Package" icon="box-open" href="https://www.npmjs.com/package/dodo-sync">
    View package details and installation instructions
  </Card>
</CardGroup>


# Dynamic Pricing Checkout with Pay What You Want
Source: https://docs.dodopayments.com/developer-resources/dynamic-pricing-checkout

Create flexible checkout links with variable pricing using a single product. Enable Pay What You Want to let customers choose their price or set dynamic amounts programmatically.

**Dynamic pricing** allows you to offer variable pricing for your products without creating multiple product entries. By enabling **Pay What You Want (PWYW)** on a single product, you can set minimum and maximum price bounds, then pass dynamic amounts when creating checkout session links.

This approach is ideal when you need:

* **Variable pricing** without managing multiple products
* **Customer-driven pricing** where buyers choose their amount
* **Programmatic price control** where you set the amount dynamically via API
* **Flexible pricing models** for digital products, donations, or experimental launches

<Warning>
  Pay What You Want is only available for **Single Payment** (one-time) products. It cannot be used with subscription products.
</Warning>

## How It Works

With Pay What You Want enabled, you can:

1. **Set price bounds**: Define a minimum price (required) and optionally a maximum price
2. **Pass dynamic amounts**: Include an `amount` field in the product cart when creating checkout sessions
3. **Let customers choose**: If no amount is provided, customers can enter their own price (within your bounds)

<Info>
  When you pass an `amount` in the product cart, that amount is used for the checkout. If you omit the `amount` field, customers can select their own price during checkout (subject to your minimum/maximum settings).
</Info>

## Step 1: Create a Product with Pay What You Want

First, create a one-time product in your Dodo Payments dashboard and enable Pay What You Want pricing.

<Steps>
  <Step title="Create a new product">
    Navigate to **Products** in your Dodo Payments dashboard and click **Add Product**.
  </Step>

  <Step title="Configure product details">
    Fill in the required product information:

    * **Product Name**: Display name for your product
    * **Product Description**: Clear description of what customers are purchasing
    * **Product Image**: Upload an image (PNG/JPG/WebP, up to 3 MB)
    * **Tax Category**: Select the appropriate tax category
  </Step>

  <Step title="Set pricing type">
    Select **Pricing Type** as **Single Payment** (one-time payment).
  </Step>

  <Step title="Enable Pay What You Want">
    In the **Pricing** section, enable the **Pay What You Want** toggle.
  </Step>

  <Step title="Set minimum price">
    Enter the **Minimum Price** that customers must pay. This is required and ensures you maintain a revenue floor.

    **Example**: If your minimum is \$5.00, enter `5.00` (or `500` cents).
  </Step>

  <Step title="Set maximum price (optional)">
    Optionally, set a **Maximum Price** to cap the amount customers can pay.
  </Step>

  <Step title="Set suggested price (optional)">
    Optionally, enter a **Suggested Price** that will be displayed to guide customers. This helps anchor expectations and can improve average order value.
  </Step>

  <Step title="Save the product">
    Click **Add Product** to save. Note your product ID (e.g., `pdt_123abc456def`) for use in checkout sessions.
  </Step>
</Steps>

<Tip>
  You can find your product ID in the dashboard under **Products** → **View Details**, or by using the [List Products API](/api-reference/products/get-products).
</Tip>

## Step 2: Create Checkout Sessions with Dynamic Pricing

Once your product is configured with Pay What You Want, you can create checkout sessions with dynamic amounts. The `amount` field in the product cart allows you to set the price programmatically for each checkout session.

### Understanding the Amount Field

When creating a checkout session, you can include an `amount` field in each product cart item:

* **If `amount` is provided**: The checkout uses this exact amount (must be within your minimum/maximum bounds)
* **If `amount` is omitted**: Customers can enter their own price during checkout (within your bounds)

<Warning>
  The `amount` field is only applicable for Pay What You Want products. For regular products, this field is ignored.
</Warning>

### Code Examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  import DodoPayments from 'dodopayments';

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

  async function createDynamicPricingCheckout(
    productId: string,
    amountInCents: number,
    returnUrl: string
  ) {
    try {
      const session = await client.checkoutSessions.create({
        product_cart: [
          {
            product_id: productId,
            quantity: 1,
            // Dynamic amount in cents (e.g., 1500 = $15.00)
            amount: amountInCents
          }
        ],
        return_url: returnUrl,
        // Optional: Pre-fill customer information
        customer: {
          email: 'customer@example.com',
          name: 'John Doe'
        },
        // Optional: Add metadata for tracking
        metadata: {
          order_id: 'order_123',
          pricing_tier: 'custom'
        }
      });

      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: Create checkout with $25.00 (2500 cents)
  const session = await createDynamicPricingCheckout(
    'pdt_123abc456def',
    2500, // $25.00 in cents
    'https://yoursite.com/checkout/success'
  );

  // Example: Create checkout with $10.00 (1000 cents)
  const session2 = await createDynamicPricingCheckout(
    'pdt_123abc456def',
    1000, // $10.00 in cents
    'https://yoursite.com/checkout/success'
  );
  ```

  ```python Python theme={null}
  import os
  from dodopayments import DodoPayments

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

  def create_dynamic_pricing_checkout(
      product_id: str,
      amount_in_cents: int,
      return_url: str
  ):
      """
      Create a checkout session with dynamic pricing.
      
      Args:
          product_id: The product ID with Pay What You Want enabled
          amount_in_cents: The amount in cents (e.g., 2500 for $25.00)
          return_url: URL to redirect after payment completion
      
      Returns:
          Session object with checkout_url and session_id
      """
      try:
          session = client.checkout_sessions.create(
              product_cart=[
                  {
                      "product_id": product_id,
                      "quantity": 1,
                      # Dynamic amount in cents (e.g., 1500 = $15.00)
                      "amount": amount_in_cents
                  }
              ],
              return_url=return_url,
              # Optional: Pre-fill customer information
              customer={
                  "email": "customer@example.com",
                  "name": "John Doe"
              },
              # Optional: Add metadata for tracking
              metadata={
                  "order_id": "order_123",
                  "pricing_tier": "custom"
              }
          )
          
          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: Create checkout with $25.00 (2500 cents)
  session = create_dynamic_pricing_checkout(
      "pdt_123abc456def",
      2500,  # $25.00 in cents
      "https://yoursite.com/checkout/success"
  )

  # Example: Create checkout with $10.00 (1000 cents)
  session2 = create_dynamic_pricing_checkout(
      "pdt_123abc456def",
      1000,  # $10.00 in cents
      "https://yoursite.com/checkout/success"
  )
  ```
</CodeGroup>

<Note>
  **Amount Format**: The `amount` field must be in the lowest denomination of the currency. For USD, this means cents (e.g., \$25.00 = `2500`). For other currencies, use the smallest unit (e.g., paise for INR).
</Note>

## Step 3: Let Customers Choose Their Price

If you want customers to select their own price during checkout, simply omit the `amount` field from the product cart. The checkout page will display an input field where customers can enter any amount within your minimum and maximum bounds.

<CodeGroup>
  ```typescript TypeScript theme={null}
  async function createCustomerChoiceCheckout(
    productId: string,
    returnUrl: string
  ) {
    try {
      const session = await client.checkoutSessions.create({
        product_cart: [
          {
            product_id: productId,
            quantity: 1
            // No amount field - customer will choose their price
          }
        ],
        return_url: returnUrl,
        customer: {
          email: 'customer@example.com',
          name: 'John Doe'
        }
      });

      return session;
    } catch (error) {
      console.error('Failed to create checkout session:', error);
      throw error;
    }
  }
  ```

  ```python Python theme={null}
  def create_customer_choice_checkout(
      product_id: str,
      return_url: str
  ):
      """
      Create a checkout session where customers choose their own price.
      """
      try:
          session = client.checkout_sessions.create(
              product_cart=[
                  {
                      "product_id": product_id,
                      "quantity": 1
                      # No amount field - customer will choose their price
                  }
              ],
              return_url=return_url,
              customer={
                  "email": "customer@example.com",
                  "name": "John Doe"
              }
          )
          
          return session
      except Exception as error:
          print(f"Failed to create checkout session: {error}")
          raise error
  ```
</CodeGroup>

## Common Use Cases

### Use Case 1: Tiered Pricing Based on User Type

Offer different prices to different customer segments using the same product:

```typescript theme={null}
// Student discount: $10.00
const studentSession = await createDynamicPricingCheckout(
  'pdt_123abc456def',
  1000, // $10.00
  'https://yoursite.com/success'
);

// Regular price: $25.00
const regularSession = await createDynamicPricingCheckout(
  'pdt_123abc456def',
  2500, // $25.00
  'https://yoursite.com/success'
);

// Premium price: $50.00
const premiumSession = await createDynamicPricingCheckout(
  'pdt_123abc456def',
  5000, // $50.00
  'https://yoursite.com/success'
);
```

### Use Case 2: Dynamic Pricing Based on Quantity

Adjust price based on quantity purchased:

```typescript theme={null}
async function createQuantityBasedCheckout(
  productId: string,
  quantity: number
) {
  // Base price: $20.00 per unit
  // Discount: 10% for 2+ items, 20% for 5+ items
  const basePrice = 2000; // $20.00 in cents
  let discount = 0;
  
  if (quantity >= 5) {
    discount = 0.20; // 20% off
  } else if (quantity >= 2) {
    discount = 0.10; // 10% off
  }
  
  const totalAmount = Math.round(basePrice * quantity * (1 - discount));
  
  const session = await client.checkoutSessions.create({
    product_cart: [
      {
        product_id: productId,
        quantity: quantity,
        amount: totalAmount
      }
    ],
    return_url: 'https://yoursite.com/success'
  });
  
  return session;
}
```

### Use Case 3: Time-Based or Promotional Pricing

Apply promotional pricing during specific periods:

```typescript theme={null}
async function createPromotionalCheckout(productId: string) {
  const isPromoActive = checkIfPromotionActive(); // Your logic
  const regularPrice = 3000; // $30.00
  const promoPrice = 2000; // $20.00
  
  const amount = isPromoActive ? promoPrice : regularPrice;
  
  const session = await client.checkoutSessions.create({
    product_cart: [
      {
        product_id: productId,
        quantity: 1,
        amount: amount
      }
    ],
    return_url: 'https://yoursite.com/success',
    metadata: {
      pricing_type: isPromoActive ? 'promotional' : 'regular'
    }
  });
  
  return session;
}
```

## Best Practices

<CardGroup>
  <Card title="Set Reasonable Bounds" icon="sliders">
    Choose a minimum price that covers your costs while remaining accessible. Use a suggested price to guide customer expectations.
  </Card>

  <Card title="Validate Amounts" icon="shield-check">
    Always validate that dynamic amounts fall within your product's minimum and maximum bounds before creating checkout sessions.
  </Card>

  <Card title="Track Pricing Decisions" icon="chart-line">
    Use metadata to track why specific amounts were chosen (e.g., `pricing_tier`, `discount_code`, `user_segment`).
  </Card>

  <Card title="Handle Edge Cases" icon="exclamation-triangle">
    Ensure your application handles cases where amounts exceed maximum bounds or fall below minimums gracefully.
  </Card>
</CardGroup>

## Validation and Error Handling

Always validate amounts against your product's minimum and maximum settings:

<CodeGroup>
  ```typescript TypeScript theme={null}
  async function createValidatedCheckout(
    productId: string,
    amountInCents: number,
    minAmount: number,
    maxAmount: number | null
  ) {
    // Validate minimum
    if (amountInCents < minAmount) {
      throw new Error(
        `Amount ${amountInCents} is below minimum ${minAmount}`
      );
    }
    
    // Validate maximum (if set)
    if (maxAmount !== null && amountInCents > maxAmount) {
      throw new Error(
        `Amount ${amountInCents} exceeds maximum ${maxAmount}`
      );
    }
    
    // Create checkout session
    return await client.checkoutSessions.create({
      product_cart: [
        {
          product_id: productId,
          quantity: 1,
          amount: amountInCents
        }
      ],
      return_url: 'https://yoursite.com/success'
    });
  }
  ```

  ```python Python theme={null}
  def create_validated_checkout(
      product_id: str,
      amount_in_cents: int,
      min_amount: int,
      max_amount: int | None
  ):
      """
      Create a checkout session with amount validation.
      """
      # Validate minimum
      if amount_in_cents < min_amount:
          raise ValueError(
              f"Amount {amount_in_cents} is below minimum {min_amount}"
          )
      
      # Validate maximum (if set)
      if max_amount is not None and amount_in_cents > max_amount:
          raise ValueError(
              f"Amount {amount_in_cents} exceeds maximum {max_amount}"
          )
      
      # Create checkout session
      return client.checkout_sessions.create(
          product_cart=[
              {
                  "product_id": product_id,
                  "quantity": 1,
                  "amount": amount_in_cents
              }
          ],
          return_url="https://yoursite.com/success"
      )
  ```
</CodeGroup>

## API Reference

<CardGroup>
  <Card title="Pay What You Want Feature" icon="dollar-sign" href="/features/pay-what-you-want">
    Learn more about the Pay What You Want pricing model and its capabilities.
  </Card>

  <Card title="Checkout Sessions Guide" icon="cart-shopping" href="/developer-resources/checkout-session">
    Explore advanced checkout session features and customization options.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Amount is being ignored">
    If your `amount` field is being ignored, verify that:

    * The product has **Pay What You Want** enabled in the dashboard
    * The product is a **Single Payment** (one-time) product, not a subscription
    * The amount is in the correct format (lowest currency denomination, e.g., cents for USD)
  </Accordion>

  <Accordion title="Amount exceeds maximum or is below minimum">
    The API will reject checkout sessions where the amount violates your product's price bounds. Always validate amounts before creating checkout sessions, or let customers choose their price by omitting the `amount` field.
  </Accordion>

  <Accordion title="Customer can't enter their own price">
    If customers aren't seeing the price input field, ensure you've omitted the `amount` field from the product cart. When `amount` is provided, the checkout uses that exact amount.
  </Accordion>
</AccordionGroup>


# Expo Boilerplate
Source: https://docs.dodopayments.com/developer-resources/expo-boilerplate

Build React Native mobile apps with Dodo Payments using our Expo boilerplate. Includes checkout integration, payment handling, and TypeScript support.

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/expo-boilerplate">
  Complete Expo + React Native + Dodo Payments boilerplate
</Card>

## Overview

A production-ready boilerplate for integrating Dodo Payments into Expo/React Native applications. This template includes checkout session creation, payment handling, and proper TypeScript configuration to help you start accepting payments in your mobile app quickly.

<Info>
  This boilerplate uses Expo SDK with TypeScript and includes example implementations for checkout sessions and payment processing.
</Info>

<Frame>
  <iframe title="Expo Boilerplate Demo | Dodo Payments" />
</Frame>

## Prerequisites

* Node.js 18+
* Expo CLI or EAS CLI
* Dodo Payments account (API key from dashboard)
* iOS Simulator or Android Emulator (or physical device)

## Quick Start

<Steps>
  <Step title="Clone the Repository">
    Clone the boilerplate repository and navigate to the project directory:

    ```bash theme={null}
    git clone https://github.com/dodopayments/expo-boilerplate.git
    cd expo-boilerplate
    ```
  </Step>

  <Step title="Get Your API Credentials">
    Obtain your credentials from the Dodo Payments dashboard in Test Mode:

    * **API Key**: Navigate to **Developer → API Keys** in your [dashboard](https://app.dodopayments.com)

    <Tip>
      Start with Test Mode to safely test your integration without processing real payments.
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the root directory:

    ```bash theme={null}
    touch .env
    ```

    Add your Dodo Payments credentials:

    ```bash .env theme={null}
    EXPO_PUBLIC_DODO_API_KEY=your_test_api_key_here
    ```

    <Warning>
      Never commit your `.env` file to version control. It's already included in `.gitignore`.
    </Warning>

    <Warning>
      `EXPO_PUBLIC_*` variables are embedded in the shipped JavaScript bundle and are readable by anyone who downloads your app. Dodo Payments API keys are bearer secrets, so use this only with a Test Mode key while developing. For production, create checkout sessions on your backend and pass only the resulting `checkout_url` to the app — see [Mobile Integration](/developer-resources/mobile-integration).
    </Warning>
  </Step>

  <Step title="Install Dependencies">
    Install the required npm packages:

    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Start the Development Server">
    Start the Expo development server:

    ```bash theme={null}
    npx expo start
    ```

    Scan the QR code with Expo Go app on your device, or press `i` for iOS simulator or `a` for Android emulator.

    <Check>
      You're ready to start building! The boilerplate includes example screens and components to help you understand the integration.
    </Check>
  </Step>
</Steps>

## What's Included

The boilerplate comes with pre-configured essentials:

<CardGroup>
  <Card title="Checkout Integration" icon="shopping-cart">
    Example implementation for creating and handling checkout sessions
  </Card>

  <Card title="Payment Handling" icon="credit-card">
    Complete payment flow with success and error handling
  </Card>

  <Card title="TypeScript Support" icon="code">
    Full TypeScript configuration with proper type definitions
  </Card>

  <Card title="Expo Router" icon="route">
    Navigation setup with Expo Router for seamless routing
  </Card>
</CardGroup>

## Project Structure

```
expo-boilerplate/
├── app/
│   ├── (tabs)/
│   │   └── index.tsx          # Home screen with examples
│   └── checkout.tsx           # Checkout screen
├── components/
│   └── PaymentButton.tsx      # Payment button component
├── lib/
│   └── dodo.ts                # Dodo Payments client setup
├── .env.example               # Environment variables template
└── package.json
```

## Next Steps

Once you have the boilerplate running:

<Steps>
  <Step title="Create Your Products">
    Add products in your [Dodo Payments dashboard](https://app.dodopayments.com) to enable checkout functionality.
  </Step>

  <Step title="Customize the Integration">
    Adapt the example code to match your application's needs and design.
  </Step>

  <Step title="Test on Real Devices">
    Test the payment flow on physical devices to ensure everything works correctly.
  </Step>

  <Step title="Go Live">
    When ready, switch to Live Mode API keys and build your app for production.
  </Step>
</Steps>

## Building for Production

<Steps>
  <Step title="Install EAS CLI">
    ```bash theme={null}
    npm install -g eas-cli
    ```
  </Step>

  <Step title="Configure EAS">
    ```bash theme={null}
    eas build:configure
    ```
  </Step>

  <Step title="Build Your App">
    For iOS:

    ```bash theme={null}
    eas build --platform ios
    ```

    For Android:

    ```bash theme={null}
    eas build --platform android
    ```
  </Step>
</Steps>

## Additional Resources

<CardGroup>
  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    Detailed guide for implementing payments in mobile apps
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/integration-guide">
    Detailed guide for implementing one-time payments
  </Card>

  <Card title="API Reference" icon="brackets-curly" href="/api-reference/introduction">
    Explore the full Dodo Payments API documentation
  </Card>
</CardGroup>

## Support

Need help with the boilerplate?

* Join our [Discord community](https://discord.gg/bYqAp4ayYh) for questions and discussions
* Check the [GitHub repository](https://github.com/dodopayments/expo-boilerplate) for issues and updates
* Contact our [support team](mailto:support@dodopayments.com) for assistance


# FastAPI Boilerplate
Source: https://docs.dodopayments.com/developer-resources/fastapi-boilerplate

Get started quickly with our FastAPI boilerplate for integrating Dodo Payments into your Python backend applications

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/fastapi-boilerplate">
  Complete FastAPI + Dodo Payments boilerplate
</Card>

## Overview

The FastAPI boilerplate provides a production-ready starting point for integrating Dodo Payments with your Python backend. This template includes checkout session handling, webhook verification, customer portal integration, and async API patterns to help you start accepting payments quickly.

<Info>
  This boilerplate uses FastAPI with async/await patterns, Pydantic for validation, and the `dodopayments` Python SDK for seamless API integration.
</Info>

### Features

* **Quick Setup** - Get started in under 5 minutes
* **Async Support** - Built with FastAPI's native async/await patterns
* **Checkout Sessions** - Pre-configured checkout flow using the Python SDK
* **Webhook Handling** - Secure webhook endpoint with signature verification
* **Customer Portal** - Easy customer portal session creation
* **Type Safety** - Full Pydantic validation and type hints
* **Environment Configuration** - Ready-to-use environment variable setup

## Prerequisites

Before you begin, make sure you have:

* **Python 3.9+** (recommended: Python 3.11+)
* **pip** or **uv** for package management
* **Dodo Payments account** (to access API and Webhook Keys from dashboard)

## Quick Start

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/fastapi-boilerplate.git
    cd fastapi-boilerplate
    ```
  </Step>

  <Step title="Create Virtual Environment">
    Set up an isolated Python environment:

    ```bash theme={null}
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```

    Or using uv for faster dependency management:

    ```bash theme={null}
    uv venv
    source .venv/bin/activate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    pip install -r requirements.txt
    ```

    Or with uv:

    ```bash theme={null}
    uv pip install -r requirements.txt
    ```
  </Step>

  <Step title="Get API Credentials">
    Sign up at [Dodo Payments](https://dodopayments.com/) and get your credentials from the dashboard:

    * **API Key:** [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Make sure you're in **Test Mode** while developing!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the root directory:

    ```bash theme={null}
    cp .env.example .env
    ```

    Update the values with your Dodo Payments credentials:

    ```bash .env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Never commit your `.env` file to version control. It's already included in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    uvicorn main:app --reload
    ```

    Open [http://localhost:8000/docs](http://localhost:8000/docs) to see the interactive API documentation!

    <Check>
      You should see FastAPI's Swagger UI with all available endpoints ready to test.
    </Check>
  </Step>
</Steps>

## Project Structure

```text theme={null}
fastapi-boilerplate/
├── main.py                 # FastAPI application entry point
├── routers/
│   ├── checkout.py         # Checkout session endpoints
│   ├── webhook.py          # Webhook handler endpoint
│   └── customer_portal.py  # Customer portal endpoints
├── config.py               # Environment configuration
├── requirements.txt        # Python dependencies
├── .env.example            # Environment template
└── README.md
```

## API Endpoints

The boilerplate includes the following pre-configured endpoints:

| Endpoint           | Method | Description                   |
| ------------------ | ------ | ----------------------------- |
| `/checkout`        | POST   | Create a new checkout session |
| `/webhook`         | POST   | Handle Dodo Payments webhooks |
| `/customer-portal` | POST   | Generate customer portal URL  |

## Code Examples

### Creating a Checkout Session

```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings

router = APIRouter()
dodo = AsyncDodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT
)

class CheckoutRequest(BaseModel):
    product_id: str
    quantity: int = 1
    customer_email: str | None = None
    customer_name: str | None = None

@router.post("/checkout")
async def create_checkout(request: CheckoutRequest):
    try:
        session = await dodo.checkout_sessions.create(
            product_cart=[{
                "product_id": request.product_id,
                "quantity": request.quantity
            }],
            customer={
                "email": request.customer_email,
                "name": request.customer_name
            } if request.customer_email else None,
            return_url="http://localhost:8000/success"
        )
        return {"checkout_url": session.checkout_url, "session_id": session.session_id}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))
```

### Handling Webhooks

```python theme={null}
from fastapi import APIRouter, Request, HTTPException
from standardwebhooks import Webhook
from config import settings

router = APIRouter()
webhook = Webhook(settings.DODO_PAYMENTS_WEBHOOK_KEY)

@router.post("/webhook")
async def handle_webhook(request: Request):
    payload = await request.body()

    # Dodo Payments follows the Standard Webhooks spec: the signature covers
    # `id.timestamp.body`, so all three webhook-* headers must be passed in.
    try:
        webhook.verify(payload, dict(request.headers))
    except Exception:
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()
    event_type = event.get("type")
    
    match event_type:
        case "payment.succeeded":
            # Handle successful payment
            payment_id = event["data"]["payment_id"]
            print(f"Payment succeeded: {payment_id}")
            
        case "subscription.active":
            # Handle subscription activation
            subscription_id = event["data"]["subscription_id"]
            print(f"Subscription activated: {subscription_id}")
            
        case "refund.succeeded":
            # Handle refund
            refund_id = event["data"]["refund_id"]
            print(f"Refund processed: {refund_id}")
    
    return {"status": "received"}
```

### Customer Portal Integration

```python theme={null}
from fastapi import APIRouter, HTTPException
from dodopayments import AsyncDodoPayments
from pydantic import BaseModel
from config import settings

router = APIRouter()
dodo = AsyncDodoPayments(
    bearer_token=settings.DODO_PAYMENTS_API_KEY,
    environment=settings.DODO_PAYMENTS_ENVIRONMENT
)

class PortalRequest(BaseModel):
    customer_id: str

@router.post("/customer-portal")
async def create_portal_session(request: PortalRequest):
    try:
        session = await dodo.customers.customer_portal.create(
            customer_id=request.customer_id,
        )
        return {"portal_url": session.link}
    except Exception as e:
        raise HTTPException(status_code=400, detail=str(e))
```

## Webhook Events

The boilerplate demonstrates handling common webhook events:

| Event                    | Description                    |
| ------------------------ | ------------------------------ |
| `payment.succeeded`      | Payment completed successfully |
| `payment.failed`         | Payment attempt failed         |
| `subscription.active`    | Subscription is now active     |
| `subscription.cancelled` | Subscription was cancelled     |
| `refund.succeeded`       | Refund processed successfully  |

Add your business logic inside the webhook handler to:

* Update user permissions in your database
* Send confirmation emails
* Provision access to digital products
* Track analytics and metrics

## Testing Webhooks Locally

For local development, use tools like [ngrok](https://ngrok.com/) to expose your local server:

```bash theme={null}
ngrok http 8000
```

Update the webhook URL in your [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks):

```
https://your-ngrok-url.ngrok.io/webhook
```

## Deployment

### Docker

```dockerfile theme={null}
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```

Build and run:

```bash theme={null}
docker build -t fastapi-dodo .
docker run -p 8000:8000 --env-file .env fastapi-dodo
```

### Production Considerations

<Warning>
  Before deploying to production:

  * Switch `DODO_PAYMENTS_ENVIRONMENT` to `live_mode`
  * Use production API keys from the dashboard
  * Update the webhook URL to your production domain
  * Enable HTTPS for all endpoints
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Import errors or missing modules">
    Ensure your virtual environment is activated and dependencies are installed:

    ```bash theme={null}
    source venv/bin/activate
    pip install -r requirements.txt
    ```
  </Accordion>

  <Accordion title="Checkout session creation fails">
    **Common causes:**

    * Invalid product ID - verify it exists in your Dodo dashboard
    * Wrong API key or environment setting in `.env`
    * Check the FastAPI logs for detailed error messages
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    For local testing, use [ngrok](https://ngrok.com) to expose your server:

    ```bash theme={null}
    ngrok http 8000
    ```

    Update the webhook URL in your [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) to the ngrok URL. Make sure to update your `.env` file with the correct webhook verification key.
  </Accordion>

  <Accordion title="Webhook signature verification fails">
    * Ensure `DODO_PAYMENTS_WEBHOOK_KEY` is correctly set in your `.env`
    * Verify you're using the raw request body for signature verification
    * Pass all three `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers to `webhook.verify()` — the Standard Webhooks signature covers `id.timestamp.body`, not the body alone
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Python SDK" icon="python" href="/developer-resources/sdks/python">
    Complete Python SDK documentation with async support
  </Card>

  <Card title="Webhooks Documentation" icon="webhook" href="/developer-resources/webhooks">
    Learn about all webhook events and best practices
  </Card>

  <Card title="Checkout Sessions" icon="credit-card" href="/developer-resources/checkout-session">
    Deep dive into checkout session configuration
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete Dodo Payments API documentation
  </Card>
</CardGroup>

## Support

Need help with the boilerplate?

* Join our [Discord community](https://discord.gg/bYqAp4ayYh) for questions and discussions
* Check the [GitHub repository](https://github.com/dodopayments/fastapi-boilerplate) for issues and updates
* Contact our [support team](mailto:support@dodopayments.com) for assistance


# Fastify Adaptor
Source: https://docs.dodopayments.com/developer-resources/fastify-adaptor

Learn how to integrate Dodo Payments with your Fastify App Router project using our NextJS Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your Fastify app.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/fastify
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using the Fastify App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Fastify app. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript Fastify Route Handler expandable theme={null}
        // route.ts
        import { Checkout } from '@dodopayments/fastify';
        import Fastify from 'fastify'

        const fastify = Fastify({})
        const checkoutGet = Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            type: 'static'
        });

        const checkoutPost = Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            type: 'dynamic'
        });

        const checkoutSession = Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            type: 'session'
        });

        fastify.get('/api/checkout', checkoutGet.getHandler);
        fastify.post('/api/checkout', checkoutPost.postHandler);
        fastify.post('/api/checkout-session', checkoutSession.postHandler);
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout-session \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Fastify Route Handler expandable theme={null}
      // route.ts
      import { CustomerPortal } from "@dodopayments/fastify";
      import Fastify from 'fastify'

      const fastify = Fastify({})
      const customerPortalHandler = CustomerPortal({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT
      });
      fastify.get('/api/customer-portal', customerPortalHandler);
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Fastify app.
    </Info>

    <CodeGroup>
      ```typescript Fastify Route Handler expandable theme={null}
      // route.ts
      import Fastify from 'fastify'
      import { Webhooks } from '@dodopayments/fastify'

      const fastify = Fastify({})
      fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
          done(null, body)
      })

      fastify.post('/api/webhooks', Webhooks({
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
      onPayload: async (payload) => {
          // Handle Payload Here
          console.log(payload)
      }
      }));

      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experiences that handle the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Fastify application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```
You are an expert Fastify developer assistant. Your task is to guide a user through integrating the @dodopayments/fastify adapter into their existing Fastify project.

The @dodopayments/fastify adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed to plug directly into an Fastify app.

First, install the necessary package. Use the package manager appropriate for the user's project (npm, yarn, or bun):

npm install @dodopayments/fastify

---

Here's how you should structure your response:

1. Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/fastify adapter would you like to integrate into your project? You can choose one or more of the following:

- Checkout Route Handler (for handling product checkouts)
- Customer Portal Route Handler (for managing customer subscriptions/details)
- Webhook Route Handler (for receiving Dodo Payments webhook events)
- All (integrate all three)"

---

2. Based on the user's selection, provide detailed integration steps for each chosen functionality.

---

**If Checkout Route Handler is selected:**

**Purpose**: This handler redirects users to the Dodo Payments checkout page.

**Integration**:
Create two routes in your Fastify app — one for static (GET) and one for dynamic (POST) checkout.


import { Checkout } from '@dodopayments/fastify';
import Fastify from 'fastify'

const fastify = Fastify({})
const checkoutGet = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'static'
});

const checkoutPost = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'dynamic'
});

const checkoutSession = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'session'
});

fastify.get('/api/checkout', checkoutGet.getHandler);
fastify.post('/api/checkout', checkoutPost.postHandler);
fastify.post('/api/checkout-session', checkoutSession.postHandler);


Config Options:

    bearerToken: Your Dodo Payments API key (recommended to be stored in DODO_PAYMENTS_API_KEY env variable).

    returnUrl (optional): URL to redirect the user after successful checkout.

    environment: "test_mode" or "live_mode"

    type: "static" (GET), "dynamic" (POST), or "session" (POST)

GET (static checkout) expects query parameters:

    productId (required)

    quantity, customer fields (fullName, email, etc.), and metadata (metadata_*) are optional.

    Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (dynamic checkout) expects a JSON body with payment details (one-time or subscription). Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}. Reference the docs for the full POST schema:

    One-time payments: https://docs.dodopayments.com/api-reference/payments/post-payments

    Subscriptions: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

POST (checkout sessions) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

    Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

If Customer Portal Route Handler is selected:

Purpose: This route allows customers to manage their subscriptions via the Dodo Payments portal.

Integration:

import { CustomerPortal } from "@dodopayments/fastify";
import Fastify from 'fastify'

const fastify = Fastify({})
const customerPortalHandler = CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});
fastify.get('/api/customer-portal', customerPortalHandler);

Query Parameters:

    customer_id (required): e.g., ?customer_id=cus_123

    send_email (optional): if true, customer is emailed the portal link

Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: Processes incoming webhook events from Dodo Payments to trigger events in your app.

Integration:

import Fastify from 'fastify'
import { Webhooks } from '@dodopayments/fastify'

const fastify = Fastify({})
fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
    done(null, body)
})

fastify.post('/api/webhooks', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Handle Payload Here
    console.log(payload)
  }
}));

Features:

    Only POST method is allowed — others return 405

    Signature verification is performed using webhookKey. Returns 401 if invalid.

    Zod-based payload validation. Returns 400 if invalid schema.

    All handlers are async functions.

Supported Webhook Event Handlers:

You may pass in any of the following handlers:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired, onSubscriptionUpdated

    onLicenseKeyCreated

    onAbandonedCheckoutDetected, onAbandonedCheckoutRecovered

    onDunningStarted, onDunningRecovered

    onCreditAdded, onCreditDeducted, onCreditExpired, onCreditRolledOver, onCreditRolloverForfeited, onCreditOverageCharged, onCreditManualAdjustment, onCreditBalanceLow

Environment Variable Setup:

Make sure to define these environment variables in your project:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""

Use these inside your code as:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

Security Note: Do NOT commit secrets to version control. Use .env files locally and secrets managers in deployment environments (e.g., AWS, Vercel, Heroku, etc.).
```


# Go Boilerplate
Source: https://docs.dodopayments.com/developer-resources/go-boilerplate

Get started quickly with our minimal Go boilerplate for integrating Dodo Payments into your Go backend applications

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/go-boilerplate">
  Minimal Go + Dodo Payments boilerplate
</Card>

## Overview

The Go boilerplate provides a production-ready starting point for integrating Dodo Payments with your Go backend. This template includes checkout session handling, webhook verification, customer portal integration, and follows Go best practices to help you start accepting payments quickly.

<Info>
  This boilerplate uses Go 1.21+ with clean architecture patterns (`cmd`, `internal`, `templates`), HTML templates, and the `dodopayments-go` SDK for seamless API integration.
</Info>

### Features

* **Quick Setup** - Get started in under 5 minutes
* **Payment Integration** - Pre-configured checkout flow using `dodopayments-go` SDK
* **Modern UI** - Clean, dark-themed pricing page with HTML templates
* **Webhook Handling** - Securely verify and process payment events
* **Customer Portal** - Self-serve subscription management
* **Go Best Practices** - Clean architecture with `cmd`, `internal`, and `templates`
* **Pre-filled Checkout** - Demonstrates passing customer data to improve UX

## Prerequisites

Before you begin, make sure you have:

* **Go 1.21+**
* **Dodo Payments account** (to access API and Webhook Keys from dashboard)

## Quick Start

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/go-boilerplate.git
    cd go-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    make install
    ```

    Or manually:

    ```bash theme={null}
    go mod download
    ```
  </Step>

  <Step title="Get API Credentials">
    Sign up at [Dodo Payments](https://dodopayments.com/) and get your credentials from the dashboard:

    * **API Key:** [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Make sure you're in **Test Mode** while developing!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the root directory:

    ```bash theme={null}
    cp .env.example .env
    ```

    Update the values with your Dodo Payments credentials:

    ```bash .env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_RETURN_URL=http://localhost:8000
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Never commit your `.env` file to version control. It's already included in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Update `internal/lib/products.go` with your actual product IDs from Dodo Payments:

    ```go theme={null}
    var Products = []Product{
        {
            ProductID:   "pdt_001", // Replace with your product ID
            Name:        "Basic Plan",
            Description: "Get access to basic features and support",
            Price:       9999, // in cents
            Features: []string{
                "Access to basic features",
                "Email support",
                "1 Team member",
                "Basic analytics",
            },
        },
        // ... add more products
    }
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    make run
    ```

    Or manually:

    ```bash theme={null}
    go run cmd/server/main.go
    ```

    Open [http://localhost:8000](http://localhost:8000) to see your pricing page!

    <Check>
      You should see a dark-themed pricing page with your products ready to purchase.
    </Check>
  </Step>
</Steps>

## Project Structure

```text theme={null}
go-boilerplate/
├── cmd/
│   └── server/             # Application entry point
├── internal/
│   ├── api/                # API handlers (Checkout, Portal, Webhook)
│   ├── core/               # Configuration and system core
│   └── lib/                # Shared logic (Products, Customer utils)
├── templates/              # HTML templates
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md
```

## API Endpoints

The boilerplate includes the following pre-configured endpoints:

| Endpoint               | Method | Description                       |
| ---------------------- | ------ | --------------------------------- |
| `/`                    | GET    | Pricing page with product listing |
| `/api/checkout`        | POST   | Create a new checkout session     |
| `/api/webhook`         | POST   | Handle Dodo Payments webhooks     |
| `/api/customer-portal` | POST   | Generate customer portal URL      |

## Customization

### Update Product Information

Edit `internal/lib/products.go` to modify:

* Product IDs (from your Dodo dashboard)
* Pricing
* Features
* Descriptions

```go theme={null}
var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999,
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
}
```

### Pre-fill Customer Data

In `templates/index.html`, replace the hardcoded customer data with your actual user data:

```javascript theme={null}
const customerData = {
    name: "John Doe",       // Replace with actual logged-in user's name
    email: "john@example.com"  // Replace with actual logged-in user's email
};
```

In a production app, you would dynamically inject these values from your authentication system.

## Webhook Events

The boilerplate demonstrates handling webhook events in `internal/api/webhook.go`. Supported events include:

| Event                 | Description                                  |
| --------------------- | -------------------------------------------- |
| `subscription.active` | Triggered when a subscription becomes active |
| `payment.succeeded`   | Triggered when a payment is successful       |

Add your business logic inside the webhook handler to:

* Update user permissions in your database
* Send confirmation emails
* Provision access to digital products
* Track analytics and metrics

## Testing Webhooks Locally

For local development, use tools like [ngrok](https://ngrok.com/) to expose your local server:

```bash theme={null}
ngrok http 8000
```

Update the webhook URL in your [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks):

```
https://your-ngrok-url.ngrok.io/api/webhook
```

## Deployment

### Build for Production

```bash theme={null}
make build
```

Or manually:

```bash theme={null}
go build -o bin/server cmd/server/main.go
./bin/server
```

### Deploy to Vercel

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate)

### Docker

Create a `Dockerfile`:

```dockerfile theme={null}
FROM golang:1.21-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o bin/server cmd/server/main.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/bin/server .
COPY --from=builder /app/templates ./templates

EXPOSE 8000
CMD ["./server"]
```

Build and run:

```bash theme={null}
docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo
```

### Production Considerations

<Warning>
  Before deploying to production:

  * Switch `DODO_PAYMENTS_ENVIRONMENT` to `live_mode`
  * Use production API keys from the dashboard
  * Update the webhook URL to your production domain
  * Enable HTTPS for all endpoints
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Build errors or missing dependencies">
    Ensure Go modules are properly downloaded:

    ```bash theme={null}
    go mod tidy
    go mod download
    ```
  </Accordion>

  <Accordion title="Checkout session creation fails">
    **Common causes:**

    * Invalid product ID - verify it exists in your Dodo dashboard
    * Wrong API key or environment setting in `.env`
    * Check the server logs for detailed error messages
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    For local testing, use [ngrok](https://ngrok.com) to expose your server:

    ```bash theme={null}
    ngrok http 8000
    ```

    Update the webhook URL in your [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) to the ngrok URL. Make sure to update your `.env` file with the correct webhook verification key.
  </Accordion>

  <Accordion title="Templates not loading">
    Ensure you're running the server from the project root directory, or that the templates path is correctly configured in your code.
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Go SDK" icon="golang" href="/developer-resources/sdks/go">
    Complete Go SDK documentation
  </Card>

  <Card title="Webhooks Documentation" icon="webhook" href="/developer-resources/webhooks">
    Learn about all webhook events and best practices
  </Card>

  <Card title="Checkout Sessions" icon="credit-card" href="/developer-resources/checkout-session">
    Deep dive into checkout session configuration
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete Dodo Payments API documentation
  </Card>
</CardGroup>

## Support

Need help with the boilerplate?

* Join our [Discord community](https://discord.gg/bYqAp4ayYh) for questions and discussions
* Check the [GitHub repository](https://github.com/dodopayments/go-boilerplate) for issues and updates
* Contact our [support team](mailto:support@dodopayments.com) for assistance


# Handle Payment Failures
Source: https://docs.dodopayments.com/developer-resources/handle-payment-failures

Detect failed payments from webhooks and the API, read the failure reason, surface it to customers safely, and decide when to retry or collect a new payment method.

<Info>
  When a payment fails, Dodo Payments tells you **why** through a standardized `error_code` and a human-readable `error_message`. This guide shows how to read those fields, decide whether a retry is worthwhile, and recover the payment without exposing sensitive information to customers.
</Info>

## How Dodo Payments Reports a Failure

Every failed payment — whether a one-time checkout or a subscription renewal — carries the same failure fields on the payment object:

| Field           | Type           | Description                                                                                                                                                                                         |
| --------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`        | string         | `failed` for a failed payment. Other non-success states include `cancelled`, `requires_customer_action`, and `requires_payment_method`.                                                             |
| `error_code`    | string \| null | The standardized failure reason, for example `INSUFFICIENT_FUNDS` or `PROCESSING_ERROR`. See the [Transaction Failures](/api-reference/transaction-failures) reference for the full list.           |
| `error_message` | string \| null | A human-readable explanation of the failure, written for you rather than your customer. For a standardized `error_code` this is a headline plus the recommended action, not the raw processor text. |
| `retry_attempt` | integer        | `0` for the original charge. `1` or higher identifies a scheduled subscription renewal retry.                                                                                                       |

<Note>
  `error_code` and `error_message` are `null` until a payment actually fails. Always check `status` first, then read the error fields.
</Note>

<Warning>
  `error_message` from the merchant API is **merchant-facing copy**. It can name the real reason for a decline, including fraud-related ones, so never render it directly to a customer. Map `error_code` to your own customer-safe wording instead, as shown in [Surface Errors to Customers Safely](#surface-errors-to-customers-safely).
</Warning>

## The `payment.failed` Webhook

The most reliable way to detect a failure is the `payment.failed` webhook. The event wraps the full payment object in `data`:

```json payment.failed payload expandable theme={null}
{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}
```

A minimal handler reads `error_code` and routes on it:

<CodeGroup>
  ```javascript Node.js expandable theme={null}
  import { Webhook } from "standardwebhooks";
  import express from "express";

  const app = express();
  // Mount the raw body parser so the exact payload is available for verification
  app.use(express.raw({ type: "application/json" }));

  const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

  app.post("/webhooks/dodo", async (req, res) => {
    // Verify the signature against the raw body before trusting the payload
    const payload = req.body.toString();
    await webhook.verify(payload, req.headers);

    const event = JSON.parse(payload);

    if (event.type === "payment.failed") {
      const payment = event.data;

      console.log(
        `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
      );

      if (payment.subscription_id) {
        // Subscription renewal — Dodo retries soft declines for you
        await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
      } else {
        // One-time payment — prompt the customer to try again
        await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
      }
    }

    res.json({ received: true });
  });
  ```

  ```python Python expandable theme={null}
  import os
  from fastapi import FastAPI, Request
  from standardwebhooks import Webhook

  app = FastAPI()
  webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

  @app.post("/webhooks/dodo")
  async def handle_webhook(request: Request):
      # Verify the signature before trusting the payload
      payload = await request.body()
      webhook.verify(payload, dict(request.headers))

      event = await request.json()

      if event["type"] == "payment.failed":
          payment = event["data"]

          print(
              f"Payment {payment['payment_id']} failed: "
              f"{payment['error_code']} ({payment['error_message']})"
          )

          if payment["subscription_id"]:
              # Subscription renewal — Dodo retries soft declines for you
              flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
          else:
              # One-time payment — prompt the customer to try again
              notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

      return {"received": True}
  ```
</CodeGroup>

<Tip>
  Always verify the webhook signature before processing. See the [Webhooks guide](/developer-resources/webhooks) for the full setup, including signature verification and idempotency.
</Tip>

## Decide Whether to Retry: Soft vs. Hard Declines

The `error_code` tells you whether retrying the same payment method is worthwhile.

| Decline type     | What it means                                                                                                        | What to do                                                                       |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Soft decline** | Temporary or correctable (for example `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`). | Retrying — after a delay, or once the customer fixes their input — can succeed.  |
| **Hard decline** | Terminal (for example `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).                                     | Do **not** retry the same card. Ask the customer for a different payment method. |

The [Transaction Failures](/api-reference/transaction-failures) reference lists the decline type and recommended action for every `error_code`.

## Handling Failures at Checkout vs. on Renewal

How you recover depends on whether the customer is present.

<Tabs>
  <Tab title="At checkout (customer present)">
    The customer is actively checking out. Surface a clear message and let them retry immediately or use another card.

    * `requires_payment_method` — the customer never provided a payment method: they didn't enter card details, or were prompted for one and took no action. This is usually a checkout **drop-off**, not a decline — re-engage the customer to complete payment (see [Abandoned Cart Recovery](/features/recovery/abandoned-cart-recovery)).
    * `requires_customer_action` — additional authentication (such as 3DS) is needed; have the customer complete it. See [3D Secure handling](/features/payment-methods/cards#3d-secure-authentication).
  </Tab>

  <Tab title="On subscription renewal (customer not present)">
    The customer is not present, so you cannot prompt them in real time. When a renewal fails, the subscription moves to `on_hold` and `subscription.on_hold` fires.

    * **Soft declines** are re-attempted automatically by [Subscription Payment Retries](/features/recovery/payment-retries).
    * **Hard declines** (and exhausted retries) are best recovered with [Subscription Dunning](/features/recovery/subscription-dunning), which emails the customer to update their payment method.

    See the [Subscription Integration Guide](/developer-resources/subscription-integration-guide#handling-subscription-on-hold) for the full on-hold → reactivate flow.
  </Tab>
</Tabs>

## Retrying a Failed Payment

* **Subscriptions:** Enable [Subscription Payment Retries](/features/recovery/payment-retries) to recover soft declines with no integration work. You can also trigger recovery by having the customer update their payment method via the [Update Payment Method API](/api-reference/subscriptions/update-payment-method), which charges any outstanding dues.
* **One-time payments:** Resend the checkout or `payment_link` so the customer can try again with a different method. There is no automatic retry for one-time payments.

<Warning>
  Do not retry hard declines against the same card. Card networks can flag repeated declines as abusive, which hurts your authorization rate.
</Warning>

## Surface Errors to Customers Safely

Show customers a friendly message — never the raw `error_code`, and never the merchant-facing `error_message`.

<Info>
  On surfaces Dodo Payments controls — checkout, the [Customer Portal](/features/customer-portal), and dunning emails — this mapping is already done for you, including the fallback to a generic message for fraud-related declines. You only need the mapping below where you render failures in your own product.
</Info>

```javascript Customer-facing messaging expandable theme={null}
const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}
```

<Warning>
  **Never reveal the real reason for `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, or `FRAUDULENT`.** Surfacing these can tip off a fraudulent actor. Show a generic decline message and only log the specific `error_code` internally.
</Warning>

## Related

<CardGroup>
  <Card title="Transaction Failures" icon="circle-exclamation" href="/api-reference/transaction-failures">
    Every decline code, its type, and the recommended action.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/error-codes">
    API and business-logic errors that are not card declines.
  </Card>

  <Card title="Subscription Payment Retries" icon="arrow-rotate-right" href="/features/recovery/payment-retries">
    Automatic recovery of soft declines on subscription renewals.
  </Card>

  <Card title="Subscription Dunning" icon="repeat" href="/features/recovery/subscription-dunning">
    Email sequences that recover hard declines.
  </Card>

  <Card title="Payment Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/payment">
    Full payload schema for payment events.
  </Card>

  <Card title="Testing Failures" icon="flask" href="/miscellaneous/testing-process">
    Test cards that simulate declines and renewal failures.
  </Card>
</CardGroup>


# Hono Adaptor
Source: https://docs.dodopayments.com/developer-resources/hono-adaptor

Learn how to integrate Dodo Payments with your Hono App Router project using our NextJS Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your Hono app.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/hono
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using the Hono App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Hono app. Supports static (GET), dynamic (POST), and session (POST) flows.
    </Info>

    <CodeGroup>
      ```typescript Hono Route Handler expandable theme={null}
        // route.ts
        import { Checkout } from '@dodopayments/hono';
        import Hono from 'hono'

        const app = new Hono()

        app.get(
        "/api/checkout",
        Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            type: 'static'
        })
        );

        app.post(
        "/api/checkout",
        Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            type: 'dynamic'
        })
        );
        
        app.post(
        "/api/checkout",
        Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            type: 'session'
        })
        );
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Hono Route Handler expandable theme={null}
      // route.ts
      import { Checkout } from '@dodopayments/hono';
      import Hono from 'hono'

      const app = new Hono()
      app.get(
          "/api/customer-portal",
          CustomerPortal({
              bearerToken: process.env.DODO_PAYMENTS_API_KEY,
              environment: process.env.DODO_PAYMENTS_ENVIRONMENT
          })
      );
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Hono app.
    </Info>

    <CodeGroup>
      ```typescript Hono Route Handler expandable theme={null}
      // route.ts
      import Hono from 'hono'
      import { Webhooks } from '@dodopayments/hono'

      const app = new Hono()
      app.post(
      "/api/webhooks",
          Webhooks({
              webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
              onPayload: async (payload) => {
              // Handle Payload Here
              console.log(payload)
              }
          })
      );

      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Hono application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```
You are an expert Hono developer assistant. Your task is to guide a user through integrating the @dodopayments/hono adapter into their existing Hono project.

The @dodopayments/hono adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed to plug directly into an Hono app.

First, install the necessary package. Use the package manager appropriate for the user's project (npm, yarn, or bun):

npm install @dodopayments/hono

---

Here's how you should structure your response:

1. Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/hono adapter would you like to integrate into your project? You can choose one or more of the following:

- Checkout Route Handler (for handling product checkouts)
- Customer Portal Route Handler (for managing customer subscriptions/details)
- Webhook Route Handler (for receiving Dodo Payments webhook events)
- All (integrate all three)"

---

2. Based on the user's selection, provide detailed integration steps for each chosen functionality.

---

**If Checkout Route Handler is selected:**

**Purpose**: This handler redirects users to the Dodo Payments checkout page.

**Integration**:
Create two routes in your Hono app — one for static (GET) and one for dynamic (POST) checkout.


import { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()

app.get(
  "/api/checkout",
  Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'static'
  })
);

app.post(
  "/api/checkout",
  Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'session' // or 'dynamic' for dynamic link
  })
);


Config Options:

    bearerToken: Your Dodo Payments API key (recommended to be stored in DODO_PAYMENTS_API_KEY env variable).

    returnUrl (optional): URL to redirect the user after successful checkout.

    environment: "test_mode" or "live_mode"

    type: "static" (GET) or "dynamic" (POST) or "session" (POST)

GET (static checkout) expects query parameters:

    productId (required)

    quantity, customer fields (fullName, email, etc.), and metadata (metadata_*) are optional.

POST (dynamic checkout) expects a JSON body with payment details (one-time or subscription). Reference the docs for the full POST schema:

    One-time payments: https://docs.dodopayments.com/api-reference/payments/post-payments

    Subscriptions: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions


POST (checkout sessions) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session


If Customer Portal Route Handler is selected:

Purpose: This route allows customers to manage their subscriptions via the Dodo Payments portal.

Integration:

import { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()
app.get(
  "/api/customer-portal",
  CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
  })
);

Query Parameters:

    customer_id (required): e.g., ?customer_id=cus_123

    send_email (optional): if true, customer is emailed the portal link

Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: Processes incoming webhook events from Dodo Payments to trigger events in your app.

Integration:

import Hono from 'hono'
import { Webhooks } from '@dodopayments/hono'

const app = new Hono()
app.post(
  "/api/webhooks",
  Webhooks({
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
      // Handle Payload Here
      console.log(payload)
    }
  })
);

Features:

    Only POST method is allowed — others return 405

    Signature verification is performed using webhookKey. Returns 401 if invalid.

    Zod-based payload validation. Returns 400 if invalid schema.

    All handlers are async functions.

Supported Webhook Event Handlers:

You may pass in any of the following handlers:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired, onSubscriptionUpdated

    onLicenseKeyCreated

    onAbandonedCheckoutDetected, onAbandonedCheckoutRecovered

    onDunningStarted, onDunningRecovered

    onCreditAdded, onCreditDeducted, onCreditExpired, onCreditRolledOver, onCreditRolloverForfeited, onCreditOverageCharged, onCreditManualAdjustment, onCreditBalanceLow

Environment Variable Setup:

Make sure to define these environment variables in your project:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""

Use these inside your code as:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

Security Note: Do NOT commit secrets to version control. Use .env files locally and secrets managers in deployment environments (e.g., AWS, Vercel, Heroku, etc.).
```


# Inline Checkout
Source: https://docs.dodopayments.com/developer-resources/inline-checkout

Embed Dodo Payments checkout directly into your website for a seamless, branded payment experience.

## Overview

Inline checkout lets you create fully integrated checkout experiences that blend seamlessly with your website or application. Unlike the [overlay checkout](/developer-resources/overlay-checkout), which opens as a modal on top of your page, inline checkout embeds the payment form directly into your page layout.

Using inline checkout, you can:

* Create checkout experiences that are fully integrated with your app or website
* Let Dodo Payments securely capture customer and payment information in an optimized checkout frame
* Display items, totals, and other information from Dodo Payments on your page
* Use SDK methods and events to build advanced checkout experiences

<Frame>
  <img alt="Inline Checkout Cover Image" />
</Frame>

## How It Works

Inline checkout works by embedding a secure Dodo Payments frame into your website or app.

The checkout frame handles collecting customer information and capturing payment details. Your page displays the items list, totals, and options for changing what's on the checkout. The SDK lets your page and the checkout frame interact with each other.

Dodo Payments automatically creates a subscription when a checkout completes, ready for you to provision.

<Note>
  The inline checkout frame securely handles all sensitive payment information, ensuring PCI compliance without additional certification on your end.
</Note>

## What Makes a Good Inline Checkout?

It's important that customers know who they're buying from, what they're buying, and how much they're paying.

To build an inline checkout that's compliant and optimized for conversion, your implementation must include:

<Frame>
  <img alt="Inline checkout example with required elements labeled" />
</Frame>

1. **Recurring information**: If recurring, how often it recurs and the total to pay on renewal. If a trial, how long the trial lasts.
2. **Item descriptions**: A description of what's being purchased.
3. **Transaction totals**: Transaction totals, including subtotal, total tax, and grand total. Be sure to include the currency too.
4. **Dodo Payments footer**: The full inline checkout frame, including the checkout footer that has information about Dodo Payments, our terms of sale, and our privacy policy.
5. **Refund policy**: A link to your refund policy, if it differs from the Dodo Payments standard refund policy.

<Warning>
  Always display the complete inline checkout frame, including the footer. Removing or hiding legal information violates compliance requirements.
</Warning>

## Customer Journey

The checkout flow is determined by your checkout session configuration. Depending on how you configure the checkout session, customers will experience a checkout that may present all information on a single page or across multiple steps.

<Steps>
  <Step title="Customer opens checkout">
    You can open inline checkout by passing items or an existing transaction. Use the SDK to show and update on-page information, and SDK methods to update items based on customer interaction.

    <img alt="Initial checkout page with items list and payment form" />
  </Step>

  <Step title="Customer enters their details">
    Inline checkout first asks customers to enter their email address, select their country, and (where required) enter their ZIP or postal code. This step gathers all necessary information to determine taxes and available payment options.

    You can prefill customer details and present saved addresses to streamline the experience.
  </Step>

  <Step title="Customer selects payment method">
    After entering their details, customers are presented with available payment methods and the payment form. Options may include credit or debit card, PayPal, Apple Pay, Google Pay, and other local payment methods based on their location.

    Display saved payment methods if available to speed up checkout.

    <img alt="Available payment methods and card details form" />
  </Step>

  <Step title="Checkout completed">
    Dodo Payments routes every payment to the best acquirer for that sale to get the best possible chance of success. Customers enter a success workflow that you can build.

    <img alt="Success screen with confirmation checkmark" />
  </Step>

  <Step title="Dodo Payments creates subscription">
    Dodo Payments automatically creates a subscription for the customer, ready for you to provision. The payment method the customer used is held on file for renewals or subscription changes.

    <img alt="Subscription created with webhook notification" />
  </Step>
</Steps>

## Quick Start

Get started with the Dodo Payments Inline Checkout in just a few lines of code:

```typescript theme={null}
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK for inline mode
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout in a specific container
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout" // ID of the container element
});
```

<Tip>
  Ensure you have a container element with the corresponding `id` on your page: `<div id="dodo-inline-checkout"></div>`.
</Tip>

## Step-by-Step Integration Guide

<Steps>
  <Step title="Install the SDK">
    Install the Dodo Payments Checkout SDK:

    <CodeGroup>
      ```bash npm theme={null}
      npm install dodopayments-checkout
      ```

      ```bash yarn theme={null}
      yarn add dodopayments-checkout
      ```

      ```bash pnpm theme={null}
      pnpm add dodopayments-checkout
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the SDK for Inline Display">
    Initialize the SDK and specify `displayType: 'inline'`. You should also listen for the `checkout.breakdown` event to update your UI with real-time tax and total calculations.

    ```typescript theme={null}
    import { DodoPayments } from "dodopayments-checkout";

    DodoPayments.Initialize({
      mode: "test",
      displayType: "inline",
      onEvent: (event) => {
        if (event.event_type === "checkout.breakdown") {
          const breakdown = event.data?.message;
          // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
        }
      },
    });
    ```
  </Step>

  <Step title="Create a Container Element">
    Add an element to your HTML where the checkout frame will be injected:

    ```html theme={null}
    <div id="dodo-inline-checkout"></div>
    ```
  </Step>

  <Step title="Open the Checkout">
    Call `DodoPayments.Checkout.open()` with the `checkoutUrl` and the `elementId` of your container:

    ```typescript theme={null}
    DodoPayments.Checkout.open({
      checkoutUrl: "https://test.dodopayments.com/session/cks_123",
      elementId: "dodo-inline-checkout"
    });
    ```
  </Step>

  <Step title="Test Your Integration">
    1. Start your development server:

    ```bash theme={null}
    npm run dev
    ```

    2. Test the checkout flow:
       * Enter your email and address details in the inline frame.
       * Verify that your custom order summary updates in real-time.
       * Test the payment flow using test credentials.
       * Confirm redirects work correctly.

    <Check>
      You should see `checkout.breakdown` events logged in your browser console if you added a console log in the `onEvent` callback.
    </Check>
  </Step>

  <Step title="Go Live">
    When you're ready for production:

    1. Change the mode to `'live'`:

    ```typescript theme={null}
    DodoPayments.Initialize({
      mode: "live",
      displayType: "inline",
      onEvent: (event) => {
        // Handle events
      }
    });
    ```

    2. Update your checkout URLs to use live checkout sessions from your backend.
    3. Test the complete flow in production.
  </Step>
</Steps>

## Complete React Example

This example demonstrates how to implement a custom order summary alongside the inline checkout, keeping them in sync using the `checkout.breakdown` event.

```tsx theme={null}
"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

```

## API Reference

### Configuration

#### Initialize Options

```typescript theme={null}
interface InitializeOptions {
  mode: "test" | "live";
  displayType: "inline"; // Required for inline checkout
  onEvent: (event: CheckoutEvent) => void;
}
```

| Option        | Type                    | Required | Description                                      |
| ------------- | ----------------------- | -------- | ------------------------------------------------ |
| `mode`        | `"test" \| "live"`      | Yes      | Environment mode.                                |
| `displayType` | `"inline" \| "overlay"` | Yes      | Must be set to `"inline"` to embed the checkout. |
| `onEvent`     | `function`              | Yes      | Callback function for handling checkout events.  |

#### Checkout Options

```typescript theme={null}
export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}
```

| Option                      | Type         | Required | Description                                                                                                                                      |
| --------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `checkoutUrl`               | `string`     | Yes      | Checkout session URL.                                                                                                                            |
| `elementId`                 | `string`     | Yes      | The `id` of the DOM element where the checkout should be rendered.                                                                               |
| `options.showTimer`         | `boolean`    | No       | Show or hide the checkout timer. Defaults to `true`. When disabled, you will receive the `checkout.link_expired` event when the session expires. |
| `options.showSecurityBadge` | `boolean`    | No       | Show or hide the security badge. Defaults to `true`.                                                                                             |
| `options.payButtonText`     | `string`     | No       | Custom text to display on the pay button.                                                                                                        |
| `options.fontSize`          | `FontSize`   | No       | Global font size for the checkout.                                                                                                               |
| `options.fontWeight`        | `FontWeight` | No       | Global font weight for the checkout.                                                                                                             |

### Methods

#### Open Checkout

Opens the checkout frame in the specified container.

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout"
});
```

You can also pass additional options to customize the checkout behavior:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    payButtonText: "Pay Now",
  },
});
```

#### Close Checkout

Programmatically removes the checkout frame and cleans up event listeners.

```typescript theme={null}
DodoPayments.Checkout.close();
```

#### Check Status

Returns whether the checkout frame is currently injected.

```typescript theme={null}
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean
```

### Events

The SDK provides real-time events through the `onEvent` callback. For inline checkout, `checkout.breakdown` is particularly useful for syncing your UI.

| Event Type                            | Description                                                                                                 |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `checkout.opened`                     | Checkout frame has been loaded.                                                                             |
| `checkout.form_ready`                 | Checkout form is ready to receive user input. Useful for hiding loading states and showing the checkout UI. |
| `checkout.breakdown`                  | Fired when prices, taxes, or discounts are updated.                                                         |
| `checkout.customer_details_submitted` | Customer details have been submitted.                                                                       |
| `checkout.pay_button_clicked`         | Fired when the customer clicks the pay button. Useful for analytics and tracking conversion funnels.        |
| `checkout.redirect`                   | Checkout will perform a redirect (e.g., to a bank page).                                                    |
| `checkout.error`                      | An error occurred during checkout.                                                                          |
| `checkout.link_expired`               | Fired when the checkout session expires. Only received when `showTimer` is set to `false`.                  |

#### Checkout Breakdown Data

The `checkout.breakdown` event provides the following data:

```typescript theme={null}
interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;         // Amount in cents
  tax?: number;              // Amount in cents
  total?: number;            // Amount in cents
  currency?: string;         // e.g., "USD"
  finalTotal?: number;       // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}
```

#### Understanding the Breakdown Event

The `checkout.breakdown` event is the primary way to keep your application's UI in sync with the Dodo Payments checkout state.

**When it fires:**

* **On initialization**: Immediately after the checkout frame is loaded and ready.
* **On address change**: Whenever the customer selects a country or enters a postal code that results in a tax recalculation.

**Field Details:**

| Field                | Description                                                                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subTotal`           | The sum of all line items in the session before any discounts or taxes are applied.                                                                                             |
| `discount`           | The total value of all applied discounts.                                                                                                                                       |
| `tax`                | The calculated tax amount. In `inline` mode, this updates dynamically as the user interacts with the address fields.                                                            |
| `total`              | The mathematical result of `subTotal - discount + tax` in the session's base currency.                                                                                          |
| `currency`           | The ISO currency code (e.g., `"USD"`) for the standard subtotal, discount, and tax values.                                                                                      |
| `finalTotal`         | The actual amount the customer is charged. This may include additional foreign exchange adjustments or local payment method fees that aren't part of the basic price breakdown. |
| `finalTotalCurrency` | The currency in which the customer is actually paying. This can differ from `currency` if purchasing power parity or local currency conversion is active.                       |

**Key Integration Tips:**

1. **Currency Formatting**: Prices are always returned as integers in the smallest currency unit (e.g., cents for USD, yen for JPY). To display them, divide by 100 (or the appropriate power of 10) or use a formatting library like `Intl.NumberFormat`.
2. **Handling Initial States**: When the checkout first loads, `tax` and `discount` may be `0` or `null` until the user provides their billing information or applies a code. Your UI should handle these states gracefully (e.g., showing a dash `—` or hiding the row).
3. **The "Final Total" vs "Total"**: While `total` gives you the standard price calculation, `finalTotal` is the source of truth for the transaction. If `finalTotal` is present, it reflects exactly what will be charged to the customer's card, including any dynamic adjustments.
4. **Real-time Feedback**: Use the `tax` field to show users that taxes are being calculated in real-time. This provides a "live" feel to your checkout page and reduces friction during the address entry step.

## Implementation Options

### Package Manager Installation

Install via npm, yarn, or pnpm as shown in the [Step-by-Step Integration Guide](#step-by-step-integration-guide).

### CDN Implementation

For quick integration without a build step, you can use our CDN:

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Inline Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test",
            displayType: "inline",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <div id="dodo-inline-checkout"></div>

    <script>
        // Open the checkout
        DodoPaymentsCheckout.DodoPayments.Checkout.open({
            checkoutUrl: "https://test.dodopayments.com/session/cks_123",
            elementId: "dodo-inline-checkout"
        });
    </script>
</body>
</html>
```

## Update Payment Method

Inline checkout supports **payment method updates** for subscriptions. When a customer needs to update their payment method -- whether for an active subscription or to reactivate an on-hold subscription -- you can render the update flow directly within your page layout.

### How It Works

1. Call the [Update Payment Method API](/features/subscription#update-payment-method-for-active-subscription) to get a `payment_link`:

```typescript theme={null}
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: { type: 'new', return_url: 'https://example.com/return' }
});
```

2. Pass the returned `payment_link` as the `checkoutUrl` to open inline checkout:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: response.payment_link,
  elementId: "dodo-inline-checkout"
});
```

The inline frame renders only the payment method collection form. Customers can enter new card details or select a saved payment method without leaving your page.

### For On-Hold Subscriptions

When updating the payment method for a subscription in `on_hold` status, Dodo Payments automatically creates a charge for any remaining dues. Monitor the `payment.succeeded` and `subscription.active` webhooks to confirm reactivation.

```typescript theme={null}
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: { type: 'new', return_url: 'https://example.com/return' }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Open inline checkout for payment collection
  DodoPayments.Checkout.open({
    checkoutUrl: response.payment_link,
    elementId: "dodo-inline-checkout"
  });
}
```

<Tip>
  You can also use an existing saved payment method instead of collecting new details by passing `type: 'existing'` with a `payment_method_id` to the Update Payment Method API.
</Tip>

## Error Handling

The SDK provides detailed error information through the event system. Always implement proper error handling in your `onEvent` callback:

```typescript theme={null}
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});
```

<Warning>
  Always handle the `checkout.error` event to provide a good user experience when issues occur.
</Warning>

## Best Practices

1. **Responsive Design**: Ensure your container element has enough width and height. The iframe will typically expand to fill its container.
2. **Synchronization**: Use the `checkout.breakdown` event to keep your custom order summary or pricing tables in sync with what the user sees in the checkout frame.
3. **Skeleton States**: Show a loading indicator in your container until the `checkout.opened` event fires.
4. **Cleanup**: Call `DodoPayments.Checkout.close()` when your component unmounts to clean up the iframe and event listeners.

<Info>
  For dark mode implementations, it's recommended to use `#0d0d0d` as the background color for optimal visual integration with the inline checkout frame.
</Info>

## Payment Status Validation

<Warning>
  Do not rely solely on inline checkout events to determine payment success or failure. Always implement server-side validation using webhooks and/or polling.
</Warning>

### Why Server-Side Validation is Essential

While inline checkout events provide real-time feedback, they should **not** be your only source of truth for payment status. Network issues, browser crashes, or users closing the page can cause events to be missed. To ensure reliable payment validation:

1. **Your server should listen to webhook events** - Dodo Payments sends webhooks for payment status changes
2. **Implement a polling mechanism** - Your frontend should poll your server for status updates
3. **Combine both approaches** - Use webhooks as the primary source and polling as a fallback

### Recommended Architecture

```mermaid theme={null}
flowchart TB
    subgraph Frontend["Your Frontend"]
        IC[Inline Checkout<br/>Dodo iframe]
        CP[Your Checkout Page]
        IC -->|events| CP
    end

    subgraph Server["Your Server"]
        WH[Webhook Handler]
        DB[(Database)]
        API[Status API]
        WH --> DB
        API --> DB
    end

    subgraph Dodo["Dodo Payments"]
        PP[Payment Processor]
    end

    CP -->|Poll for status| API
    PP -->|Webhooks| WH
    IC -.->|Payment request| PP
```

### Implementation Steps

**1. Listen for checkout events** - When the user clicks pay, start preparing to verify the status:

```typescript theme={null}
onEvent: (event) => {
  if (event.event_type === 'checkout.pay_button_clicked') {
    // Start polling your server for confirmed status
    startPolling();
  }
}
```

**2. Poll your server** - Create an endpoint that checks your database for the payment status (updated by webhooks):

```typescript theme={null}
// Poll every 2 seconds until status is confirmed
const interval = setInterval(async () => {
  const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json());
  if (status === 'succeeded' || status === 'failed') {
    clearInterval(interval);
    handlePaymentResult(status);
  }
}, 2000);
```

**3. Handle webhooks server-side** - Update your database when Dodo sends `payment.succeeded` or `payment.failed` webhooks. See our [Webhooks documentation](/developer-resources/webhooks) for details.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Checkout frame is not appearing">
    * Verify that `elementId` matches the `id` of a `div` that actually exists in the DOM.
    * Ensure `displayType: 'inline'` was passed to `Initialize`.
    * Check that the `checkoutUrl` is valid.
  </Accordion>

  <Accordion title="Taxes are not updating in my UI">
    * Ensure you are listening for the `checkout.breakdown` event.
    * Taxes are only calculated after the user enters a valid country and postal code in the checkout frame.
  </Accordion>
</AccordionGroup>

## Enabling Digital Wallets

For detailed information about setting up Apple Pay, Google Pay, and other digital wallets, see the <a href="/features/payment-methods/digital-wallets">Digital Wallets</a> page.

### Quick Setup for Apple Pay

<Info>
  Domain verification is only required for **inline (embedded) checkout**. It is not required for hosted checkout.
</Info>

<Warning>
  Apple Pay is not available for overlay checkout.
</Warning>

Apple Pay is verified per-domain from the dashboard.

<Steps>
  <Step title="Open Wallet domains">
    Go to **Settings → Payment Methods** and, on the **Apple Pay** row, click **Manage domains**.

    <Frame>
      <img alt="Manage domains button on the Apple Pay row in Payment Methods settings" />
    </Frame>
  </Step>

  <Step title="Download the domain association file">
    From the Wallet domains panel, download the association file.

    <Frame>
      <img alt="Wallet domains panel with the Download file button" />
    </Frame>
  </Step>

  <Step title="Register your domain">
    Click **Register domain** and enter the domain where you embed inline checkout (e.g. `shop.example.com`), then **Continue**.

    <Frame>
      <img alt="Register a domain form with a domain entered" />
    </Frame>
  </Step>

  <Step title="Host the file on your domain">
    Host it at:

    ```
    https://shop.example.com/.well-known/apple-developer-merchantid-domain-association
    ```

    It must be served over HTTPS, reachable without redirects, and served with `Content-Type: application/octet-stream` or `text/plain`.
  </Step>

  <Step title="Verify the domain">
    Click **Verify domain**. Dodo Payments confirms the file is live and submits your domain to Apple.

    <Frame>
      <img alt="Verify your domain screen with the association file host path and Verify domain button" />
    </Frame>
  </Step>

  <Step title="Confirm it's active">
    When the status shows **Active**, Apple Pay is enabled for that domain. Use the **Enabled** toggle to turn it on or off per domain.

    <Frame>
      <img alt="Wallet domains list showing domains with an Active Apple Pay status and Enabled toggles" />
    </Frame>
  </Step>

  <Step title="Test the integration">
    1. Open checkout on an Apple device
    2. Verify Apple Pay button appears
    3. Complete a test transaction
  </Step>
</Steps>

## Browser Support

The Dodo Payments Checkout SDK supports the following browsers:

* Chrome (latest)
* Firefox (latest)
* Safari (latest)
* Edge (latest)
* IE11+

## Inline vs Overlay Checkout

Choose the right checkout type for your use case:

| Feature               | Inline Checkout                              | Overlay Checkout                  |
| --------------------- | -------------------------------------------- | --------------------------------- |
| Integration depth     | Fully embedded in page                       | Modal on top of page              |
| Layout control        | Full control                                 | Limited                           |
| Branding              | Seamless                                     | Separate from page                |
| Implementation effort | Higher                                       | Lower                             |
| Best for              | Custom checkout pages, high-conversion flows | Quick integration, existing pages |

<Tip>
  Use **inline checkout** when you want maximum control over the checkout experience and seamless branding. Use **overlay checkout** for faster integration with minimal changes to your existing pages.
</Tip>

## Related Resources

<CardGroup>
  <Card title="Overlay Checkout" icon="layer-group" href="/developer-resources/overlay-checkout">
    Use the overlay checkout for quick modal-based integration.
  </Card>

  <Card title="Checkout Sessions API" icon="code" href="/api-reference/checkout-sessions/create">
    Create checkout sessions to power your checkout experiences.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle payment events server-side with webhooks.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/integration-guide">
    Complete guide to integrating Dodo Payments.
  </Card>
</CardGroup>

For more help, visit our [Discord community](https://discord.gg/bYqAp4ayYh) or contact our developer support team.


# One-time Payments Integration Guide
Source: https://docs.dodopayments.com/developer-resources/integration-guide

This guide will help you integrate the Dodo Payments API into your website.

## Prerequisites

To integrate the Dodo Payments API, you'll need:

* A Dodo Payments merchant account
* API Credentials (API key and webhook secret key) from dashboard

## Dashboard Setup

1. Navigate to the [Dodo Payments Dashboard](https://app.dodopayments.com/)

2. Create a product (one-time payment or subscription). Subscription products must be priced at least **\$1** (or the equivalent in your chosen currency); amounts below this minimum are not supported.

3. Generate your API key:
   * Go to Developer > API
   * [Detailed Guide](/api-reference/introduction#api-key-generation)
   * Copy the API key the in env named DODO\_PAYMENTS\_API\_KEY

4. Configure webhooks:
   * Go to Developer > Webhooks
   * Create a webhook URL for payment notifications
   * Copy the webhook secret key in env

## Integration

### Payment Links

Choose the integration path that fits your use case:

* **Checkout Sessions (recommended)**: Best for most integrations. Create a session on your server and redirect customers to a secure, hosted checkout.
* **Overlay Checkout**: Use when you need an in-page experience that opens checkout as a modal overlay on your site.
* **Inline Checkout**: Embed checkout directly into your page layout for fully integrated, branded checkout experiences.
* **Static Payment Links**: No-code, instantly shareable URLs for quick payment collection.
* **Dynamic Payment Links**: Programmatically created links. However, Checkout Sessions are recommended and provide more flexibility.
* **[Mobile Checkout SDKs](/developer-resources/mobile-integration)**: For native Android, iOS, React Native, and Flutter apps. Create the session on your server as above, then hand the `checkout_url` to the SDK.

<Info>
  Overlay and Inline Checkout are browser-only — they embed checkout into a web
  page. If you're building a native mobile app, create the checkout session on
  your server and open it with the
  [Mobile Checkout SDKs](/developer-resources/mobile-integration) instead.
</Info>

#### 1. Checkout Sessions

Use Checkout Sessions to create a secure, hosted checkout experience for one-time payments or subscriptions. You create a session on your server, then redirect the customer to the returned `checkout_url`.

<Info>
  Checkout sessions are valid for 24 hours by default. If you pass <code>confirm=true</code>, sessions are valid for 15 minutes and all required fields must be provided.
</Info>

<Steps>
  <Step title="Create a checkout session">
    Choose your preferred SDK or call the REST API.

    <Tabs>
      <Tab title="Node.js SDK">
        ```javascript theme={null}
        import DodoPayments from 'dodopayments';

        const client = new DodoPayments({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          environment: 'test_mode', // defaults to 'live_mode'
        });

        const session = await client.checkoutSessions.create({
          product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
          customer: { email: 'customer@example.com', name: 'John Doe' },
          return_url: 'https://yourapp.com/checkout/success',
        });
        ```
      </Tab>

      <Tab title="Python SDK">
        ```python theme={null}
        import os
        from dodopayments import DodoPayments

        client = DodoPayments(
            bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
            environment="test_mode",  # defaults to "live_mode"
        )

        session = client.checkout_sessions.create(
            product_cart=[{"product_id": "pdt_123", "quantity": 1}],
            customer={"email": "customer@example.com", "name": "John Doe"},
            return_url="https://yourapp.com/checkout/success",
        )
        ```
      </Tab>

      <Tab title="REST API">
        ```javascript theme={null}
        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({
            product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
            customer: { email: 'customer@example.com', name: 'John Doe' },
            return_url: 'https://yourapp.com/checkout/success',
          }),
        });
        const session = await response.json();
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Redirect customer to checkout">
    After session creation, redirect to the `checkout_url` to start the hosted flow.

    ```javascript theme={null}
    // Example in a browser context
    window.location.href = session.checkout_url;
    ```
  </Step>
</Steps>

<Tip>
  Prefer Checkout Sessions for the fastest, most reliable way to start taking payments. For advanced customization, see the full <a href="/developer-resources/checkout-session">Checkout Sessions guide</a> and the <a href="/api-reference/checkout-sessions/create">API Reference</a>.
</Tip>

#### 2. Overlay Checkout

For a seamless in-page checkout experience, explore our [Overlay Checkout](/developer-resources/overlay-checkout) integration that allows customers to complete payments without leaving your website.

#### 3. Inline Checkout

For fully integrated checkout experiences embedded directly in your page, use our [Inline Checkout](/developer-resources/inline-checkout) integration. This allows you to build custom order summaries and have complete control over the checkout layout while Dodo Payments securely handles payment collection.

#### 4. Static Payment Links

Static payment links let you quickly accept payments by sharing a simple URL. You can customize the checkout experience by passing query parameters to pre-fill customer details, control form fields, and add custom metadata.

<Steps>
  <Step title="Construct your payment link">
    Start with the base URL and append your product ID:

    ```text theme={null}
    https://checkout.dodopayments.com/buy/{productid}
    ```
  </Step>

  <Step title="Add core parameters">
    Include essential query parameters:

    * <ParamField type="integer">Number of items to purchase.</ParamField>
    * <ParamField type="string">URL to redirect after payment completion.</ParamField>

    <Note>
      The redirect URL will include payment details as query parameters, for example:<br />
      <code>[https://example.com/?payment\_id=pay\_ts2ySpzg07phGeBZqePbH\&status=succeeded\&email=customer%40example.com](https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH\&status=succeeded\&email=customer%40example.com)</code><br /><br />
      If the product has license keys enabled, a `license_key` parameter is also appended (comma-separated for multiple keys):<br />
      <code>[https://example.com/?payment\_id=pay\_xxx\&status=succeeded\&license\_key=LK-001\&email=customer%40example.com](https://example.com/?payment_id=pay_xxx\&status=succeeded\&license_key=LK-001\&email=customer%40example.com)</code>
    </Note>
  </Step>

  <Step title="Pre-fill customer information (optional)">
    Add customer or billing fields as query parameters to streamline checkout.

    <AccordionGroup>
      <Accordion title="Supported Customer Fields">
        * <ParamField type="string">Customer's full name (ignored if firstName or lastName is provided).</ParamField>
        * <ParamField type="string">Customer's first name.</ParamField>
        * <ParamField type="string">Customer's last name.</ParamField>
        * <ParamField type="string">Customer's email address.</ParamField>
        * <ParamField type="string">Customer's country.</ParamField>
        * <ParamField type="string">Street address.</ParamField>
        * <ParamField type="string">City.</ParamField>
        * <ParamField type="string">State or province.</ParamField>
        * <ParamField type="string">Postal/ZIP code.</ParamField>
        * <ParamField type="boolean">true or false</ParamField>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Control form fields (optional)">
    <Info>
      You can disable specific fields to make them read-only for the customer. This is useful when you already have the customer's details (e.g., logged-in users).
    </Info>

    To disable a field, provide its value and set the corresponding <code>disable...</code> flag to <code>true</code>:

    <CodeGroup>
      ```text Example theme={null}
      &email=alice@example.com&disableEmail=true
      ```
    </CodeGroup>

    <Tabs>
      <Tab title="Disable Flags Table">
        | Field        | Disable Flag         | Required Parameter |
        | ------------ | -------------------- | ------------------ |
        | Full Name    | `disableFullName`    | `fullName`         |
        | First Name   | `disableFirstName`   | `firstName`        |
        | Last Name    | `disableLastName`    | `lastName`         |
        | Email        | `disableEmail`       | `email`            |
        | Country      | `disableCountry`     | `country`          |
        | Address Line | `disableAddressLine` | `addressLine`      |
        | City         | `disableCity`        | `city`             |
        | State        | `disableState`       | `state`            |
        | ZIP Code     | `disableZipCode`     | `zipCode`          |
      </Tab>
    </Tabs>

    <Tip>
      Disabling fields helps prevent accidental changes and ensures data consistency.
    </Tip>

    <Note>
      Setting <code>showDiscounts=false</code> will disable and hide the discounts section in the checkout form. Use this if you want to prevent customers from entering coupon or promo codes during checkout.
    </Note>
  </Step>

  <Step title="Add advanced controls (optional)">
    * <ParamField type="string">Specifies the payment currency. Defaults to the billing country's currency.</ParamField>
    * <ParamField type="boolean">Show or hide the currency selector.</ParamField>
    * <ParamField type="number">Fixes the amount charged, in major currency units (e.g. <code>12.5</code> for \$12.50). Pay What You Want products only. The value is ignored if it is below the product's minimum price.</ParamField>
    * <ParamField type="string">Custom metadata fields (e.g., <code>metadata\_orderId=123</code>).</ParamField>

    <Warning>
      `paymentAmount` on a payment link is **not** the same unit as the `amount` field in the Checkout Sessions API. The link parameter takes major currency units (`12.5` = $12.50), while the API's `product_cart[].amount` takes the lowest denomination (`1250` = $12.50). See [Dynamic Pricing](/developer-resources/dynamic-pricing-checkout) for the API field.
    </Warning>
  </Step>

  <Step title="Share the link">
    Send the completed payment link to your customer. When they visit, all query parameters are collected and stored with a session ID. The URL is then simplified to include just the session parameter (e.g., <code>?session=sess\_1a2b3c4d</code>). The stored information persists through page refreshes and is accessible throughout the checkout process.

    <Check>
      The customer's checkout experience is now streamlined and personalized based on your parameters.
    </Check>
  </Step>
</Steps>

#### 4. Dynamic Payment Links

<Tip>
  Prefer Checkout Sessions for most use cases, they offer more flexibility and control.
</Tip>

Created via API call or our SDK with customer details. Here's an example:

There are two APIs for creating dynamic payment links:

* One-time Payment Link API [API reference](/api-reference/payments/post-payments)
* Subscription Payment Link API [API reference](/api-reference/subscriptions/post-subscriptions)

<Warning>
  Both link-creation endpoints are **deprecated**. `POST /payments` and `POST /subscriptions` continue to work for existing integrations, but new integrations should use [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`) instead.
</Warning>

The guide below is for one-time payment link creation.

For detailed instructions on integrating subscriptions, refer to this [Subscription Integration Guide](/developer-resources/subscription-integration-guide).

<Info>Make sure you are passing `payment_link = true` to get payment link </Info>

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
    bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
    environment: 'test_mode', // defaults to 'live_mode'
    });

    async function main() {
    const payment = await client.payments.create({
    payment_link: true,
    billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: '10001' },
    customer: { email: 'email@email.com', name: 'name' },
    product_cart: [{ product_id: 'product_id', quantity: 0 }],
    });

    console.log(payment.payment_id);
    }

    main();
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from dodopayments import DodoPayments

    client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted (if using same name `DODO_PAYMENTS_API_KEY`)
    environment="test_mode",  # defaults to "live_mode"
    )
    payment = client.payments.create(
    payment_link=True,
    billing={
        "city": "city",
        "country": "AF",
        "state": "state",
        "street": "street",
        "zipcode": "10001",
    },
    customer={
        "email": "email@email.com",
        "name": "name",
    },
    product_cart=[{
        "product_id": "product_id",
        "quantity": 0,
    }],
    )
    print(payment.payment_link)
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    package main

    import (
    "context"
    "fmt"

    "github.com/dodopayments/dodopayments-go"
    "github.com/dodopayments/dodopayments-go/option"
    )

    func main() {
    client := dodopayments.NewClient(
    option.WithBearerToken("My Bearer Token"), // defaults to os.LookupEnv("DODO_PAYMENTS_API_KEY")
    )
    payment, err := client.Payments.New(context.TODO(), dodopayments.PaymentNewParams{
    PaymentLink: dodopayments.F(true),
    Billing: dodopayments.F(dodopayments.BillingAddressParam{
      City: dodopayments.F("city"),
      Country: dodopayments.F(dodopayments.CountryCodeAf),
      State: dodopayments.F("state"),
      Street: dodopayments.F("street"),
      Zipcode: dodopayments.F("10001"),
    }),
    Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](dodopayments.NewCustomerParam{
      Email: dodopayments.F("email@email.com"),
      Name: dodopayments.F("name"),
    }),
    ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
      ProductID: dodopayments.F("product_id"),
      Quantity: dodopayments.F(int64(1)),
    }}),
    })
    if err != nil {
    panic(err.Error())
    }
    fmt.Printf("%+v\n", payment.PaymentLink)
    }

    ```
  </Tab>

  <Tab title="Api Reference">
    ```javascript theme={null}
    import { NextRequest, NextResponse } from "next/server";      

    export async function POST(request: NextRequest) {
    try {
    const body = await request.json();
    const { formData, cartItems } = paymentRequestSchema.parse(body);

    const response = await fetch(`${process.env.NEXT_PUBLIC_DODO_TEST_API}/payments`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.DODO_API_KEY}`, // Replace with your API secret key generated from the Dodo Payments Dashboard
      },
      body: JSON.stringify({
        billing: {
          city: formData.city,
          country: formData.country,
          state: formData.state,
          street: formData.addressLine,
          zipcode: formData.zipCode,
        },
        customer: {
          email: formData.email,
          name: `${formData.firstName} ${formData.lastName}`,
          phone_number: formData.phoneNumber || undefined,
        },
        payment_link: true,
        product_cart: cartItems.map((id) => ({
          product_id: id,
          quantity: 1,
        })),
        return_url: process.env.NEXT_PUBLIC_RETURN_URL,
      }),
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => null);
      return NextResponse.json(
        { error: "Payment link creation failed", details: errorData },
        { status: response.status }
      );
    }

    const data = await response.json();
    return NextResponse.json({ paymentLink: data.payment_link });
    } catch (err) {
    console.error("Payment error:", err);
    return NextResponse.json(
      {
        error: err instanceof Error ? err.message : "An unknown error occurred",
      },
      { status: 500 }
    );
    }
    }
    ```
  </Tab>
</Tabs>

<Info>After creating the payment link, redirect your customers to complete their payment.</Info>

### Implementing Webhooks

Set up an API endpoint to receive payment notifications. Here's an example using Next.js:

```javascript theme={null}
import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}
```

Our webhook implementation follows the [Standard Webhooks](https://standardwebhooks.com/) specification. For webhook type definitions, refer to our [Webhook Event Guide](/developer-resources/webhooks/intents/webhook-events-guide).

#### Events to Listen For

Switch on `payload.type` and handle the events relevant to a one-time payment flow. At minimum, listen for:

| Event Type           | When it fires                                                  | What to do                                                                       |
| -------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `payment.succeeded`  | Payment is successfully processed.                             | Fulfill the order — grant access, provision the product, send the receipt.       |
| `payment.failed`     | Payment attempt fails (declined card, error, etc.).            | Notify the customer and prompt a retry; do not fulfill.                          |
| `payment.processing` | Payment is accepted but still being processed (async methods). | Wait for the terminal `payment.succeeded`/`payment.failed` — do not fulfill yet. |
| `payment.cancelled`  | Payment is cancelled before completion.                        | Release any held state and mark the order abandoned.                             |

<Tip>
  Always **fulfill on `payment.succeeded` from the webhook**, not on the browser redirect — the redirect can be missed if the customer closes the tab, whereas the webhook is retried until acknowledged.
</Tip>

If you sell digital products with license keys, also handle `license_key.created`. For the complete list of events — including subscription, entitlement, credit, recovery, and dunning events — see the [Webhook Event Guide](/developer-resources/webhooks/intents/webhook-events-guide).

You can refer to this project with demo implementation on [GitHub](https://github.com/dodopayments/dodo-checkout-demo) using Next.js and TypeScript.

You can check out the live implementation [here](https://atlas.dodopayments.com/).

## Key Things to Know About Checkout & Currency

<Warning>
  **Dynamic (Pay-What-You-Want) amounts are in the product's base currency** — not an arbitrary local currency — and base currency is limited to **USD, INR, GBP, and EUR**. To collect a fixed amount in another currency (e.g. PHP), you can't pass it directly: use **Adaptive Pricing** (converts your base amount at live FX) or **Localized Pricing** (fixed per-currency price, but not compatible with Pay-What-You-Want).
</Warning>

<Tip>
  **Fix the currency explicitly.** Pass `billing_currency` and `billing_address.country` on the checkout session. If omitted, the currency and country are detected from the customer's IP (Adaptive Currency) and may not match what you intend to charge.
</Tip>

<Info>
  **Checkout sessions expire in 24 hours** (15 minutes when `confirm: true`), and each `checkout_url` is **single-use** — generate a fresh session per customer and per payment attempt rather than reusing a link.
</Info>

<Info>
  **One-click repeat purchase.** For a returning customer with a saved payment method, pass `payment_method_id` together with `confirm: true` to charge instantly, skipping method selection entirely.
</Info>

## Related API Reference

<CardGroup>
  <Card title="Create Checkout Session" icon="code" href="/api-reference/checkout-sessions/create">
    API reference for creating secure, hosted checkout sessions for one-time payments and subscriptions
  </Card>

  <Card title="Create Payment Link" icon="link" href="/api-reference/payments/post-payments">
    API reference for creating dynamic payment links programmatically
  </Card>
</CardGroup>


# Manual License Key Fulfillment Integration Guide
Source: https://docs.dodopayments.com/developer-resources/manual-license-key-fulfillment

Build an end-to-end system that sells a product and lets you supply your own license keys on demand: create the product and entitlement, detect pending grants, and deliver the key to the customer.

This guide walks through building a **manual license key fulfillment** system end to end. Instead of Dodo Payments auto-generating a key on payment, each purchase creates a `Pending` grant and waits for *you* to supply the key value from your own system, a third-party vendor, or a finite pool of codes.

By the end you will have:

* A product with a License Key entitlement set to `manual` fulfillment.
* A webhook listener that detects when a customer is waiting for a key.
* A fulfillment call that delivers the key and notifies the customer automatically.

<CardGroup>
  <Card title="License Keys overview" icon="key" href="/features/license-keys">
    The full license key lifecycle and the `fulfillment_mode` setting.
  </Card>

  <Card title="Fulfill License Key Grant API" icon="code" href="/api-reference/entitlements/fulfill-license-key">
    API reference for the endpoint you call to deliver a key.
  </Card>
</CardGroup>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant D as Dodo Payments
    participant M as Your Backend
    C->>D: Purchase (manual-mode License Key product)
    D->>D: Create grant (status: Pending, no key)
    D->>M: entitlement_grant.created (integration_type: license_key, status: Pending)
    M->>M: Obtain key from own system / vendor
    M->>D: POST /grants/{grant_id}/license-key { key }
    D->>C: Deliver license key to customer
    D->>M: entitlement_grant.delivered
```

Manual fulfillment changes only the **issuance** step. Activation, validation, deactivation, expiry, and revocation behave exactly like an auto-generated key once delivered.

## Prerequisites

To follow this guide you'll need:

* A Dodo Payments merchant account.
* Your API key (`DODO_PAYMENTS_API_KEY`) and webhook secret key from the dashboard. See the [API key generation guide](/api-reference/introduction#api-key-generation).
* A backend endpoint that can receive webhooks.

<Info>
  Use `https://test.dodopayments.com` and test-mode credentials while building. Switch to `https://live.dodopayments.com` and live keys when you go to production.
</Info>

## Step 1 — Create a License Key Entitlement in Manual Mode

An **entitlement** is a reusable definition of what you deliver. Create a License Key entitlement and set its `fulfillment_mode` to `manual`.

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open Entitlements">
        Go to **Entitlements** in your dashboard and click **+** to create a new entitlement.
      </Step>

      <Step title="Choose License Key">
        Select **License Key** as the integration and give it a **Name**. The form exposes these fields:

        * **Fulfillment Mode** — `Automatic` by default. This is the setting that enables manual fulfillment; you change it in the next step.
        * **License Length** — how long each issued key stays valid, or **No expiration**.
        * **Activations Limit** — maximum activations per key, or **Unlimited**.
        * **Activation Message** — optional customer-facing message shown when they activate the key.

        <Frame>
          <img alt="New License Key entitlement form with name, fulfillment mode, license length, activations limit, and activation message" />
        </Frame>
      </Step>

      <Step title="Set Fulfillment Mode to Manual">
        Open the **Fulfillment Mode** dropdown and change it from **Automatic** to **Manual**. This is the setting that drives this entire guide — without it, keys are generated and emailed automatically and no pending grant is created. With **Manual** selected, each purchase creates a `Pending` grant for you to fulfill. Click **Create Entitlement** to save.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    Create the entitlement with `integration_config.fulfillment_mode` set to `manual`.

    <CodeGroup>
      ```typescript Node.js theme={null} theme={null}
      import DodoPayments from 'dodopayments';

      const client = new DodoPayments({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode', // defaults to 'live_mode'
      });

      const entitlement = await client.entitlements.create({
        name: 'Pro License (Manual)',
        integration_type: 'license_key',
        integration_config: {
          fulfillment_mode: 'manual',
          activations_limit: 5,
          duration_count: 1,
          duration_interval: 'Year',
        },
      });

      console.log(entitlement.id); // ent_...
      ```

      ```python Python theme={null} theme={null}
      import os
      from dodopayments import DodoPayments

      client = DodoPayments(
          bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
          environment="test_mode",  # defaults to "live_mode"
      )

      entitlement = client.entitlements.create(
          name="Pro License (Manual)",
          integration_type="license_key",
          integration_config={
              "fulfillment_mode": "manual",
              "activations_limit": 5,
              "duration_count": 1,
              "duration_interval": "Year",
          },
      )

      print(entitlement.id)
      ```

      ```bash cURL theme={null} theme={null}
      curl -X POST https://test.dodopayments.com/entitlements \
        -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Pro License (Manual)",
          "integration_type": "license_key",
          "integration_config": {
            "fulfillment_mode": "manual",
            "activations_limit": 5,
            "duration_count": 1,
            "duration_interval": "Year"
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Note>
  `fulfillment_mode` defaults to `auto`. Omitting it, or leaving an existing entitlement unchanged, keeps the automatic behavior. Only entitlements explicitly set to `manual` create pending grants.
</Note>

## Step 2 — Attach the Entitlement to a Product

Open the product you want to sell, expand **Advanced Settings → Entitlements & Credits**, and select the **License Key entitlement you set to Manual** in Step 1. A single product can deliver this license key alongside other entitlements on the same purchase.

<Frame>
  <img alt="Product entitlements panel with License Key selected" />
</Frame>

<Note>
  Fulfillment mode is a property of the **entitlement**, not the product. Because you set it to **Manual** in Step 1, every product this entitlement is attached to creates `Pending` license-key grants on purchase — there is nothing extra to configure here.
</Note>

<Tip>
  If you don't have a product yet, create one first (one-time or subscription). See the [One-time Payments Integration Guide](/developer-resources/integration-guide) for selling the product through checkout.
</Tip>

## Step 3 — Detect Pending Grants

When a customer buys the product, Dodo Payments creates a grant in `Pending` status with **no key attached** and fires an `entitlement_grant.created` webhook. This is your signal that a customer is waiting for a key.

### Listen for the webhook

Set up a webhook endpoint (Developer → Webhooks in the dashboard) and act on pending license-key grants. The implementation follows the [Standard Webhooks](https://standardwebhooks.com/) specification.

```typescript theme={null} theme={null}
import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id') || '',
    'webhook-signature': request.headers.get('webhook-signature') || '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
  };

  await webhook.verify(rawBody, headers);
  const event = JSON.parse(rawBody);

  // A customer bought a manual-mode license key and is waiting for it.
  if (
    event.type === 'entitlement_grant.created' &&
    event.data.integration_type === 'license_key' &&
    event.data.status === 'Pending'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}
```

The grant payload carries `integration_type: "license_key"`, so you can recognize a license-key grant without an extra lookup. See the [Entitlement Grant webhook reference](/developer-resources/webhooks/intents/entitlement-grant) for the full payload.

### Or poll the List Grants API

If you'd rather not rely on webhooks, list the grants for your License Key entitlement and filter by `status`. Every grant on a License Key entitlement is already a license-key grant, so no `integration_type` filter is needed:

<CodeGroup>
  ```typescript Node.js theme={null} theme={null}
  const pending = await client.entitlements.grants.list('ent_license_key_id', {
    status: 'Pending',
  });

  for (const grant of pending.items) {
    console.log(`Grant ${grant.id} for customer ${grant.customer_id} needs a key`);
  }
  ```

  ```bash cURL theme={null} theme={null}
  curl -G https://test.dodopayments.com/entitlements/ent_license_key_id/grants \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
    --data-urlencode "status=Pending"
  ```
</CodeGroup>

## Step 4 — Deliver the Key

Obtain the key value from your own system, then submit it with the [Fulfill License Key Grant](/api-reference/entitlements/fulfill-license-key) endpoint. This requires your secret API key (Editor permission); it is **not** one of the public license endpoints.

<CodeGroup>
  ```typescript Node.js theme={null} theme={null}
  async function fulfill(grantId: string, key: string) {
    const res = await fetch(
      `https://test.dodopayments.com/grants/${grantId}/license-key`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
        },
        body: JSON.stringify({
          key,
          // Optional — fall back to the entitlement config when omitted
          activations_limit: 5,
          expires_at: '2027-05-01T00:00:00Z',
        }),
      },
    );

    if (!res.ok) {
      // See the status code table below for handling
      throw new Error(`Fulfillment failed: ${res.status}`);
    }

    return res.json(); // updated grant, now status: "Delivered"
  }
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST https://test.dodopayments.com/grants/grant_8VbC6JDZ/license-key \
    -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "activations_limit": 5,
      "expires_at": "2027-05-01T00:00:00Z"
    }'
  ```
</CodeGroup>

### Request fields

<ParamField type="string">
  The license key string to deliver to the customer. Whitespace is trimmed; an empty or whitespace-only value is rejected.
</ParamField>

<ParamField type="integer">
  Per-key activation limit. Falls back to the entitlement config when omitted.
</ParamField>

<ParamField type="string">
  Per-key expiry (ISO 8601). Falls back to the entitlement config's duration when omitted. For subscription-issued grants, validity remains tied to the subscription regardless.
</ParamField>

On success the grant moves to `Delivered`, the customer is sent the key automatically (the same email they'd receive under auto fulfillment), and the `license_key.created` and `entitlement_grant.delivered` webhook events fire.

The customer receives an email with the license key, the product, activation limit, expiry, and your activation instructions:

<Frame>
  <img alt="Customer license key email showing the key, product, activation limit, expiry, and activation instructions" />
</Frame>

<Check>
  You do not need to email the key yourself — delivery happens automatically when the grant is fulfilled.
</Check>

## Step 5 — Handle Errors and Retries

The endpoint validates the grant before delivering anything. Handle these responses:

| Status | Meaning                                                                                                       | What to do                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `200`  | Key delivered, grant is now `Delivered`.                                                                      | Done.                                                                               |
| `400`  | Not a license-key grant, or the key is empty/whitespace.                                                      | Fix the request; do not retry as-is.                                                |
| `404`  | No grant with that ID for your business.                                                                      | Verify the `grant_id`.                                                              |
| `409`  | Grant not awaiting fulfillment (already delivered or already has a key), **or** the key value already exists. | If already delivered, treat as success. If a duplicate key, supply a different key. |
| `422`  | Request body failed validation (e.g. `activations_limit < 1`).                                                | Correct the field and retry.                                                        |

<Warning>
  Fulfillment is safe to retry on transient errors (timeouts, `5xx`). Each grant can be fulfilled only once, so a retry after a successful-but-unacknowledged call returns `409` rather than issuing a second key or sending a duplicate email. Use the grant `id` as your idempotency key.
</Warning>

## Verify the Flow

1. Buy the product in test mode (see the [checkout guides](/developer-resources/integration-guide)).
2. Confirm your webhook received `entitlement_grant.created` with `status: "Pending"` and `integration_type: "license_key"`, or that the grant appears in the List Grants response with those filters.
3. Call the fulfill endpoint with a test key.
4. Confirm the response shows `status: "Delivered"` with a populated `license_key`, the customer receives the key email, and `entitlement_grant.delivered` fires.

<Check>
  Once delivered, the customer can [activate and validate](/features/license-keys#activation-validation-deactivation) the key against the public license endpoints exactly like an auto-generated key.
</Check>

## Related API Reference

<CardGroup>
  <Card title="Create Entitlement" icon="plus" href="/api-reference/entitlements/create-entitlement">
    Create the License Key entitlement with `fulfillment_mode: manual`.
  </Card>

  <Card title="List Grants" icon="users" href="/api-reference/entitlements/list-grants">
    Filter by `status` and `customer_id` to find pending grants.
  </Card>

  <Card title="Fulfill License Key Grant" icon="code" href="/api-reference/entitlements/fulfill-license-key">
    Deliver the key value and transition the grant to delivered.
  </Card>

  <Card title="Entitlement Grant Webhooks" icon="webhook" href="/developer-resources/webhooks/intents/entitlement-grant">
    The `entitlement_grant.*` events that signal pending and delivered grants.
  </Card>
</CardGroup>


# MCP Server
Source: https://docs.dodopayments.com/developer-resources/mcp-server

Enable AI assistants to interact with the Dodo Payments API through Code Mode—a high-performance architecture for seamless payment operations and subscription management.

## Overview

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and APIs. The Dodo Payments MCP Server provides AI assistants like Claude, Cursor, and other MCP-compatible clients with structured access to your payment infrastructure.

The Dodo Payments MCP Server uses the **Code Mode** architecture. Instead of exposing hundreds of individual tools for every API endpoint, Code Mode enables AI agents to write and execute TypeScript code against the Dodo Payments SDK in an isolated sandbox environment.

### Key capabilities

* **Payment Operations**: Create, retrieve, and manage payments and refunds
* **Subscription Management**: Handle recurring billing, upgrades, and cancellations
* **Customer Administration**: Manage customer data and portal access
* **Product Catalog**: Create and update products, pricing, and discounts
* **License Management**: Activate, validate, and manage software licenses
* **Usage-Based Billing**: Track and bill for metered usage

## How Code Mode Works

The Dodo Payments MCP Server provides your AI agent with exactly two tools:

1. **Docs Search Tool**: Queries documentation about the Dodo Payments API and SDK to understand available operations and parameters.
2. **Code Execution Tool**: Writes TypeScript code against the SDK that executes in a secure sandbox environment.

This architecture allows agents to perform complex, multi-step operations in a single invocation. For example, an agent can list all active subscriptions, filter them based on specific criteria, and apply a discount to each—all within one script.

<Tip>
  Using Code Mode, agents can chain multiple API calls, handle conditional logic, and perform calculations without requiring multiple round-trips to the LLM.
</Tip>

### Quick Setup

Connect to the Dodo Payments MCP Server in your AI client:

<Tabs>
  <Tab title="Agent Plugin (recommended)">
    The [Dodo Agent Plugin](/developer-resources/build-with-ai-coding-agents) installs both MCP servers and all seventeen skills in one step for Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro, and OpenCode. Gemini CLI gets the two MCP servers only, since it has no agent-skill primitive. See the [AI Coding Agents guide](/developer-resources/build-with-ai-coding-agents) for per-agent install commands.

    If your agent isn't in that list, use the tabs below to configure the MCP server directly.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to your Claude Desktop configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```

    Configuration file locations:

    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux**: `~/.config/Claude/claude_desktop_config.json`
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Run in your terminal:

    ```bash theme={null}
    claude mcp add dodopayments -- npx -y mcp-remote@latest https://mcp.dodopayments.com/sse
    ```
  </Tab>
</Tabs>

<Note>
  Requires Node.js 18 or higher. The remote server uses OAuth for authentication — you will be prompted to enter your API key and select your environment on first connection.
</Note>

## Dodo Knowledge MCP

In addition to the Dodo Payments MCP Server (for executing API operations), we provide **Dodo Knowledge MCP**—a semantic search server that gives AI assistants instant access to Dodo Payments documentation and knowledge base.

<Info>
  **Built with [ContextMCP.ai](https://contextmcp.ai)**: Dodo Knowledge MCP is powered by ContextMCP, enabling fast semantic search across our documentation using vector embeddings.
</Info>

### What is Dodo Knowledge MCP?

Dodo Knowledge MCP is a remote MCP server that provides:

* **Semantic Documentation Search**: Find relevant documentation using natural language queries.
* **Contextual Answers**: AI assistants get accurate, up-to-date information about Dodo Payments.
* **Zero Setup**: No API keys or local installation required—just connect and start querying.

### Quick Setup

Connect to Dodo Knowledge MCP in your AI client:

<Tabs>
  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "dodo-knowledge": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to your Claude Desktop configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "dodo-knowledge": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
        }
      }
    }
    ```

    Configuration file locations:

    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux**: `~/.config/Claude/claude_desktop_config.json`
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "dodo-knowledge": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Run in your terminal:

    ```bash theme={null}
    claude mcp add dodo-knowledge -- npx -y mcp-remote@latest https://knowledge.dodopayments.com/mcp
    ```
  </Tab>
</Tabs>

<Note>
  Requires Node.js 18 or higher. The `mcp-remote` package handles the connection to the remote MCP server.
</Note>

### Using Both MCP Servers Together

For the best AI-assisted development experience, we recommend using both MCP servers:

| Server                 | Purpose              | Use Case                                                           |
| ---------------------- | -------------------- | ------------------------------------------------------------------ |
| **Dodo Knowledge MCP** | Documentation search | "How do I handle webhooks?", "What payment methods are supported?" |
| **Dodo Payments MCP**  | API operations       | Create payments, manage subscriptions, handle refunds              |

```json theme={null}
{
  "mcpServers": {
    "dodo-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"]
    },
    "dodopayments": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
    }
  }
}
```

<Tip>
  With both servers configured, your AI assistant can first search documentation to understand how to implement a feature, then execute the actual API calls—all in a single conversation.
</Tip>

### Troubleshooting Knowledge MCP

If you encounter connection issues:

1. **Clear MCP authentication cache**: `rm -rf ~/.mcp-auth`
2. **Restart your client application**
3. **Check client logs** for error messages
4. **Verify Node.js version**: Requires Node.js 18+

<Card title="Knowledge MCP Server" icon="book-open" href="https://knowledge.dodopayments.com">
  Access the Dodo Knowledge MCP configuration page
</Card>

## Installation

Choose the installation method that best fits your workflow.

### Remote MCP Server (Recommended)

Access the hosted MCP server without any local setup or installation. This is the fastest way to get started.

<Frame>
  <iframe title="Using Dodo Payment's Remote MCP Server" />
</Frame>

<Steps>
  <Step title="Access the remote server">
    Navigate to [https://mcp.dodopayments.com](https://mcp.dodopayments.com) in your browser.
  </Step>

  <Step title="Configure your MCP client">
    Copy the provided JSON configuration for your specific client. For Cursor or Claude Desktop, add this to your MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments_api": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```
  </Step>

  <Step title="Authenticate and configure">
    The OAuth flow will prompt you to:

    * Enter your Dodo Payments API key
    * Select your environment (test or live)
    * Choose your MCP client type

    <Warning>
      Keep your API key secure. Use test mode keys during development.
    </Warning>
  </Step>

  <Step title="Complete setup">
    Click **Login and Approve** to authorize the connection.

    <Check>
      Once connected, your AI assistant can interact with the Dodo Payments API on your behalf.
    </Check>
  </Step>
</Steps>

### NPM Package

Install and run the MCP server locally using NPM.

<Tabs>
  <Tab title="NPX (No Installation)">
    ```bash theme={null}
    # Set your environment variables
    export DODO_PAYMENTS_API_KEY="dodo_test_..."
    export DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key"
    export DODO_PAYMENTS_ENVIRONMENT="live_mode"

    # Run the latest version
    npx -y dodopayments-mcp@latest
    ```
  </Tab>

  <Tab title="MCP Client Configuration">
    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments_api": {
          "command": "npx",
          "args": ["-y", "dodopayments-mcp@latest"],
          "env": {
            "DODO_PAYMENTS_API_KEY": "dodo_test_...",
            "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key",
            "DODO_PAYMENTS_ENVIRONMENT": "live_mode"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Use `@latest` to always pull the most recent version, or pin to a specific version like `@1.0.0` for stability.
</Tip>

### Docker

Run the MCP server in a containerized environment for consistent deployment.

<CodeGroup>
  ```bash Docker theme={null}
  # Pull the latest image
  docker pull ghcr.io/dodopayments/mcp:latest

  # Run the container
  docker run -e DODO_PAYMENTS_API_KEY="dodo_test_..." \
    -e DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
    -e DODO_PAYMENTS_ENVIRONMENT="live_mode" \
    ghcr.io/dodopayments/mcp:latest
  ```

  ```yaml Docker Compose theme={null}
  services:
    dodopayments-mcp:
      image: ghcr.io/dodopayments/mcp:latest
      environment:
        - DODO_PAYMENTS_API_KEY=dodo_test_...
        - DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key
        - DODO_PAYMENTS_ENVIRONMENT=live_mode
      restart: unless-stopped
  ```
</CodeGroup>

<Note>
  Docker images are available on [GitHub Container Registry](https://github.com/orgs/dodopayments/packages/container/package/mcp).
</Note>

## Client Configuration

Configure the Dodo Payments MCP server in your preferred AI client.

<Tabs>
  <Tab title="Cursor">
    Set up the Dodo Payments MCP server in Cursor to enable conversational access to your payments data.

    **One-Click Install**

    Use the button below to install the MCP server directly in Cursor:

    [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=dodopayments-mcp\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvZG9wYXltZW50cy1tY3AiXSwiZW52Ijp7IkRPRE9fUEFZTUVOVFNfQVBJX0tFWSI6IlNldCB5b3VyIERPRE9fUEFZTUVOVFNfQVBJX0tFWSBoZXJlLiIsIkRPRE9fUEFZTUVOVFNfV0VCSE9PS19LRVkiOiJTZXQgeW91ciBET0RPX1BBWU1FTlRTX1dFQkhPT0tfS0VZIGhlcmUuIn19)

    After clicking, set your environment variables in Cursor's `mcp.json` via **Cursor Settings** > **Tools & MCP** > **New MCP Server**.

    **Manual Configuration**

    <Steps>
      <Step title="Open Cursor settings">
        Navigate to **Cursor Settings** > **Features** > **Model Context Protocol** or press `Cmd/Ctrl + Shift + P` and search for "MCP Settings".
      </Step>

      <Step title="Edit configuration">
        Click **Edit Config** to open the `mcp_config.json` file.
      </Step>

      <Step title="Add Dodo Payments configuration">
        Choose one of the following configurations:

        **Remote Server (Recommended)**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
            }
          }
        }
        ```

        **Local NPX**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
                "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Save and restart">
        Save the configuration file and restart Cursor.

        <Check>
          Verify the connection by asking the AI assistant about your Dodo Payments data.
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    Set up the Dodo Payments MCP server in Claude Desktop to enable conversational access to your payments data.

    <Steps>
      <Step title="Locate configuration file">
        Find the Claude Desktop configuration file:

        * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
        * **Linux**: `~/.config/Claude/claude_desktop_config.json`
      </Step>

      <Step title="Edit configuration">
        Open the file in a text editor and add the Dodo Payments configuration:

        **Remote Server (Recommended)**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
            }
          }
        }
        ```

        **Local NPX**

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
                "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Restart Claude Desktop">
        Close and reopen Claude Desktop for the changes to take effect.

        <Tip>
          Look for the 🔌 icon in Claude Desktop to confirm the MCP server is connected.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    Set up the Dodo Payments MCP server in Claude Code CLI.

    Run the following command in your terminal:

    ```bash theme={null}
    claude mcp add --transport stdio dodopayments_api \
      --env DODO_PAYMENTS_API_KEY="dodo_test_..." \
      DODO_PAYMENTS_WEBHOOK_KEY="your_webhook_key" \
      -- npx -y dodopayments-mcp
    ```

    The configuration will be stored in your home directory's `.claude.json` file.

    <Tip>
      Claude Code automatically picks up environment variables from your shell, so you can also export them before running the command.
    </Tip>
  </Tab>

  <Tab title="VS Code">
    Set up the Dodo Payments MCP server in VS Code.

    **One-Click Install**

    [Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22dodopayments-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22dodopayments-mcp%22%5D%2C%22env%22%3A%7B%22DODO_PAYMENTS_API_KEY%22%3A%22Set%20your%20DODO_PAYMENTS_API_KEY%20here.%22%2C%22DODO_PAYMENTS_WEBHOOK_KEY%22%3A%22Set%20your%20DODO_PAYMENTS_WEBHOOK_KEY%20here.%22%7D%7D)

    After clicking, set your environment variables in VS Code's `mcp.json` via **Command Palette** > **MCP: Open User Configuration**.

    **Manual Configuration**

    <Steps>
      <Step title="Open MCP configuration">
        Open the Command Palette (`Cmd/Ctrl + Shift + P`) and search for "MCP: Open User Configuration".
      </Step>

      <Step title="Add server configuration">
        Add the Dodo Payments MCP server:

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
                "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Reload window">
        Reload VS Code (`Cmd/Ctrl + Shift + P` > "Reload Window") to activate the MCP server.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cline (VS Code)">
    Set up the Dodo Payments MCP server in Cline (VS Code) to enable conversational access to your payments data.

    <Steps>
      <Step title="Open Cline settings">
        Locate the Cline configuration file:

        * **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
        * **Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
        * **Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
      </Step>

      <Step title="Configure MCP server">
        Add the Dodo Payments MCP server configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
                "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Reload VS Code">
        Reload the VS Code window (`Cmd/Ctrl + Shift + P` > "Reload Window") to activate the MCP server connection.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Zed">
    Set up the Dodo Payments MCP server in Zed to enable conversational access to your payments data.

    <Steps>
      <Step title="Open Zed settings">
        Navigate to **Settings** > **Assistant** > **Model Context Protocol**.
      </Step>

      <Step title="Add server configuration">
        Add the following configuration:

        ```json theme={null}
        {
          "mcpServers": {
            "dodopayments": {
              "command": "npx",
              "args": ["-y", "dodopayments-mcp@latest"],
              "env": {
                "DODO_PAYMENTS_API_KEY": "dodo_test_...",
                "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Save and verify">
        Save the configuration. The MCP server should now be available in Zed's AI assistant.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Other Clients">
    Set up the Dodo Payments MCP server in other MCP-compatible clients.

    **Remote Server (Recommended)**

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```

    **Local NPX**

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments": {
          "command": "npx",
          "args": ["-y", "dodopayments-mcp@latest"],
          "env": {
            "DODO_PAYMENTS_API_KEY": "dodo_test_...",
            "DODO_PAYMENTS_WEBHOOK_KEY": "your_webhook_key"
          }
        }
      }
    }
    ```

    <Info>
      Visit [modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients) for a complete list of MCP-compatible clients and their configuration methods.
    </Info>
  </Tab>
</Tabs>

## Environment Variables

Configure the MCP server behavior using environment variables.

| Variable                    | Description                       | Required |
| --------------------------- | --------------------------------- | -------- |
| `DODO_PAYMENTS_API_KEY`     | Your Dodo Payments API key        | Yes      |
| `DODO_PAYMENTS_WEBHOOK_KEY` | Your webhook signing key          | No       |
| `DODO_PAYMENTS_ENVIRONMENT` | Set to `live_mode` for production | No       |

## Running Remotely

Deploy the MCP server as a remote HTTP server for web-based clients or agentic workflows.

```bash theme={null}
# Start as remote server
npx -y dodopayments-mcp --transport=http

# Specify a custom port
npx -y dodopayments-mcp --transport=http --port=3000
```

### Remote Server Configuration

Once deployed, clients can connect using the server URL:

```json theme={null}
{
  "mcpServers": {
    "dodopayments_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}
```

### Authorization Headers

The remote server accepts authentication via the following headers:

| Header                    | Description                 |
| ------------------------- | --------------------------- |
| `Authorization`           | Bearer token authentication |
| `x-dodo-payments-api-key` | Direct API key header       |

## Security Best Practices

Code Mode provides inherent security by executing code in a sandboxed environment and injecting API keys server-side. Follow these additional best practices to protect your credentials.

<AccordionGroup>
  <Accordion title="API Key Management">
    **Never commit credentials to version control**

    Store API keys in environment variables or secure secret management systems.

    ```bash theme={null}
    # Use environment variables
    export DODO_PAYMENTS_API_KEY="dodo_test_..."

    # Use a .env file (add to .gitignore)
    echo "DODO_PAYMENTS_API_KEY=dodo_test_..." > .env
    ```

    **Rotate keys regularly**

    Generate new API keys periodically and revoke old ones through your Dodo Payments dashboard.

    **Use test keys for development**

    Always use test mode API keys during development to avoid affecting production data.
  </Accordion>

  <Accordion title="Access Control">
    **Implement authentication for remote servers**

    When deploying remotely, always require authentication via the `Authorization` header or `x-dodo-payments-api-key` header.

    **Monitor API usage**

    Track MCP server activity through your Dodo Payments dashboard and set up alerts for unusual patterns.
  </Accordion>

  <Accordion title="Network Security">
    **Use HTTPS for remote servers**

    Always deploy remote MCP servers behind HTTPS endpoints.

    **Implement rate limiting**

    Protect against abuse by implementing rate limits at both the MCP server and API levels.

    **Restrict network access**

    Configure firewall rules to limit which clients can connect to your MCP server.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection issues">
    **Verify your API key**

    Ensure your API key is correctly set and has the necessary permissions.

    ```bash theme={null}
    # Test your API key
    curl -H "Authorization: Bearer dodo_test_..." \
      https://test.dodopayments.com/payments
    ```

    **Check your network connection**

    Verify you can reach the Dodo Payments API endpoints.

    **Review client logs**

    Enable verbose logging in your MCP client to diagnose connection problems.
  </Accordion>

  <Accordion title="Authentication errors">
    **Confirm API key environment**

    Ensure you're using test keys with test endpoints and live keys with production endpoints.

    **Check environment variable**

    Verify `DODO_PAYMENTS_ENVIRONMENT` is set correctly (`live_mode` for production).

    **Regenerate credentials**

    If issues persist, generate a new API key through your dashboard.
  </Accordion>

  <Accordion title="Tool execution failures">
    **Validate input parameters**

    Ensure the AI assistant is providing correctly formatted parameters for each tool.

    **Review error messages**

    Check the error response from the API for specific guidance on what went wrong.

    **Test with API directly**

    Verify the operation works when calling the Dodo Payments API directly via curl or Postman.
  </Accordion>
</AccordionGroup>

## Why Code Mode

Traditional MCP implementations often suffer from "tool proliferation," where every API endpoint is exposed as a separate tool. Code Mode is a superior approach for several reasons:

### LLMs are better at writing code than calling tools

LLMs have been trained on millions of lines of real-world code, making them naturally proficient at writing scripts. In contrast, tool-calling is often based on synthetic examples.

<Info>
  "Making an LLM perform tasks with tool calling is like putting Shakespeare through a month-long class in Mandarin and then asking him to write a play in it." — [Cloudflare](https://blog.cloudflare.com/code-mode/)
</Info>

### Eliminates context window bloat

In a traditional approach, every tool definition consumes tokens before the conversation even starts. Exposing 50+ tools can easily eat 55K–100K+ tokens. Anthropic found that tool definitions could consume up to 134K tokens before optimization.

With Code Mode, only 2 tool definitions are loaded (\~1K tokens). The agent searches for the documentation it needs on-demand. Anthropic's Tool Search Tool preserved 95% of the context window, reducing overhead from 77K to 8.7K tokens.

### Reduces latency via programmatic orchestration

Traditional tool-calling requires a full model inference round-trip for every single operation. If a task requires 20 API calls, that's 20 round-trips. In Code Mode, the agent writes one script that executes all calls and returns only the final result.

Anthropic observed a 37% reduction in tokens and improved accuracy (knowledge retrieval improved from 25.6% to 28.5%) using this programmatic approach.

### More secure by design

Code Mode provides inherent security benefits:

* **No API keys in parameters**: API keys are injected server-side and never exposed in the tool parameters sent to the LLM.
* **Isolated sandbox**: Code runs in a secure environment with no access to the network or the host filesystem.
* **Controlled SDK**: Only authorized SDK methods are available to the agent.

### Scales to any API size

As an API grows, traditional MCP performance degrades because more tools must be loaded into the context. Code Mode remains constant with 2 tools regardless of the API's surface area. Cloudflare successfully collapsed over 2,500 API endpoints into just 2 tools and approximately 1,000 tokens of context.

<Info>
  For more details on the benefits of this architecture, see the engineering blogs from [Anthropic](https://www.anthropic.com/engineering/advanced-tool-use) and [Cloudflare](https://blog.cloudflare.com/code-mode/), and the [Programmatic Tool Calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) documentation from Claude.
</Info>

## Resources

<CardGroup>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore the complete Dodo Payments API documentation
  </Card>

  <Card title="MCP Protocol" icon="link" href="https://modelcontextprotocol.io">
    Learn more about the Model Context Protocol standard
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-typescript/tree/main/packages/mcp-server">
    View the MCP server source code and contribute
  </Card>

  <Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/dodopayments-mcp">
    Install the MCP server from NPM
  </Card>
</CardGroup>


# Mobile Integration Guide
Source: https://docs.dodopayments.com/developer-resources/mobile-integration

Unified guide for integrating Dodo Payments into Android, iOS, React Native and Flutter mobile applications.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="#integration-workflow">
    Get your mobile payment integration running in 4 simple steps
  </Card>

  <Card title="Platform Examples" icon="code" href="#choose-your-sdk">
    Complete code examples for Android, iOS, React Native, and Flutter
  </Card>
</CardGroup>

<Info>
  Dodo Payments ships an official checkout SDK for **Android, iOS, React Native,
  and Flutter**. Each one wraps the pattern documented below (open the checkout
  URL, capture the return, parse the result) behind a single typed `start(...)`
  call, with abandoned-session recovery built in. Reach for a manual WebView only
  if none of them fits your stack.
</Info>

## Prerequisites

Before integrating Dodo Payments into your mobile app, ensure you have:

* **Dodo Payments Account**: Active merchant account with API access
* **API Credentials**: API key and webhook secret key from your dashboard
* **Mobile App Project**: Android, iOS, React Native, or Flutter application
* **Backend Server**: To securely handle checkout session creation

## Integration Workflow

The mobile integration follows a secure 4-step process where your backend handles API calls and your mobile app manages the user experience.

<Steps>
  <Step title="Backend: Create Checkout Session">
    <Card title="Checkout Session API Docs" icon="book" href="/developer-resources/checkout-session">
      Learn how to create a checkout session in your backend using Node.js, Python, and more. See complete examples and parameter references in the dedicated <strong>Checkout Sessions API</strong> documentation.
    </Card>

    <Note>
      **Security**: Checkout sessions must be created on your backend server, never in the mobile app. This protects your API keys and ensures proper validation.
    </Note>
  </Step>

  <Step title="Mobile: Get Checkout URL">
    Your mobile app calls your backend to get the checkout URL. Authenticate
    this request with the signed-in user's own session token.

    <Tabs>
      <Tab title="iOS (Swift)">
        ```swift theme={null}
        func getCheckoutURL(productId: String, customerEmail: String, customerName: String) async throws -> String {
            let url = URL(string: "https://your-backend.com/api/create-checkout-session")!
            var request = URLRequest(url: url)
            request.httpMethod = "POST"
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
            request.setValue("Bearer \(userSessionToken)", forHTTPHeaderField: "Authorization")
            
            let requestData: [String: Any] = [
                "productId": productId,
                "customerEmail": customerEmail,
                "customerName": customerName
            ]
            request.httpBody = try JSONSerialization.data(withJSONObject: requestData)
            
            let (data, _) = try await URLSession.shared.data(for: request)
            let response = try JSONDecoder().decode(CheckoutResponse.self, from: data)
            return response.checkout_url
        }
        ```
      </Tab>

      <Tab title="Android (Kotlin)">
        ```kotlin theme={null}
        suspend fun getCheckoutURL(productId: String, customerEmail: String, customerName: String): String {
            val client = OkHttpClient()
            val requestBody = JSONObject().apply {
                put("productId", productId)
                put("customerEmail", customerEmail)
                put("customerName", customerName)
            }.toString().toRequestBody("application/json".toMediaType())
            
            val request = Request.Builder()
                .url("https://your-backend.com/api/create-checkout-session")
                .header("Authorization", "Bearer $userSessionToken")
                .post(requestBody)
                .build()
            
            val response = client.newCall(request).execute()
            val responseBody = response.body?.string()
            val jsonResponse = JSONObject(responseBody ?: "")
            return jsonResponse.getString("checkout_url")
        }
        ```
      </Tab>

      <Tab title="React Native (JavaScript)">
        ```javascript theme={null}
        const getCheckoutURL = async (productId, customerEmail, customerName) => {
          try {
            const response = await fetch('https://your-backend.com/api/create-checkout-session', {
              method: 'POST',
              headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${userSessionToken}`,
              },
              body: JSON.stringify({
                productId,
                customerEmail,
                customerName
              })
            });
            
            const data = await response.json();
            return data.checkout_url;
          } catch (error) {
            console.error('Failed to get checkout URL:', error);
            throw error;
          }
        };
        ```
      </Tab>

      <Tab title="Flutter (Dart)">
        ```dart theme={null}
        import 'dart:convert';
        import 'package:http/http.dart' as http;

        Future<String> getCheckoutUrl({
          required String productId,
          required String customerEmail,
          required String customerName,
        }) async {
          final response = await http.post(
            Uri.parse('https://your-backend.com/api/create-checkout-session'),
            headers: {
              'Content-Type': 'application/json',
              'Authorization': 'Bearer $userSessionToken',
            },
            body: jsonEncode({
              'productId': productId,
              'customerEmail': customerEmail,
              'customerName': customerName,
            }),
          );

          if (response.statusCode != 200) {
            throw Exception('Failed to get checkout URL: ${response.statusCode}');
          }
          return jsonDecode(response.body)['checkout_url'] as String;
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      **Security**: Mobile apps only communicate with your backend, never directly with Dodo Payments API.
    </Note>
  </Step>

  <Step title="Mobile: Open Checkout in Browser">
    Open the checkout URL in a secure in-app browser for payment processing.
    Or skip the manual setup entirely with the official checkout SDK for your
    platform.

    <Card title="Pick your mobile SDK" icon="box" href="#choose-your-sdk">
      Install steps and setup instructions for Android, iOS, React Native, and Flutter.
    </Card>
  </Step>

  <Step title="Backend: Handle Payment Completion">
    Process payment completion via webhooks and redirect URLs to confirm payment status.
  </Step>
</Steps>

## Choose Your SDK

Every mobile SDK exposes the same contract: one `start(...)` call opens Dodo's
hosted checkout in the platform's native browser surface and returns a typed
`CheckoutResult` whose `status` is `succeeded`, `failed`, `cancelled`,
`pending`, or `expired`. None of them holds an API key or calls the Dodo
Payments API, and all four support abandoned-session recovery.

<CardGroup>
  <Card title="Android" icon="android" href="/developer-resources/sdks/android">
    `com.dodopayments.api:checkout-android` opens a Chrome Custom Tab. Requires `minSdk` 23.
  </Card>

  <Card title="iOS" icon="apple" href="/developer-resources/sdks/ios">
    `dodopayments-mobile-sdk-ios` opens `SFSafariViewController`. Requires iOS 16+.
  </Card>

  <Card title="React Native" icon="react" href="/developer-resources/sdks/react-native">
    `@dodopayments/react-native-checkout`, a Turbo Module over both native cores. Requires React Native 0.76+.
  </Card>

  <Card title="Flutter" icon="layer-group" href="/developer-resources/sdks/flutter">
    `dodopayments_checkout`, a Pigeon channel over both native cores. Requires Flutter 3.44+.
  </Card>
</CardGroup>

<Warning>
  The `status` you get back is a UI hint, not proof of payment. Confirm every
  payment from your backend via the `payment.succeeded` / `subscription.active`
  webhook, or by retrieving the payment with your secret key.
</Warning>

### Registering a Callback URL Scheme

All four SDKs hand control back to your app through a custom URL scheme that
you choose, for example `myapp://checkout/return`. Register it once per
platform:

<Tabs>
  <Tab title="Android">
    ```kotlin android/app/build.gradle theme={null}
    android {
        defaultConfig {
            manifestPlaceholders["dodoCallbackScheme"] = "myapp"
        }
    }
    ```

    The SDK's own manifest already declares the redirect activity, so there is no
    manifest XML to add.
  </Tab>

  <Tab title="iOS">
    ```xml Info.plist theme={null}
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLName</key>
        <string>myapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>myapp</string>
        </array>
      </dict>
    </array>
    ```

    On iOS you must also forward incoming URLs into the SDK, because
    `SFSafariViewController` cannot catch its own return URL. See the
    [iOS](/developer-resources/sdks/ios) or
    [React Native](/developer-resources/sdks/react-native) page for the exact
    handler.
  </Tab>

  <Tab title="Expo">
    `@dodopayments/react-native-checkout` ships a config plugin that registers the
    scheme for both platforms at `prebuild`. Pass it a `scheme` option:

    ```json app.json theme={null}
    {
      "expo": {
        "scheme": "myapp",
        "plugins": [
          [
            "@dodopayments/react-native-checkout",
            { "scheme": "myappcheckout" }
          ]
        ]
      }
    }
    ```

    `scheme` must match `returnUrl` and must differ from `expo.scheme`, which Expo
    already registers on `MainActivity`. See the
    [React Native SDK](/developer-resources/sdks/react-native) page for details.

    If `android/app/build.gradle` is hand-maintained without a standard
    `defaultConfig { }` block, set the placeholder manually instead (see the
    Android tab).

    Works with development builds only, not Expo Go. Run
    `npx expo prebuild --clean` after editing `app.json`.
  </Tab>
</Tabs>

<Note>
  Prefer to build it yourself? Open the `checkout_url` in a WebView and intercept
  the navigation to your `return_url`, then read the `status` and `payment_id`
  query parameters. The SDKs above do this for you in the platform's real browser
  surface, which is why Apple Pay and Google Pay keep working.
</Note>

## Appearance Customization

Every SDK accepts an optional `customization` parameter on `start(...)` /
`CheckoutParams` that controls the native browser surface's appearance and
behavior — the toolbar, buttons, and presentation. This is separate from the
checkout page's own theme, which you configure server-side via
[`customization.theme_config`](/developer-resources/checkout-session) on the
checkout session.

Options are grouped by platform because Android's Custom Tab and iOS's
`SFSafariViewController` expose different native controls. All fields are
optional; omitting `customization` entirely uses each platform's default
appearance.

<AccordionGroup>
  <Accordion title="Android — Custom Tab">
    <ParamField type="Color">
      Toolbar background color.
    </ParamField>

    <ParamField type="Color">
      Navigation bar color.
    </ParamField>

    <ParamField type="Color">
      Divider color above the navigation bar.
    </ParamField>

    <ParamField type="'default' | 'back'">
      `default` shows the system "X" icon; `back` draws a back arrow instead.
    </ParamField>

    <ParamField type="'start' | 'end'">
      Which side of the toolbar the close button appears on.
    </ParamField>

    <ParamField type="boolean">
      Shows the toolbar's share icon.
    </ParamField>

    <ParamField type="boolean">
      Shows the page title under the URL in the toolbar.
    </ParamField>

    <ParamField type="boolean">
      Lets the toolbar auto-hide as the page scrolls.
    </ParamField>

    <ParamField type="boolean">
      Shows "Bookmark this page" in the overflow menu.
    </ParamField>

    <ParamField type="boolean">
      Shows "Download page" in the overflow menu.
    </ParamField>

    <ParamField type="'system' | 'light' | 'dark'">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>

  <Accordion title="iOS — SFSafariViewController">
    <ParamField type="'done' | 'close' | 'cancel'">
      Label or icon for the dismiss button.
    </ParamField>

    <ParamField type="'pageSheet' | 'fullScreen'">
      `pageSheet` presents as a card with swipe-to-dismiss; `fullScreen` covers the whole screen.
    </ParamField>

    <ParamField type="boolean">
      Lets the toolbar collapse on scroll. Only visible when `presentationStyle` is `fullScreen` — `pageSheet` keeps the bars pinned regardless of this setting.
    </ParamField>

    <ParamField type="'system' | 'light' | 'dark'">
      Forces light or dark appearance regardless of the device's system setting.
    </ParamField>
  </Accordion>
</AccordionGroup>

<Tabs>
  <Tab title="React Native">
    ```typescript theme={null}
    const result = await DodoCheckout.start({
      checkoutUrl,
      returnUrl: 'myapp://checkout/return',
      customization: {
        android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
        ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
      },
    });
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    final result = await DodoCheckout.instance.start(
      CheckoutParams(
        checkoutUrl: Uri.parse(checkoutUrl),
        returnUrl: Uri.parse('myapp://checkout/return'),
        customization: BrowserCustomization(
          android: AndroidBrowserOptions(
            toolbarColor: Color(0xFF6366F1),
            closeButtonStyle: CloseButtonStyle.back,
          ),
          ios: IosBrowserOptions(
            presentationStyle: PresentationStyle.fullScreen,
            colorScheme: BrowserColorScheme.dark,
          ),
        ),
      ),
    );
    ```
  </Tab>

  <Tab title="Android (Kotlin)">
    ```kotlin theme={null}
    val result = DodoCheckout.start(
        activity,
        CheckoutParams(
            checkoutUrl = checkoutUrl,
            returnUrl = "myapp://checkout/return",
            customization = BrowserCustomization(
                toolbarColor = Color.parseColor("#6366F1"),
                closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
            )
        )
    ) { event -> }
    ```
  </Tab>

  <Tab title="iOS (Swift)">
    ```swift theme={null}
    let result = try await DodoCheckout.start(
        checkoutUrl: checkoutUrl,
        returnUrl: URL(string: "myapp://checkout/return")!,
        customization: BrowserCustomization(
            presentationStyle: .fullScreen,
            colorScheme: .dark
        )
    )
    ```
  </Tab>
</Tabs>

## Best Practices

* **Security**: Never ship an API key in your app. Create checkout sessions on your backend and pass only the resulting `checkout_url` to the client.
* **Authority**: Treat `CheckoutResult.status` as a UI hint. Grant access only after your backend confirms the payment.
* **User Experience**: Show a loading state while your backend creates the session, and handle `cancelled` as a normal outcome rather than an error.
* **Testing**: Use test mode and test cards, and verify the return-URL round trip on a real device as well as a simulator.

## Troubleshooting

### Common Issues

* **Callback never arrives**: The scheme in `returnUrl` must match the one you registered. On Android that is the `dodoCallbackScheme` manifest placeholder; on iOS and React Native it is the `Info.plist` URL type.
* **Checkout returns to the browser instead of your app (iOS)**: You haven't forwarded the incoming URL. Call `DodoCheckout.handleOpenURL(url)` from `.onOpenURL`, `scene(_:openURLContexts:)`, or a React Native `Linking` listener.
* **`PLATFORM_ERROR` on Android**: Most often a scheme mismatch. It can also appear if your `MainActivity` sets `android:taskAffinity=""` (the stock `flutter create` default), which lets some OEM builds lose the in-flight checkout.
* **`ALREADY_IN_PROGRESS`**: A checkout is still open. Await or dismiss the previous one before starting another.
* **Build fails with an unresolved placeholder**: You added the Android SDK but never set `manifestPlaceholders["dodoCallbackScheme"]`.
* **Payment succeeded but access wasn't granted**: Expected if you're keying off the mobile result. Grant access from the `payment.succeeded` / `subscription.active` webhook instead.

## Additional Resources

* [Payment Integration Guide](/developer-resources/integration-guide)
* [Webhook Documentation](/developer-resources/webhooks/intents/webhook-events-guide)
* [Testing Process](/miscellaneous/testing-process)
* [Technical FAQs](/miscellaneous/faq)

<Check>
  For questions or support, contact <a href="mailto:support@dodopayments.com">[support@dodopayments.com](mailto:support@dodopayments.com)</a>.
</Check>


# Next.js Minimal Boilerplate
Source: https://docs.dodopayments.com/developer-resources/nextjs-boilerplate

Get started quickly with our minimal Next.js boilerplate for integrating Dodo Payments into your Next.js application

## Overview

The Next.js minimal boilerplate provides a ready-to-use starting point for integrating Dodo Payments with your Next.js application. This template includes checkout sessions, webhook handling, customer portal, and modern UI components to help you start accepting payments quickly.

<Info>
  This boilerplate uses Next.js 16 App Router with TypeScript, Tailwind CSS 4, and the `@dodopayments/nextjs` adapter.
</Info>

### Features

* **Quick Setup** - Get started in under 5 minutes
* **Payment Integration** - Pre-configured checkout flow using `@dodopayments/nextjs`
* **Modern UI** - Clean, dark-themed pricing page with Tailwind CSS
* **Webhook Handler** - Ready-to-use webhook endpoint for payment events
* **Customer Portal** - One-click subscription management
* **TypeScript** - Fully typed with minimal, focused types
* **Pre-filled Checkout** - Demonstrates passing customer data to improve UX

## Prerequisites

Before you begin, make sure you have:

* **Node.js 20.9+** (required for Next.js 16)
* **Dodo Payments account** (to access API and Webhook Keys from dashboard)

## Quick Start

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate.git
    cd dodo-nextjs-minimal-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Get API Credentials">
    Sign up at [Dodo Payments](https://dodopayments.com/) and get your credentials from the dashboard:

    * **API Key:** [Dashboard → Developer → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Dashboard → Developer → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Make sure you're in **Test Mode** while developing!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in the root directory:

    ```bash theme={null}
    cp .env.example .env
    ```

    Update the values with your Dodo Payments credentials:

    ```env theme={null}
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
    DODO_PAYMENTS_RETURN_URL=http://localhost:3000
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Never commit your `.env` file to version control. It's already included in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Update `src/lib/products.ts` with your actual product IDs from Dodo Payments:

    ```typescript theme={null}
    export const products: Product[] = [
      {
        product_id: "pdt_001", // Replace with your product ID
        name: "Basic Plan",
        description: "Get access to basic features and support",
        price: 9999, // in cents
        features: [
          "Access to basic features",
          "Email support",
          "1 Team member",
          "Basic analytics",
        ],
      },
      // ... add more products
    ];
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    npm run dev
    ```

    Open [http://localhost:3000](http://localhost:3000) to see your pricing page!
  </Step>
</Steps>

## Project Structure

```text theme={null}
src/
├── app/
│   ├── api/
│   │   ├── checkout/          # Checkout session handler
│   │   ├── customer-portal/   # Customer portal redirect
│   │   └── webhook/           # Webhook event handler
│   ├── components/
│   │   ├── Footer.tsx         # Reusable footer
│   │   ├── Header.tsx         # Navigation header
│   │   └── ProductCard.tsx    # Product pricing card
│   ├── globals.css            # Global styles
│   ├── layout.tsx             # Root layout
│   └── page.tsx               # Pricing page (home)
└── lib/
    └── products.ts            # Product definitions
```

## Customization

### Update Product Information

Edit `src/lib/products.ts` to modify:

* Product IDs (from your Dodo dashboard)
* Pricing
* Features
* Descriptions

### Pre-fill Customer Data

In `src/app/components/ProductCard.tsx`, replace the hardcoded values with your actual user data:

```typescript theme={null}
customer: {
  name: "John Doe",
  email: "john@example.com",
},
```

### Update Customer Portal

In `src/app/components/Header.tsx`, replace the hardcoded customer ID:

```typescript theme={null}
const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID
```

You can complete a test purchase to get the customer ID for testing.

## Webhook Events

The boilerplate demonstrates handling two webhook events in `src/app/api/webhook/route.ts`:

* `onSubscriptionActive` - Triggered when a subscription becomes active
* `onPaymentSucceeded` - Triggered when a payment is successful

Add your business logic inside these handlers:

```typescript theme={null}
onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},
```

Add more webhook events as needed.

For local development, you can use tools like [ngrok](https://ngrok.com/) to create a secure tunnel to your local server and use it as your webhook URL.

## Deployment

### Build for Production

```bash theme={null}
npm run build
npm start
```

### Deploy to Vercel

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate)

Don't forget to add your environment variables in the Vercel dashboard!

### Update Webhook URL

After deploying, update your webhook URL in the [Dodo Payments Dashboard](https://app.dodopayments.com/developer/webhooks):

```
https://example.com/api/webhook
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Module not found or build errors">
    Delete `node_modules` and reinstall dependencies:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="Checkout redirect fails">
    **Common causes:**

    * Invalid product ID - verify it exists in your Dodo dashboard
    * Wrong API key or environment setting in `.env`
    * Check browser console and terminal for errors
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    For local testing, use [ngrok](https://ngrok.com) to expose your server:

    ```bash theme={null}
    ngrok http 3000
    ```

    Update the webhook URL in your [Dodo dashboard](https://app.dodopayments.com/developer/webhooks) to the ngrok URL. Remember to update your .env file with the correct webhook verification key.
  </Accordion>

  <Accordion title="Customer portal link doesn't work">
    Replace the hardcoded `CUSTOMER_ID` in `src/app/components/Header.tsx` with an actual customer ID from your Dodo dashboard.

    Or integrate your authentication system and database to fetch the customer ID dynamically.
  </Accordion>
</AccordionGroup>

## Learn More

* [Dodo Payments Documentation](https://docs.dodopayments.com/)
* [Checkout Sessions Documentation](https://docs.dodopayments.com/developer-resources/checkout-session)
* [Webhooks Documentation](https://docs.dodopayments.com/developer-resources/webhooks)

## Support

Need help with the boilerplate?

* Join our [Discord community](https://discord.gg/bYqAp4ayYh) for questions and discussions
* Check the [GitHub repository](https://github.com/dodopayments/dodo-nextjs-minimal-boilerplate) for issues and updates
* Contact our [support team](mailto:support@dodopayments.com) for assistance


# Overlay Checkout
Source: https://docs.dodopayments.com/developer-resources/overlay-checkout

A modern TypeScript library for embedding Dodo Payments overlay checkout and listening to checkout events in real-time.

## Overview

The Dodo Payments Checkout SDK provides a seamless way to integrate our payment overlay into your web application. Built with TypeScript and modern web standards, it offers a robust solution for handling payments with real-time event handling and customizable themes.

<Frame>
  <img alt="Overlay Checkout Cover Image" />
</Frame>

## Demo

<Card title="Interactive Demo" icon="play" href="https://atlas.dodopayments.com/pricing">
  See the overlay checkout in action with our live demo.
</Card>

## Quick Start

Get started with the Dodo Payments Checkout SDK in just a few lines of code:

```typescript theme={null}
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
```

<Tip>
  Get your checkout URL from the [create checkout session API](/api-reference/checkout-sessions/create).
</Tip>

## Step-by-Step Integration Guide

<Steps>
  <Step title="Install the SDK">
    Install the Dodo Payments Checkout SDK using your preferred package manager:

    <CodeGroup>
      ```bash npm theme={null}
      npm install dodopayments-checkout
      ```

      ```bash yarn theme={null}
      yarn add dodopayments-checkout
      ```

      ```bash pnpm theme={null}
      pnpm add dodopayments-checkout
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the SDK">
    Initialize the SDK in your application, typically in your main component or app entry point:

    ```typescript theme={null}
    import { DodoPayments } from "dodopayments-checkout";

    DodoPayments.Initialize({
      mode: "test", // Change to 'live' for production
      displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
      onEvent: (event) => {
        console.log("Checkout event:", event);
        
        // Handle different events
        switch (event.event_type) {
          case "checkout.opened":
            // Checkout overlay has been opened
            break;
          case "checkout.closed":
            // Checkout has been closed
            break;
          case "checkout.error":
            // Handle errors
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
    ```

    <Warning>
      Always initialize the SDK before attempting to open the checkout. Initialization should happen once when your application loads.
    </Warning>
  </Step>

  <Step title="Create a Checkout Button Component">
    Create a component that opens the checkout overlay:

    ```typescript theme={null}
    // components/CheckoutButton.tsx
    "use client";

    import { Button } from "@/components/ui/button";
    import { DodoPayments } from "dodopayments-checkout";
    import { useEffect, useState } from "react";

    export function CheckoutButton() {
      const [isLoading, setIsLoading] = useState(false);

      useEffect(() => {
        // Initialize the SDK
        DodoPayments.Initialize({
          mode: "test",
          displayType: "overlay",
          onEvent: (event) => {
            switch (event.event_type) {
              case "checkout.opened":
                setIsLoading(false);
                break;
              case "checkout.error":
                setIsLoading(false);
                console.error("Checkout error:", event.data?.message);
                break;
            }
          },
        });
      }, []);

      const handleCheckout = async () => {
        try {
          setIsLoading(true);
          await DodoPayments.Checkout.open({
            checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
          });
        } catch (error) {
          console.error("Failed to open checkout:", error);
          setIsLoading(false);
        }
      };

      return (
        <Button 
          onClick={handleCheckout}
          disabled={isLoading}
        >
          {isLoading ? "Loading..." : "Checkout Now"}
        </Button>
      );
    }
    ```
  </Step>

  <Step title="Add Checkout to Your Page">
    Use the checkout button component in your application:

    ```typescript theme={null}
    // app/page.tsx
    import { CheckoutButton } from "@/components/CheckoutButton";

    export default function Home() {
      return (
        <main className="flex min-h-screen flex-col items-center justify-center p-24">
          <h1>Welcome to Our Store</h1>
          <CheckoutButton />
        </main>
      );
    }
    ```
  </Step>

  <Step title="Handle Success and Failure Pages">
    Create pages to handle checkout redirects:

    ```typescript theme={null}
    // app/success/page.tsx
    export default function SuccessPage() {
      return (
        <div className="flex min-h-screen flex-col items-center justify-center">
          <h1>Payment Successful!</h1>
          <p>Thank you for your purchase.</p>
        </div>
      );
    }

    // app/failure/page.tsx
    export default function FailurePage() {
      return (
        <div className="flex min-h-screen flex-col items-center justify-center">
          <h1>Payment Failed</h1>
          <p>Please try again or contact support.</p>
        </div>
      );
    }
    ```
  </Step>

  <Step title="Test Your Integration">
    1. Start your development server:

    ```bash theme={null}
    npm run dev
    ```

    2. Test the checkout flow:
       * Click the checkout button
       * Verify the overlay appears
       * Test the payment flow using test credentials
       * Confirm redirects work correctly

    <Check>
      You should see checkout events logged in your browser console.
    </Check>
  </Step>

  <Step title="Go Live">
    When you're ready for production:

    1. Change the mode to `'live'`:

    ```typescript theme={null}
    DodoPayments.Initialize({
      mode: "live",
      displayType: "overlay",
      onEvent: (event) => {
        console.log("Checkout event:", event);
      }
    });
    ```

    2. Update your checkout URLs to use live checkout sessions from your backend
    3. Test the complete flow in production
    4. Monitor events and errors
  </Step>
</Steps>

## API Reference

### Configuration

#### Initialize Options

```typescript theme={null}
interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}
```

| Option        | Type                    | Required | Description                                                                              |
| ------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `mode`        | `"test" \| "live"`      | Yes      | Environment mode: `'test'` for development, `'live'` for production                      |
| `displayType` | `"overlay" \| "inline"` | No       | Display type: `'overlay'` for modal checkout (default), `'inline'` for embedded checkout |
| `onEvent`     | `function`              | Yes      | Callback function for handling checkout events                                           |

#### Checkout Options

```typescript theme={null}
interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}
```

| Option                      | Type      | Required | Description                                                                                                                                      |
| --------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `checkoutUrl`               | `string`  | Yes      | Checkout session URL from the [create checkout session API](/api-reference/checkout-sessions/create)                                             |
| `options.showTimer`         | `boolean` | No       | Show or hide the checkout timer. Defaults to `true`. When disabled, you will receive the `checkout.link_expired` event when the session expires. |
| `options.showSecurityBadge` | `boolean` | No       | Show or hide the security badge. Defaults to `true`.                                                                                             |

### Methods

#### Open Checkout

Opens the checkout overlay with the specified checkout session URL.

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
```

You can also pass additional options to customize the checkout behavior:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
  },
});
```

#### Close Checkout

Programmatically closes the checkout overlay.

```typescript theme={null}
DodoPayments.Checkout.close();
```

#### Check Status

Returns whether the checkout overlay is currently open.

```typescript theme={null}
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean
```

### Events

The SDK provides real-time events that you can listen to through the `onEvent` callback:

```typescript theme={null}
DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
    }
  }
});
```

| Event Type                            | Description                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `checkout.opened`                     | Checkout overlay has been opened                                                           |
| `checkout.form_ready`                 | Checkout form is ready to receive user input. Useful for hiding loading states.            |
| `checkout.payment_page_opened`        | Payment page has been displayed                                                            |
| `checkout.customer_details_submitted` | Customer and billing details have been submitted                                           |
| `checkout.closed`                     | Checkout overlay has been closed                                                           |
| `checkout.redirect`                   | Checkout will perform a redirect                                                           |
| `checkout.error`                      | An error occurred during checkout                                                          |
| `checkout.link_expired`               | Fired when the checkout session expires. Only received when `showTimer` is set to `false`. |

## Implementation Options

### Package Manager Installation

Install via npm, yarn, or pnpm as shown in the [Step-by-Step Integration Guide](#step-by-step-integration-guide).

### CDN Implementation

For quick integration without a build step, you can use our CDN:

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            displayType: "overlay",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <button onclick="openCheckout()">Checkout Now</button>

    <script>
        function openCheckout() {
            DodoPaymentsCheckout.DodoPayments.Checkout.open({
                checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>
```

### Theme Customization

You can customize the checkout appearance by passing a `themeConfig` object in the `options` parameter when opening checkout. The theme configuration supports both light and dark modes, allowing you to customize colors, borders, text, buttons, and border radius.

<Warning>
  The client-side `themeConfig` option is **deprecated** and will be removed in the next major version of the Checkout SDK (v2.0.0). Passing it logs a deprecation warning in the browser console. Configure your theme when creating the checkout session via the API instead, using the `customization.theme_config` parameter — see [Checkout Theme Customization](/features/checkout#checkout-theme-customization) — or visually on the [Design page](/features/design) in the dashboard. Session-configured themes apply to overlay, inline, and hosted checkout alike.
</Warning>

<Info>
  This section covers the deprecated **client-side** theme configuration using the Checkout SDK. The recommended approach is to configure themes **server-side** when creating a checkout session via the API using the `theme_config` parameter. See [Checkout Theme Customization](/features/checkout#checkout-theme-customization) for API-level configuration, or use the [Design page](/features/design) in the dashboard to configure themes visually with live preview.
</Info>

#### Basic Theme Configuration

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});
```

#### Complete Theme Configuration

All available theme properties:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});
```

#### Light Mode Only

If you only want to customize the light theme:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});
```

#### Dark Mode Only

If you only want to customize the dark theme:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});
```

#### Partial Theme Override

You can override only specific properties. The checkout will use default values for properties you don't specify:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});
```

#### Theme Configuration with Other Options

You can combine theme configuration with other checkout options:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});
```

#### TypeScript Types

For TypeScript users, all theme configuration types are exported:

```typescript theme={null}
import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};
```

## Error Handling

The SDK provides detailed error information through the event system. Always implement proper error handling in your `onEvent` callback:

```typescript theme={null}
DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});
```

<Warning>
  Always handle the `checkout.error` event to provide a good user experience when errors occur.
</Warning>

## Best Practices

1. **Initialize once**: Initialize the SDK once when your application loads, not on every checkout attempt
2. **Error handling**: Always implement proper error handling in your event callback
3. **Test mode**: Use `test` mode during development and switch to `live` only when ready for production
4. **Event handling**: Handle all relevant events for a complete user experience
5. **Valid URLs**: Always use valid checkout URLs from the create checkout session API
6. **TypeScript**: Use TypeScript for better type safety and developer experience
7. **Loading states**: Show loading states while the checkout is opening to improve UX
8. **Timer management**: Disable the timer (`showTimer: false`) if you want to handle session expiration manually

## Troubleshooting

<AccordionGroup>
  <Accordion title="Checkout not opening">
    **Possible causes:**

    * SDK not initialized before calling `open()`
    * Invalid checkout URL
    * JavaScript errors in console
    * Network connectivity issues

    **Solutions:**

    * Verify SDK initialization happens before opening checkout
    * Check for console errors
    * Ensure checkout URL is valid and from the create checkout session API
    * Verify network connectivity
  </Accordion>

  <Accordion title="Events not firing">
    **Possible causes:**

    * Event handler not properly set up
    * JavaScript errors preventing event propagation
    * SDK not initialized correctly

    **Solutions:**

    * Confirm event handler is properly configured in `Initialize()`
    * Check browser console for JavaScript errors
    * Verify SDK initialization completed successfully
    * Test with a simple event handler first
  </Accordion>

  <Accordion title="Styling issues">
    **Possible causes:**

    * CSS conflicts with your application styles
    * Theme settings not applied correctly
    * Responsive design issues

    **Solutions:**

    * Check for CSS conflicts in browser DevTools
    * Verify theme settings are correct
    * Test on different screen sizes
    * Ensure no z-index conflicts with overlay
  </Accordion>
</AccordionGroup>

## Enabling Digital Wallets

For detailed information about setting up Google Pay and other digital wallets, see the <a href="/features/payment-methods/digital-wallets">Digital Wallets</a> page.

<Note>
  Apple Pay is not yet supported in overlay checkout. Support for Apple Pay is coming soon.
</Note>

## Browser Support

The Dodo Payments Checkout SDK supports the following browsers:

* Chrome (latest)
* Firefox (latest)
* Safari (latest)
* Edge (latest)
* IE11+

## Overlay vs Inline Checkout

Choose the right checkout type for your use case:

| Feature               | Overlay Checkout                  | Inline Checkout                              |
| --------------------- | --------------------------------- | -------------------------------------------- |
| Integration depth     | Modal on top of page              | Fully embedded in page                       |
| Layout control        | Limited                           | Full control                                 |
| Branding              | Separate from page                | Seamless                                     |
| Implementation effort | Lower                             | Higher                                       |
| Best for              | Quick integration, existing pages | Custom checkout pages, high-conversion flows |

<Tip>
  Use **overlay checkout** for faster integration with minimal changes to your existing pages. Use **inline checkout** when you want maximum control over the checkout experience and seamless branding.
</Tip>

## Related Resources

<CardGroup>
  <Card title="Inline Checkout" icon="credit-card" href="/developer-resources/inline-checkout">
    Embed checkout directly into your page for fully integrated experiences.
  </Card>

  <Card title="Checkout Sessions API" icon="code" href="/api-reference/checkout-sessions/create">
    Create checkout sessions to power your checkout experiences.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Handle payment events server-side with webhooks.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/integration-guide">
    Complete guide to integrating Dodo Payments.
  </Card>
</CardGroup>

For more help, visit our [Discord community](https://discord.gg/bYqAp4ayYh) or contact our developer support team.


# Remix Adaptor
Source: https://docs.dodopayments.com/developer-resources/remix-adaptor

Learn how to integrate Dodo Payments with your Remix App Router project using our Remix Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your Remix app.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/remix
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret
    DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using the Remix App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your Remix app. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript Remix Route Handler expandable theme={null}
      // app/routes/api.checkout.tsx
      import { Checkout } from "@dodopayments/remix";
      import type { LoaderFunctionArgs } from "@remix-run/node";

      const checkoutGetHandler = Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "static"
      });

      const checkoutPostHandler = Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "dynamic", // for dynamic checkout
      });

      const checkoutSessionHandler = Checkout({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "session", // for checkout sessions
      });

      export const loader = ({ request }: LoaderFunctionArgs) => checkoutGetHandler(request);
      export const action = ({ request }: LoaderFunctionArgs) => {
          // You can conditionally route to different handlers based on your needs
          // For checkout sessions, use checkoutSessionHandler(request)
          return checkoutPostHandler(request);
      };
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript Remix Route Handler expandable theme={null}
      // app/routes/api.customer-portal.tsx
      import { CustomerPortal } from "@dodopayments/remix";
      import type { LoaderFunctionArgs } from "@remix-run/node";

      const customerPortalHandler = CustomerPortal({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT
      });

      export const loader = ({ request }: LoaderFunctionArgs) => customerPortalHandler(request);
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your Remix app.
    </Info>

    <CodeGroup>
      ```typescript Remix Route Handler expandable theme={null}
      // app/routes/api.webhook.tsx
      import { Webhooks } from "@dodopayments/remix";
      import type { LoaderFunctionArgs } from "@remix-run/node";

      const webhookHandler = Webhooks({
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET,
      onPayload: async (payload) => {
          //Handle Payload Here
          console.log(payload)
      }
      });
      export const action = ({ request }: LoaderFunctionArgs) => webhookHandler(request);
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your Remix application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```

You are an expert Remix developer assistant. Your task is to guide a user through integrating the @dodopayments/remix adapter into their existing Remix project.

The @dodopayments/remix adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Remix route handlers.

First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):

npm install @dodopayments/remix

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/remix adapter would you like to integrate into your project? You can choose one or more of the following:

    Checkout Route Handler (for handling product checkouts)

    Customer Portal Route Handler (for managing customer subscriptions/details)

    Webhook Route Handler (for receiving Dodo Payments webhook events)

    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Route Handler is selected:

Purpose: This handler redirects users to the Dodo Payments checkout page.
File Creation: Create a new file at app/routes/api.checkout.tsx in your Remix project.

Code Snippet:

// app/routes/api.checkout.tsx
import { Checkout } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const checkoutGetHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static",
});

const checkoutPostHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic", // for dynamic checkout
});

const checkoutSessionHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session", // for checkout sessions
});

export const loader = ({ request }: LoaderFunctionArgs) => checkoutGetHandler(request);

export const action = ({ request }: LoaderFunctionArgs) => {
  // You can conditionally route to different handlers based on your needs
  // For checkout sessions, use checkoutSessionHandler(request)
  return checkoutPostHandler(request);
};

If Customer Portal Route Handler is selected:

Purpose: This handler redirects authenticated users to their Dodo Payments customer portal.
File Creation: Create a new file at app/routes/api.customer-portal.tsx in your Remix project.

Code Snippet:

// app/routes/api.customer-portal.tsx
import { CustomerPortal } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const customerPortalHandler = CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});

export const loader = ({ request }: LoaderFunctionArgs) => customerPortalHandler(request);

Query Parameters:

    customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)

    send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.

    Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at app/routes/api.webhook.tsx in your Remix project.

Code Snippet:

// app/routes/api.webhook.tsx
import { Webhooks } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";

const webhookHandler = Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET,
  onPayload: async (payload) => {
    //Handle Payload Here
    console.log(payload)
  }
});

export const action = ({ request }: LoaderFunctionArgs) => webhookHandler(request);

Handler Details:

    Method: Only POST requests are supported. Other methods return 405.

    Signature Verification: The handler verifies the webhook signature using the webhookKey and returns 401 if verification fails.

    Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:

    401: Invalid signature

    400: Invalid payload

    500: Internal error during verification

Event Routing: Calls the appropriate event handler based on the payload type.

Supported Webhook Event Handlers:

    onPayload?: (payload: WebhookPayload) => Promise<void>

    onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>

    onPaymentFailed?: (payload: WebhookPayload) => Promise<void>

    onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>

    onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>

    onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>

    onRefundFailed?: (payload: WebhookPayload) => Promise<void>

    onDisputeOpened?: (payload: WebhookPayload) => Promise<void>

    onDisputeExpired?: (payload: WebhookPayload) => Promise<void>

    onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>

    onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>

    onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>

    onDisputeWon?: (payload: WebhookPayload) => Promise<void>

    onDisputeLost?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>

    onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>

    onDunningStarted?: (payload: WebhookPayload) => Promise<void>

    onDunningRecovered?: (payload: WebhookPayload) => Promise<void>

    onCreditAdded?: (payload: WebhookPayload) => Promise<void>

    onCreditDeducted?: (payload: WebhookPayload) => Promise<void>

    onCreditExpired?: (payload: WebhookPayload) => Promise<void>

    onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>

    onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>

    onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>

    onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>

    onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

    Environment Variable Setup:

To ensure the adapter functions correctly, you will need to manually set up the following environment variables in your Remix project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):

    DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).

    DODO_PAYMENTS_RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

    DODO_PAYMENTS_ENVIRONMENT: (Optional) The environment for the API (e.g., test or live).

    DODO_PAYMENTS_WEBHOOK_SECRET: Your Dodo Payments Webhook Secret (required for Webhook handler).

Example .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=your-return-url
DODO_PAYMENTS_ENVIRONMENT=test
DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret

Usage in your code:

bearerToken: process.env.DODO_PAYMENTS_API_KEY
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance. You can also add comments to their PR or chat depending on the context

```


# Dodo CLI
Source: https://docs.dodopayments.com/developer-resources/sdks/cli

The official command-line interface for Dodo Payments — manage resources, run AI-powered queries, create checkout sessions, and test webhooks from your terminal.

Manage your Dodo Payments resources, run AI-powered queries against your account, create checkout sessions, and test webhooks — all from the terminal. The CLI ships with an interactive TUI, a built-in AI assistant powered by MCP, and offline webhook testing.

<Frame>
  <iframe title="Dodo CLI | Dodo Payments" />
</Frame>

## Features

* **Interactive TUI** — launch `dodo` with no arguments to open the full interactive interface with command palette, history, and live notifications.
* **AI assistant built in** — ask questions or take actions in plain English with `/ai`. No extra setup, runs `dodopayments-mcp` locally.
* **Secure by default** — API keys are stored in your OS secret store (macOS Keychain, Windows Credential Vault, Linux libsecret). No plaintext config on disk.
* **Auto update** — the CLI checks for new versions on startup and notifies you in-app. Run `/update` to upgrade in place.
* **Webhook tooling** — listen for live webhooks or trigger payloads offline for local development.

## Installation

Install the CLI in one line on macOS or Linux:

```bash theme={null}
curl -fsSL https://dodopayments.com/install.sh | sh
```

### Install with npm or Bun

If you already have Node or Bun, the package-manager installs always pull the latest version:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g dodopayments-cli
  ```

  ```bash Bun theme={null}
  bun install -g dodopayments-cli
  ```
</CodeGroup>

### Manual installation (no Node / Bun required)

If you'd rather not pipe a remote script to `sh`, download the binary yourself.

<Steps>
  <Step title="Download the binary">
    Download the binary for your platform from the latest [GitHub Release](https://github.com/dodopayments/dodopayments-cli/releases).

    | Platform              | Binary                     |
    | --------------------- | -------------------------- |
    | macOS (Apple Silicon) | `dodo-cli-darwin-arm64`    |
    | macOS (Intel)         | `dodo-cli-darwin-x64`      |
    | Linux (x86\_64)       | `dodo-cli-linux-x64`       |
    | Linux (arm64)         | `dodo-cli-linux-arm64`     |
    | Windows (x86\_64)     | `dodo-cli-windows-x64.exe` |
  </Step>

  <Step title="Rename the binary to `dodo`">
    <CodeGroup>
      ```bash Linux / macOS theme={null}
      mv ./dodo-cli-* ./dodo && chmod +x ./dodo
      ```

      ```powershell Windows theme={null}
      ren .\dodo-cli-windows-x64.exe .\dodo.exe
      ```
    </CodeGroup>
  </Step>

  <Step title="Move it to a directory on your PATH">
    <CodeGroup>
      ```bash Linux / macOS theme={null}
      sudo mv ./dodo /usr/local/bin/
      ```

      ```powershell Windows theme={null}
      move .\dodo.exe C:\Windows\System32\dodo.exe
      ```
    </CodeGroup>

    <Info>
      On Windows, moving to `C:\Windows\System32` requires administrator privileges.
    </Info>
  </Step>

  <Step title="(Optional) Verify the download">
    Each release publishes a `SHA256SUMS.txt`. Verify your download with:

    ```bash theme={null}
    shasum -a 256 -c SHA256SUMS.txt
    ```
  </Step>
</Steps>

## Authentication

Before using authenticated commands, log in with your API key:

```bash theme={null}
dodo login
```

Or, from inside the interactive TUI:

```text theme={null}
/login
```

The login flow will:

1. Open your browser to the Dodo Payments API Keys page.
2. Prompt you to paste your API Key.
3. Ask you to select an environment — **Test Mode** or **Live Mode**.
4. Store the credentials in your OS secret store (Keychain on macOS, Credential Vault on Windows, libsecret on Linux).

<Info>
  Because credentials are stored in the OS secret store, you may be prompted for your **device password** the first time the CLI reads or writes credentials. If you're upgrading from an older version, any existing plaintext API key will be **migrated to the secret store and the legacy file deleted** automatically.
</Info>

### Switching modes and logging out

You can keep one **Test Mode** and one **Live Mode** key authenticated at the same time. To clear credentials:

<CodeGroup>
  ```bash Direct theme={null}
  dodo logout
  ```

  ```text TUI theme={null}
  /logout
  ```
</CodeGroup>

The logout flow lets you choose between **All accounts**, **Test Mode**, or **Live Mode** independently.

## Usage

You can use the CLI in two modes.

### 1. Interactive TUI (recommended)

Run `dodo` with no arguments to launch the full interactive interface:

```bash theme={null}
dodo
```

Type `/` to open the command palette, or just start typing — anything that isn't a slash command is sent to the AI assistant.

| Command   | Description                                            |
| --------- | ------------------------------------------------------ |
| `/help`   | Show the command reference                             |
| `/update` | Check for and install a CLI update                     |
| `/login`  | Authenticate with an API key                           |
| `/logout` | Sign out of one or all environments                    |
| `/clear`  | Clear the TUI screen                                   |
| `/exit`   | Exit the TUI (also: type `exit`, or press `Esc` twice) |

### 2. Direct subcommands

Run commands directly without entering the TUI:

```bash theme={null}
dodo <category> <sub-command> [args...]
```

For example:

```bash theme={null}
dodo payments list 1
dodo customers create
dodo wh trigger
```

The reference tables below show every command. In the TUI, prefix them with `/`; in direct mode, drop the `/`.

## AI Assistant

Ask questions or take actions in natural language. The assistant uses `dodopayments-mcp` running locally — no additional setup or OAuth flow required, and your AI traffic doesn't leave your machine except to talk to the model provider.

| Command                | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| `/ai <query>`          | Ask the AI assistant a question or give it an instruction |
| *(any non-slash text)* | Sent to the AI assistant by default while in the TUI      |

Examples:

```text theme={null}
how much revenue did I make this week?
/ai create a new customer named Acme Inc.
/ai find my last failed payment
```

<Tip>
  The assistant respects your active environment (Test / Live), so it only operates on data from the environment you're currently logged into.
</Tip>

## Project Scaffolding

`dodo init` scaffolds Dodo Payments billing routes directly into an existing project. It generates the boilerplate route files, installs the matching `@dodopayments/*` adapter package, and safely writes the `DODO_PAYMENTS_*` environment variables to your `.env` (it only appends variables that aren't already present). The command runs **without logging in**.

```bash theme={null}
dodo init <framework>
```

| Scaffold                | Description                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `dodo init nextjs`      | Scaffold Next.js App Router billing routes (checkout, customer portal, and webhook handlers) using `@dodopayments/nextjs` |
| `dodo init express`     | Scaffold Express server billing routes using `@dodopayments/express`                                                      |
| `dodo init better-auth` | Scaffold a Better-Auth plugin configuration using `@dodopayments/better-auth`                                             |

For the Better-Auth scaffold you can pass a comma-separated list of plugins to generate (defaults to all): `checkout`, `portal`, `usage`, `webhooks`.

```bash theme={null}
# Scaffold every Better-Auth plugin (default)
dodo init better-auth

# Scaffold only specific plugins
dodo init better-auth checkout,portal
```

<Info>
  The scaffolder auto-detects a `src/` directory and adjusts output paths accordingly, and auto-detects your package manager (`bun`, `pnpm`, `yarn`, or `npm`) to run the correct install command.
</Info>

## Command Reference

### Products

Manage your product catalog.

| Command                     | Description                            |
| --------------------------- | -------------------------------------- |
| `dodo products list <page>` | List products                          |
| `dodo products create`      | Open the dashboard to create a product |
| `dodo products info <id>`   | View details for a specific product    |

### Payments

View payment transactions.

| Command                     | Description                              |
| --------------------------- | ---------------------------------------- |
| `dodo payments list <page>` | List payments                            |
| `dodo payments info <id>`   | Get information about a specific payment |

### Customers

Manage your customer base.

| Command                      | Description                 |
| ---------------------------- | --------------------------- |
| `dodo customers list <page>` | List customers              |
| `dodo customers create`      | Create a new customer       |
| `dodo customers update <id>` | Update an existing customer |

### Discounts

Manage coupons and discounts.

| Command                      | Description                            |
| ---------------------------- | -------------------------------------- |
| `dodo discounts list <page>` | List discounts                         |
| `dodo discounts create`      | Create a new percentage-based discount |
| `dodo discounts delete <id>` | Remove a discount by ID                |

### Licenses

Manage software licenses.

| Command                     | Description   |
| --------------------------- | ------------- |
| `dodo licences list <page>` | List licenses |

### Addons

Manage product addons.

| Command                   | Description                           |
| ------------------------- | ------------------------------------- |
| `dodo addons list <page>` | List addons                           |
| `dodo addons create`      | Open the dashboard to create an addon |
| `dodo addons info <id>`   | View details for a specific addon     |

### Refunds

View refund information.

| Command                    | Description                        |
| -------------------------- | ---------------------------------- |
| `dodo refunds list <page>` | List refunds                       |
| `dodo refunds info <id>`   | View details for a specific refund |

### Checkout

Create hosted checkout sessions.

| Command             | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| `dodo checkout new` | Interactively create a hosted checkout session and get a payment link |

## Webhooks

The CLI includes two powerful tools for testing webhooks during development: a **listener** that forwards live test webhooks to your local server, and a **trigger** that sends mock webhook payloads to any endpoint.

| Command           | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `dodo wh listen`  | Listen for webhooks in real time and forward them to your local dev server |
| `dodo wh trigger` | Trigger a test webhook event interactively — even while logged out         |

### Listen for webhooks

Forward webhooks from Dodo Payments directly to your local development server in real time.

```bash theme={null}
dodo wh listen
```

<Steps>
  <Step title="Enter your local endpoint URL">
    Provide the local URL where you want to receive webhooks (e.g., `http://localhost:3000/webhook`).
  </Step>

  <Step title="Automatic setup">
    The CLI automatically creates a webhook endpoint on your Dodo Payments account if one doesn't already exist, then opens a WebSocket connection to receive events in real time.
  </Step>

  <Step title="Receive and forward">
    When a webhook event fires (from a test payment, subscription change, etc.), the CLI receives it, logs the event type, and forwards the full request with headers and body to your local endpoint. The response from your endpoint is logged and sent back.
  </Step>
</Steps>

<Warning>
  `dodo wh listen` requires a **Test Mode** API key. Live Mode keys are not supported by the listen flow.
</Warning>

<Tip>
  The listener preserves the original webhook headers (`webhook-id`, `webhook-signature`, `webhook-timestamp`) when forwarding to your local endpoint, so you can test your signature verification logic.
</Tip>

### Trigger test webhooks

Send mock webhook payloads to any endpoint for quick testing without needing to create real transactions.

```bash theme={null}
dodo wh trigger
```

The `/wh trigger` flow guides you through:

1. Setting a destination **endpoint URL**
2. Selecting a specific **event** to trigger from an interactive menu

<Info>
  `dodo wh trigger` does **not** require login. It works as a local/offline webhook payload generator.
</Info>

<Warning>
  Triggered events are **not signed**. While testing, disable webhook signature verification on your endpoint — for example, use `unsafe_unwrap()` instead of `unwrap()` in your webhook handler **during testing only**.
</Warning>

### Supported webhook events

`dodo wh trigger` can send mock payloads for all 47 event types Dodo Payments delivers:

| Category               | Events                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscription**       | `active`, `updated`, `on_hold`, `paused`, `unpaused`, `renewed`, `plan_changed`, `cancelled`, `failed`, `expired`, `update_payment_method`  |
| **Payment**            | `succeeded`, `failed`, `processing`, `cancelled`                                                                                            |
| **Refund**             | `succeeded`, `failed`                                                                                                                       |
| **Dispute**            | `opened`, `expired`, `accepted`, `cancelled`, `challenged`, `won`, `lost`                                                                   |
| **License Key**        | `created`                                                                                                                                   |
| **Payout**             | `created`, `in_progress`, `on_hold`, `failed`, `success`                                                                                    |
| **Credit**             | `added`, `deducted`, `expired`, `rolled_over`, `rollover_forfeited`, `overage_charged`, `overage_reset`, `manual_adjustment`, `balance_low` |
| **Abandoned Checkout** | `detected`, `recovered`                                                                                                                     |
| **Dunning**            | `started`, `recovered`                                                                                                                      |
| **Entitlement Grant**  | `created`, `delivered`, `failed`, `revoked`                                                                                                 |

<Note>
  Mock payload shapes follow the corresponding schemas in the API reference. See [Webhook Events](/developer-resources/webhooks/intents/webhook-events-guide) for what each event means and when Dodo Payments emits it in production.
</Note>

<Tip>
  `payout.created` is emitted while the payout still reports a `not_initiated` status, so the mock payload reflects that too. See [Payout Events](/developer-resources/webhooks/intents/payout) for the full payout lifecycle.
</Tip>

### Environment variables

| Variable                  | Description                                                            |
| ------------------------- | ---------------------------------------------------------------------- |
| `DODO_WH_TEST_SERVER_URL` | Override the default webhook relay server URL used by `dodo wh listen` |

## Updates

The CLI checks for a newer version on startup and surfaces a notification in the status bar when one is available. To upgrade:

```text theme={null}
/update
```

Or, re-run the installer to upgrade in place:

<CodeGroup>
  ```bash install.sh theme={null}
  curl -fsSL https://dodopayments.com/install.sh | sh
  ```

  ```bash npm theme={null}
  npm install -g dodopayments-cli
  ```

  ```bash Bun theme={null}
  bun install -g dodopayments-cli
  ```
</CodeGroup>

## Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-cli">
    View source code and releases
  </Card>

  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/dodopayments-cli">
    View on npm registry
  </Card>
</CardGroup>

## Support

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-cli/issues)
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)


# Seat-Based Pricing with Add-ons and Payment Links
Source: https://docs.dodopayments.com/developer-resources/seat-based-pricing

Learn how to create add-ons for seat-based pricing and generate payment links with custom add-on quantities using Dodo Payments

In this tutorial, you'll learn how to implement seat-based pricing using Dodo Payments add-ons. We'll create a subscription product with add-ons for additional seats and show you how to generate payment links with custom add-on quantities.

<Note>
  This tutorial provides sample implementation code for a Node.js/Express application. You can modify this code for your specific framework (Next.js, React, Vue, etc.) and customize the user interface according to your application's needs.
</Note>

By the end of this tutorial, you'll know how to:

* Create subscription products with seat-based pricing
* Set up add-ons for additional seats
* Generate payment links with custom add-on quantities
* Handle checkout sessions with dynamic seat counts

## What We're Building

Let's create a seat-based pricing model:

* **Base Plan**: \$49/month for up to 5 team members
* **Seat Add-on**: \$2/month per additional seat
* **Payment Links**: Dynamic checkout with custom seat quantities

<Info>
  Before we start, make sure you have:

  * A Dodo Payments account
  * Basic familiarity with TypeScript/Node.js
</Info>

## Step 1: Create Your Seat Add-On

Now we need to create an add-on that represents additional seats. This add-on will be attached to our base subscription and allow customers to purchase additional seats.

<Frame>
  <img alt="Creating base subscription product" />
</Frame>

<Tip>
  **What we're building**: An add-on that costs \$2/month per seat and can be added to any base subscription.
</Tip>

<Steps>
  <Step title="Navigate to Add-Ons">
    1. In your Dodo Payments dashboard, stay in the **Products** section
    2. Click on the **Add-Ons** tab
    3. Click **Create Add-On**

    This will open the add-on creation form.
  </Step>

  <Step title="Enter add-on details">
    Fill in these values for our seat add-on:

    **Add-On Name**: `Additional Team Seat`

    **Description**: `Add extra team members to your workspace with full access to all features`

    **Price**: Enter → `2.00`

    **Currency**: Must match your base subscription currency

    **Tax Category**: Select appropriate category for your product.
  </Step>

  <Step title="Save your add-on">
    1. Review all your settings:
       * Name: Additional Team Seat
       * Price: \$2.00/month
    2. Click **Create Add-On**

    <Check>
      **Add-on created!** Your seat add-on is now available to attach to subscriptions.
    </Check>
  </Step>
</Steps>

## Step 2: Create Your Base Subscription Product

We'll start by creating a base subscription product that includes 5 team members. This will be the foundation of our seat-based pricing model.

<Frame>
  <img alt="Creating base subscription product" />
</Frame>

<Steps>
  <Step title="Navigate to Products">
    1. Log into your Dodo Payments dashboard
    2. Click on **Products** in the left sidebar
    3. Click the **Create Product** button
    4. Select **Subscription** as the product type

    You should see a form where we'll configure our base subscription.
  </Step>

  <Step title="Fill in the subscription details">
    Now we'll enter the specific details for our base plan:

    **Product Name**: `Motion`

    **Description**: `Where your team's documentation lives.`

    **Recurring Price**: Enter → `49.00`

    **Billing Cycle**: Select → `Monthly`

    **Currency**: Select your preferred currency (e.g., `USD`)
  </Step>
</Steps>

## Step 3: Connect Add-On to Subscription

Now we need to associate our seat add-on with the base subscription so customers can purchase additional seats during checkout.

<Steps>
  <Step title="Attach the seat add-on">
    <Frame>
      <img alt="Attaching add-on to subscription" />
    </Frame>

    1. Scroll down to the **Add-Ons** section
    2. Click **Add Add-Ons**
    3. From the dropdown, select your seat add-on
    4. Confirm that it appears in your subscription configuration
  </Step>

  <Step title="Save subscription changes">
    1. Review your complete subscription setup:
       * Base plan: \$49/month for 5 seats
       * Add-on: \$2/month per additional seat
       * Free trial: 14 days
    2. Click **Save Changes**

    <Check>
      **Seat-based pricing configured!** Customers can now purchase your base plan and add extra seats as needed.
    </Check>
  </Step>
</Steps>

## Step 4: Generate Payment Links with Custom Add-on Quantities

Now let's create an Express.js application that generates payment links with custom add-on quantities. This is where the real power of seat-based pricing comes in - you can dynamically create checkout sessions with any number of additional seats.

<Steps>
  <Step title="Set up your project">
    Create a new Node.js project and install the required dependencies:

    ```bash theme={null}
    mkdir seat-based-pricing
    cd seat-based-pricing
    npm init -y
    npm install dodopayments express dotenv
    npm install -D @types/node @types/express typescript ts-node
    ```

    Create a `tsconfig.json` file:

    ```json theme={null}
    {
      "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "outDir": "./dist",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true
      }
    }
    ```
  </Step>

  <Step title="Create your environment file">
    Create a `.env` file with your Dodo Payments API key:

    ```bash theme={null}
    DODO_PAYMENTS_API_KEY=your_actual_dodo_api_key_here
    ```

    <Warning>
      Never commit your API key to version control. Add `.env` to your `.gitignore` file.
    </Warning>
  </Step>

  <Step title="Implement the checkout session creation">
    Create a `src/server.ts` file with the following code:

    <CodeGroup>
      ```typescript server.ts expandable theme={null}
      // Add this new endpoint for dynamic seat quantities
      import 'dotenv/config';
      import DodoPayments from 'dodopayments';
      import express, { Request, Response } from 'express';

      const app = express();

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

      async function createCheckoutSession(seatCount: number) {
        try {
          const session = await client.checkoutSessions.create({
            // Products to sell - use IDs from your Dodo Payments dashboard
            product_cart: [
              {
                product_id: 'pdt_7Rl9OWT2Mz4wwUTKz74iZ', // Replace with your actual product ID
                quantity: 1,
                addons: [
                  {
                    addon_id: 'adn_eKQbNakKrivDpaxmI8wKI', // Replace with your actual addon ID
                    quantity: seatCount
                  }
                ]
              }
            ],
            
            // Pre-fill customer information to reduce friction
            customer: {
              email: 'steve@example.com',
              name: 'Steve Irwin',
            },
            // Where to redirect after successful payment
            return_url: 'https://example.com/checkout/success',
          });

          // 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/:seatCount', async (req: Request, res: Response) => {
        try {
          const seatCount = parseInt(req.params.seatCount);
          const session = await createCheckoutSession(seatCount);
          res.json({ checkout_url: session.checkout_url });
        } catch (error) {
          res.status(500).json({ error: 'Failed to create checkout session' });
        }
      });

      // Add this line after your other middleware
      app.use(express.static('public'));

      // Add this route to serve the demo page
      app.get('/', (req, res) => {
        res.sendFile(__dirname + '/../public/index.html');
      });

      app.listen(3000, () => {
        console.log('Server is running on port 3000');
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Add a simple web interface">
    Create a `public/index.html` file for easy testing:

    <CodeGroup>
      ```html index.html expandable theme={null}
      <!DOCTYPE html>
      <html>
      <head>
          <title>Seat-Based Pricing Demo</title>
          <style>
              body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }
              .form-group { margin: 20px 0; }
              label { display: block; margin-bottom: 5px; font-weight: bold; }
              input { width: 100%; padding: 10px; border: 1px solid #ddd; border-radius: 4px; }
              button { background: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer; }
              button:hover { background: #0056b3; }
              .result { margin-top: 20px; padding: 15px; background: #f8f9fa; border-radius: 4px; }
          </style>
      </head>
      <body>
          <h1>Seat-Based Pricing Demo</h1>
          <p>Generate checkout links with custom seat quantities:</p>
          
          <div class="form-group">
              <label for="seatCount">Number of Additional Seats:</label>
              <input type="number" id="seatCount" value="3" min="0" max="50">
          </div>
          
          <button onclick="createCheckout()">Generate Checkout Link</button>
          
          <div id="result" class="result" style="display: none;">
              <h3>Checkout Link Generated!</h3>
              <p><strong>Seat Count:</strong> <span id="seatCountDisplay"></span></p>
              <p><strong>Total Cost:</strong> $<span id="totalCost"></span>/month</p>
              <p><strong>Checkout URL:</strong></p>
              <a id="checkoutUrl" href="#" target="_blank">Click here to checkout</a>
          </div>

          <script>
              async function createCheckout() {
                  const seatCount = document.getElementById('seatCount').value;
                  
                  try {
                      const response = await fetch(`/create-checkout/${seatCount}`, {
                          method: 'POST'
                      });
                      
                      const data = await response.json();
                      
                      if (response.ok) {
                          document.getElementById('seatCountDisplay').textContent = seatCount;
                          document.getElementById('totalCost').textContent = data.total_cost;
                          document.getElementById('checkoutUrl').href = data.checkout_url;
                          document.getElementById('result').style.display = 'block';
                      } else {
                          alert('Error: ' + data.error);
                      }
                  } catch (error) {
                      alert('Error creating checkout session');
                  }
              }
          </script>
      </body>
      </html>
      ```
    </CodeGroup>

    <Check>
      **Web interface created!** You now have a simple UI to test different seat quantities.
    </Check>
  </Step>

  <Step title="Serve static files">
    Add this to your `src/server.ts` to serve the HTML file:

    ```typescript theme={null}
    // Add this line after your other middleware
    app.use(express.static('public'));

    // Add this route to serve the demo page
    app.get('/', (req, res) => {
      res.sendFile(__dirname + '/../public/index.html');
    });
    ```

    <Check>
      **Static files configured!** Visit `http://localhost:3000` to see your demo interface.
    </Check>
  </Step>
</Steps>

## Step 5: Test Your Implementation

Let's test our seat-based pricing implementation to make sure everything works correctly.

<Steps>
  <Step title="Start your server">
    1. Make sure you have your `.env` file with the correct API key
    2. Update the product and add-on IDs in your code with the actual values from your Dodo Payments dashboard
    3. Start your server:

    ```bash theme={null}
    npm run dev
    ```

    <Check>
      Your server should start successfully and show "Server running on [http://localhost:3000](http://localhost:3000)"
    </Check>
  </Step>

  <Step title="Test the web interface">
    <Frame>
      <img alt="Creating base subscription product" />
    </Frame>

    1. Open your browser and go to `http://localhost:3000`
    2. You should see the seat-based pricing demo interface
    3. Try different seat quantities (0, 3, 10, etc.)
    4. Click "Generate Checkout Link" for each quantity
    5. Verify that the checkout URLs are generated correctly
  </Step>

  <Step title="Test a checkout session">
    1. Generate a checkout link with 3 additional seats
    2. Click the checkout URL to open the Dodo Payments checkout
    3. Verify that the checkout shows:
       * Base plan: \$49/month
       * Additional seats: 3 × 2 dollars = \$6/month
    4. Complete the test purchase

    <Check>
      The checkout should display the correct pricing breakdown and allow you to complete the purchase.
    </Check>
  </Step>

  <Step title="Listen for webhooks and update your DB">
    To keep your database in sync with subscription and seat changes, you need to listen for webhook events from Dodo Payments. Webhooks notify your backend when a customer completes checkout, updates their subscription, or changes seat counts.

    Follow the official Dodo Payments webhooks guide for step-by-step instructions on setting up webhook endpoints and handling events:

    <Card title="Dodo Payments Webhooks Documentation" icon="bell" href="/developer-resources/webhooks">
      Learn how to securely receive and process webhook events for subscription and seat management.
    </Card>
  </Step>
</Steps>

## Troubleshooting

Common issues and their solutions:

<AccordionGroup>
  <Accordion title="Checkout creation failing">
    **Possible causes:**

    * Invalid product ID or add-on ID
    * API key doesn't have sufficient permissions
    * Add-on not properly associated with subscription
    * Network connectivity issues

    **Solutions:**

    1. Verify product and add-on IDs exist in your Dodo Payments dashboard
    2. Check that add-on is properly attached to the subscription
    3. Ensure API key has checkout session creation permissions
    4. Test API connectivity with a simple GET request
  </Accordion>
</AccordionGroup>

## Congratulations! You've Implemented Seat-Based Pricing

You've successfully created a seat-based pricing system with Dodo Payments! Here's what you accomplished:

<CardGroup>
  <Card title="Base Subscription">
    Created a subscription product with 5 included seats at \$49/month
  </Card>

  <Card title="Seat Add-ons">
    Configured add-ons for additional seats at \$2/month per seat
  </Card>

  <Card title="Checkout">
    Built an API that generates checkout sessions with custom seat quantities
  </Card>

  <Card title="Web Interface">
    Created a simple web interface for testing different seat quantities
  </Card>
</CardGroup>

<Info>
  This example demonstrates only a minimal implementation of seat-based pricing. For production use, you should add robust error handling, authentication, data validation, security measures, and adapt the logic to fit your application's requirements.
</Info>


# Sentra
Source: https://docs.dodopayments.com/developer-resources/sentra

Install the Sentra extension for VS Code, Cursor, or Windsurf to integrate billing and payments into your app using AI-powered assistance.

<Frame>
  <iframe title="Sentra Extension Demo" />
</Frame>

## Overview

Sentra adds intelligence and execution on top of Dodo Payments' core stacks. It's an AI agent that integrates, analyzes, and acts on billing and payments. Sentra connects SDKs, APIs, and adapters across your stack (Auth, DB, CRM, etc.), surfaces revenue insights like growth drivers, and executes customer actions such as refunds, upgrades, and credits.

<Info>
  Sentra is currently in Beta. Features, APIs, and integrations may change rapidly. We welcome feedback and bug reports as we iterate!
</Info>

## Install

Sentra is available as an extension for VS Code, Cursor, and Windsurf. Choose your IDE below:

<Tabs>
  <Tab title="VS Code">
    <Steps>
      <Step title="Open Extensions Marketplace">
        1. Open VS Code.
        2. Click the Extensions icon in the sidebar (or press `Cmd+Shift+X` on macOS / `Ctrl+Shift+X` on Windows/Linux).
        3. Search for "Sentra by Dodo Payments" in the marketplace.

        <Frame>
          <img alt="VS Code Extensions Marketplace showing Sentra extension" />
        </Frame>
      </Step>

      <Step title="Install the Extension">
        1. Click on "Sentra by Dodo Payments" from the search results.
        2. Click the **Install** button.
        3. Wait for the installation to complete.
      </Step>

      <Step title="Restart VS Code">
        After installation, restart VS Code to activate the extension.

        <Tip>
          If the extension doesn't appear after installation, restarting the editor will resolve the issue in most cases.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open Extensions Marketplace">
        1. Open Cursor.
        2. Click the Extensions icon in the sidebar (or press `Cmd+Shift+X` on macOS / `Ctrl+Shift+X` on Windows/Linux).
        3. Search for "Sentra by Dodo Payments" in the marketplace.
      </Step>

      <Step title="Install the Extension">
        1. Click on "Sentra by Dodo Payments" from the search results.
        2. Click the **Install** button.
        3. Wait for the installation to complete.
      </Step>

      <Step title="Restart Cursor">
        After installation, restart Cursor to activate the extension.

        <Tip>
          If the extension doesn't appear after installation, restarting the editor will resolve the issue in most cases.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windsurf">
    <Steps>
      <Step title="Open Extensions Marketplace">
        1. Open Windsurf.
        2. Click the Extensions icon in the sidebar (or press `Cmd+Shift+X` on macOS / `Ctrl+Shift+X` on Windows/Linux).
        3. Search for "Sentra by Dodo Payments" in the marketplace.
      </Step>

      <Step title="Install the Extension">
        1. Click on "Sentra by Dodo Payments" from the search results.
        2. Click the **Install** button.
        3. Wait for the installation to complete.
      </Step>

      <Step title="Restart Windsurf">
        After installation, restart Windsurf to activate the extension.

        <Tip>
          If the extension doesn't appear after installation, restarting the editor will resolve the issue in most cases.
        </Tip>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Setup

Once installed, you need to configure Sentra with your Dodo Payments API key and environment settings.

<Steps>
  <Step title="Get Your API Key">
    1. Log in to your [Dodo Payments dashboard](https://app.dodopayments.com).
    2. Navigate to **Developer** › **API Keys**.
    3. Copy your API key.
  </Step>

  <Step title="Configure Sentra">
    1. Open your IDE (VS Code, Cursor, or Windsurf).
    2. Open the Command Palette (`Cmd+Shift+P` on macOS / `Ctrl+Shift+P` on Windows/Linux).
    3. Type "Sentra: Configure" and select it.
    4. Enter your Dodo Payments API key when prompted.

    <Frame>
      <img alt="Sentra configuration screen with API key input and environment selection" />
    </Frame>
  </Step>

  <Step title="Select Environment Mode">
    Choose your environment mode:

    * **Test Mode**: For development and testing
    * **Live Mode**: For production use

    <Warning>
      Start with Test mode to validate your setup before switching to Live mode for production data.
    </Warning>
  </Step>

  <Step title="Set Model Reasoning Effort">
    Select your preferred model reasoning effort level:

    * **Low**: Faster responses, suitable for simple tasks
    * **Medium**: Balanced performance (recommended)
    * **High**: More thorough analysis, suitable for complex integrations
  </Step>

  <Step title="Complete Setup">
    Click **Let's go!** to complete the setup and start using Sentra.

    <Check>
      Your API keys are stored securely in your IDE's Secret Storage and never exposed in your code.
    </Check>
  </Step>
</Steps>

## How It Works

Sentra follows a simple four-step process from prompt to production:

<Steps>
  <Step title="Prompt">
    Type what you want to build. For example: "Add usage-based billing with a free trial for my Pro plan."

    <Frame>
      <img alt="Sentra interface showing prompt input with example task" />
    </Frame>
  </Step>

  <Step title="Plan">
    Sentra generates the changes (SDK hooks, objects, config) and presents a plan for your review.
  </Step>

  <Step title="Approve">
    Review the generated plan and confirm the changes you want Sentra to implement.
  </Step>

  <Step title="Execute">
    Sentra applies the changes, tests them, and confirms success.
  </Step>
</Steps>

## Using Sentra

### Modes

Sentra offers three interaction modes accessible from the interface:

* **Ask**: Ask questions about Dodo Payments, billing models, API usage, and best practices
* **Build**: Integrate billing and UI into your application with guided assistance
* **Plan**: Design scalable billing architectures with architectural guidance

### Example Tasks

Here are some common tasks you can accomplish with Sentra:

* **Integrate Pricing Page**: Set up a complete pricing page with product listings and checkout
* **Implement Webhook**: Configure webhook handlers for payment events
* **Add Subscription Flow**: Create subscription management with upgrade/downgrade capabilities
* **Set Up Usage-Based Billing**: Configure meters and event ingestion for usage tracking
* **Create Customer Portal**: Build a customer self-service portal for billing management

### Auto-Approval Settings

You can configure auto-approval settings to streamline your workflow:

* **None**: Review and approve all changes manually (recommended for production)
* **Low Risk**: Auto-approve simple, low-risk changes
* **All**: Auto-approve all changes (use with caution)

## Supported Billing Models

Sentra supports all Dodo Payments billing models:

* **One-time Payments**: Single purchase transactions
* **Subscriptions**: Recurring billing with multiple intervals
* **Usage-Based Billing**: Metered billing based on consumption
* **Outcome-Based Billing**: Pay-per-result pricing models

## Who Is It For

Sentra bridges engineering and business, so every team can ship monetization without friction:

* **Developers**: Ship monetization faster inside your IDE
* **Founders & PMs**: Prototype billing models without deep infra work
* **RevOps & Finance**: Use guardrailed actions without needing engineers
* **Support & Success**: Solve billing cases safely, with approvals where needed

## Troubleshooting

<AccordionGroup>
  <Accordion title="Extension not appearing after installation">
    If Sentra doesn't appear in your IDE after installation, try the following:

    1. **Restart your editor**: Close and reopen VS Code, Cursor, or Windsurf completely
    2. **Check installation**: Verify the extension is installed by going to Extensions and searching for "Sentra"
    3. **Reload window**: Use the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and run "Developer: Reload Window"

    <Check>
      Restarting the editor resolves the issue in most cases.
    </Check>
  </Accordion>

  <Accordion title="Invalid API key or authentication errors">
    * Verify your API key is correct and active in the Dodo Payments dashboard
    * Ensure you're using the correct environment mode (Test vs Live) that matches your API key
    * Check that your API key has the necessary permissions
    * Try regenerating your API key if the issue persists
  </Accordion>

  <Accordion title="Configuration not saving">
    * Ensure you've completed all required fields in the configuration screen
    * Check that your IDE has permission to access Secret Storage
    * Try reconfiguring Sentra through the Command Palette
  </Accordion>

  <Accordion title="Plan generation fails">
    * Verify your API key is valid and has access to the required resources
    * Check your internet connection
    * Ensure you're using a supported billing model
    * Try rephrasing your prompt with more specific details
  </Accordion>

  <Accordion title="Execution errors">
    * Review the generated plan carefully before approval
    * Check that your project structure matches Sentra's expectations
    * Verify all dependencies are installed
    * Check the IDE's output panel for detailed error messages
  </Accordion>
</AccordionGroup>

<Warning>
  If you continue to experience issues after restarting your editor, contact support with details about your IDE version and the specific error messages you're seeing.
</Warning>

## Additional Resources

<CardGroup>
  <Card title="Dodo Payments Docs" icon="book" href="/introduction">
    Learn more about Dodo Payments features and capabilities.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the complete Dodo Payments API reference.
  </Card>

  <Card title="Webhook Setup" icon="webhook" href="/developer-resources/webhooks">
    Understand how to configure webhooks for payment events.
  </Card>

  <Card title="Get Beta Access" icon="rocket" href="https://dodopayments.com/sentra">
    Visit the Sentra website to learn more and get beta access.
  </Card>
</CardGroup>


# Subscription Integration Guide
Source: https://docs.dodopayments.com/developer-resources/subscription-integration-guide

This guide will help you integrate the Dodo Payments Subscription Product into your website.

## Prerequisites

To integrate the Dodo Payments API, you'll need:

* A Dodo Payments merchant account
* API credentials (API key and webhook secret key) from the dashboard

For a more detailed guide on the prerequisites, check this [section](/developer-resources/integration-guide#dashboard-setup).

## API Integration

### Checkout Sessions

Use Checkout Sessions to sell subscription products with a secure, hosted checkout. Pass your subscription product in `product_cart` and redirect customers to the returned `checkout_url`.

<Tip>
  **Mixed Checkout**: You can combine subscription products with one-time products in the same checkout session. This enables use cases like setup fees with subscriptions, hardware bundles with SaaS, and more. See the [Checkout Sessions guide](/developer-resources/checkout-session) for examples.
</Tip>

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: 'test_mode', // defaults to 'live_mode'
    });

    async function main() {
      const session = await client.checkoutSessions.create({
        product_cart: [
          { product_id: 'pdt_subscription_monthly', quantity: 1 }
        ],
        // Optional: configure trials for subscription products
        subscription_data: { trial_period_days: 14 },
        customer: {
          email: 'subscriber@example.com',
          name: 'Jane Doe',
        },
        return_url: 'https://example.com/success',
      });

      console.log(session.checkout_url);
    }

    main();
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from dodopayments import DodoPayments

    client = DodoPayments(
        bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
        environment="test_mode",  # defaults to "live_mode"
    )

    session = client.checkout_sessions.create(
        product_cart=[
            {"product_id": "pdt_subscription_monthly", "quantity": 1}
        ],
        subscription_data={"trial_period_days": 14},  # optional
        customer={
            "email": "subscriber@example.com",
            "name": "Jane Doe",
        },
        return_url="https://example.com/success",
    )

    print(session.checkout_url)
    ```
  </Tab>

  <Tab title="REST API">
    ```javascript theme={null}
    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({
        product_cart: [
          { product_id: 'pdt_subscription_monthly', quantity: 1 }
        ],
        subscription_data: { trial_period_days: 14 }, // optional
        customer: {
          email: 'subscriber@example.com',
          name: 'Jane Doe'
        },
        return_url: 'https://example.com/success'
      })
    });

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

    const session = await response.json();
    console.log(session.checkout_url);
    ```
  </Tab>
</Tabs>

### API Response

The following is an example of the response:

```json theme={null}
{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
```

Redirect the customer to `checkout_url`.

### Webhooks

When integrating subscriptions, you'll receive webhooks to track the subscription lifecycle. These webhooks help you manage subscription states and payment scenarios effectively.

To set up your webhook endpoint, please follow our [Detailed Integration Guide](/developer-resources/integration-guide#implementing-webhooks).

#### Subscription Event Types

The following webhook events track subscription status changes:

1. **`subscription.active`** - Subscription is successfully activated.
2. **`subscription.updated`** - Subscription object was updated (fires on any field change).
3. **`subscription.on_hold`** - Subscription is put on hold due to failed renewal.
4. **`subscription.failed`** - Subscription creation failed during mandate creation.
5. **`subscription.renewed`** - Subscription is renewed for the next billing period.

For reliable subscription lifecycle management, we recommend tracking these subscription events.

<Tip>
  Use `subscription.updated` to get real-time notifications about any subscription changes, keeping your application state in sync without polling the API.
</Tip>

#### Payment Scenarios

**Successful Payment Flow**

The webhooks you receive, and their timing, depend on whether the product has a trial.

*Immediate billing (0 trial days):*

1. `subscription.active`: the mandate is authorized and the subscription is activated.
2. `payment.succeeded`: confirms the first charge. Expect this within **2–10 minutes** of checkout.

*With a trial period:*

1. **At trial start (checkout):** `subscription.active` fires once the payment method is authorized. **No recurring charge is taken yet.** The first real charge is deferred until the trial ends.
2. **At trial end:** the recurring amount is charged, and you receive `payment.succeeded` **together with** `subscription.renewed`.

*Every subsequent renewal:*

* `subscription.renewed`: fires on each billing cycle when the renewal payment is deducted, **always alongside** `payment.succeeded`. It also carries the updated `next_billing_date`.

<Info>
  Whenever money is actually deducted for a subscription product, you get `subscription.renewed` **and** `payment.succeeded`. Use `subscription.renewed` (rather than `payment.succeeded` alone) as your signal to extend access for the next cycle.
</Info>

**Payment Failure Scenarios**

1. Subscription Failure

* `subscription.failed` - Subscription creation failed due to failure to create a mandate.
* `payment.failed` - Indicates failed payment.

2. Subscription On Hold

* `subscription.on_hold` - Subscription is put on hold due to failed renewal payment or failed plan change charge.
* When a subscription goes on hold, it will not renew automatically until the payment method is updated.

<Info>**Best Practice**: To simplify implementation, we recommend primarily tracking subscription events for managing the subscription lifecycle.</Info>

<Tip>
  For a complete walkthrough of reading `error_code`/`error_message`, deciding when to retry, and surfacing failures to customers, see [Handle Payment Failures](/developer-resources/handle-payment-failures).
</Tip>

#### `subscription.failed` vs. `subscription.on_hold`

These two events are easy to confuse, but they require very different handling:

| Event                  | When it fires                                                                          | Status    | Recoverable?      | What to do                                                                                                         |
| ---------------------- | -------------------------------------------------------------------------------------- | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `subscription.failed`  | The **initial** mandate could not be created at subscription **creation**              | `failed`  | **No (terminal)** | Do not grant access. Ask the customer to start a **new** subscription with a different payment method.             |
| `subscription.on_hold` | A **renewal** payment (or plan-change charge) failed on an already-active subscription | `on_hold` | **Yes**           | Recover by updating the payment method; see [Handling Subscription On Hold](#handling-subscription-on-hold) below. |

<Warning>
  `subscription.failed` is terminal. The subscription cannot be reactivated. The customer must create a new subscription. Never grant entitlements when this event fires.
</Warning>

### Handling Subscription On Hold

When a subscription enters `on_hold` state, you need to update the payment method to reactivate it. This section explains when subscriptions go on hold and how to handle them.

#### When Subscriptions Go On Hold

A subscription is placed on hold when:

* **Renewal payment fails**: The automatic renewal charge fails due to insufficient funds, expired card, or bank decline
* **Plan change charge fails**: An immediate charge during plan upgrade/downgrade fails
* **Payment method authorization fails**: The payment method cannot be authorized for recurring charges

<Warning>
  Subscriptions in `on_hold` state will not renew automatically. You must update the payment method to reactivate the subscription.
</Warning>

#### Reactivating Subscriptions from On Hold

To reactivate a subscription from `on_hold` state, use the Update Payment Method API. This automatically:

1. Creates a charge for remaining dues
2. Generates an invoice for the charge
3. Processes the payment using the new payment method
4. Reactivates the subscription to `active` state upon successful payment

<Steps>
  <Step title="Handle subscription.on_hold webhook">
    When you receive a `subscription.on_hold` webhook, update your application state and notify the customer:

    ```javascript theme={null}
    // Webhook handler
    app.post('/webhooks/dodo', async (req, res) => {
      const event = req.body;
      
      if (event.type === 'subscription.on_hold') {
        const subscription = event.data;
        
        // Update subscription status in your database
        await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
        
        // Notify customer to update payment method
        await sendEmailToCustomer(subscription.customer_id, {
          subject: 'Payment Required - Subscription On Hold',
          message: 'Your subscription is on hold. Please update your payment method to continue service.'
        });
      }
      
      res.json({ received: true });
    });
    ```
  </Step>

  <Step title="Update payment method">
    When the customer is ready to update their payment method, call the Update Payment Method API:

    <CodeGroup>
      ```javascript Node.js theme={null}
      // Update with new payment method
      const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
        payment_method: { type: 'new', return_url: 'https://example.com/return' }
      });

      // For on_hold subscriptions, a charge is automatically created
      if (response.payment_id) {
        console.log('Charge created for remaining dues:', response.payment_id);
        // Redirect customer to response.payment_link to complete payment
      }
      ```

      ```python Python theme={null}
      # Update with new payment method
      response = client.subscriptions.update_payment_method(
          subscription_id=subscription_id,
          payment_method={"type": "new", "return_url": "https://example.com/return"},
      )

      # For on_hold subscriptions, a charge is automatically created
      if response.payment_id:
          print("Charge created for remaining dues:", response.payment_id)
          # Redirect customer to response.payment_link to complete payment
      ```
    </CodeGroup>

    <Info>
      You can also use an existing payment method ID if the customer has saved payment methods:

      ```javascript theme={null}
      await client.subscriptions.updatePaymentMethod(subscriptionId, {
        payment_method: { type: 'existing', payment_method_id: 'pm_abc123' }
      });
      ```
    </Info>
  </Step>

  <Step title="Monitor webhook events">
    After updating the payment method, monitor for these webhook events:

    1. **`payment.succeeded`** - The charge for remaining dues was successful
    2. **`subscription.active`** - The subscription has been reactivated

    ```javascript theme={null}
    if (event.type === 'payment.succeeded') {
      const payment = event.data;
      
      // Check if this payment is for an on_hold subscription
      if (payment.subscription_id) {
        // Wait for subscription.active webhook to confirm reactivation
      }
    }

    if (event.type === 'subscription.active') {
      const subscription = event.data;
      
      // Update subscription status in your database
      await updateSubscriptionStatus(subscription.subscription_id, 'active');
      
      // Restore customer access
      await restoreCustomerAccess(subscription.customer_id);
      
      // Notify customer of successful reactivation
      await sendEmailToCustomer(subscription.customer_id, {
        subject: 'Subscription Reactivated',
        message: 'Your subscription has been reactivated successfully.'
      });
    }
    ```
  </Step>
</Steps>

### Sample Subscription event payload

***

| Property      | Type   | Required | Description                                                                                  |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `business_id` | string | Yes      | The unique identifier for the business                                                       |
| `timestamp`   | string | Yes      | The timestamp of when the event occurred (not necessarily the same as when it was delivered) |
| `type`        | string | Yes      | The type of event. See [Event Types](#event-types)                                           |
| `data`        | object | Yes      | The main data payload. See [Data Object](#data-object)                                       |

## Changing Subscription Plans

You can upgrade or downgrade a subscription plan using the change plan API endpoint. This allows you to modify the subscription's product, quantity, and handle proration.

<Card title="Change Plan API Reference" icon="arrows-rotate" href="/api-reference/subscriptions/change-plan">
  For detailed information about changing subscription plans, please refer to our Change Plan API documentation.
</Card>

### Proration Options

When changing subscription plans, you have four options for handling the immediate charge:

#### 1. `prorated_immediately`

* Calculates the prorated amount based on the remaining time in the current billing cycle
* Charges the customer only for the difference between the old and new plan
* During a trial period, this will immediately switch the user to the new plan, charging the customer right away

#### 2. `full_immediately`

* Charges the customer the full subscription amount for the new plan
* Ignores any remaining time or credits from the previous plan
* Useful when you want to reset the billing cycle or charge the full amount regardless of proration

#### 3. `difference_immediately`

* When upgrading, the customer is immediately charged the difference between the two plan amounts.
* For example, if the current plan is 30 Dollars and the customer upgrades to an 80 Dollars, they are charged \$50 instantly.
* When downgrading, the unused amount from the current plan is added as internal credit and automatically applied to future subscription renewals.
* For example, if the current plan is 50 Dollars and the customer switches to a 20 Dollars plan, the remaining \$30 is credited and used toward the next billing cycle.

#### 4. `do_not_bill`

* Applies the plan change immediately but does **not** charge anything at the time of the change.
* The updated plan (and quantity/add-ons) is billed at the **next scheduled renewal**, and the **original billing date is preserved**.

<Warning>
  **All three "charge now" modes reset the billing cycle.** `prorated_immediately`, `difference_immediately`, and `full_immediately` move the subscription's `next_billing_date` to the change date. Only `do_not_bill` keeps the original renewal date, but it applies no immediate charge.
</Warning>

### Behavior

* When you invoke this API, Dodo Payments immediately initiates a charge based on your selected proration option
* If the plan change is a downgrade and you use `prorated_immediately`, credits will be automatically calculated and added to the subscription's credit balance. These credits are specific to that subscription and will only be used to offset future recurring payments of the same subscription
* The `full_immediately` option bypasses credit calculations and charges the complete new plan amount

<Tip>
  **Choose your proration option carefully**: Use `prorated_immediately` for fair billing that accounts for unused time, or `full_immediately` when you want to charge the complete new plan amount regardless of the current billing cycle.
</Tip>

### Charge Processing

* The immediate charge initiated upon plan change usually completes processing in less than 2 minutes
* If this immediate charge fails for any reason, the subscription is automatically placed on hold until the issue is resolved

## On-Demand Subscriptions

<Info>
  On-demand subscriptions let you charge customers flexibly, not just on a fixed schedule. This feature is available for all accounts.
</Info>

**To create an on-demand subscription:**

To create an on-demand subscription, use the [POST /subscriptions](/api-reference/subscriptions/post-subscriptions) API endpoint and include the `on_demand` field in your request body. This allows you to authorize a payment method without an immediate charge, or set a custom initial price.

<Warning>
  `POST /subscriptions` is **deprecated**. It still works for existing integrations, but new integrations should create on-demand subscriptions through a [Checkout Session](/developer-resources/checkout-session) (`POST /checkouts`) with `subscription_data.on_demand`. See the [On-Demand Subscriptions Guide](/developer-resources/ondemand-subscriptions) for the current flow.
</Warning>

**To charge an on-demand subscription:**

For subsequent charges, use the [POST /subscriptions//charge](/api-reference/subscriptions/create-charge) endpoint and specify the amount to charge the customer for that transaction.

<Note>
  For a complete, step-by-step guide (including request/response examples, safe retry policies, and webhook handling), see the <a href="/developer-resources/ondemand-subscriptions">On-Demand Subscriptions Guide</a>.
</Note>

## Key Things to Know About Subscription Billing

<Warning>
  **Set the subscription period longer than the payment frequency.** If the subscription period equals the payment frequency (e.g. period = 1 month, frequency = 1 month), the subscription is valid for a **single cycle** and then moves to `expired` instead of renewing. For an ongoing monthly plan, set a long subscription period (e.g. 20 years) with a monthly payment frequency.
</Warning>

<Warning>
  **Currency locks at the first successful charge.** Always pass `billing_currency` **and** `billing_address.country` explicitly when creating the checkout. If omitted, they're detected from the customer's IP (Adaptive Currency), and once the subscription takes its first charge the currency is fixed for its lifetime. A customer who later travels can't switch it.
</Warning>

<Info>
  **Trials take a \$0 authorization, not a charge.** When a subscription has a trial, the trial start creates a **\$0 mandate authorization** to save the card; the first real charge happens when the trial ends. In the payments list a subscription in trial shows exactly one payment with `amount: 0`.
</Info>

<Info>
  **Subscription lifecycle:** `on_hold` = a renewal failed (recoverable: prompt the customer to update their payment method; dunning retries apply). `expired` = the term ended without renewal and **cannot be reactivated**. The customer must resubscribe. `cancelled` = ended by the customer or merchant. Most renewal failures are **issuer-side declines** (insufficient funds, card declined), not a Dodo error.
</Info>

<Warning>
  **Indian cards run on an RBI e-mandate.** Off-session charges (renewals and plan-change charges) can take **up to \~48 hours** to settle, and recurring auto-debits **above ₹15,000** require fresh customer authentication (so an upgrade crossing that limit can't ride the existing mandate). While one charge is still `processing`, a second charge on the same subscription fails with *"Cannot create new charge as previous payment is not successful yet."* Non-Indian cards confirm near-instantly.
</Warning>

<Tip>
  **Subscription charges have a \$1 minimum** (or currency equivalent). Amounts of `$0.01–$0.99` are rejected with `product_price: value out of range`; only `$0` is allowed, via an on-demand `mandate_only` setup.
</Tip>

## Related API Reference

<CardGroup>
  <Card title="Create Subscription" icon="code" href="/api-reference/subscriptions/post-subscriptions">
    API reference for creating subscription products and managing subscription lifecycle
  </Card>

  <Card title="Change Subscription Plan" icon="arrows-rotate" href="/api-reference/subscriptions/change-plan">
    API reference for upgrading, downgrading, or changing subscription plans with proration options
  </Card>

  <Card title="Update Payment Method" icon="credit-card" href="/api-reference/subscriptions/update-payment-method">
    API reference for updating payment methods and reactivating on-hold subscriptions
  </Card>

  <Card title="Patch Subscription" icon="pen" href="/api-reference/subscriptions/patch-subscriptions">
    API reference for updating subscription details and configuration
  </Card>
</CardGroup>


# Subscription Upgrade & Downgrade Guide
Source: https://docs.dodopayments.com/developer-resources/subscription-upgrade-downgrade

Learn how to change a customer's subscription plan, handle proration, and process webhooks reliably.

<CardGroup>
  <Card title="Change Plan API" icon="code" href="/api-reference/subscriptions/change-plan">
    Full API docs for updating subscriptions.
  </Card>

  <Card title="Plan Change Preview" icon="eye" href="/api-reference/subscriptions/preview-change-plan">
    See charge amounts before changing plans.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/subscription-integration-guide">
    Step-by-step subscription setup.
  </Card>
</CardGroup>

## What is a subscription upgrade or downgrade?

Changing plans lets you move a customer between subscription tiers or quantities. Use it to:

* Align pricing with usage or features
* Move from monthly to annual (or vice versa)
* Adjust quantity for seat-based products

<Info>
  Plan changes can trigger an immediate charge depending on the proration mode you choose.
</Info>

## When to use plan changes

* Upgrade when a customer needs more features, usage, or seats
* Downgrade when usage decreases
* Migrate users to a new product or price without cancelling their subscription

## Plan Change Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant A as Your App
    participant D as Dodo Payments
    C->>A: Request plan change
    A->>D: Preview change
    D-->>A: Charge breakdown
    A->>C: Show cost details
    C->>A: Confirm
    A->>D: Change plan API call
    D->>D: Prorate & charge
    D-->>A: Result + invoice
    D->>A: Webhooks (payment, plan_changed)
    A->>C: Plan updated
```

## Prerequisites

Before implementing subscription plan changes, ensure you have:

* A Dodo Payments merchant account with active subscription products
* API credentials (API key and webhook secret key) from the dashboard
* An existing active subscription to modify
* Webhook endpoint configured to handle subscription events

<Info>
  For detailed setup instructions, see our [Integration Guide](/developer-resources/integration-guide#dashboard-setup).
</Info>

## Step-by-Step Implementation Guide

Follow this comprehensive guide to implement subscription plan changes in your application:

<Steps>
  <Step title="Understand Plan Change Requirements">
    Before implementing, determine:

    * Which subscription products can be changed to which others
    * What proration mode fits your business model
    * How to handle failed plan changes gracefully
    * Which webhook events to track for state management

    <Tip>
      Test plan changes thoroughly in test mode before implementing in production.
    </Tip>
  </Step>

  <Step title="Choose Your Proration Strategy">
    Select the billing approach that aligns with your business needs:

    <Tabs>
      <Tab title="prorated_immediately">
        Best for: SaaS applications wanting to charge fairly for unused time

        * Calculates exact prorated amount based on remaining cycle time
        * Charges a prorated amount based on unused time remaining in the cycle
        * Provides transparent billing to customers
      </Tab>

      <Tab title="difference_immediately">
        Best for: Clear upgrade/downgrade scenarios

        * Upgrade: Charge immediate difference (e.g., $30→$80 = charge \$50)
        * Downgrade: Credit remaining value for future renewals
        * Simplifies billing logic and customer communication
      </Tab>

      <Tab title="full_immediately">
        Best for: When you want to reset the billing cycle

        * Charges full amount of new plan immediately
        * Ignores remaining time from old plan
        * Useful for annual to monthly transitions
      </Tab>

      <Tab title="do_not_bill">
        Best for: Free migrations, courtesy switches, or absorbing cost differences

        * No charges or credits calculated
        * Customer moves to the new plan immediately without any billing adjustment
        * Billing cycle remains unchanged
      </Tab>
    </Tabs>
  </Step>

  <Step title="Implement the Change Plan API">
    Use the Change Plan API to modify subscription details:

    <ParamField type="string">
      The ID of the active subscription to modify.
    </ParamField>

    <ParamField type="string">
      The new product ID to change the subscription to.
    </ParamField>

    <ParamField type="integer">
      Number of units for the new plan (for seat-based products).
    </ParamField>

    <ParamField type="string">
      How to handle immediate billing: `prorated_immediately`, `full_immediately`, `difference_immediately`, or `do_not_bill`.
    </ParamField>

    <ParamField type="array">
      Optional addons for the new plan. Leaving this empty removes any existing addons.
    </ParamField>

    <ParamField type="string">
      Controls behavior when the plan change payment fails:

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

      If not specified, uses the business-level default setting.
    </ParamField>

    <ParamField type="array">
      Optional **stacked** discount codes to apply to the new plan (max 20, applied in array order). Behavior depends on what you pass:

      * **Not provided / `null`** — existing discounts with `preserve_on_plan_change=true` are preserved if applicable to the new product.
      * **`[]` (empty array)** — removes all existing discounts from the subscription.
      * **`["CODE_A", "CODE_B", ...]`** — replaces any existing discounts with this stacked set.
    </ParamField>

    <ParamField type="string">
      **Deprecated** — prefer `discount_codes` for new integrations. This field still works for backward compatibility, but cannot be combined with `discount_codes` in the same request.
    </ParamField>

    <ParamField type="string">
      When to apply the plan change:

      * `immediately` (default): Apply the plan change right away
      * `next_billing_date`: Schedule the change for the next billing date. The customer retains their current plan until the billing period ends.

      Use `next_billing_date` for downgrades so customers keep their current plan benefits until the end of the billing period.
    </ParamField>
  </Step>

  <Step title="Handle Webhook Events">
    Set up webhook handling to track plan change outcomes:

    * `subscription.active`: Plan change successful, subscription updated
    * `subscription.plan_changed`: Subscription plan changed (upgrade/downgrade/addon update)
    * `subscription.on_hold`: Plan change charge failed, subscription paused
    * `payment.succeeded`: Immediate charge for plan change succeeded
    * `payment.failed`: Immediate charge failed

    <Warning>
      Always verify webhook signatures and implement idempotent event processing.
    </Warning>
  </Step>

  <Step title="Update Your Application State">
    Based on webhook events, update your application:

    * Grant/revoke features based on new plan
    * Update customer dashboard with new plan details
    * Send confirmation emails about plan changes
    * Log billing changes for audit purposes
  </Step>

  <Step title="Test and Monitor">
    Thoroughly test your implementation:

    * Test all proration modes with different scenarios
    * Verify webhook handling works correctly
    * Monitor plan change success rates
    * Set up alerts for failed plan changes

    <Check>
      Your subscription plan change implementation is now ready for production use.
    </Check>
  </Step>
</Steps>

## Preview Plan Changes

Before committing to a plan change, use the Preview API to show customers exactly what they'll be charged:

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    const preview = await client.subscriptions.previewChangePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately'
    });

    // Show customer the charge before confirming
    console.log('Immediate charge:', preview.immediate_charge.summary);
    console.log('New plan details:', preview.new_plan);
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    preview = client.subscriptions.preview_change_plan(
        subscription_id="sub_123",
        product_id="pdt_pro",
        quantity=1,
        proration_billing_mode="prorated_immediately"
    )

    # Show customer the charge before confirming
    print("Immediate charge:", preview.immediate_charge.summary)
    print("New plan details:", preview.new_plan)
    ```
  </Tab>
</Tabs>

<Tip>
  Use the preview API to build confirmation dialogs that show customers the exact amount they'll be charged before they confirm a plan change.
</Tip>

## Change Plan API

Use the Change Plan API to modify product, quantity, and proration behavior for an active subscription.

### Quick start examples

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    import DodoPayments from 'dodopayments';

    const client = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: 'test_mode', // defaults to 'live_mode'
    });

    async function changePlan() {
      // change-plan returns 200 with an empty body.
      await client.subscriptions.changePlan('sub_123', {
        product_id: 'pdt_new',
        quantity: 3,
        proration_billing_mode: 'prorated_immediately',
        on_payment_failure: 'prevent_change', // Optional: control behavior on payment failure
      });
      console.log('Plan change accepted; awaiting webhooks');
    }

    changePlan();
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    import os
    from dodopayments import DodoPayments

    client = DodoPayments(
        bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
        environment="test_mode",  # defaults to "live_mode"
    )

    # change_plan returns 200 with an empty body.
    client.subscriptions.change_plan(
        subscription_id="sub_123",
        product_id="pdt_new",
        quantity=3,
        proration_billing_mode="prorated_immediately",
        on_payment_failure="prevent_change",  # Optional: control behavior on payment failure
    )
    print("Plan change accepted; awaiting webhooks")
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    package main

    import (
      "context"
      "fmt"
      "github.com/dodopayments/dodopayments-go"
      "github.com/dodopayments/dodopayments-go/option"
    )

    func main() {
      client := dodopayments.NewClient(option.WithBearerToken("YOUR_TOKEN"))
      // ChangePlan returns no response body; a nil error means the change succeeded.
      err := client.Subscriptions.ChangePlan(context.TODO(), "sub_123", dodopayments.SubscriptionChangePlanParams{
        UpdateSubscriptionPlanReq: dodopayments.UpdateSubscriptionPlanReqParam{
          ProductID:            dodopayments.F("pdt_new"),
          Quantity:             dodopayments.F(int64(3)),
          ProrationBillingMode: dodopayments.F(dodopayments.UpdateSubscriptionPlanReqProrationBillingModeProratedImmediately),
          OnPaymentFailure:     dodopayments.F(dodopayments.UpdateSubscriptionPlanReqOnPaymentFailurePreventChange), // Optional
        },
      })
      if err != nil { panic(err) }
      fmt.Println("Plan change applied")
    }
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
      -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "product_id": "pdt_new",
        "quantity": 3,
        "proration_billing_mode": "prorated_immediately",
        "on_payment_failure": "prevent_change"
      }'
    ```
  </Tab>
</Tabs>

A successful plan change returns `200 OK` with an **empty response body**.

<Note>
  Because there is no response payload, always rely on webhook events (e.g. <code>subscription.plan\_changed</code>, <code>payment.succeeded</code>, <code>payment.failed</code>) to confirm the outcome, or re-read the subscription with <code>GET /subscriptions/\{subscription\_id}</code>.
</Note>

<Warning>
  If the immediate charge fails, the subscription may move to `subscription.on_hold` until payment succeeds.
</Warning>

## Managing Addons

When changing subscription plans, you can also modify addons:

```javascript theme={null}
// Add addons to the new plan
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [
    { addon_id: 'addon_123', quantity: 2 }
  ]
});

// Remove all existing addons
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [] // Empty array removes all existing addons
});
```

<Info>
  Addons are included in the proration calculation and will be charged according to the selected proration mode.
</Info>

## Applying Discount Codes

You can apply one or more **stacked discount codes** when changing subscription plans (max 20, applied in array order). This is useful for offering promotional pricing on upgrades or migrations.

<Tabs>
  <Tab title="Node.js SDK">
    ```javascript theme={null}
    // Apply stacked discount codes during plan change
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately',
      discount_codes: ['UPGRADE20']
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    # Apply stacked discount codes during plan change
    client.subscriptions.change_plan(
        subscription_id="sub_123",
        product_id="pdt_pro",
        quantity=1,
        proration_billing_mode="prorated_immediately",
        discount_codes=["UPGRADE20"]
    )
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    curl -X POST "$DODO_API_BASE/subscriptions/sub_123/change-plan" \
      -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "product_id": "pdt_pro",
        "quantity": 1,
        "proration_billing_mode": "prorated_immediately",
        "discount_codes": ["UPGRADE20"]
      }'
    ```
  </Tab>
</Tabs>

### Discount behavior on plan change

| `discount_codes` value      | Behavior                                                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Not provided / `null`       | Existing discounts with `preserve_on_plan_change=true` are automatically preserved if applicable to the new product. |
| `[]` (empty array)          | **All** existing discounts are removed from the subscription.                                                        |
| `["CODE_A", "CODE_B", ...]` | Replaces any existing discounts with this stacked set, validated and applied in array order.                         |

<Info>
  The singular `discount_code` field on this endpoint is **deprecated** but still works for backward compatibility — existing integrations don't need to change immediately. It cannot be combined with `discount_codes` in the same request. Migrate to the array form when convenient.
</Info>

<Tip>
  Use the [Preview Plan Change API](/api-reference/subscriptions/preview-change-plan) with `discount_codes` to show customers exactly how much they'll save before confirming the plan change.
</Tip>

## Proration modes

Choose how to bill the customer when changing plans:

#### `prorated_immediately`

* Charges for the partial difference in the current cycle
* If in trial, charges immediately and switches to the new plan now
* Downgrade: may generate a prorated credit applied to future renewals

#### `full_immediately`

* Charges the full amount of the new plan immediately
* Ignores remaining time from the old plan

<Info>
  Credits created by downgrades using <code>difference\_immediately</code> are subscription-scoped and distinct from <a href="/features/credit-based-billing">Credit-Based Billing</a> entitlements. They automatically apply to future renewals of the same subscription and are not transferable between subscriptions.
</Info>

#### `difference_immediately`

* Upgrade: immediately charge the price difference between old and new plans
* Downgrade: add remaining value as internal credit to the subscription and auto-apply on renewals

#### `do_not_bill`

* No charges or credits are calculated
* Customer switches to the new plan immediately without any billing adjustment
* Billing cycle remains unchanged
* Best for courtesy migrations, free plan switches, or absorbing cost differences

| Feature              | `prorated_immediately`                 | `difference_immediately`            | `full_immediately`              | `do_not_bill`                        |
| -------------------- | -------------------------------------- | ----------------------------------- | ------------------------------- | ------------------------------------ |
| **Upgrade charge**   | Prorated difference for remaining days | Full price difference between plans | Full new plan price             | No charge                            |
| **Downgrade credit** | Prorated credit for remaining days     | Full price difference as credit     | No credit                       | No credit                            |
| **Billing cycle**    | Resets to today                        | Resets to today                     | Resets to today                 | Unchanged                            |
| **Trial behavior**   | Ends trial, charges immediately        | Ends trial, charges immediately     | Ends trial, charges full amount | Ends trial, no charge                |
| **Best for**         | Fair time-based billing                | Simple upgrade/downgrade math       | Resetting billing cycles        | Free migrations or courtesy switches |
| **Complexity**       | Medium (day calculation)               | Low (simple subtraction)            | Low (full charge)               | None                                 |

```mermaid theme={null}
flowchart TD
    A{Need fair day-by-day billing?} -->|Yes| B[prorated_immediately]
    A -->|No| C{Need to reset billing cycle?}
    C -->|Yes| D[full_immediately]
    C -->|No| E{Skip billing entirely?}
    E -->|Yes| F[do_not_bill]
    E -->|No| G[difference_immediately]
```

### Example scenarios

Use these canonical numbers consistently:

* Current plan: **Basic** at **\$30/month**
* Upgrade target: **Pro** at **\$80/month**
* Downgrade target (from Pro): **Starter** at **\$20/month**
* Billing cycle: **30 days**, started on **January 1**
* Plan change happens on **January 16** (15 days remaining, 15 days used)

<AccordionGroup>
  <Accordion title="Upgrade: Basic ($30) → Pro ($80) with prorated_immediately">
    ```
    Step 1: Calculate unused credit from current plan
      Unused days = 15 out of 30 days
      Credit = $30 × (15/30) = $15.00

    Step 2: Calculate prorated cost of new plan
      Remaining days = 15 out of 30 days
      New plan cost = $80 × (15/30) = $40.00

    Step 3: Calculate immediate charge
      Charge = New plan cost − Credit
      Charge = $40.00 − $15.00 = $25.00

    → Customer pays $25.00 now
    → Billing cycle resets to today (January 16)
    → Next renewal (Feb 15): $80.00/month
    ```

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately'
    })
    ```
  </Accordion>

  <Accordion title="Downgrade: Pro ($80) → Starter ($20) with prorated_immediately">
    ```
    Step 1: Calculate unused credit from current plan
      Unused days = 15 out of 30 days
      Credit = $80 × (15/30) = $40.00

    Step 2: Calculate prorated cost of new plan
      Remaining days = 15 out of 30 days
      New plan cost = $20 × (15/30) = $10.00

    Step 3: Calculate credit balance
      Credit = $40.00 − $10.00 = $30.00

    → No charge — $30.00 credit added to subscription
    → Billing cycle resets to today (January 16)
    → Credit auto-applies to future renewals
    → Next renewal (Feb 15): $20.00 − $20.00 (from credit) = $0.00 ($10.00 credit remaining)
    → Following renewal (Mar 15): $20.00 − $10.00 remaining credit = $10.00
    ```

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_starter',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately'
    })
    ```
  </Accordion>

  <Accordion title="Upgrade: Basic ($30) → Pro ($80) with difference_immediately">
    ```
    Immediate charge = New plan price − Old plan price
                     = $80 − $30
                     = $50.00

    → Customer pays $50.00 now (regardless of cycle position)
    → Billing cycle resets to today (January 16)
    → Next renewal (Feb 15): $80.00/month
    ```

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'difference_immediately'
    })
    ```
  </Accordion>

  <Accordion title="Downgrade: Pro ($80) → Starter ($20) with difference_immediately">
    ```
    Credit = Old plan price − New plan price
           = $80 − $20
           = $60.00

    → No charge — $60.00 credit added to subscription
    → Credit auto-applies to future renewals
    → Next renewal: $20.00 − $20.00 (from credit) = $0.00
    → Following renewal: $20.00 − $20.00 (from credit) = $0.00
    → Third renewal: $20.00 − $20.00 (from remaining credit) = $0.00
    ```

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_starter',
      quantity: 1,
      proration_billing_mode: 'difference_immediately'
    })
    ```
  </Accordion>

  <Accordion title="Upgrade: Basic ($30) → Pro ($80) with full_immediately">
    ```
    Immediate charge = Full new plan price = $80.00

    → Customer pays $80.00 now
    → No credit for unused time on old plan
    → Billing cycle resets to today (January 16)
    → Next renewal: February 16 at $80.00/month
    ```

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'full_immediately'
    })
    ```
  </Accordion>

  <Accordion title="Mid-cycle upgrade with add-ons using prorated_immediately">
    ```
    Current: Basic plan ($30/month), no add-ons
    New: Pro plan ($80/month) + Extra Seats add-on ($10/seat × 3 seats = $30/month)
    Change on day 16 of 30 (15 days remaining)

    Step 1: Credit from current plan
      Credit = $30 × (15/30) = $15.00

    Step 2: Prorated cost of new plan + add-ons
      New plan = $80 × (15/30) = $40.00
      Add-ons = $30 × (15/30) = $15.00
      Total new = $55.00

    Step 3: Immediate charge
      Charge = $55.00 − $15.00 = $40.00

    → Customer pays $40.00 now
    → Next renewal: $80.00 + $30.00 = $110.00/month
    ```

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately',
      addons: [
        { addon_id: 'addon_seats', quantity: 3 }
      ]
    })
    ```
  </Accordion>
</AccordionGroup>

### How each mode processes billing

```mermaid theme={null}
flowchart LR
    A[Plan Change] --> B{Proration Mode}
    B -->|prorated| C[Calculate remaining days]
    C --> D[Charge prorated diff]
    D --> E[Reset billing date]
    B -->|difference| F[Price difference]
    F -->|Upgrade| G[Charge diff]
    F -->|Downgrade| H[Add credit]
    G --> E
    H --> E
    B -->|full| I[Charge full price]
    I --> E
    B -->|do_not_bill| J[No charge / no credit]
    J --> K[Keep billing date]
```

<Tip>
  Pick `prorated_immediately` for fair-time accounting; choose `full_immediately` to restart billing; use `difference_immediately` for simple upgrades and automatic credit on downgrades; or use `do_not_bill` to switch plans without any billing adjustment.
</Tip>

## Handling Payment Failures

Control what happens when a plan change payment fails using the `on_payment_failure` parameter.

### Payment Failure Modes

<Tabs>
  <Tab title="prevent_change (Recommended for critical upgrades)">
    **Behavior**: Keep the subscription on its current plan until payment succeeds.

    * Plan change is marked as "pending"
    * Customer retains access to their current plan
    * Subscription moves to `active` state only after successful payment
    * Useful when you want to ensure payment before granting upgraded features

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately',
      on_payment_failure: 'prevent_change'
    });
    ```
  </Tab>

  <Tab title="apply_change (Default)">
    **Behavior**: Apply the plan change immediately regardless of payment outcome.

    * Plan change is applied even if payment fails
    * Customer gets immediate access to the new plan
    * Subscription may move to `on_hold` if payment fails
    * Good for non-critical upgrades or when you trust the customer

    ```javascript theme={null}
    await client.subscriptions.changePlan('sub_123', {
      product_id: 'pdt_pro',
      quantity: 1,
      proration_billing_mode: 'prorated_immediately',
      on_payment_failure: 'apply_change' // This is the default
    });
    ```
  </Tab>
</Tabs>

<Info>
  If not specified, the `on_payment_failure` parameter uses your business-level default setting configured in the dashboard.
</Info>

### When to Use Each Mode

| Scenario                       | Recommended Mode | Reason                                |
| ------------------------------ | ---------------- | ------------------------------------- |
| Upgrading to premium features  | `prevent_change` | Ensure payment before granting access |
| Quantity increase (more seats) | `prevent_change` | Prevent usage without payment         |
| Downgrading plans              | `apply_change`   | Customer is reducing spend            |
| Trusted enterprise customers   | `apply_change`   | Lower risk of non-payment             |
| Trial to paid conversion       | `prevent_change` | Critical payment moment               |

## Business & Collection Defaults

Instead of passing proration parameters on every plan change, you can set **default upgrade & downgrade behavior** once at the business level. These defaults apply to all customer-portal plan changes, and can be **overridden per product collection**.

There are separate defaults for upgrades and downgrades:

| Setting                         | Field (upgrade / downgrade)                                                 | Default (upgrade)        | Default (downgrade)      |
| ------------------------------- | --------------------------------------------------------------------------- | ------------------------ | ------------------------ |
| When the new plan starts        | `effective_at_on_upgrade` / `effective_at_on_downgrade`                     | `immediately`            | `next_billing_date`      |
| How the customer is charged     | `proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade` | `difference_immediately` | `difference_immediately` |
| If the customer's payment fails | `on_payment_failure`                                                        | `apply_change`           | `apply_change`           |

Configure business defaults under **Settings → Subscriptions**, and collection overrides on each product collection. Each collection field is independent — leave it unset to **inherit from the business default**, or set a value to override it for that collection only.

### Resolution order

For any given plan change, each setting resolves in this order:

```
per-request value (Change Plan API) → collection field (if set) → business field → system default
```

<Info>
  A value passed explicitly to the [Change Plan API](/api-reference/subscriptions/change-plan) always wins. The business and collection defaults only take effect when no explicit value is supplied — which is the case for all plan changes initiated from the customer portal.
</Info>

<Tip>
  A common setup: keep upgrades `immediately` + `difference_immediately` so customers pay the difference and get access right away, and keep downgrades on `next_billing_date` so customers keep their current plan until the cycle ends.
</Tip>

## Handling webhooks

Track subscription state through webhooks to confirm plan changes and payments.

### Event types to handle

* `subscription.active`: subscription activated
* `subscription.plan_changed`: subscription plan changed (upgrade/downgrade/addon changes)
* `subscription.on_hold`: charge failed, subscription paused
* `subscription.renewed`: renewal succeeded
* `payment.succeeded`: payment for plan change or renewal succeeded
* `payment.failed`: payment failed

<Info>
  We recommend driving business logic from subscription events and using payment events for confirmation and reconciliation.
</Info>

### Verify signatures and handle intents

<Tabs>
  <Tab title="Next.js Route Handler">
    ```javascript theme={null}
    import { NextRequest, NextResponse } from 'next/server';

    export async function POST(req) {
      const webhookId = req.headers.get('webhook-id');
      const webhookSignature = req.headers.get('webhook-signature');
      const webhookTimestamp = req.headers.get('webhook-timestamp');
      const secret = process.env.DODO_WEBHOOK_SECRET;

      const payload = await req.text();
      // verifySignature is a placeholder – in production, use a Standard Webhooks library
      const { valid, event } = await verifySignature(
        payload,
        { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
        secret
      );
      if (!valid) return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });

      switch (event.type) {
        case 'subscription.active':
          // mark subscription active in your DB
          break;
        case 'subscription.plan_changed':
          // refresh entitlements and reflect the new plan in your UI
          break;
        case 'subscription.on_hold':
          // notify user to update payment method
          break;
        case 'subscription.renewed':
          // extend access window
          break;
        case 'payment.succeeded':
          // reconcile payment for plan change
          break;
        case 'payment.failed':
          // log and alert
          break;
        default:
          // ignore unknown events
          break;
      }

      return NextResponse.json({ received: true });
    }
    ```
  </Tab>

  <Tab title="Express.js">
    ```javascript theme={null}
    import express from 'express';

    const app = express();
    app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
      const webhookId = req.header('webhook-id');
      const webhookSignature = req.header('webhook-signature');
      const webhookTimestamp = req.header('webhook-timestamp');
      const secret = process.env.DODO_WEBHOOK_SECRET;
      const payload = req.body.toString('utf8');

      const { valid, event } = await verifySignature(
        payload,
        { id: webhookId, signature: webhookSignature, timestamp: webhookTimestamp },
        secret
      );
      if (!valid) return res.status(400).send('Invalid signature');

      // handle events like above
      res.json({ received: true });
    });

    app.listen(3000);
    ```
  </Tab>
</Tabs>

<Note>
  For detailed payload schemas, see the <a href="/developer-resources/webhooks/intents/subscription">Subscription webhook payloads</a> and <a href="/developer-resources/webhooks/intents/payment">Payment webhook payloads</a>.
</Note>

## Best Practices

Follow these recommendations for reliable subscription plan changes:

### Plan Change Strategy

* **Test thoroughly**: Always test plan changes in test mode before production
* **Choose proration carefully**: Select the proration mode that aligns with your business model
* **Handle failures gracefully**: Implement proper error handling and retry logic
* **Monitor success rates**: Track plan change success/failure rates and investigate issues

### Webhook Implementation

* **Verify signatures**: Always validate webhook signatures to ensure authenticity
* **Implement idempotency**: Handle duplicate webhook events gracefully
* **Process asynchronously**: Don't block webhook responses with heavy operations
* **Log everything**: Maintain detailed logs for debugging and audit purposes

### User Experience

* **Communicate clearly**: Inform customers about billing changes and timing
* **Provide confirmations**: Send email confirmations for successful plan changes
* **Handle edge cases**: Consider trial periods, prorations, and failed payments
* **Update UI immediately**: Reflect plan changes in your application interface

## Common Issues and Solutions

Resolve typical problems encountered during subscription plan changes:

<AccordionGroup>
  <Accordion title="Charge created but subscription not updated">
    **Symptoms**: API call succeeds but subscription remains on old plan

    **Common causes**:

    * Webhook processing failed or was delayed
    * Application state not updated after receiving webhooks
    * Database transaction issues during state update

    **Solutions**:

    * Implement robust webhook handling with retry logic
    * Use idempotent operations for state updates
    * Add monitoring to detect and alert on missed webhook events
    * Verify webhook endpoint is accessible and responding correctly
  </Accordion>

  <Accordion title="Credits not applied after downgrade">
    **Symptoms**: Customer downgrades but doesn't see credit balance

    **Common causes**:

    * Proration mode expectations: downgrades credit the full plan price difference with `difference_immediately`, while `prorated_immediately` creates a prorated credit based on remaining time in the cycle
    * Credits are subscription-specific and don't transfer between subscriptions
    * Credit balance not visible in customer dashboard

    **Solutions**:

    * Use `difference_immediately` for downgrades when you want automatic credits
    * Explain to customers that credits apply to future renewals of the same subscription
    * Implement customer portal to show credit balances
    * Check next invoice preview to see applied credits
  </Accordion>

  <Accordion title="Webhook signature verification fails">
    **Symptoms**: Webhook events rejected due to invalid signature

    **Common causes**:

    * Incorrect webhook secret key
    * Raw request body modified before signature verification
    * Wrong signature verification algorithm

    **Solutions**:

    * Verify you're using the correct `DODO_WEBHOOK_SECRET` from dashboard
    * Read raw request body before any JSON parsing middleware
    * Use the standard webhook verification library for your platform
    * Test webhook signature verification in development environment
  </Accordion>

  <Accordion title="Plan change fails with 422 error">
    **Symptoms**: API returns 422 Unprocessable Entity error

    **Common causes**:

    * Invalid subscription ID or product ID
    * Subscription not in active state
    * Missing required parameters
    * Product not available for plan changes

    **Solutions**:

    * Verify subscription exists and is active
    * Check product ID is valid and available
    * Ensure all required parameters are provided
    * Review API documentation for parameter requirements
  </Accordion>

  <Accordion title="Immediate charge fails during plan change">
    **Symptoms**: Plan change initiated but immediate charge fails

    **Common causes**:

    * Insufficient funds on customer's payment method
    * Payment method expired or invalid
    * Bank declined the transaction
    * Fraud detection blocked the charge

    **Solutions**:

    * Handle `payment.failed` webhook events appropriately
    * Notify customer to update payment method
    * Implement retry logic for temporary failures
    * Consider allowing plan changes with failed immediate charges
  </Accordion>

  <Accordion title="Subscription on hold after plan change">
    **Symptoms**: Plan change charge fails and subscription moves to `on_hold` state

    **What happens**:
    When a plan change charge fails, the subscription is automatically placed in `on_hold` state. The subscription will not renew automatically until the payment method is updated.

    **Solution**: Update the payment method to reactivate the subscription

    To reactivate a subscription from `on_hold` state after a failed plan change:

    1. **Update the payment method** using the Update Payment Method API
    2. **Automatic charge creation**: The API automatically creates a charge for remaining dues
    3. **Invoice generation**: An invoice is generated for the charge
    4. **Payment processing**: The payment is processed using the new payment method
    5. **Reactivation**: Upon successful payment, the subscription is reactivated to `active` state

    <CodeGroup>
      ```javascript Node.js theme={null}
      // Reactivate subscription from on_hold after failed plan change
      async function reactivateAfterFailedPlanChange(subscriptionId) {
        // Update payment method - automatically creates charge for remaining dues
        const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
          payment_method: { type: 'new', return_url: 'https://example.com/return' }
        });
        
        if (response.payment_id) {
          console.log('Charge created for remaining dues:', response.payment_id);
          console.log('Payment link:', response.payment_link);
          
          // Redirect customer to payment_link to complete payment
          // Monitor webhooks for:
          // 1. payment.succeeded - charge succeeded
          // 2. subscription.active - subscription reactivated
        }
        
        return response;
      }

      // Or use existing payment method if available
      async function reactivateWithExistingPaymentMethod(subscriptionId, paymentMethodId) {
        const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
          payment_method: { type: 'existing', payment_method_id: paymentMethodId }
        });
        
        // Monitor webhooks for payment.succeeded and subscription.active
        return response;
      }
      ```

      ```python Python theme={null}
      # Reactivate subscription from on_hold after failed plan change
      def reactivate_after_failed_plan_change(subscription_id):
          # Update payment method - automatically creates charge for remaining dues
          response = client.subscriptions.update_payment_method(
              subscription_id=subscription_id,
              payment_method={"type": "new", "return_url": "https://example.com/return"},
          )
          
          if response.payment_id:
              print("Charge created for remaining dues:", response.payment_id)
              print("Payment link:", response.payment_link)
              
              # Redirect customer to payment_link to complete payment
              # Monitor webhooks for:
              # 1. payment.succeeded - charge succeeded
              # 2. subscription.active - subscription reactivated
          
          return response

      # Or use existing payment method if available
      def reactivate_with_existing_payment_method(subscription_id, payment_method_id):
          response = client.subscriptions.update_payment_method(
              subscription_id=subscription_id,
              payment_method={"type": "existing", "payment_method_id": payment_method_id},
          )
          
          # Monitor webhooks for payment.succeeded and subscription.active
          return response
      ```
    </CodeGroup>

    **Webhook events to monitor**:

    * `subscription.on_hold`: Subscription placed on hold (received when plan change charge fails)
    * `payment.succeeded`: Payment for remaining dues succeeded (after updating payment method)
    * `subscription.active`: Subscription reactivated after successful payment

    **Best practices**:

    * Notify customers immediately when a plan change charge fails
    * Provide clear instructions on how to update their payment method
    * Monitor webhook events to track reactivation status
    * Consider implementing automatic retry logic for temporary payment failures

    <Card title="Update Payment Method API Reference" icon="code" href="/api-reference/subscriptions/update-payment-method">
      View the complete API documentation for updating payment methods and reactivating subscriptions.
    </Card>
  </Accordion>
</AccordionGroup>

## Testing Your Implementation

Follow these steps to thoroughly test your subscription plan change implementation:

<Steps>
  <Step title="Set up test environment">
    * Use test API keys and test products
    * Create test subscriptions with different plan types
    * Configure test webhook endpoint
    * Set up monitoring and logging
  </Step>

  <Step title="Test different proration modes">
    * Test `prorated_immediately` with various billing cycle positions
    * Test `difference_immediately` for upgrades and downgrades
    * Test `full_immediately` to reset billing cycles
    * Test `do_not_bill` for no-charge/no-credit plan switches
    * Verify credit calculations are correct
  </Step>

  <Step title="Test webhook handling">
    * Verify all relevant webhook events are received
    * Test webhook signature verification
    * Handle duplicate webhook events gracefully
    * Test webhook processing failure scenarios
  </Step>

  <Step title="Test error scenarios">
    * Test with invalid subscription IDs
    * Test with expired payment methods
    * Test network failures and timeouts
    * Test with insufficient funds
  </Step>

  <Step title="Monitor in production">
    * Set up alerts for failed plan changes
    * Monitor webhook processing times
    * Track plan change success rates
    * Review customer support tickets for plan change issues
  </Step>
</Steps>

## Error Handling

Handle common API errors gracefully in your implementation:

### HTTP Status Codes

<AccordionGroup>
  <Accordion title="200 OK">
    Plan change request processed successfully. The response body is empty. If `on_payment_failure=prevent_change`, the plan change stays pending until payment succeeds.
  </Accordion>

  <Accordion title="400 Bad Request">
    Invalid request parameters. Check that all required fields are provided and properly formatted.
  </Accordion>

  <Accordion title="401 Unauthorized">
    Invalid or missing API key. Verify your `DODO_PAYMENTS_API_KEY` is correct and has proper permissions.
  </Accordion>

  <Accordion title="404 Not Found">
    Subscription ID not found or doesn't belong to your account.
  </Accordion>

  <Accordion title="409 Conflict">
    A pending plan change already exists for this subscription (`PendingPlanChangeExists`). Cancel the scheduled change with `DELETE /subscriptions/{subscription_id}/change-plan/scheduled` before submitting a new one.
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    The subscription is inactive or on-demand; plan change is not supported.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    Server error occurred. Retry the request after a brief delay.
  </Accordion>
</AccordionGroup>

### Error Response Format

```json theme={null}
{
  "error": {
    "code": "subscription_not_found",
    "message": "The subscription with ID 'sub_123' was not found",
    "details": {
      "subscription_id": "sub_123"
    }
  }
}
```

## Next steps

* Review the <a href="/api-reference/subscriptions/change-plan">Change Plan API</a>
* Explore <a href="/features/credit-based-billing">Credit-Based Billing</a>
* Implement alerts for `subscription.on_hold`
* Check out our <a href="/developer-resources/webhooks">Webhook Integration Guide</a>


# Supabase Boilerplate
Source: https://docs.dodopayments.com/developer-resources/supabase-boilerplate

Use the official Next.js + Supabase + Dodo Payments subscription starter to ship subscriptions fast. Includes auth, database schema, webhook handler, and pricing UI.

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-supabase-subscription-starter">
    Minimal Next.js + Supabase + Dodo Payments subscription boilerplate
  </Card>

  <Card title="Live Demo" icon="rocket" href="https://dodopayments-supabase-nextjs.vercel.app">
    Explore the deployed demo
  </Card>
</CardGroup>

## Overview

A production-ready boilerplate for subscriptions using Next.js 15, React 19, Supabase, Drizzle ORM, and Dodo Payments. It ships with Google OAuth, subscription checkout, webhook handling, database schema, and a basic dashboard.

<Info>
  If you need only route handlers for an existing app, see the dedicated adaptors: <a href="/developer-resources/nextjs-adaptor">Next.js Adaptor</a> and <a href="/developer-resources/express-adaptor">Express Adaptor</a>.
</Info>

## Prerequisites

* Node.js 18+ (or Bun 1.0+)
* Supabase project (URL, Anon key, Service role key, Database URL)
* Dodo Payments account (API key, Webhook secret)
* Google Cloud OAuth client (Client ID and Secret)

## Quickstart

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/dodopayments/dodo-supabase-subscription-starter.git
    cd dodo-supabase-subscription-starter
    # choose one
    bun install
    # or
    npm install
    # or
    pnpm install
    ```
  </Step>

  <Step title="Create Supabase project">
    Create a Supabase project and copy:

    * NEXT\_PUBLIC\_SUPABASE\_URL
    * NEXT\_PUBLIC\_SUPABASE\_ANON\_KEY
    * SUPABASE\_SERVICE\_ROLE\_KEY
    * DATABASE\_URL (Connection string)
  </Step>

  <Step title="Configure Google OAuth">
    Set the redirect URI to: `https://[your-project-ref].supabase.co/auth/v1/callback` in Google Cloud, then enable Google provider in Supabase Auth using your Client ID and Secret.
  </Step>

  <Step title="Configure Dodo Payments">
    Generate an API key and Webhook secret from the Dodo dashboard. Set environment to `test_mode` while developing.
  </Step>

  <Step title="Create .env.local">
    ```env theme={null}
    # Supabase
    NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
    NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
    SUPABASE_SERVICE_ROLE_KEY=your-service-role

    # Database
    DATABASE_URL=postgresql://postgres:[password]@db.[project-ref].supabase.co:5432/postgres

    # Dodo Payments
    DODO_PAYMENTS_API_KEY=your-dodo-api-key
    DODO_WEBHOOK_SECRET=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT=test_mode
    ```

    <Warning>
      Never commit secrets. Use environment variables in deployment environments.
    </Warning>
  </Step>

  <Step title="Provision database schema">
    ```bash theme={null}
    bun run db:push
    # or
    npm run db:push
    # or
    pnpm run db:push
    ```

    <Check>
      Tables created: `users`, `subscriptions`, `payments`.
    </Check>
  </Step>

  <Step title="Deploy webhook function">
    ```bash theme={null}
    # login (one-time)
    bunx supabase login
    # or
    npx supabase login

    # deploy the edge function
    bun run deploy:webhook --project-ref [your-project-ref]
    # or
    npm run deploy:webhook -- --project-ref [your-project-ref]
    # or
    pnpm run deploy:webhook --project-ref [your-project-ref]
    ```

    ```bash cURL theme={null}
    curl -X POST \
      'https://[your-project-ref].supabase.co/functions/v1/dodo-webhook' \
      -H 'Content-Type: application/json' \
      -H 'Dodo-Signature: <signature>' \
      -d '{"type":"payment.succeeded","data":{}}'
    ```
  </Step>

  <Step title="Add webhook in Dodo Payments">
    Set endpoint URL to:

    ```text theme={null}
    https://[your-project-ref].supabase.co/functions/v1/dodo-webhook
    ```

    Select payment and subscription events.
  </Step>

  <Step title="Create products and features">
    In Dodo dashboard → Products → Create Product. Optionally add metadata:

    ```json theme={null}
    {
      "features": ["Feature 1", "Feature 2", "Feature 3"]
    }
    ```

    The pricing UI reads this `features` array and renders it dynamically.
  </Step>

  <Step title="Run the dev server">
    ```bash theme={null}
    bun run dev
    # or
    npm run dev
    # or
    pnpm run dev
    ```

    Open [http://localhost:3000](http://localhost:3000).
  </Step>
</Steps>

## What’s included

* Authentication via Supabase (Google OAuth configured)
* Subscription checkout via Dodo Payments
* Supabase Edge Function for webhooks (`dodo-webhook`)
* Drizzle ORM schema and migrations
* Dashboard with invoices, subscription status, and plan features

<Tip>
  Keep `DODO_PAYMENTS_ENVIRONMENT` as `test_mode` until you complete end-to-end tests.
</Tip>

## Key files and paths

<Tabs>
  <Tab title="Edge Function">
    ```text theme={null}
    supabase/functions/dodo-webhook/
      index.ts            # webhook handler verifying signatures
      deno.json           # permissions
    ```
  </Tab>

  <Tab title="Next.js routes">
    ```text theme={null}
    app/(marketing)/*     # landing + pricing UI
    app/(dashboard)/*     # protected pages
    app/api/*             # server actions & helpers
    ```
  </Tab>

  <Tab title="Database (Drizzle)">
    ```text theme={null}
    lib/db/schema.ts      # users, subscriptions, payments
    lib/db/index.ts       # client
    ```
  </Tab>
</Tabs>

## Environment variables

<AccordionGroup>
  <Accordion title="Supabase">
    ```env theme={null}
    NEXT_PUBLIC_SUPABASE_URL=
    NEXT_PUBLIC_SUPABASE_ANON_KEY=
    SUPABASE_SERVICE_ROLE_KEY=
    DATABASE_URL=
    ```
  </Accordion>

  <Accordion title="Dodo Payments">
    ```env theme={null}
    DODO_PAYMENTS_API_KEY=
    DODO_WEBHOOK_SECRET=
    DODO_PAYMENTS_ENVIRONMENT=test_mode|live_mode
    ```
  </Accordion>

  <Accordion title="Google OAuth">
    ```env theme={null}
    GOOGLE_CLIENT_ID=
    GOOGLE_CLIENT_SECRET=
    ```
  </Accordion>
</AccordionGroup>

## Verification and troubleshooting

<AccordionGroup>
  <Accordion title="Webhook signature invalid (401)">
    * Ensure `DODO_WEBHOOK_SECRET` matches the value from Dodo dashboard
    * Confirm you deployed the latest `dodo-webhook` function
    * Verify the header name is correct in your function (Dodo-Signature)
  </Accordion>

  <Accordion title="Database push fails">
    * Check `DATABASE_URL` syntax and Supabase network egress
    * Wait \~2–3 minutes after project creation before first push
  </Accordion>

  <Accordion title="OAuth redirect mismatch">
    * Redirect URI must be `https://[ref].supabase.co/auth/v1/callback`
    * Ensure the same in Google Cloud and Supabase Auth provider
  </Accordion>
</AccordionGroup>

<Check>
  You now have a working subscription SaaS scaffolded with Supabase and Dodo Payments.
</Check>

<Info>
  Original repository and detailed steps: <a href="https://github.com/dodopayments/dodo-supabase-subscription-starter">dodo-supabase-subscription-starter</a>.
</Info>


# SvelteKit Adaptor
Source: https://docs.dodopayments.com/developer-resources/sveltekit-adaptor

Learn how to integrate Dodo Payments with your SvelteKit App Router project using our SvelteKit Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.

<CardGroup>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrate Dodo Payments checkout into your SvelteKit app.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Allow customers to manage subscriptions and details.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Receive and process Dodo Payments webhook events.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Run the following command in your project root:

    ```bash theme={null}
    npm install @dodopayments/sveltekit
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a <code>.env</code> file in your project root:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
    ```

    <Warning>
      Never commit your <code>.env</code> file or secrets to version control.
    </Warning>
  </Step>
</Steps>

## Route Handler Examples

<Info>
  All examples assume you are using the SvelteKit App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Use this handler to integrate Dodo Payments checkout into your SvelteKit app. Supports static (GET), dynamic (POST), and session (POST) payment flows.
    </Info>

    <CodeGroup>
      ```typescript SvelteKit Route Handler expandable theme={null}
      // src/routes/api/checkout/+server.ts
      import { Checkout } from "@dodopayments/sveltekit";
      import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from '$env/static/private';

      const checkoutGetHandler = Checkout({
          bearerToken: DODO_PAYMENTS_API_KEY,
          returnUrl: DODO_PAYMENTS_RETURN_URL,
          environment: DODO_PAYMENTS_ENVIRONMENT,
          type: "static",
      });

      const checkoutPostHandler = Checkout({
          bearerToken: DODO_PAYMENTS_API_KEY,
          returnUrl: DODO_PAYMENTS_RETURN_URL,
          environment: DODO_PAYMENTS_ENVIRONMENT,
          type: "session", // or "dynamic" for dynamic link
      });

      export const GET = checkoutGetHandler.GET;
      export const POST = checkoutPostHandler.POST;
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{ 
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{ 
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Use this handler to allow customers to manage their subscriptions and details via the Dodo Payments customer portal.
    </Info>

    <CodeGroup>
      ```typescript SvelteKit Route Handler expandable theme={null}
      // src/routes/api/checkout/+server.ts
      import { CustomerPortal } from "@dodopayments/sveltekit";
      import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from '$env/static/private';

      const customerPortalHandler = CustomerPortal({
          bearerToken: DODO_PAYMENTS_API_KEY,
          environment: DODO_PAYMENTS_ENVIRONMENT,
      });

      export const GET = customerPortalHandler.GET;
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Use this handler to receive and process Dodo Payments webhook events securely in your SvelteKit app.
    </Info>

    <CodeGroup>
      ```typescript SvelteKit Route Handler expandable theme={null}
      // src/routes/api/webhook/+server.ts
      import { Webhooks } from "@dodopayments/sveltekit";
      import { DODO_PAYMENTS_WEBHOOK_KEY } from '$env/static/private';

      export const POST = Webhooks({
          webhookKey: DODO_PAYMENTS_WEBHOOK_KEY,
          onPayload: async (payload) => {
              console.log(payload);
          }
      });
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout Route Handler

<Info>
  Dodo Payments supports three types of payment flows for integrating payments into your website, this adaptor supports all types of payment flows.
</Info>

* **Static Payment Links:** Instantly shareable URLs for quick, no-code payment collection.
* **Dynamic Payment Links:** Programmatically generate payment links with custom details using the API or SDKs.
* **Checkout Sessions:** Create secure, customizable checkout experiences with pre-configured product carts and customer details.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Supported Query Parameters

    <ParamField type="string">
      Product identifier (e.g., <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField type="integer">
      Quantity of the product.
    </ParamField>

    <ParamField type="string">
      Customer's full name.
    </ParamField>

    <ParamField type="string">
      Customer's first name.
    </ParamField>

    <ParamField type="string">
      Customer's last name.
    </ParamField>

    <ParamField type="string">
      Customer's email address.
    </ParamField>

    <ParamField type="string">
      Customer's country.
    </ParamField>

    <ParamField type="string">
      Customer's address line.
    </ParamField>

    <ParamField type="string">
      Customer's city.
    </ParamField>

    <ParamField type="string">
      Customer's state/province.
    </ParamField>

    <ParamField type="string">
      Customer's zip/postal code.
    </ParamField>

    <ParamField type="boolean">
      Disable full name field.
    </ParamField>

    <ParamField type="boolean">
      Disable first name field.
    </ParamField>

    <ParamField type="boolean">
      Disable last name field.
    </ParamField>

    <ParamField type="boolean">
      Disable email field.
    </ParamField>

    <ParamField type="boolean">
      Disable country field.
    </ParamField>

    <ParamField type="boolean">
      Disable address line field.
    </ParamField>

    <ParamField type="boolean">
      Disable city field.
    </ParamField>

    <ParamField type="boolean">
      Disable state field.
    </ParamField>

    <ParamField type="boolean">
      Disable zip code field.
    </ParamField>

    <ParamField type="string">
      Specify the payment currency (e.g., <code>USD</code>).
    </ParamField>

    <ParamField type="boolean">
      Show currency selector.
    </ParamField>

    <ParamField type="number">
      Fixes the amount charged, in major currency units (e.g., <code>12.5</code> for \$12.50). Pay What You Want products only, and ignored if below the product's minimum price.
    </ParamField>

    <ParamField type="boolean">
      Show discount fields.
    </ParamField>

    <ParamField type="string">
      Any query parameter starting with <code>metadata\_</code> will be passed as metadata.
    </ParamField>

    <Warning>
      If <code>productId</code> is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
    </Warning>

    ### Response Format

    Static checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/"
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Send parameters as a JSON body in a POST request.
    * Supports both one-time and recurring payments.
    * For a complete list of supported POST body fields, refer to:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Response Format

    Dynamic checkout returns a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/"
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout sessions provide a more secure, hosted checkout experience that handles the complete payment flow for both one-time purchases and subscriptions with full customization control.

    Refer to [Checkout Sessions Integration Guide](https://docs.dodopayments.com/developer-resources/checkout-session) for more details and a complete list of supported fields.

    ### Response Format

    Checkout sessions return a JSON response with the checkout URL:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Customer Portal Route Handler

The Customer Portal Route Handler enables you to seamlessly integrate the Dodo Payments customer portal into your SvelteKit application.

### Query Parameters

<ParamField type="string">
  The customer ID for the portal session (e.g., <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField type="boolean">
  If set to <code>true</code>, sends an email to the customer with the portal link.
</ParamField>

<Warning>
  Returns 400 if <code>customer\_id</code> is missing.
</Warning>

## Webhook Route Handler

* **Method:** Only POST requests are supported. Other methods return 405.
* **Signature Verification:** Verifies the webhook signature using <code>webhookKey</code>. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
  * 401: Invalid signature
  * 400: Invalid payload
  * 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.

### Supported Webhook Event Handlers

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
  onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
  onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
  onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
  onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
  onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
  onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
  onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
  onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
  onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
  onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt for LLM

```

You are an expert SvelteKit developer assistant. Your task is to guide a user through integrating the @dodopayments/sveltekit adapter into their existing SvelteKit project.

The @dodopayments/sveltekit adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for the SvelteKit App Router.

First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):

npm install @dodopayments/sveltekit

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/sveltekit adapter would you like to integrate into your project? You can choose one or more of the following:

    Checkout Route Handler (for handling product checkouts)

    Customer Portal Route Handler (for managing customer subscriptions/details)

    Webhook Route Handler (for receiving Dodo Payments webhook events)

    All (integrate all three)"

    Based on the user's selection, provide detailed integration steps for each chosen functionality.

If Checkout Route Handler is selected:

Purpose: This handler manages different types of checkout flows. All checkout types (static, dynamic, and sessions) return JSON responses with checkout URLs for programmatic handling.
File Creation: Create a new file at app/checkout/route.ts in your SvelteKit project.

Code Snippet:

// src/routes/api/checkout/+server.ts
import { Checkout } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from '$env/static/private';

const checkoutGetHandler = Checkout({
    bearerToken: DODO_PAYMENTS_API_KEY,
    returnUrl: DODO_PAYMENTS_RETURN_URL,
    environment: DODO_PAYMENTS_ENVIRONMENT,
    type: "static",
});

const checkoutPostHandler = Checkout({
    bearerToken: DODO_PAYMENTS_API_KEY,
    returnUrl: DODO_PAYMENTS_RETURN_URL,
    environment: DODO_PAYMENTS_ENVIRONMENT,
    type: "session", // or "dynamic" for dynamic link
});

export const GET = checkoutGetHandler.GET;
export const POST = checkoutPostHandler.POST;


Configuration & Usage:

    bearerToken: Your Dodo Payments API key. It's recommended to set this via the DODO_PAYMENTS_API_KEY environment variable.

    returnUrl: (Optional) The URL to redirect the user to after a successful checkout.

    environment: (Optional) Set to "test_mode" for testing, or omit/set to "live_mode" for production.

    type: (Optional) Set to "static" for GET/static checkout, "dynamic" for POST/dynamic checkout, or "session" for POST/checkout sessions. Defaults to "static".

Static Checkout (GET) Query Parameters:

    productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)

    quantity (optional): Quantity of the product

    Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode

    Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode

    Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts

    Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)
    
    Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}

Dynamic Checkout (POST) - Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/..."}. For a complete list of supported POST body fields, refer to:

    Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments

    Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions


Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. For a complete list of supported fields, refer to:

  Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session

Error Handling: If productId is missing or other parameters are invalid, the handler will return a 400 response.

If Customer Portal Route Handler is selected:

Purpose: This handler redirects authenticated users to their Dodo Payments customer portal.
File Creation: Create a new file at app/customer-portal/route.ts in your SvelteKit project.

Code Snippet:

// src/routes/api/checkout/+server.ts
import { CustomerPortal } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from '$env/static/private';

const customerPortalHandler = CustomerPortal({
    bearerToken: DODO_PAYMENTS_API_KEY,
    environment: DODO_PAYMENTS_ENVIRONMENT,
});

export const GET = customerPortalHandler.GET;


Query Parameters:

    customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)

    send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.

    Returns 400 if customer_id is missing.

If Webhook Route Handler is selected:

Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at app/api/webhook/dodo-payments/route.ts in your SvelteKit project.

Code Snippet:

// src/routes/api/webhook/+server.ts
import { Webhooks } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_WEBHOOK_KEY } from '$env/static/private';

export const POST = Webhooks({
    webhookKey: DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
        console.log(payload);
    }
});

Handler Details:

    Method: Only POST requests are supported. Other methods return 405.

    Signature Verification: The handler verifies the webhook signature using the webhookKey and returns 401 if verification fails.

    Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.

Error Handling:

    401: Invalid signature

    400: Invalid payload

    500: Internal error during verification

Event Routing: Calls the appropriate event handler based on the payload type.

Supported Webhook Event Handlers:

    onPayload?: (payload: WebhookPayload) => Promise<void>

    onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>

    onPaymentFailed?: (payload: WebhookPayload) => Promise<void>

    onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>

    onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>

    onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>

    onRefundFailed?: (payload: WebhookPayload) => Promise<void>

    onDisputeOpened?: (payload: WebhookPayload) => Promise<void>

    onDisputeExpired?: (payload: WebhookPayload) => Promise<void>

    onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>

    onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>

    onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>

    onDisputeWon?: (payload: WebhookPayload) => Promise<void>

    onDisputeLost?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>

    onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>

    onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>

    onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>

    onDunningStarted?: (payload: WebhookPayload) => Promise<void>

    onDunningRecovered?: (payload: WebhookPayload) => Promise<void>

    onCreditAdded?: (payload: WebhookPayload) => Promise<void>

    onCreditDeducted?: (payload: WebhookPayload) => Promise<void>

    onCreditExpired?: (payload: WebhookPayload) => Promise<void>

    onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>

    onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>

    onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>

    onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>

    onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>

    Environment Variable Setup:

To ensure the adapter functions correctly, you will need to manually set up the following environment variables in your SvelteKit project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):

    DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).

    RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).

    DODO_PAYMENTS_WEBHOOK_SECRET: Your Dodo Payments Webhook Secret (required for Webhook handler).

Example .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=your-return-url
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"

Usage in your code:

bearerToken: process.env.DODO_PAYMENTS_API_KEY
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY

Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.

If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance. You can also add comments to their PR or chat depending on the context

```


# Build an AI Image Generator with Usage-Based Billing
Source: https://docs.dodopayments.com/developer-resources/usage-based-billing-build-ai-image-generator

Follow along as we build PixelGen AI - an AI image generation service with pay-per-use billing

In this tutorial, you'll build **PixelGen AI** - a sample AI image generation service that demonstrates usage-based billing. We'll create everything from scratch: the billing meter, product configuration, and sample application code that generates images and tracks usage in real-time.

<Note>
  This tutorial provides sample implementation code for a terminal-based application. You can modify this code for your specific framework (React, Vue, Angular, etc.) and customize the user input method according to your application's needs.
</Note>

By the end of this tutorial, you'll have a working sample service that:

* Generates images using OpenAI's DALL-E API
* Tracks every image generation for billing
* Charges customers automatically based on usage
* Handles different quality tiers (standard vs HD)

## What We're Building

Let's start by understanding our PixelGen AI service:

* **Service**: AI image generation using OpenAI's DALL-E API
* **Pricing Model**: Pay-per-image (\$0.05 per image)
* **Free Tier**: 10 free images per customer per month
* **Quality Options**: Standard and HD images (same price for simplicity)

<Info>
  Before we start, make sure you have:

  * A Dodo Payments account
  * Access to OpenAI's API
  * Basic familiarity with TypeScript/Node.js
</Info>

## Step 1: Create Your Usage Meter

We'll start by creating a meter in your Dodo Payments dashboard that will track every image our service generates. Think of this as the "counter" that tracks billable events.

<Frame>
  <img alt="" />
</Frame>

<Tip>
  **What we're building**: A meter named "Image Generation Meter" that counts every time someone generates an image using our service.
</Tip>

<Steps>
  <Step title="Open the Meters section">
    1. Log into your Dodo Payments dashboard
    2. Click on **Meters** in the left sidebar
    3. Click the **Create Meter** button

    You should see a form where we'll configure our image generation tracking.
  </Step>

  <Step title="Fill in the basic meter information">
    Now we'll enter the specific details for our PixelGen AI service:

    **Meter Name**: Copy and paste this exactly → `Image Generation Meter`

    **Description**: Copy this → `Tracks each AI image generation request made by customers using our DALL-E powered service`

    **Event Name**: This is crucial - copy exactly → `image.generated`

    <Warning>
      The event name `image.generated` must match exactly what we'll send from our application code later. Event names are case-sensitive!
    </Warning>
  </Step>

  <Step title="Configure how we count images">
    Set up the aggregation (how the meter counts our events):

    **Aggregation Type**: Select **Count** from the dropdown

    **Measurement Unit**: Type → `images`

    <Info>
      We're using "Count" because we want to bill per image generated, not by size or generation time. Each successful image = 1 billable unit.
    </Info>
  </Step>

  <Step title="Add quality filtering">
    <Frame>
      <img alt="" />
    </Frame>

    We want to make sure we only count legitimate images (not test runs or failures):

    1. **Enable Event Filtering**: Toggle this **ON**
    2. **Filter Logic**: Select **OR** (this means "count if ANY of these conditions are true")
    3. **Add the first condition**:
       * Property Key: `quality`
       * Comparator: `equals`
       * Value: `standard`
    4. **Click "Add Condition"** for the second one:
       * Property Key: `quality`
       * Comparator: `equals`
       * Value: `hd`

    <Tip>
      This setup means we'll only count events where the quality is either "standard" OR "hd" - filtering out any test events or malformed requests.
    </Tip>
  </Step>

  <Step title="Create your meter">
    1. Double-check all your settings match the values above
    2. Click **Create Meter**

    <Check>
      **Meter created!** Your "Image Generation Meter" is now ready to start counting image generations. Next, we'll connect it to a billing product.
    </Check>
  </Step>
</Steps>

## Step 2: Create Your Billing Product

Now we need to create a product that defines our pricing (\$0.05 per image with 10 free images). This connects our meter to actual billing.

<Tip>
  **What we're building**: A product called "PixelGen AI - Image Generation" that charges \$0.05 per image after the first 10 free images each month.
</Tip>

<Steps>
  <Step title="Navigate to Products">
    1. In your Dodo Payments dashboard, click **Products** in the left sidebar
    2. Click **Create Product**
    3. Select **Usage-Based** as the product type

    This tells Dodo Payments that billing will be based on meter usage, not a fixed subscription.
  </Step>

  <Step title="Enter product details">
    Fill in these exact values for our PixelGen AI service:

    **Product Name**: Copy this → `PixelGen AI - Image Generation`

    **Description**: Copy this → `AI-powered image generation service with pay-per-use billing`

    **Product Image**: Upload a clear, relevant image.

    <Info>
      These will appear on customer invoices, so make them clear and professional.
    </Info>
  </Step>

  <Step title="Connect your meter">
    <Frame>
      <img alt="" />
    </Frame>

    Before connecting your meter, make sure you have selected **Usage Based Billing** as the price type for your product.

    Additionally, set the **Fixed Price** to `0` to ensure customers are only charged based on their usage, with no base fee.

    Now, link the meter you just created:

    1. Scroll down to the **Associated Meter** section
    2. Click **Add Meters**
    3. From the dropdown, select **"Image Generation Meter"** (the one you created earlier)
    4. Confirm that it appears in your product configuration

    <Check>
      Your meter is now successfully connected to this product.
    </Check>
  </Step>

  <Step title="Set your pricing">
    Here's where we define our business model:

    <Frame>
      <img alt="" />
    </Frame>

    **Price Per Unit**: Enter → `0.05` (this is \$0.05 per image)

    **Free Threshold**: Enter → `10` (customers get 10 free images per month)

    <Tip>
      **How billing works**: If a customer generates 25 images in a month, they'll be charged for 15 images (25 - 10 free) = 15 × $0.05 = $0.75
    </Tip>
  </Step>

  <Step title="Save your product">
    1. Review all your settings:
       * Name: PixelGen AI - Image Generation
       * Meter: Image Generation Meter
       * Price: \$0.05 per image
       * Free tier: 10 images
    2. Click **Save Changes**

    <Check>
      **Product created!** Your billing is now configured. Customers will automatically be charged based on their image generation usage.
    </Check>
  </Step>
</Steps>

## Step 3: Make a Test Purchase

Before we start ingesting usage events, we need to make a test purchase.

<Steps>
  <Step title="Get your payment link">
    1. In your Dodo Payments dashboard, go to **Products**
    2. Find your "PixelGen AI - Image Generation" product
    3. Click the **Share** button next to your product
    4. Copy the payment link that appears

    The payment link will look something like: `https://test.checkout.dodopayments.com/buy/pdt_IgPWlRsfpbPd5jQKezzW1?quantity=1`
  </Step>

  <Step title="Complete a test purchase">
    1. Open the payment link in a new browser tab
    2. Enter test payment details and complete purchase.

    <Check>
      After successful payment, you'll have a customer ID that we'll use in our application code.
    </Check>
  </Step>

  <Step title="Find your customer ID">
    1. Go back to your Dodo Payments dashboard
    2. Navigate to **Sales → Customers** in the sidebar
    3. Find the customer you just created (with the test email)
    4. Copy the customer ID - it will look like `cus_abc123def456`

    <Note>
      Save this customer ID - we'll hardcode it in our sample application code to ensure events are properly tracked.
    </Note>
  </Step>
</Steps>

## Step 4: Build the Sample Application

Now we have our billing setup complete and a test customer created. Let's build the sample PixelGen AI application that generates images and automatically tracks usage for billing.

<Steps>
  <Step title="Set up your project">
    Create a new directory and initialize the project:

    ```bash theme={null}
    mkdir pixelgen-ai
    cd pixelgen-ai
    npm init -y
    ```
  </Step>

  <Step title="Install dependencies">
    Install the packages we need:

    ```bash theme={null}
    npm install openai dotenv
    npm install -D typescript @types/node ts-node
    ```
  </Step>

  <Step title="Create the main application">
    Create a file called `index.ts` and copy this complete application code:
  </Step>
</Steps>

Here's the complete PixelGen AI application with integrated billing:

<CodeGroup>
  ```typescript index.ts expandable theme={null}
  import 'dotenv/config';
  import OpenAI from 'openai';
  import * as readline from 'readline';
  import { randomUUID } from 'crypto';

  // Initialize OpenAI client
  const openai = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY,
  });

  // Dodo Payments configuration
  const DODO_PAYMENTS_CONFIG = {
    apiKey: process.env.DODO_PAYMENTS_API_KEY,
    baseUrl: 'https://test.dodopayments.com',
    customerId: 'cus_FX5FAB43aShGyiHJGIqjB', // Replace with your actual customer ID from Step 3
  };

  // DALL-E 3 pricing (as of 2024-2025)
  const PRICING = {
    'standard': 0.040, // $0.040 per image (1024×1024)
    'hd': 0.080,       // $0.080 per image (1024×1024, HD quality)
  };

  interface ImageGenerationOptions {
    prompt: string;
    model?: 'dall-e-3' | 'dall-e-2';
    quality?: 'standard' | 'hd';
    size?: '1024x1024' | '1792x1024' | '1024x1792';
    style?: 'vivid' | 'natural';
  }

  interface UsageEvent {
    event_id: string;
    customer_id: string;
    event_name: string;
    timestamp: string;
    metadata: {
      quality: string;
    };
  }

  /**
   * Send usage event to Dodo Payments for billing tracking
   */
  async function sendUsageEvent(event: UsageEvent): Promise<void> {
    try {
      console.log('Sending usage event to Dodo Payments...');
      console.log(`URL: ${DODO_PAYMENTS_CONFIG.baseUrl}/events/ingest`);
      console.log(`API Key present: ${!!DODO_PAYMENTS_CONFIG.apiKey}`);
      console.log(`API Key length: ${DODO_PAYMENTS_CONFIG.apiKey?.length || 0}`);
      console.log(`Customer ID: ${DODO_PAYMENTS_CONFIG.customerId}`);
      
      const requestBody = {
        events: [event]
      };
      console.log('Request body:', JSON.stringify(requestBody, null, 2));
      
      const headers = {
        'Authorization': `Bearer ${DODO_PAYMENTS_CONFIG.apiKey}`,
        'Content-Type': 'application/json',
      }
      console.log('Headers:', headers);
      const response = await fetch(`${DODO_PAYMENTS_CONFIG.baseUrl}/events/ingest`, {
        method: 'POST',
        headers: headers,
        body: JSON.stringify(requestBody),
      });

      console.log(`Response status: ${response.status}`);
      console.log(`Response headers:`, Object.fromEntries(response.headers.entries()));

      if (!response.ok) {
        const errorData = await response.text();
        console.log(`Error response body: ${errorData}`);
        throw new Error(`HTTP ${response.status}: ${errorData}`);
      }

      const result = await response.json();
      console.log('Usage event sent successfully');
      console.log(`   • Event ID: ${event.event_id}`);
      console.log(`   • Customer: ${event.customer_id}`);
      console.log(`   • Quality: ${event.metadata.quality}`);
      
    } catch (error) {
      console.error('Failed to send usage event:', error);
      // In production, you might want to queue failed events for retry
      throw error;
    }
  }

  async function generateImage(options: ImageGenerationOptions) {
    const startTime = Date.now();
    const eventId = randomUUID();
    
    try {
      console.log('Generating image...');
      console.log(`Prompt: "${options.prompt}"`);
      console.log(`Quality: ${options.quality || 'standard'}`);
      console.log(`Size: ${options.size || '1024x1024'}`);
      
      const response = await openai.images.generate({
        model: options.model || 'dall-e-3',
        prompt: options.prompt,
        n: 1,
        size: options.size || '1024x1024',
        quality: options.quality || 'standard',
        style: options.style || 'vivid',
      });

      const endTime = Date.now();
      const duration = (endTime - startTime) / 1000;
      const cost = PRICING[options.quality || 'standard'];
      
      // Create usage event for Dodo Payments
      const usageEvent: UsageEvent = {
        event_id: eventId,
        customer_id: DODO_PAYMENTS_CONFIG.customerId!,
        event_name: 'image.generated',
        timestamp: new Date().toISOString(),
        metadata: {
          quality: options.quality || 'standard',
        }
      };

      // Send usage event to Dodo Payments for billing
      await sendUsageEvent(usageEvent);
      
      console.log('\nImage generated successfully!');
      console.log(`Generation Stats:`);
      console.log(`   • Duration: ${duration.toFixed(2)} seconds`);
      console.log(`   • Quality: ${options.quality || 'standard'}`);
      console.log(`   • Cost: $${cost.toFixed(3)}`);
      console.log(`   • Image URL: ${response.data?.[0]?.url}`);
      
      if (response.data?.[0]?.revised_prompt) {
        console.log(`   • Revised prompt: "${response.data[0].revised_prompt}"`);
      }

      return {
        imageUrl: response.data?.[0].url,
        revisedPrompt: response.data?.[0].revised_prompt,
        cost: cost,
        duration: duration,
        eventId: eventId,
      };

    } catch (error) {
      console.error('Error generating image:', error);
      
      // Send failure event for monitoring (optional)
      try {
        const failureEvent: UsageEvent = {
          event_id: eventId,
          customer_id: DODO_PAYMENTS_CONFIG.customerId!,
          event_name: 'image.generation.failed',
          timestamp: new Date().toISOString(),
          metadata: {
            quality: options.quality || 'standard',
          }
        };
        
        // Note: You might want to create a separate meter for failed attempts
        // await sendUsageEvent(failureEvent);
      } catch (eventError) {
        console.error('Failed to send failure event:', eventError);
      }
      
      throw error;
    }
  }

  async function getUserInput(): Promise<string> {
    const rl = readline.createInterface({
      input: process.stdin,
      output: process.stdout
    });

    return new Promise((resolve) => {
      rl.question('Enter your image prompt: ', (answer) => {
        rl.close();
        resolve(answer);
      });
    });
  }

  async function main() {
    console.log('PixelGen AI - Image Generator with Usage Billing\n');
    
    // Validate environment variables
    const requiredEnvVars = [
      'OPENAI_API_KEY',
      'DODO_PAYMENTS_API_KEY'
    ];
    
    for (const envVar of requiredEnvVars) {
      if (!process.env[envVar]) {
        console.error(`Error: ${envVar} environment variable is not set.`);
        console.log('Please set all required environment variables:');
        console.log('export OPENAI_API_KEY="your-openai-key"');
        console.log('export DODO_PAYMENTS_API_KEY="your-dodo-api-key"');
        console.log('Note: Customer ID is hardcoded in the application');
        process.exit(1);
      }
    }

    try {
      const prompt = await getUserInput();
      
      if (!prompt.trim()) {
        console.log('No prompt provided. Exiting...');
        return;
      }

      const result = await generateImage({
        prompt: prompt.trim(),
        quality: 'standard', // Change to 'hd' for higher quality (costs more)
        size: '1024x1024',
        style: 'vivid'
      });

      console.log('\nProcess completed successfully!');
      console.log(`Billing Information:`);
      console.log(`   • Total cost: $${result.cost.toFixed(3)}`);
      console.log(`   • Event ID: ${result.eventId}`);
      console.log(`   • Billing will be processed automatically via Dodo Payments`);
      
    } catch (error) {
      console.error('Application error:', error);
      process.exit(1);
    }
  }

  // Run the application
  if (require.main === module) {
    main().catch(console.error);
  }
  ```

  ```bash .env theme={null}
  # Create .env file with your API keys
  OPENAI_API_KEY=your_openai_api_key_here
  DODO_PAYMENTS_API_KEY=your_DODO_PAYMENTS_payments_api_key_here
  # Note: Customer ID is hardcoded in the application code
  ```

  ```typescript package.json theme={null}
  {
    "name": "pixelgen-ai",
    "version": "1.0.0",
    "description": "AI Image Generation with Usage-Based Billing",
    "main": "index.js",
    "scripts": {
      "start": "ts-node index.ts",
      "build": "tsc",
      "dev": "ts-node --watch index.ts"
    },
    "dependencies": {
      "openai": "^4.0.0",
      "dotenv": "^16.0.0"
    },
    "devDependencies": {
      "@types/node": "^20.0.0",
      "typescript": "^5.0.0",
      "ts-node": "^10.0.0"
    }
  }
  ```
</CodeGroup>

## Step 5: Test Your Sample Application

Time to test our sample PixelGen AI service and see the billing in action! Let's make sure everything works end-to-end.

<Tip>
  **What we're testing**: We'll generate some images, verify the events reach Dodo Payments, and confirm billing calculations are correct.
</Tip>

<Steps>
  <Step title="Set up your environment">
    First, make sure you have everything configured:

    1. Create a `.env` file in your `pixelgen-ai` directory
    2. Add your actual API keys:

    ```bash theme={null}
    OPENAI_API_KEY=sk-your-actual-openai-key
    DODO_PAYMENTS_API_KEY=your-actual-dodo-api-key
    # Customer ID is hardcoded in the application
    ```

    3. Install dependencies and run the app:

    ```bash theme={null}
    npm install
    npm start
    ```

    <Warning>
      Make sure to use real API keys and update the hardcoded customer ID in the code with your actual customer ID from Step 3!
    </Warning>
  </Step>

  <Step title="Generate your first test image">
    When the app starts, you'll see:

    ```
    PixelGen AI - Image Generator with Usage Billing

    Enter your image prompt:
    ```

    Try this prompt: **"A cute robot painting a landscape"**

    You should see output like this:

    ```
    Generating image...
    Prompt: "A cute robot painting a landscape"
    Quality: standard
    Size: 1024x1024

    Sending usage event to Dodo Payments...
    Usage event sent successfully
       • Event ID: 550e8400-e29b-41d4-a716-446655440000
       • Customer: cus_atXa1lklCRRzMicTqfiw2
       • Quality: standard

    Image generated successfully!
    Generation Stats:
       • Duration: 8.45 seconds
       • Quality: standard
       • Cost: $0.040
       • Image URL: https://oaidalleapi...
    ```

    <Check>
      If you see "Usage event sent successfully", your billing integration is working!
    </Check>
  </Step>

  <Step title="Generate a few more images">
    Let's generate 2-3 more images to test multiple events. Try these prompts:

    1. **"A sunset over mountains with purple clouds"**
    2. **"A steampunk coffee machine in a Victorian kitchen"**
    3. **"A friendly dragon reading a book in a library"**

    Each time, watch for the "Usage event sent successfully" message.
  </Step>

  <Step title="Check your Dodo Payments dashboard">
    Now let's verify the events are being received:

    1. Open your Dodo Payments dashboard
    2. Go to *Usage Billing* → \***Meters** → **Image Generation Meter**
    3. Click on the **Events**  tab
    4. You should see your image generation events listed

    **What to look for**:

    * Event names: `image.generated`
    * Customer ID: Your test customer ID

    <Check>
      You should see one event for each image you generated!
    </Check>
  </Step>

  <Step title="Verify billing calculations">
    Let's check if the usage counting is working:

    <Frame>
      <img alt="" />
    </Frame>

    1. In your meter, go to the **Customers** tab
    2. Find your test customer
    3. Check the "Consumed Units" column
  </Step>

  <Step title="Test the billing threshold">
    Let's exceed the free tier to see billing in action:

    1. Generate 8 more images (to reach 12 total)
    2. Check your meter dashboard again
    3. You should now see:
       * Consumed units: 12
       * Billable units: 2 (12 - 10 free)
       * Billing amount: \$0.10

    <Check>
      **Success!** Your usage-based billing is working perfectly. Customers will be automatically charged based on their actual image generation usage.
    </Check>
  </Step>
</Steps>

## Troubleshooting

Common issues and their solutions:

<AccordionGroup>
  <Accordion title="Events not appearing in dashboard">
    **Possible causes:**

    * Event name doesn't match meter configuration exactly
    * Customer ID doesn't exist in your account
    * API key is invalid or expired
    * Network connectivity issues

    **Solutions:**

    1. Verify event name matches meter configuration exactly (case-sensitive)
    2. Check that customer ID exists in Dodo Payments
    3. Test API key with a simple API call
    4. Check network connectivity and firewall settings
  </Accordion>
</AccordionGroup>

## Congratulations! You Built PixelGen AI

You've successfully created a snippet for AI image generation with usage-based billing! Here's what you accomplished:

<CardGroup>
  <Card title="Usage Meter" icon="sliders">
    Created "Image Generation Meter" that tracks every image generation event
  </Card>

  <Card title="Billing Product" icon="credit-card">
    Configured pricing at \$0.05 per image with 10 free images per month
  </Card>

  <Card title="AI Application" icon="robot">
    Built a working TypeScript app that generates images using OpenAI's DALL-E
  </Card>

  <Card title="Automated Billing" icon="bolt">
    Integrated real-time event tracking that automatically bills customers
  </Card>
</CardGroup>


# Usage-Based Billing Integration guide
Source: https://docs.dodopayments.com/developer-resources/usage-based-billing-guide

Learn how to set up meters and send usage events to enable accurate usage-based billing with Dodo Payments.

<CardGroup>
  <Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
    Access the complete API documentation for ingesting usage events and test event ingestion requests and responses interactively.
  </Card>

  <Card title="API Reference - Meters Creation" icon="code" href="/api-reference/meters/create-meter">
    Explore the full API documentation for creating meters and interactively test meter creation requests and responses.
  </Card>
</CardGroup>

## Creating a Meter

Meters define how your usage events are aggregated and measured for billing purposes.

Before creating a meter, plan your usage tracking strategy:

* Identify what usage events you want to track
* Determine how events should be aggregated (count, sum, etc.)
* Define any filtering requirements for specific use cases

### Step-by-Step Meter Creation

Follow this comprehensive guide to set up your usage meter:

<Steps>
  <Step title="Configure Basic Information">
    Set up the fundamental details for your meter.

    <ParamField type="string">
      Choose a clear, descriptive name that identifies what this meter tracks.

      Examples: "Tokens", "API Calls", "Storage Usage", "Compute Hours"
    </ParamField>

    <ParamField type="string">
      Provide a detailed explanation of what this meter measures.

      Example: "Counts each POST /v1/orders request made by the customer"
    </ParamField>

    <ParamField type="string">
      Specify the event identifier that will trigger this meter.

      Examples: "token", "api.call", "storage.usage", "compute.session"
    </ParamField>

    <Info>
      The event name must match exactly what you send in your usage events. Event names are case-sensitive.
    </Info>
  </Step>

  <Step title="Configure Aggregation Settings">
    Define how the meter calculates usage from your events.

    <ParamField type="string">
      Select how events should be aggregated:

      <Tabs>
        <Tab title="Count">
          Simply counts the number of events received.

          Use case: API calls, page views, file uploads

          Calculation: Total number of events
        </Tab>

        <Tab title="Sum">
          Adds up values from a specific property in your events.

          Use case: Data transfer, storage consumption, processing time

          Calculation: Sum of all property values
        </Tab>

        <Tab title="Max">
          Records the highest value of a specific property during the billing period.

          Use case: Peak concurrent users, maximum storage used, highest bandwidth

          Calculation: Maximum property value observed
        </Tab>

        <Tab title="Last">
          Uses the most recent value of a specific property.

          Use case: Current plan tier, latest configuration setting

          Calculation: Last recorded property value
        </Tab>
      </Tabs>
    </ParamField>

    <ParamField type="string">
      The property name from event metadata to aggregate over.

      <Warning>
        This field is required when using Sum, Max, or Last aggregation types.
      </Warning>
    </ParamField>

    <ParamField type="string">
      Define the unit label for display purposes in reports and billing.

      Examples: "calls", "GB", "hours", "tokens"
    </ParamField>
  </Step>

  <Step title="Configure Event Filtering (Optional)">
    Set up criteria to control which events are included in the meter.

    <Info>
      Event filtering allows you to create sophisticated rules that determine which events contribute to your usage calculations. This is useful for excluding test events, filtering by user tiers, or focusing on specific actions.
    </Info>

    **Enable Event Filtering**

    Toggle **Enable Event Filtering** to activate conditional event processing.

    **Choose Filter Logic**

    Select how multiple conditions are evaluated:

    <Tabs>
      <Tab title="AND Logic">
        All conditions must be true for an event to be counted. Use this when you need events to meet multiple strict criteria simultaneously.

        **Example:** Count API calls where `user_tier = "premium"` AND `endpoint = "/api/v2/users"`
      </Tab>

      <Tab title="OR Logic">
        At least one condition must be true for an event to be counted. Use this when you want to include events that meet any of several criteria.

        **Example:** Count events where `method = "POST"` OR `method = "PUT"` OR `method = "DELETE"`
      </Tab>
    </Tabs>

    **Setting Up Filter Conditions**

    <Steps>
      <Step title="Add Condition">
        Click **Add condition** to create a new filter rule.
      </Step>

      <Step title="Configure Property Key">
        Specify the property name from your event metadata.
      </Step>

      <Step title="Select Comparator">
        Choose from available operators:

        * `equals` - Exact match
        * `not_equals` - Exclusion filter
        * `greater_than` - Numeric comparison
        * `greater_than_or_equals` - Numeric comparison (inclusive)
        * `less_than` - Numeric comparison
        * `less_than_or_equals` - Numeric comparison (inclusive)
        * `contains` - String contains substring
        * `does_not_contain` - String exclusion filter
      </Step>

      <Step title="Set Comparison Value">
        Set the target value for comparison.
      </Step>

      <Step title="Add Groups">
        Use **Add Group** to create additional condition groups for complex logic.
      </Step>
    </Steps>

    <Warning>
      Filtered properties must be included in your event metadata for the conditions to work properly. Events missing required properties will be excluded from counting.
    </Warning>
  </Step>

  <Step title="Create Meter">
    Review your meter configuration and click on **Create Meter**.

    <Check>
      Your meter is now ready to receive and aggregate usage events.
    </Check>
  </Step>
</Steps>

## Linking Meter in a Product

Once you have created your meter, you need to link it to a product to enable usage-based billing. This process connects your meter's usage data to pricing rules for customer billing.

Linking meters to products establishes the connection between usage tracking and billing:

* Products define pricing rules and billing behavior
* Meters provide usage data for billing calculations
* Multiple meters can be linked to a single product for complex billing scenarios

### Product Configuration Process

Transform your usage data into billable charges by properly configuring your product settings:

<Steps>
  <Step title="Choose Usage-Based Billing Product Type">
    Navigate to your product creation or editing page and select **Usage-Based** as the product type.
  </Step>

  <Step title="Select Associated Meter">
    Click on **Associated Meter** to open the meter selection panel from the side.

    This panel allows you to configure which meters will track usage for this product.
  </Step>

  <Step title="Add Your Meter">
    In the meter selection panel:

    1. Click **Add Meters** to view available meters
    2. Select the meter you created from the dropdown list
    3. The selected meter will appear in your product configuration
  </Step>

  <Step title="Configure Price Per Unit">
    Set the pricing for each unit of usage tracked by your meter.

    <ParamField type="number">
      Define how much to charge for each unit measured by your meter.

      **Example**: Setting `$0.50` per unit means:

      * 1,000 units consumed = 1,000 × \$0.50 = 500.00 charged
      * 500 units consumed = 500 × \$0.50 = 250.00 charged
      * 100 units consumed = 100 × \$0.50 = 50.00 charged
    </ParamField>
  </Step>

  <Step title="Set Free Threshold (Optional)">
    Configure a free usage allowance before billing begins.

    <ParamField type="number">
      Number of units customers can consume at no charge before paid usage calculation starts.

      **How it works**:

      * Free threshold: 100 units
      * Price per unit: \$0.50
      * Customer usage: 250 units
      * **Calculation**: (250 - 100) × $0.50 = **$75.00\*\* charged
    </ParamField>

    <Info>
      Free thresholds are ideal for freemium models, trial periods, or providing customers with a base allowance included in their plan.
    </Info>

    <Check>
      The free threshold applies to each billing cycle, giving customers fresh allowances monthly or according to your billing schedule.
    </Check>
  </Step>

  <Step title="Save Configuration">
    Review your meter and pricing configuration, then click **Save Changes** to finalize the setup.

    <Check>
      Your product is now configured for usage-based billing and will automatically charge customers based on their measured consumption.
    </Check>

    **What happens next**:

    * Usage events sent to your meter will be tracked and aggregated
    * Billing calculations will apply your pricing rules automatically
    * Customers will be charged based on actual consumption during each billing cycle
  </Step>
</Steps>

<Note>
  Remember that you can add up to 10 meters per product, enabling sophisticated usage tracking across multiple dimensions like API calls, storage, compute time, and custom metrics.
</Note>

## Sending Usage Events

Once your meter is configured, you can start sending usage events from your application to track customer usage.

### Event Structure

Each usage event must include these required fields:

<ParamField type="string">
  Unique identifier for this specific event. Must be unique across all events.
</ParamField>

<ParamField type="string">
  The Dodo Payments customer ID this usage should be attributed to.
</ParamField>

<ParamField type="string">
  The event name that matches your meter configuration. Event names trigger the appropriate meter.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp when the event occurred. Defaults to the current UTC timestamp if not provided. Must fall within 1 hour in the past and 5 minutes in the future — timestamps outside that window are rejected.
</ParamField>

<ParamField type="object">
  Additional properties for filtering and aggregation. Include any values referenced in your meter's "Over Property" or filtering conditions.
</ParamField>

### Usage Events API Examples

Send usage events to your configured meters using the Events API:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://test.dodopayments.com/events/ingest', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      events: [
        {
          event_id: "api_call_1234",
          customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
          event_name: "api.call",
          timestamp: new Date().toISOString(),
          metadata: {
            endpoint: "/v1/orders",
            method: "POST",
            response_size: 1024
          }
        }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests
  from datetime import datetime

  response = requests.post(
      'https://test.dodopayments.com/events/ingest',
      headers={
          'Authorization': f'Bearer {api_key}',
          'Content-Type': 'application/json'
      },
      json={
          'events': [
              {
                  'event_id': 'api_call_1234',
                  'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
                  'event_name': 'api.call',
                  'timestamp': datetime.now().isoformat(),
                  'metadata': {
                      'endpoint': '/v1/orders',
                      'method': 'POST',
                      'response_size': 1024
                  }
              }
          ]
      }
  )
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://test.dodopayments.com/events/ingest' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "events": [
        {
          "event_id": "api_call_1234",
          "customer_id": "cus_atXa1lklCRRzMicTqfiw2",
          "event_name": "api.call", 
          "timestamp": "2024-01-15T10:30:00Z",
          "metadata": {
            "endpoint": "/v1/orders",
            "method": "POST",
            "response_size": 1024
          }
        }
      ]
    }'
  ```
</CodeGroup>

### Key Things to Know for Reliable Ingestion

Follow these practices to keep usage tracking accurate and resilient in production.

<Tip>
  **Use deterministic, idempotent `event_id`s.** The `event_id` must be unique across all events and acts as the idempotency key — a reused `event_id` is treated as a duplicate and not counted again, so retries never double-bill. Derive the ID from the action instead of a random value, e.g. `` `${customer_id}_${action}_${timestamp}` ``.
</Tip>

<Tip>
  **Batch events, up to 1,000 per request.** The `/events/ingest` endpoint enforces a hard maximum of **1,000 events per call**; batches larger than that are rejected, so split high volumes across multiple calls. For high-volume workloads, buffer events and flush in batches rather than sending one request per event.
</Tip>

<Warning>
  **Retry `5xx` and `429`, never `4xx`.** Retry on server errors (`5xx`) and rate limits (`429`) with exponential backoff. Do **not** retry `400`/`422` validation errors — the payload is malformed and will fail every time; fix it and re-send. Queue events that still fail after retries so none are lost.
</Warning>

<Info>
  **Set timestamps intentionally.** Omit `timestamp` for real-time events and it defaults to the current UTC timestamp. Set it explicitly (ISO 8601) for delayed or batched events so usage lands in the correct billing period, but note the accepted window is narrow: events timestamped more than **1 hour in the past** or more than **5 minutes in the future** are rejected. Historical backfill is not supported — flush buffered events within the hour.
</Info>

<Warning>
  **Send aggregated metadata as numbers, not strings.** Any property referenced by a meter's **Over Property** (Sum, Max, Last) must be a numeric type — `{ "tokens": 150 }`, not `{ "tokens": "150" }`. String values will not aggregate.
</Warning>

## Usage-Based Billing Analytics

Monitor and analyze your usage-based billing data with comprehensive analytics dashboard. Track customer consumption patterns, meter performance, and billing trends to optimize your pricing strategy and understand usage behaviors.

### Overview Analytics

The Overview tab provides a comprehensive view of your usage-based billing performance:

#### Activity Metrics

Track key usage statistics across different time periods:

<ParamField type="metric">
  Shows usage activity for the current billing period, helping you understand monthly consumption patterns.
</ParamField>

<ParamField type="metric">
  Displays cumulative usage statistics since you started tracking, providing long-term growth insights.
</ParamField>

<Tip>
  Use the time period selector to compare usage across different months and identify seasonal trends or growth patterns.
</Tip>

#### Meter Quantities Chart

<Frame>
  <img alt="Meter quantities chart showing usage trends over time with purple gradient visualization" />
</Frame>

The meter quantities chart visualizes usage trends over time with the following features:

* **Time-series visualization**: Track usage patterns across days, weeks, or months
* **Multiple meter support**: View data from different meters simultaneously
* **Trend analysis**: Identify usage spikes, patterns, and growth trajectories

<Info>
  The chart automatically scales based on your usage volume and selected time range, providing clear visibility into both small fluctuations and major usage changes.
</Info>

### Events Analytics

<Frame>
  <img alt="Events table showing event names, IDs, and pagination controls for detailed event analysis" />
</Frame>

The Events tab provides granular visibility into individual usage events:

#### Event Information Display

The events table provides a clear view of individual usage events with the following columns:

* **Event Name**: The specific action or trigger that generated the usage event
* **Event ID**: Unique identifier for each event instance
* **Customer ID**: The customer associated with the event
* **Timestamp**: When the event occurred

<Info>
  This view allows you to track and monitor individual usage events across your customer base, providing transparency into billing calculations and usage patterns.
</Info>

### Customer Analytics

The Customers tab provides a detailed table view of customer usage data with the following information:

#### Available Data Columns

<ParamField type="string">
  Email address of the customer for identification.
</ParamField>

<ParamField type="string">
  Unique identifier for the customer's subscription.
</ParamField>

<ParamField type="number">
  Number of free units included in the customer's plan before charges apply.
</ParamField>

<ParamField type="currency">
  The cost per unit for usage beyond the free threshold.
</ParamField>

<ParamField type="timestamp">
  Timestamp of the customer's most recent usage event.
</ParamField>

<ParamField type="currency">
  Total amount charged to the customer for usage-based billing.
</ParamField>

<ParamField type="number">
  Total number of units the customer has consumed.
</ParamField>

<ParamField type="number">
  Number of units that exceed the free threshold and are being charged.
</ParamField>

#### Table Features

* **Column Filtering**: Use the "Edit Columns" feature to show/hide specific data columns
* **Real-time Updates**: Usage data reflects the most current consumption metrics

## Aggregation Examples

Here are practical examples of how different aggregation types work:

### Understanding Aggregation Types

Different aggregation types serve different billing scenarios. Choose the right type based on how you want to measure and charge for usage.

### Practical Implementation Examples

These examples demonstrate real-world applications of each aggregation type with sample events and expected results.

<AccordionGroup>
  <Accordion title="Count Aggregation - API Calls">
    Scenario: Track the total number of API requests

    Meter Configuration:

    * Event Name: `api.call`
    * Aggregation Type: Count
    * Measurement Unit: `calls`

    **Sample Events**:

    ```json theme={null}
    {
      "events": [
        {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
        {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
        {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
      ]
    }
    ```

    Result: 3 calls billed to customer
  </Accordion>

  <Accordion title="Sum Aggregation - Data Transfer">
    Scenario: Bill based on total bytes transferred

    Meter Configuration:

    * Event Name: `data.transfer`
    * Aggregation Type: Sum
    * Over Property: `bytes`
    * Measurement Unit: `GB`

    **Sample Events**:

    ```json theme={null}
    {
      "events": [
        {
          "event_id": "transfer_1",
          "customer_id": "cus_123", 
          "event_name": "data.transfer",
          "metadata": {"bytes": 1073741824}
        },
        {
          "event_id": "transfer_2",
          "customer_id": "cus_123",
          "event_name": "data.transfer", 
          "metadata": {"bytes": 536870912}
        }
      ]
    }
    ```

    Result: 1.5 GB total transfer billed to customer
  </Accordion>

  <Accordion title="Max Aggregation - Peak Concurrent Users">
    Scenario: Bill based on highest concurrent user count

    Meter Configuration:

    * Event Name: `concurrent.users`
    * Aggregation Type: Max
    * Over Property: `count`
    * Measurement Unit: `users`

    **Sample Events**:

    ```json theme={null}
    {
      "events": [
        {
          "event_id": "peak_1",
          "customer_id": "cus_123",
          "event_name": "concurrent.users", 
          "metadata": {"count": 15}
        },
        {
          "event_id": "peak_2",
          "customer_id": "cus_123",
          "event_name": "concurrent.users",
          "metadata": {"count": 23}
        },
        {
          "event_id": "peak_3",
          "customer_id": "cus_123",
          "event_name": "concurrent.users",
          "metadata": {"count": 18}
        }
      ]
    }
    ```

    Result: 23 peak concurrent users billed to customer
  </Accordion>
</AccordionGroup>

### Event Filtering Examples

<Tabs>
  <Tab title="Filter by API Endpoint">
    Only count API calls to specific endpoints:

    Filter Configuration:

    * Property: `endpoint`
    * Comparator: `equals`
    * Value: `/v1/orders`

    Sample Event:

    ```json theme={null}
    {
      "event_id": "call_1",
      "customer_id": "cus_123",
      "event_name": "api.call",
      "metadata": {
        "endpoint": "/v1/orders",
        "method": "POST"
      }
    }
    ```

    Result: Events matching the filter criteria would be counted. Events with different endpoints would be ignored.
  </Tab>

  <Tab title="Filter by Value Range">
    Only count large file uploads:

    Filter Configuration:

    * Property: `file_size`
    * Comparator: `greater_than`
    * Value: `1048576` (1MB in bytes)

    Sample Event:

    ```json theme={null}
    {
      "event_id": "upload_1",
      "customer_id": "cus_123", 
      "event_name": "file.upload",
      "metadata": {
        "file_size": 5242880,
        "file_type": "image"
      }
    }
    ```

    Result: Files larger than 1MB would be counted. Smaller files would be ignored.
  </Tab>

  <Tab title="Complex Multi-Condition Filters">
    Count premium API calls during business hours:

    Filter Configuration (using AND logic):

    * Property: `plan_type`, Comparator: `equals`, Value: `premium`
    * Property: `hour`, Comparator: `greater_than_or_equals`, Value: `9`
    * Property: `hour`, Comparator: `less_than`, Value: `17`

    Sample Event:

    ```json theme={null}
    {
      "event_id": "call_1",
      "customer_id": "cus_123",
      "event_name": "api.call",
      "metadata": {
        "plan_type": "premium",
        "hour": 14,
        "endpoint": "/v1/analytics"
      }
    }
    ```

    Result: Premium API calls during business hours (9 AM - 5 PM) would be counted.
  </Tab>
</Tabs>

## Troubleshooting

Resolve common issues with usage-based billing implementation and ensure accurate tracking and billing.

### Common Issues

Most usage-based billing problems fall into these categories:

* Event delivery and processing issues
* Meter configuration problems
* Data type and formatting errors
* Customer ID and authentication issues

### Debugging Steps

When troubleshooting usage-based billing:

1. Verify event delivery in the Events analytics tab
2. Check meter configuration matches your event structure
3. Validate customer IDs and API authentication
4. Review filtering conditions and aggregation settings

### Solutions and Fixes

<AccordionGroup>
  <Accordion title="Events not showing in meter">
    Common causes:

    * Event name doesn't exactly match meter configuration
    * Event filtering conditions are excluding your events
    * Customer ID doesn't exist in your Dodo Payments account
    * Event timestamp is outside the current billing period

    Solutions:

    * Verify event name spelling and case sensitivity
    * Review and test your filtering conditions
    * Confirm customer ID is valid and active
    * Check event timestamps are recent and properly formatted
  </Accordion>

  <Accordion title="Aggregation not working as expected">
    Common causes:

    * Over Property name doesn't match event metadata keys
    * Metadata values are wrong data type (string vs number)
    * Missing required metadata properties

    Solutions:

    * Ensure metadata keys exactly match your Over Property setting
    * Convert string numbers to actual numbers in your events
    * Include all required properties in every event
  </Accordion>

  <Accordion title="Filtering not working">
    Common causes:

    * Filter property names don't match event metadata
    * Wrong comparator for data type (string vs number)
    * Case sensitivity in string comparisons

    Solutions:

    * Double-check property names match exactly
    * Use appropriate comparators for your data types
    * Consider case sensitivity when filtering strings
  </Accordion>
</AccordionGroup>

## Related API Reference

<CardGroup>
  <Card title="Create Meter" icon="gauge" href="/api-reference/meters/create-meter">
    API reference for creating and configuring usage meters for tracking customer consumption
  </Card>

  <Card title="Ingest Usage Events" icon="arrow-right" href="/api-reference/usage-events/ingest-events">
    API reference for sending usage events to your configured meters for billing calculations
  </Card>
</CardGroup>


# Webhooks
Source: https://docs.dodopayments.com/developer-resources/webhooks

Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.

<Frame>
  <img alt="Webhook Cover Image" />
</Frame>

Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.

<Info>
  Our webhook implementation follows the [Standard Webhooks](https://standardwebhooks.com/) specification, ensuring compatibility with industry best practices and existing webhook libraries.
</Info>

## Key Features

<CardGroup>
  <Card title="Real-time Delivery" icon="bolt">
    Receive instant notifications when events occur
  </Card>

  <Card title="Secure by Default" icon="shield-check">
    HMAC SHA256 signature verification included
  </Card>

  <Card title="Automatic Retries" icon="rotate">
    Built-in retry logic with exponential backoff
  </Card>

  <Card title="Event Filtering" icon="filter">
    Subscribe only to events you need
  </Card>
</CardGroup>

## Getting Started

<Info>
  The Dodo Payments webhooks portal has been rebuilt with a native dashboard experience. Your existing endpoints, signing secrets, signature verification, event names, and webhook payloads are unchanged. No integration work is needed.
</Info>

<Note>
  **Where things live.**

  * **Under Developer → Webhooks** — the **Endpoints**, **Event catalog**, **Logs**, **Activity**, and **Settings** tabs.
  * **On an individual endpoint** — the **Overview** tab, carrying delivery stats, the signing secret and **Replay history**, plus the **Testing** and **Advanced** tabs and the bulk replay actions.
  * **On a message** — opened from the **Logs** tab, where each delivery attempt can be replayed on its own without opening the endpoint.
</Note>

<Steps>
  <Step title="Access Webhook Settings">
    Navigate to the Dodo Payments Dashboard and go to **Developer → Webhooks**.
  </Step>

  <Step title="Create Webhook Endpoint">
    Click **Add endpoint** to open the endpoint creation side sheet.
  </Step>

  <Step title="Enter Endpoint URL or Choose Integration">
    Enter the URL where you want to receive webhook events, or select an integration connector to route events to a third-party service (Slack, Discord, Zapier, Resend, etc.).
  </Step>

  <Step title="Select Events to Receive">
    Choose the specific events your endpoint should listen for. Events are organized in a searchable tree grouped by resource. You can select individual events or a parent resource to receive all related events.

    <Tip>
      Only selected events will trigger webhooks to your endpoint, helping you avoid unnecessary traffic and processing.
    </Tip>
  </Step>

  <Step title="Create Endpoint">
    Click **Create endpoint** to save your configuration.
  </Step>

  <Step title="Get Secret Key">
    Your webhook signing secret is displayed on the endpoint's **Overview** tab. You'll use this to verify the authenticity of received webhooks.

    <Warning>
      Keep your webhook secret key secure and never expose it in client-side code or public repositories.
    </Warning>
  </Step>

  <Step title="Rotate Secret (Optional)">
    If needed, you can rotate your webhook secret for enhanced security. Click **Rotate secret**, alongside the secret on the **Overview** tab.

    <Warning>
      Rotating the secret will expire it and replace it with a new one. The old secret will only be valid for the next 24 hours. Afterward, trying to verify with the old secret will fail.
    </Warning>

    <Info>
      Use secret rotation periodically or immediately if you suspect your current secret has been compromised.
    </Info>
  </Step>
</Steps>

## Integration Connectors

Instead of building your own webhook receiver, you can route webhook events directly to third-party services using integration connectors. This eliminates the need to write and maintain custom webhook handlers for popular platforms.

### How Connectors Work

A connector carries a transformation that converts the Dodo Payments event into the shape the destination expects. Which details you supply depends on the destination:

| Connector type           | What you provide                                                    | Destinations                                                                                                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Incoming webhook URL** | A webhook URL you create in the vendor's own dashboard. No API key. | [Slack](/integrations/slack), [Discord](/integrations/discord), [Microsoft Teams](/integrations/microsoft-teams), [Zapier](/integrations/zapier), [Windmill](/integrations/windmill)                                                                 |
| **Vendor API**           | An API key. The destination URL comes from the connector template.  | [Resend](/integrations/resend), [SendGrid](/integrations/sendgrid), [Segment](/integrations/segment), [Customer.io](/integrations/customer-io), [HubSpot](/integrations/hubspot), [Close CRM](/integrations/close-crm), [Loops](/integrations/loops) |

The connector picker in the dashboard shows the full set currently available to your business, so treat the table above as the destinations with step-by-step setup instructions rather than an exhaustive list. See [External Integrations](/integrations/introduction) for what each destination can do once events reach it.

### Setting Up a Connector

Pick a connector while creating or editing an endpoint, and the side sheet shows setup instructions written for that destination — for example, how to create an incoming webhook URL in Slack, or where to find your Resend API key. Before you save, run the connector transformation test to confirm the event is converted correctly for the destination.

<Tip>
  Use a connector to reach a supported destination without writing code. If you need custom logic, use a standard endpoint with a [transformation](#transformations) instead.
</Tip>

## Configuring Subscribed Events

You can configure which specific events each webhook endpoint should receive.

<Steps>
  <Step title="Navigate to Webhook Endpoints">
    Go to your Dodo Payments Dashboard and navigate to **Developer → Webhooks**.
  </Step>

  <Step title="Select Your Endpoint">
    Click on the webhook endpoint you want to configure.
  </Step>

  <Step title="Open Event Configuration">
    Click **Edit** to open the endpoint configuration side sheet.
  </Step>

  <Step title="Browse Event Types">
    The event type selector displays all available webhook events organized in a searchable tree, grouped by resource (e.g., `payment`, `subscription`, `dispute`). Use the search bar to quickly find specific events by name or keyword.
  </Step>

  <Step title="Select Events">
    Check the boxes next to the events you want to receive. You can:

    * Select individual events (e.g., `payment.succeeded`, `payment.failed`)
    * Select a parent resource to receive all related events
    * Mix and match specific events based on your needs
  </Step>

  <Step title="Save Configuration">
    Click **Save** to apply your changes, or **Cancel** to discard modifications.
  </Step>
</Steps>

<Warning>
  If you deselect all events, your webhook endpoint will not receive any notifications. Make sure to select at least the events your application needs to function properly.
</Warning>

## Event Catalog

Go to **Developer → Webhooks** and open the **Event catalog** tab. It lists every event type Dodo Payments can send, so you can see what is available before subscribing an endpoint to it. Select an event to view its schema and an example payload, which is the quickest way to check the shape of a field you plan to read.

<Card title="Webhook Events Guide" icon="list" href="/developer-resources/webhooks/intents/webhook-events-guide">
  Browse the same events as reference documentation, grouped by resource.
</Card>

## Webhook Delivery

### Timeouts

Webhooks have a **15-second timeout window** for both connection and read operations. Ensure your endpoint responds quickly to avoid timeouts.

<Tip>
  Process webhooks asynchronously by acknowledging receipt immediately with a `200` status code, then handling the actual processing in the background.
</Tip>

### Automatic Retries

If a webhook delivery fails, Dodo Payments automatically retries with exponential backoff to prevent overwhelming your system.

| Attempt | Delay       | Description                                                  |
| ------- | ----------- | ------------------------------------------------------------ |
| 1       | Immediately | First retry happens right away                               |
| 2       | 5 seconds   | Second attempt after short delay                             |
| 3       | 5 minutes   | Third attempt with increased backoff                         |
| 4       | 30 minutes  | Fourth attempt continuing backoff                            |
| 5       | 2 hours     | Fifth attempt with extended delay                            |
| 6       | 5 hours     | Sixth attempt with longer delay                              |
| 7       | 10 hours    | Seventh attempt with maximum delay                           |
| 8       | 10 hours    | **Final attempt** - webhook marked as failed if unsuccessful |

<Info>
  **Maximum of 8 retry attempts** per webhook event. For example, if a webhook fails three times before succeeding, the total delivery time is approximately 35 minutes and 5 seconds from the first attempt.
</Info>

<Tip>
  Use the Dodo Payments dashboard to manually retry individual messages or bulk recover all failed messages at any time.
</Tip>

### Idempotency

Each webhook event includes a unique `webhook-id` header. Use this identifier to implement idempotency and prevent duplicate processing.

```javascript theme={null}
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
```

<Warning>
  Always implement idempotency checks. Due to retries, you may receive the same event multiple times.
</Warning>

### Event Ordering

Webhook events may arrive out of order due to retries or network conditions. Design your system to handle events in any sequence.

<Info>
  You will receive the **latest payload at the time of delivery**, regardless of when the webhook event was originally emitted.
</Info>

## Securing Webhooks

To ensure the security of your webhooks, always validate the payloads and use HTTPS.

### Verifying Signatures

Each webhook request includes a `webhook-signature` header, an HMAC SHA256 signature of the webhook payload and timestamp, signed with your secret key.

#### SDK verification (recommended)

All official SDKs include built‑in helpers to securely validate and parse incoming webhooks. Two methods are available:

* `unwrap()`: Verifies signatures using your webhook secret key
* `unsafe_unwrap()`: Parses payloads without verification

<Tip>
  Provide your webhook secret via `DODO_PAYMENTS_WEBHOOK_KEY` when initializing the Dodo Payments client.
</Tip>

<CodeGroup>
  ```typescript TypeScript/Node.js theme={null}
  import DodoPayments from 'dodopayments';
  import express from 'express';

  const app = express();
  app.use(express.raw({ type: 'application/json' }));

  const client = new DodoPayments({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  });

  app.post('/webhook', async (req, res) => {
    try {
      const unwrapped = client.webhooks.unwrap(req.body.toString(), {
        headers: {
          'webhook-id': req.headers['webhook-id'] as string,
          'webhook-signature': req.headers['webhook-signature'] as string,
          'webhook-timestamp': req.headers['webhook-timestamp'] as string,
        },
      });
      res.json({ received: true });
    } catch (error) {
      res.status(401).json({ error: 'Invalid signature' });
    }
  });
  ```

  ```python Python theme={null}
  from fastapi import FastAPI, Request, HTTPException
  from dodopayments import DodoPayments
  import os

  app = FastAPI()
  client = DodoPayments(
      bearer_token=os.getenv("DODO_PAYMENTS_API_KEY"),
      environment=os.getenv("DODO_PAYMENTS_ENVIRONMENT"),
      webhook_key=os.getenv("DODO_PAYMENTS_WEBHOOK_KEY"),
  )

  @app.post("/webhook")
  async def handle_webhook(request: Request):
      try:
          unwrapped = client.webhooks.unwrap(
              await request.body(),
              headers={
                  "webhook-id": request.headers.get("webhook-id", ""),
                  "webhook-signature": request.headers.get("webhook-signature", ""),
                  "webhook-timestamp": request.headers.get("webhook-timestamp", ""),
              },
          )
          return {"received": True}
      except Exception:
          raise HTTPException(status_code=401, detail="Invalid signature")
  ```

  ```go Go theme={null}
  import (
  	"context"
  	"io"
  	"net/http"
  	"os"
  	"github.com/dodopayments/dodopayments-go"
  	"github.com/dodopayments/dodopayments-go/option"
  )

  func webhookHandler(w http.ResponseWriter, r *http.Request) {
  	client := dodopayments.NewClient(
  		option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
  		option.WithEnvironment(os.Getenv("DODO_PAYMENTS_ENVIRONMENT")),
  		option.WithWebhookKey(os.Getenv("DODO_PAYMENTS_WEBHOOK_KEY")),
  	)
  	rawBody, _ := io.ReadAll(r.Body)
  	if _, err := client.Webhooks.Unwrap(context.Background(), rawBody, map[string]string{
  		"webhook-id":       r.Header.Get("webhook-id"),
  		"webhook-signature": r.Header.Get("webhook-signature"),
  		"webhook-timestamp": r.Header.Get("webhook-timestamp"),
  	}); err != nil {
  		http.Error(w, "Invalid signature", http.StatusUnauthorized)
  		return
  	}
  	w.WriteHeader(http.StatusOK)
  }
  ```
</CodeGroup>

#### Manual verification (alternative)

If you are not using an SDK, you can verify signatures yourself following the Standard Webhooks spec:

1. Build the signed message by concatenating `webhook-id`, `webhook-timestamp`, and the exact raw stringified `payload`, separated by periods (`.`).
2. Compute the HMAC SHA256 of that string using your webhook secret key from the Dashboard.
3. Compare the computed signature to the `webhook-signature` header. If they match, the webhook is authentic.

<Info>
  We follow the Standard Webhooks specification. You can use their libraries to verify signatures: [https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries). For event payload formats, see the [Webhook Payload](/developer-resources/webhooks/intents/payment).
</Info>

### Responding to Webhooks

* Your webhook handler must return a `2xx status code` to acknowledge receipt of the event.
* Any other response will be treated as a failure, and the webhook will be retried.

### Best Practices

<AccordionGroup>
  <Accordion title="Use HTTPS endpoints only" icon="lock">
    Always use HTTPS URLs for webhook endpoints. HTTP endpoints are vulnerable to man-in-the-middle attacks and expose your webhook data.
  </Accordion>

  <Accordion title="Respond immediately" icon="bolt">
    Return a `200` status code immediately upon receiving the webhook. Process the event asynchronously to avoid timeouts.

    ```javascript theme={null}
    app.post('/webhook', async (req, res) => {
      // Acknowledge receipt immediately
      res.status(200).json({ received: true });
      
      // Process asynchronously
      processWebhookAsync(req.body).catch(console.error);
    });
    ```
  </Accordion>

  <Accordion title="Handle duplicate events" icon="rotate">
    Implement idempotency using the `webhook-id` header to safely process the same event multiple times without side effects.
  </Accordion>

  <Accordion title="Secure your webhook secret" icon="key">
    Store your webhook secret securely using environment variables or a secrets manager. Never commit secrets to version control.
  </Accordion>
</AccordionGroup>

## Webhook Payload Structure

Understanding the webhook payload structure helps you parse and process events correctly.

### Request Format

```http theme={null}
POST /your-webhook-url
Content-Type: application/json
```

### Headers

<ParamField type="string">
  Unique identifier for this webhook event. Use this for idempotency checks.
</ParamField>

<ParamField type="string">
  HMAC SHA256 signature for verifying the webhook authenticity.
</ParamField>

<ParamField type="string">
  Unix timestamp (in seconds) when the webhook was sent.
</ParamField>

### Request Body

<ResponseField name="business_id" type="string">
  Your Dodo Payments business identifier.
</ResponseField>

<ResponseField name="type" type="string">
  Event type that triggered this webhook (e.g., `payment.succeeded`, `subscription.active`).
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 formatted timestamp of when the event occurred.
</ResponseField>

<ResponseField name="data" type="object">
  Event-specific payload containing detailed information about the event.

  <Expandable title="Data object properties">
    <ResponseField name="payload_type" type="string">
      Type of resource. One of: `Payment`, `Subscription`, `Refund`, `Dispute`, `LicenseKey`, `CreditLedgerEntry`, `CreditBalanceLow`, `AbandonedCheckout`, `DunningAttempt`, `EntitlementGrant`, or `Payout`.
    </ResponseField>

    Additional fields vary by event type. See the event-specific documentation for complete schemas.
  </Expandable>
</ResponseField>

### Example Payload

```json theme={null}
{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey | CreditLedgerEntry | CreditBalanceLow | AbandonedCheckout | DunningAttempt | EntitlementGrant | Payout",
    // ... event-specific fields (see below)
  }
}
```

<CardGroup>
  <Card title="Event Types" icon="list" href="/developer-resources/webhooks/intents/webhook-events-guide">
    Browse all available webhook event types
  </Card>

  <Card title="Event Payloads" icon="code" href="/developer-resources/webhooks/intents/payment">
    View detailed payload schemas for each event
  </Card>

  <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
    React to `payment.failed` and recover declined payments
  </Card>
</CardGroup>

## Testing Webhooks

You can test your webhook integration directly from the Dodo Payments dashboard to ensure your endpoint is working correctly before going live.

<Steps>
  <Step title="Navigate to Webhooks">
    Go to your Dodo Payments Dashboard and navigate to **Developer → Webhooks**.
  </Step>

  <Step title="Select Your Endpoint">
    Click on your webhook endpoint to access its details page.
  </Step>

  <Step title="Open Testing Tab">
    Click on the **Testing** tab to access the webhook testing interface.
  </Step>
</Steps>

### Send an Example Event

The **Testing** tab dispatches a sample payload to this endpoint so you can verify your receiver.

<Steps>
  <Step title="Select Event Type">
    Use **Select an event type** to choose the event you want to test, for example `payment.succeeded` or `payment.failed`.
  </Step>

  <Step title="Send Example">
    Click **Send example**. The sample payload is delivered to your endpoint URL exactly like a real event, signed the same way.

    <Warning>
      Failed messages sent from the Testing tab are not retried. Use it to verify your receiver, not to test the retry schedule.
    </Warning>
  </Step>

  <Step title="Check Your Endpoint">
    The tab records when the **Last example sent** went out. Confirm the event arrived, that your signature verification passed, and that you returned a `2xx` status code.
  </Step>
</Steps>

### Implementation Example

Here's a complete Express.js implementation showing webhook verification and handling:

<CodeGroup>
  ```typescript Express.js Webhook Handler theme={null}
  import { Webhook } from "standardwebhooks";
  import express from "express";

  const app = express();
  app.use(express.json());

  const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

  app.post('/webhook/dodo-payments', async (req, res) => {
    try {
      // Extract webhook headers
      const webhookHeaders = {
        "webhook-id": req.headers["webhook-id"] as string,
        "webhook-signature": req.headers["webhook-signature"] as string,
        "webhook-timestamp": req.headers["webhook-timestamp"] as string,
      };

      // Verify the webhook signature
      const payload = JSON.stringify(req.body);
      await webhook.verify(payload, webhookHeaders);
      
      // Acknowledge receipt immediately
      res.status(200).json({ received: true });
      
      // Process webhook asynchronously
      processWebhookAsync(req.body).catch(console.error);
      
    } catch (error) {
      console.error('Webhook verification failed:', error);
      res.status(400).json({ error: 'Invalid signature' });
    }
  });

  async function processWebhookAsync(data: any) {
    // Handle the webhook event based on type
    switch (data.type) {
      case 'payment.succeeded':
        await handlePaymentSucceeded(data);
        break;
      case 'subscription.active':
        await handleSubscriptionActive(data);
        break;
      // Add more event handlers...
    }
  }
  ```

  ```javascript Testing Webhooks Locally theme={null}
  const { Webhook } = require("standardwebhooks");
  const axios = require("axios");
  const crypto = require("crypto");

  // Generate test webhook
  const timestamp = new Date();
  const webhookId = crypto.randomUUID();
  const payload = {
    business_id: "biz_test123",
    type: "payment.succeeded",
    timestamp: timestamp.toISOString(),
    data: {
      payload_type: "Payment",
      payment_id: "pay_test456",
      amount: 2999
    }
  };

  // Sign the payload
  const webhookSecret = process.env.DODO_WEBHOOK_SECRET;
  const webhookInstance = new Webhook(webhookSecret);
  const payloadString = JSON.stringify(payload);
  const signature = webhookInstance.sign(webhookId, timestamp, payloadString);

  // Send test webhook
  const response = await axios.post('http://localhost:3000/webhook/dodo-payments', payload, {
    headers: {
      "webhook-id": webhookId,
      "webhook-timestamp": Math.floor(timestamp.getTime() / 1000),
      "webhook-signature": signature,
      "Content-Type": "application/json"
    }
  });

  console.log("Test webhook sent successfully:", response.data);
  ```
</CodeGroup>

<Tip>
  Test your webhook handler thoroughly using the dashboard testing interface before processing production events. This helps identify and fix issues early.
</Tip>

## Testing Webhooks with the CLI

The [Dodo Payments CLI](/developer-resources/sdks/cli) provides two commands for testing webhooks during local development, without needing to leave your terminal.

### Listen for Live Webhooks Locally

Forward real webhook events from your test mode account to your local development server in real time:

```bash theme={null}
dodo wh listen
```

The CLI opens a WebSocket connection to Dodo Payments and forwards every webhook event to your local endpoint (e.g., `http://localhost:3000/webhook`), preserving all headers including signature headers for verification testing.

<Info>
  The listener only works with **test mode** API keys. Run `dodo login` and select Test Mode before using this command.
</Info>

### Trigger Mock Webhook Events

Send mock webhook payloads to any endpoint without creating real transactions:

```bash theme={null}
dodo wh trigger
```

This interactive tool lets you pick an event type and sends a realistic mock payload to your endpoint. It loops so you can test multiple events in one session.

The trigger command covers all 46 event types Dodo Payments delivers, including the subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning, and entitlement grant families — see [Supported Webhook Events](/developer-resources/sdks/cli#supported-webhook-events) for the exact list.

<Warning>
  Mock webhook payloads from `dodo wh trigger` are not signed. Use `unsafe_unwrap()` instead of `unwrap()` in your webhook handler during testing only.
</Warning>

<Card title="CLI Webhook Testing Docs" icon="terminal" href="/developer-resources/sdks/cli#webhooks">
  See the full CLI webhook testing documentation
</Card>

## Advanced Settings

The **Advanced** tab provides additional configuration options for fine-tuning your webhook endpoint behavior.

### Rate Limiting (Throttling)

Control the rate at which webhook events are delivered to your endpoint to prevent overwhelming your system.

<Steps>
  <Step title="Open Advanced Tab">
    From your endpoint details page, click the **Advanced** tab.
  </Step>

  <Step title="Configure Rate Limit">
    In the "Rate Limit (throttling)" section, click **Edit** to modify the rate limit settings.

    <Info>
      By default, webhooks have no rate limit applied, meaning events are delivered as soon as they occur.
    </Info>
  </Step>

  <Step title="Set Your Limit">
    Configure your desired rate limit to control webhook delivery frequency and prevent system overload.
  </Step>
</Steps>

<Tip>
  Use rate limiting when your webhook handler needs time to process events or when you want to batch multiple events together.
</Tip>

### Custom Headers

Add custom HTTP headers to all webhook requests sent to your endpoint. This is useful for authentication, routing, or adding metadata.

<Steps>
  <Step title="Add Headers">
    In the "Custom Headers" section, enter a **Key** and **Value** for each custom header.
  </Step>

  <Step title="Add Multiple Headers">
    Click the **+** button to add additional custom headers as needed.
  </Step>
</Steps>

Your custom headers are included in all webhook requests to this endpoint.

### Transformations

Transformations allow you to modify a webhook's payload and optionally redirect it to a different URL. This powerful feature enables you to:

* Modify the payload structure before processing
* Route webhooks to different endpoints based on content
* Add or remove fields from the payload
* Transform data formats

<Steps>
  <Step title="Enable Transformations">
    Toggle the **Enabled** switch to activate the transformation feature.
  </Step>

  <Step title="Configure Transformation">
    Click **Edit transformation** to define your transformation rules using JavaScript.
  </Step>

  <Step title="Test Transformation">
    Use the transformation test interface to verify your transformation works correctly before going live.
  </Step>
</Steps>

<Warning>
  Transformations can impact webhook delivery performance. Test thoroughly and keep transformation logic simple and efficient.
</Warning>

<Tip>
  Transformations are particularly useful for:

  * Converting between different data formats
  * Filtering events based on specific criteria
  * Adding computed fields to the payload
  * Routing events to different microservices
</Tip>

## Monitoring Webhook Logs

The **Logs** tab provides comprehensive visibility into your webhook delivery status, allowing you to monitor, debug, and manage webhook events effectively.

<Steps>
  <Step title="Navigate to Logs Tab">
    Go to **Developer → Webhooks** and open the **Logs** tab.
  </Step>

  <Step title="Browse Delivery History">
    View a table of all webhook delivery attempts with columns for Event type, Message ID, Event ID, Sent at, Attempted at, Response code, and Duration.
  </Step>

  <Step title="Search and Filter">
    Use the search bar to find specific messages by ID or event type. Filter by status (Succeeded, Failed, Pending, etc.) to focus on the events you need to investigate.
  </Step>

  <Step title="View Message Details">
    Click on any message to open the message detail page, which shows:

    * The complete webhook payload
    * Every delivery attempt with response code and duration
    * Timestamp of each attempt
    * Any error messages from your endpoint

    Each attempt carries a **Replay** action, so you can re-drive that one message without leaving the page.
  </Step>
</Steps>

## Activity Monitoring

Go to **Developer → Webhooks** and open the **Activity** tab for a view of delivery performance across your endpoints.

**Delivery activity** plots attempts over time, bucketed as **Attempts per 5 minutes**, **Attempts per hour**, or **Attempts per day** depending on the window. Each bar is split by outcome, and hovering a segment shows the status, the number of attempts, and its share of the total. On an endpoint, **Delivery stats (last 24h)** on the **Overview** tab summarizes the same information for the past day.

<Tip>
  The **Error rate (24h)** column on the **Endpoints** tab tells you at a glance which endpoints need attention, before you open any of them.
</Tip>

## Replaying and Recovering Messages

How you re-drive a message depends on how many you need:

* **One message** — open it from the **Logs** tab and use the **Replay** action on the attempt. No need to open the endpoint.
* **A range of messages** — open the endpoint, since the bulk modes act on a single endpoint at a time.

### Replaying in Bulk

Open the endpoint from **Developer → Webhooks**. Three modes are available, each acting on that endpoint alone. The range you set depends on the mode:

| Mode                        | What it does                                                                                                          | What you set                                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Recover failed messages** | Replays every message to this endpoint that failed.                                                                   | A starting point: **8 hours ago**, **Yesterday**, **3 days ago**, **Last week**, or **2 weeks ago**          |
| **Replay missing messages** | Replays messages that were never dispatched to this endpoint, for example after you subscribe it to a new event type. | The same starting points                                                                                     |
| **Bulk replay messages**    | Replays messages matching the filters you choose, including ones that already delivered successfully.                 | **Since** and **Until** bounds, defaulting to the last two weeks, plus optional event types, channel, or tag |

<Steps>
  <Step title="Open More Actions">
    On the endpoint, open **More actions** and pick one of the three modes above.
  </Step>

  <Step title="Set the Range">
    Fill in the range that mode asks for, as listed in the table.
  </Step>

  <Step title="Start the Run">
    Click **Recover** or **Replay**, depending on the mode you picked.
  </Step>
</Steps>

Every run appears under **Replay history** on the endpoint's **Overview** tab, with its mode, time range, status, and the number of messages resent.

## Email Alerts

Receive an email notification when webhook deliveries to an endpoint are failing, so you can address problems before they turn into a backlog.

<Steps>
  <Step title="Navigate to Settings Tab">
    Go to **Developer → Webhooks** and open the **Settings** tab.
  </Step>

  <Step title="Find Email Alerting">
    Locate the **Email alerting** card.
  </Step>

  <Step title="Configure Email Addresses">
    Enter the addresses that should receive the alerts. Separate multiple addresses with commas, and leave the field empty to turn alerts off.
  </Step>

  <Step title="Save">
    Click **Save** to apply your changes.
  </Step>
</Steps>

<Tip>
  Enable email alerts to catch webhook delivery problems early and maintain reliable integrations.
</Tip>

## Deploy to Cloud Platforms

Ready to deploy your webhook handler to production? We provide platform-specific guides to help you deploy webhooks to popular cloud providers with best practices for each platform.

<CardGroup>
  <Card title="Vercel" icon="triangle" href="/developer-resources/webhooks/examples/vercel-example">
    Deploy webhooks to Vercel with serverless functions
  </Card>

  <Card title="Cloudflare Workers" icon="cloud" href="/developer-resources/webhooks/examples/cloudflare-example">
    Run webhooks on Cloudflare's edge network
  </Card>

  <Card title="Supabase Edge Functions" icon="database" href="/developer-resources/webhooks/examples/supabase-example">
    Integrate webhooks with Supabase
  </Card>

  <Card title="Netlify Functions" icon="circle-nodes" href="/developer-resources/webhooks/examples/netlify-example">
    Deploy webhooks as Netlify serverless functions
  </Card>
</CardGroup>

<Info>
  Each platform guide includes environment setup, signature verification, and deployment steps specific to that provider.
</Info>

## Related API Reference

<CardGroup>
  <Card title="Create Webhook" icon="code" href="/api-reference/webhooks/create-webhook">
    API reference for creating and configuring webhook endpoints programmatically
  </Card>

  <Card title="List Webhooks" icon="list" href="/api-reference/webhooks/list-webhooks">
    API reference for retrieving and managing your webhook endpoints
  </Card>
</CardGroup>


# Cloudflare Workers
Source: https://docs.dodopayments.com/developer-resources/webhooks/examples/cloudflare-example

Deploy DodoPayments webhooks to Cloudflare Workers

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/cloud-functions/tree/main/cloudflare">
  Complete source code and setup guide
</Card>

## Quick Setup

### 1. Prerequisites

* [Cloudflare account](https://dash.cloudflare.com/sign-up)
* [Neon database](https://neon.com) account
* DodoPayments API key from [dashboard](https://app.dodopayments.com/)

### 2. Install Dependencies

```bash theme={null}
npm install -g wrangler
wrangler login
git clone https://github.com/dodopayments/cloud-functions.git
cd cloud-functions/cloudflare
npm install
```

### 3. Database Setup

1. Sign up for [Neon](https://neon.com)
2. Create a new project
3. Open the SQL Editor
4. Copy and paste the contents of [`schema.sql`](#database-schema)
5. Run the query
6. Get your connection string from Neon → Connection Details

### 4. Configure Initial Secrets

```bash theme={null}
# Set your Neon database URL
wrangler secret put DATABASE_URL

# Set your API key
wrangler secret put DODO_PAYMENTS_API_KEY
```

> **Note:** We'll set `DODO_PAYMENTS_WEBHOOK_KEY` after deployment once you have your webhook URL.

### 5. Update wrangler.toml

Edit `wrangler.toml` and set your worker name:

```toml theme={null}
name = "my-dodo-webhook"
```

### 6. Deploy

```bash theme={null}
npm run deploy
```

### 7. Get Your Webhook URL

Your webhook URL is:

```
https://[worker-name].[your-subdomain].workers.dev
```

### 8. Register Webhook in DodoPayments Dashboard

1. Go to [DodoPayments Dashboard](https://app.dodopayments.com) → Developer → Webhooks
2. Create a new webhook endpoint
3. Configure your webhook URL as the endpoint
4. Enable these subscription events:
   * `subscription.active`
   * `subscription.cancelled`
   * `subscription.renewed`
5. Copy the **Signing Secret**

### 9. Set Webhook Key & Redeploy

```bash theme={null}
wrangler secret put DODO_PAYMENTS_WEBHOOK_KEY
npm run deploy
```

## What It Does

Processes subscription events and stores them in PostgreSQL:

* **subscription.active** - Creates/updates customer and subscription records
* **subscription.cancelled** - Marks subscription as cancelled
* **subscription.renewed** - Updates next billing date

## Key Features

✅ **Signature verification** - Using the dodopayments library\
✅ **Idempotency** - Prevents duplicate processing with webhook IDs\
✅ **Event logging** - Complete audit trail in `webhook_events` table\
✅ **Error handling** - Logged and retryable

> **Note:** This implementation demonstrates handling three core subscription events (`subscription.active`, `subscription.cancelled`, `subscription.renewed`) with minimal fields. You can easily extend it to support additional event types and fields based on your requirements.

## Configuration Files

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "dodo-webhook-cloudflare",
    "version": "1.0.0",
    "type": "module",
    "description": "DodoPayments Webhook Handler for Cloudflare Workers",
    "main": "worker.ts",
    "scripts": {
      "dev": "wrangler dev",
      "deploy": "wrangler deploy",
      "tail": "wrangler tail"
    },
    "dependencies": {
      "@neondatabase/serverless": "^1.0.2",
      "dodopayments": "^2.4.1"
    },
    "devDependencies": {
      "@cloudflare/workers-types": "^4.0.0",
      "typescript": "^5.9.3",
      "wrangler": "^4.43.0"
    }
  }
  ```

  ```toml wrangler.toml expandable theme={null}
  # Cloudflare Workers Configuration
  name = "dodo-webhook"
  main = "worker.ts"
  compatibility_date = "2025-10-20"

  [observability]
  [observability.logs]
  enabled = true
  head_sampling_rate = 1
  invocation_logs = true
  persist = true
  ```

  ```json tsconfig.json theme={null}
  {
    "compilerOptions": {
      "target": "ES2022",
      "module": "ES2022",
      "lib": ["ES2022"],
      "moduleResolution": "bundler",
      "types": ["@cloudflare/workers-types"],
      "esModuleInterop": true,
      "strict": true,
      "skipLibCheck": true,
      "resolveJsonModule": true,
      "allowSyntheticDefaultImports": true,
      "forceConsistentCasingInFileNames": true,
      "isolatedModules": true
    },
    "include": ["*.ts"],
    "exclude": ["node_modules"]
  }
  ```
</CodeGroup>

## Database Schema

<CodeGroup>
  ```sql schema.sql expandable theme={null}
  -- DodoPayments Webhook Database Schema
  -- Compatible with PostgreSQL (Supabase, Neon, etc.)

  -- Enable UUID extension (if not already enabled)
  CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

  -- Customers table
  CREATE TABLE IF NOT EXISTS customers (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email TEXT NOT NULL,
    name TEXT NOT NULL,
    dodo_customer_id TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Subscriptions table
  CREATE TABLE IF NOT EXISTS subscriptions (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
    dodo_subscription_id TEXT UNIQUE NOT NULL,
    product_id TEXT NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('pending', 'active', 'on_hold', 'cancelled', 'failed', 'expired')),
    billing_interval TEXT NOT NULL CHECK (billing_interval IN ('day', 'week', 'month', 'year')),
    amount INTEGER NOT NULL,
    currency TEXT NOT NULL,
    next_billing_date TIMESTAMP WITH TIME ZONE NOT NULL,
    cancelled_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Webhook events log
  CREATE TABLE IF NOT EXISTS webhook_events (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    webhook_id TEXT UNIQUE,
    event_type TEXT NOT NULL,
    data JSONB NOT NULL,
    processed BOOLEAN DEFAULT FALSE,
    error_message TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    processed_at TIMESTAMP WITH TIME ZONE,
    attempts INTEGER DEFAULT 0
  );

  -- Indexes for better query performance
  CREATE INDEX IF NOT EXISTS idx_customers_email ON customers(email);
  CREATE INDEX IF NOT EXISTS idx_customers_dodo_id ON customers(dodo_customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_dodo_id ON subscriptions(dodo_subscription_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_customer_id ON subscriptions(customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_status ON subscriptions(status);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_processed ON webhook_events(processed, created_at);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_type ON webhook_events(event_type);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_created_at ON webhook_events(created_at DESC);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_webhook_id ON webhook_events(webhook_id);

  -- Function to automatically update updated_at timestamp
  CREATE OR REPLACE FUNCTION update_updated_at_column()
  RETURNS TRIGGER AS $$
  BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
  END;
  $$ LANGUAGE plpgsql;

  -- Triggers to automatically update updated_at
  CREATE TRIGGER update_customers_updated_at
    BEFORE UPDATE ON customers
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  CREATE TRIGGER update_subscriptions_updated_at
    BEFORE UPDATE ON subscriptions
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  -- Comments for documentation
  COMMENT ON TABLE customers IS 'Stores customer information from DodoPayments';
  COMMENT ON TABLE subscriptions IS 'Stores subscription data from DodoPayments';
  COMMENT ON TABLE webhook_events IS 'Logs all incoming webhook events for audit and retry purposes';

  COMMENT ON COLUMN customers.dodo_customer_id IS 'Unique customer ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.dodo_subscription_id IS 'Unique subscription ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.amount IS 'Amount in smallest currency unit (e.g., cents)';
  COMMENT ON COLUMN subscriptions.currency IS 'Currency used for the subscription payments (e.g., USD, EUR, INR)';
  COMMENT ON COLUMN webhook_events.attempts IS 'Number of processing attempts for failed webhooks';
  COMMENT ON COLUMN webhook_events.data IS 'Full webhook payload as JSON';
  ```
</CodeGroup>

**Tables created:**

* **customers** - Email, name, dodo\_customer\_id
* **subscriptions** - Status, amount, next\_billing\_date, linked to customers
* **webhook\_events** - Event log with webhook\_id for idempotency

## Implementation Code

<CodeGroup>
  ```typescript worker.ts expandable theme={null}
  import { DodoPayments } from 'dodopayments';
  import { neon, NeonQueryFunction } from '@neondatabase/serverless';

  interface Env {
    DATABASE_URL: string;
    DODO_PAYMENTS_API_KEY: string;
    DODO_PAYMENTS_WEBHOOK_KEY: string;
  }

  interface WebhookPayload {
    business_id: string;
    type: string;
    timestamp: string;
    data: {
      payload_type:
        | "Payment"
        | "Subscription"
        | "Refund"
        | "Dispute"
        | "LicenseKey"
        | "CreditLedgerEntry"
        | "CreditBalanceLow"
        | "AbandonedCheckout"
        | "DunningAttempt"
        | "EntitlementGrant"
        | "Payout";
      subscription_id: string;
      customer: {
        customer_id: string;
        email: string;
        name: string;
      };
      product_id: string;
      status: string;
      recurring_pre_tax_amount: number;
      payment_frequency_interval: string;
      created_at: string;
      next_billing_date: string;
      cancelled_at?: string | null;
      currency: string;
    };
  }

  const corsHeaders = {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type, webhook-id, webhook-signature, webhook-timestamp',
    'Access-Control-Allow-Methods': 'POST, OPTIONS',
  };

  async function handleSubscriptionEvent(sql: NeonQueryFunction<false, false>, payload: WebhookPayload, status: string) {
    if (!payload.data.customer.customer_id || !payload.data.subscription_id) {
      throw new Error('Missing required fields: customer_id or subscription_id');
    }

    console.log('🔄 Processing subscription event:', JSON.stringify(payload, null, 2));

    const customer = payload.data.customer;

    // Upsert customer (create if doesn't exist, otherwise use existing)
    const customerResult = await sql`
      INSERT INTO customers (email, name, dodo_customer_id, created_at)
      VALUES (${customer.email}, ${customer.name}, ${customer.customer_id}, ${new Date().toISOString()})
      ON CONFLICT (dodo_customer_id) 
      DO UPDATE SET 
        email = EXCLUDED.email,
        name = EXCLUDED.name,
        updated_at = ${new Date().toISOString()}
      RETURNING id
    `;

    const customerId = customerResult[0].id;
    console.log(`✅ Customer upserted with ID: ${customerId}`);

    // Upsert subscription
    await sql`
      INSERT INTO subscriptions (
        customer_id, dodo_subscription_id, product_id, status, 
        billing_interval, amount, currency, created_at, next_billing_date, cancelled_at, updated_at
      )
      VALUES (
        ${customerId}, ${payload.data.subscription_id},
        ${payload.data.product_id}, ${status},
        ${payload.data.payment_frequency_interval.toLowerCase()}, ${payload.data.recurring_pre_tax_amount},
        ${payload.data.currency}, ${payload.data.created_at}, ${payload.data.next_billing_date},
        ${payload.data.cancelled_at ?? null}, ${new Date().toISOString()}
      )
      ON CONFLICT (dodo_subscription_id) 
      DO UPDATE SET 
        customer_id = EXCLUDED.customer_id,
        product_id = EXCLUDED.product_id,
        status = EXCLUDED.status,
        billing_interval = EXCLUDED.billing_interval,
        amount = EXCLUDED.amount,
        currency = EXCLUDED.currency,
        created_at = EXCLUDED.created_at,
        next_billing_date = EXCLUDED.next_billing_date,
        cancelled_at = EXCLUDED.cancelled_at,
        updated_at = EXCLUDED.updated_at
    `;

    console.log(`✅ Subscription upserted with ${status} status`)
  }

  export default {
    async fetch(request: Request, env: Env): Promise<Response> {
      // Handle CORS preflight
      if (request.method === 'OPTIONS') {
        return new Response('ok', { headers: corsHeaders });
      }

      if (request.method !== 'POST') {
        return new Response(JSON.stringify({ error: 'Method not allowed' }), {
          status: 405,
          headers: { ...corsHeaders, 'Content-Type': 'application/json' }
        });
      }

      try {
        const rawBody = await request.text();
        console.log('📨 Webhook received');

        // Verify required environment variables
        if (!env.DODO_PAYMENTS_API_KEY) {
          console.error('❌ DODO_PAYMENTS_API_KEY is not configured');
          return new Response(
            JSON.stringify({ error: 'API key not configured' }),
            { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
          );
        }

        if (!env.DODO_PAYMENTS_WEBHOOK_KEY) {
          console.error('❌ DODO_PAYMENTS_WEBHOOK_KEY is not configured');
          return new Response(
            JSON.stringify({ error: 'Webhook verification key not configured' }),
            { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
          );
        }

        if (!env.DATABASE_URL) {
          console.error('❌ DATABASE_URL is not configured');
          return new Response(
            JSON.stringify({ error: 'Database URL not configured' }),
            { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
          );
        }

        // Verify webhook signature (required for security)
        const webhookHeaders = {
          'webhook-id': request.headers.get('webhook-id') || '',
          'webhook-signature': request.headers.get('webhook-signature') || '',
          'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
        };

        try {
          const dodoPaymentsClient = new DodoPayments({
            bearerToken: env.DODO_PAYMENTS_API_KEY,
            webhookKey: env.DODO_PAYMENTS_WEBHOOK_KEY,
          });
          const unwrappedWebhook = dodoPaymentsClient.webhooks.unwrap(rawBody, { headers: webhookHeaders });
          console.log('Unwrapped webhook:', unwrappedWebhook);
          console.log('✅ Webhook signature verified');
        } catch (error) {
          console.error('❌ Webhook verification failed:', error);
          return new Response(
            JSON.stringify({ error: 'Webhook verification failed' }),
            { status: 401, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
          );
        }

        // Initialize Neon client
        const sql = neon(env.DATABASE_URL);

        const payload: WebhookPayload = JSON.parse(rawBody);
        const eventType = payload.type;
        const eventData = payload.data;
        const webhookId = request.headers.get('webhook-id') || '';

        console.log(`📋 Webhook payload:`, JSON.stringify(payload, null, 2));

        // Check for duplicate webhook-id (idempotency)
        if (webhookId) {
          const existingEvent = await sql`
            SELECT id FROM webhook_events WHERE webhook_id = ${webhookId}
          `;

          if (existingEvent.length > 0) {
            console.log(`⚠️ Webhook ${webhookId} already processed, skipping (idempotency)`);
            return new Response(
              JSON.stringify({ success: true, message: 'Webhook already processed' }),
              { status: 200, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
            );
          }
        }

        // Log webhook event with webhook_id for idempotency
        const logResult = await sql`
          INSERT INTO webhook_events (webhook_id, event_type, data, processed, created_at)
          VALUES (${webhookId || null}, ${eventType}, ${JSON.stringify(eventData)}, ${false}, ${new Date().toISOString()})
          RETURNING id
        `;

        const loggedEventId = logResult[0].id;
        console.log('📝 Webhook event logged with ID:', loggedEventId);

        console.log(`🔄 Processing: ${eventType} (${eventData.payload_type || 'unknown payload type'})`);

        try {
          switch (eventType) {
            case 'subscription.active':
              await handleSubscriptionEvent(sql, payload, 'active');
              break;
            case 'subscription.cancelled':
              await handleSubscriptionEvent(sql, payload, 'cancelled');
              break;
            case 'subscription.renewed':
              console.log('🔄 Subscription renewed - keeping active status and updating billing date');
              await handleSubscriptionEvent(sql, payload, 'active');
              break;
            default:
              console.log(`ℹ️ Event ${eventType} logged but not processed (no handler available)`);
          }

          await sql`
            UPDATE webhook_events 
            SET processed = ${true}, processed_at = ${new Date().toISOString()}
            WHERE id = ${loggedEventId}
          `;

          console.log('✅ Webhook marked as processed');
        } catch (processingError) {
          console.error('❌ Error processing webhook event:', processingError);

          await sql`
            UPDATE webhook_events 
            SET processed = ${false}, 
                error_message = ${processingError instanceof Error ? processingError.message : 'Unknown error'},
                processed_at = ${new Date().toISOString()}
            WHERE id = ${loggedEventId}
          `;

          throw processingError;
        }

        console.log('✅ Webhook processed successfully');

        return new Response(
          JSON.stringify({
            success: true,
            event_type: eventType,
            event_id: loggedEventId
          }),
          { status: 200, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );

      } catch (error) {
        console.error('❌ Webhook processing failed:', error);
        return new Response(
          JSON.stringify({
            error: 'Webhook processing failed',
            details: error instanceof Error ? error.message : 'Unknown error'
          }),
          { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }
    }
  };
  ```
</CodeGroup>

## How It Works

The webhook handler:

1. **Verifies the signature** - Ensures the request is from DodoPayments using HMAC-SHA256
2. **Checks for duplicates** - Uses webhook ID to prevent processing the same event twice
3. **Logs the event** - Stores raw webhook in `webhook_events` table for audit trail
4. **Processes the event** - Creates or updates customers and subscriptions
5. **Handles errors** - Logs failures and marks event as unprocessed for retry

## Testing

**Local development:**

```bash theme={null}
npm run dev  # Available at http://localhost:8787
```

**Configure in DodoPayments Dashboard:**

1. Go to Developers → Webhooks
2. Add endpoint with your Worker URL
3. Enable: subscription.active, subscription.cancelled, subscription.renewed

## Common Issues

| Issue                     | Solution                                                 |
| ------------------------- | -------------------------------------------------------- |
| Verification failed       | Check webhook key is correct from DodoPayments dashboard |
| Database connection error | Verify Neon connection string                            |
| Worker not deploying      | Run `npm install`, check `wrangler.toml` syntax          |

## Resources

* [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
* [Neon Docs](https://neon.com/docs/)
* [Webhook Events Guide](/developer-resources/webhooks/intents/webhook-events-guide)
* [GitHub Repo](https://github.com/dodopayments/cloud-functions/tree/main/cloudflare)


# Netlify Functions
Source: https://docs.dodopayments.com/developer-resources/webhooks/examples/netlify-example

Deploy DodoPayments webhooks to Netlify Functions

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/cloud-functions/tree/main/netlify">
  Complete source code and setup guide
</Card>

## Quick Setup

### 1. Prerequisites

* [Netlify account](https://app.netlify.com/signup)
* [Neon database](https://neon.com) account
* DodoPayments API key from [dashboard](https://app.dodopayments.com/)

### 2. Install Dependencies

```bash theme={null}
npm install -g netlify-cli
netlify login
git clone https://github.com/dodopayments/cloud-functions.git
cd cloud-functions/netlify
npm install
```

### 3. Database Setup

1. Sign up for [Neon](https://neon.com)
2. Create a new project
3. Open the SQL Editor
4. Copy and paste the contents of [`schema.sql`](#database-schema)
5. Run the query
6. Get your connection string from Neon → Connection Details

### 4. Set Initial Environment Variables

```bash theme={null}
netlify env:set DATABASE_URL "your-neon-connection-string"
netlify env:set DODO_PAYMENTS_API_KEY "your-api-key"
```

> **Note:** We'll set `DODO_PAYMENTS_WEBHOOK_KEY` after deployment once you have your webhook URL.

### 5. Initialize & Deploy

```bash theme={null}
netlify init       # Link to your site (first time only)
npm run deploy
```

### 6. Get Your Webhook URL

Your webhook URL is:

```
https://[your-project].netlify.app/.netlify/functions/webhook
```

### 7. Register Webhook in DodoPayments Dashboard

1. Go to [DodoPayments Dashboard](https://app.dodopayments.com) → Developer → Webhooks
2. Create a new webhook endpoint
3. Configure your webhook URL as the endpoint
4. Enable these subscription events:
   * `subscription.active`
   * `subscription.cancelled`
   * `subscription.renewed`
5. Copy the **Signing Secret**

### 8. Set Webhook Key & Redeploy

```bash theme={null}
netlify env:set DODO_PAYMENTS_WEBHOOK_KEY "your-webhook-signing-key"
npm run deploy
```

## What It Does

Processes subscription events and stores them in PostgreSQL:

* **subscription.active** - Creates/updates customer and subscription records
* **subscription.cancelled** - Marks subscription as cancelled
* **subscription.renewed** - Updates next billing date

## Key Features

✅ **Signature verification** - Using the dodopayments library\
✅ **Idempotency** - Prevents duplicate processing with webhook IDs\
✅ **Event logging** - Complete audit trail in `webhook_events` table\
✅ **Error handling** - Logged and retryable

> **Note:** This implementation demonstrates handling three core subscription events (`subscription.active`, `subscription.cancelled`, `subscription.renewed`) with minimal fields. You can easily extend it to support additional event types and fields based on your requirements.

## Configuration Files

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "dodo-webhook-netlify",
    "version": "1.0.0",
    "type": "module",
    "description": "DodoPayments Webhook Handler for Netlify",
    "scripts": {
      "dev": "netlify dev",
      "deploy": "netlify deploy --prod"
    },
    "dependencies": {
      "@neondatabase/serverless": "^1.0.2",
      "dodopayments": "^2.4.1"
    },
    "devDependencies": {
      "@netlify/functions": "^5.0.0",
      "netlify-cli": "^23.9.1",
      "typescript": "^5.9.3"
    }
  }
  ```

  ```json tsconfig.json theme={null}
  {
    "compilerOptions": {
      "target": "ES2022",
      "module": "ES2022",
      "lib": ["ES2022"],
      "moduleResolution": "node",
      "esModuleInterop": true,
      "strict": true,
      "skipLibCheck": true,
      "resolveJsonModule": true,
      "allowSyntheticDefaultImports": true,
      "forceConsistentCasingInFileNames": true,
      "isolatedModules": true,
      "types": ["node"]
    },
    "include": ["functions/*.ts"],
    "exclude": ["node_modules"]
  }
  ```

  ```toml netlify.toml theme={null}
  [build]
    functions = "functions"

  [build.environment]
    NODE_VERSION = "18"

  [functions]
    # Functions will be available at /.netlify/functions/[function-name]
    directory = "functions"
  ```
</CodeGroup>

## Database Schema

<CodeGroup>
  ```sql schema.sql expandable theme={null}
  -- DodoPayments Webhook Database Schema
  -- Compatible with PostgreSQL (Supabase, Neon, etc.)

  -- Enable UUID extension (if not already enabled)
  CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

  -- Customers table
  CREATE TABLE IF NOT EXISTS customers (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email TEXT NOT NULL,
    name TEXT NOT NULL,
    dodo_customer_id TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Subscriptions table
  CREATE TABLE IF NOT EXISTS subscriptions (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
    dodo_subscription_id TEXT UNIQUE NOT NULL,
    product_id TEXT NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('pending', 'active', 'on_hold', 'cancelled', 'failed', 'expired')),
    billing_interval TEXT NOT NULL CHECK (billing_interval IN ('day', 'week', 'month', 'year')),
    amount INTEGER NOT NULL,
    currency TEXT NOT NULL,
    next_billing_date TIMESTAMP WITH TIME ZONE NOT NULL,
    cancelled_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Webhook events log
  CREATE TABLE IF NOT EXISTS webhook_events (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    webhook_id TEXT UNIQUE,
    event_type TEXT NOT NULL,
    data JSONB NOT NULL,
    processed BOOLEAN DEFAULT FALSE,
    error_message TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    processed_at TIMESTAMP WITH TIME ZONE,
    attempts INTEGER DEFAULT 0
  );

  -- Indexes for better query performance
  CREATE INDEX IF NOT EXISTS idx_customers_email ON customers(email);
  CREATE INDEX IF NOT EXISTS idx_customers_dodo_id ON customers(dodo_customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_dodo_id ON subscriptions(dodo_subscription_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_customer_id ON subscriptions(customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_status ON subscriptions(status);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_processed ON webhook_events(processed, created_at);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_type ON webhook_events(event_type);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_created_at ON webhook_events(created_at DESC);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_webhook_id ON webhook_events(webhook_id);

  -- Function to automatically update updated_at timestamp
  CREATE OR REPLACE FUNCTION update_updated_at_column()
  RETURNS TRIGGER AS $$
  BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
  END;
  $$ LANGUAGE plpgsql;

  -- Triggers to automatically update updated_at
  CREATE TRIGGER update_customers_updated_at
    BEFORE UPDATE ON customers
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  CREATE TRIGGER update_subscriptions_updated_at
    BEFORE UPDATE ON subscriptions
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  -- Comments for documentation
  COMMENT ON TABLE customers IS 'Stores customer information from DodoPayments';
  COMMENT ON TABLE subscriptions IS 'Stores subscription data from DodoPayments';
  COMMENT ON TABLE webhook_events IS 'Logs all incoming webhook events for audit and retry purposes';

  COMMENT ON COLUMN customers.dodo_customer_id IS 'Unique customer ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.dodo_subscription_id IS 'Unique subscription ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.amount IS 'Amount in smallest currency unit (e.g., cents)';
  COMMENT ON COLUMN subscriptions.currency IS 'Currency used for the subscription payments (e.g., USD, EUR, INR)';
  COMMENT ON COLUMN webhook_events.attempts IS 'Number of processing attempts for failed webhooks';
  COMMENT ON COLUMN webhook_events.data IS 'Full webhook payload as JSON';
  ```
</CodeGroup>

**Tables created:**

* **customers** - Email, name, dodo\_customer\_id
* **subscriptions** - Status, amount, next\_billing\_date, linked to customers
* **webhook\_events** - Event log with webhook\_id for idempotency

## Implementation Code

<CodeGroup>
  ```typescript functions/webhook.ts expandable theme={null}
  import { Handler, HandlerEvent, HandlerContext } from '@netlify/functions';
  import { neon, NeonQueryFunction } from '@neondatabase/serverless';
  import { DodoPayments } from 'dodopayments';

  interface WebhookPayload {
    business_id: string;
    type: string;
    timestamp: string;
    data: {
      payload_type:
        | "Payment"
        | "Subscription"
        | "Refund"
        | "Dispute"
        | "LicenseKey"
        | "CreditLedgerEntry"
        | "CreditBalanceLow"
        | "AbandonedCheckout"
        | "DunningAttempt"
        | "EntitlementGrant"
        | "Payout";
      subscription_id: string;
      customer: {
        customer_id: string;
        email: string;
        name: string;
      };
      product_id: string;
      status: string;
      recurring_pre_tax_amount: number;
      payment_frequency_interval: string;
      created_at: string;
      next_billing_date: string;
      cancelled_at?: string | null;
      currency: string;
    };
  }

  const corsHeaders = {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type, webhook-id, webhook-signature, webhook-timestamp',
    'Access-Control-Allow-Methods': 'POST, OPTIONS',
  };

  async function handleSubscriptionEvent(sql: NeonQueryFunction<false, false>, payload: WebhookPayload, status: string) {
    if (!payload.data.customer.customer_id || !payload.data.subscription_id) {
      throw new Error('Missing required fields: customer_id or subscription_id');
    }

    console.log('🔄 Processing subscription event:', JSON.stringify(payload, null, 2));

    const customer = payload.data.customer;

    // Upsert customer (create if doesn't exist, otherwise use existing)
    const customerResult = await sql`
      INSERT INTO customers (email, name, dodo_customer_id, created_at)
      VALUES (${customer.email}, ${customer.name}, ${customer.customer_id}, ${new Date().toISOString()})
      ON CONFLICT (dodo_customer_id) 
      DO UPDATE SET 
        email = EXCLUDED.email,
        name = EXCLUDED.name,
        updated_at = ${new Date().toISOString()}
      RETURNING id
    `;

    const customerId = customerResult[0].id;
    console.log(`✅ Customer upserted with ID: ${customerId}`);

    // Upsert subscription
    await sql`
      INSERT INTO subscriptions (
        customer_id, dodo_subscription_id, product_id, status, 
        billing_interval, amount, currency, created_at, next_billing_date, cancelled_at, updated_at
      )
      VALUES (
        ${customerId}, ${payload.data.subscription_id},
        ${payload.data.product_id}, ${status},
        ${payload.data.payment_frequency_interval.toLowerCase()}, ${payload.data.recurring_pre_tax_amount},
        ${payload.data.currency}, ${payload.data.created_at}, ${payload.data.next_billing_date},
        ${payload.data.cancelled_at ?? null}, ${new Date().toISOString()}
      )
      ON CONFLICT (dodo_subscription_id) 
      DO UPDATE SET 
        customer_id = EXCLUDED.customer_id,
        product_id = EXCLUDED.product_id,
        status = EXCLUDED.status,
        billing_interval = EXCLUDED.billing_interval,
        amount = EXCLUDED.amount,
        currency = EXCLUDED.currency,
        created_at = EXCLUDED.created_at,
        next_billing_date = EXCLUDED.next_billing_date,
        cancelled_at = EXCLUDED.cancelled_at,
        updated_at = EXCLUDED.updated_at
    `;

    console.log(`✅ Subscription upserted with ${status} status`)
  }

  export const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
    // Handle CORS preflight
    if (event.httpMethod === 'OPTIONS') {
      return {
        statusCode: 200,
        headers: corsHeaders,
        body: 'ok'
      };
    }

    if (event.httpMethod !== 'POST') {
      return {
        statusCode: 405,
        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
        body: JSON.stringify({ error: 'Method not allowed' })
      };
    }

    try {
      const rawBody = event.body || '';
      console.log('📨 Webhook received');

      const DATABASE_URL = process.env.DATABASE_URL;
      const API_KEY = process.env.DODO_PAYMENTS_API_KEY;
      const WEBHOOK_KEY = process.env.DODO_PAYMENTS_WEBHOOK_KEY;

      if (!DATABASE_URL) {
        console.error('❌ Missing DATABASE_URL environment variable');
        return {
          statusCode: 500,
          headers: { ...corsHeaders, 'Content-Type': 'application/json' },
          body: JSON.stringify({ error: 'Server configuration error' })
        };
      }

      // Verify required environment variables
      if (!API_KEY) {
        console.error('❌ DODO_PAYMENTS_API_KEY is not configured');
        return {
          statusCode: 500,
          headers: { ...corsHeaders, 'Content-Type': 'application/json' },
          body: JSON.stringify({ error: 'API key not configured' })
        };
      }

      if (!WEBHOOK_KEY) {
        console.error('❌ DODO_PAYMENTS_WEBHOOK_KEY is not configured');
        return {
          statusCode: 500,
          headers: { ...corsHeaders, 'Content-Type': 'application/json' },
          body: JSON.stringify({ error: 'Webhook verification key not configured' })
        };
      }

      // Verify webhook signature (required for security)
      const webhookHeaders = {
        'webhook-id': event.headers['webhook-id'] || '',
        'webhook-signature': event.headers['webhook-signature'] || '',
        'webhook-timestamp': event.headers['webhook-timestamp'] || '',
      };

      try {
        const dodoPaymentsClient = new DodoPayments({
          bearerToken: API_KEY,
          webhookKey: WEBHOOK_KEY,
        });
        const unwrappedWebhook = dodoPaymentsClient.webhooks.unwrap(rawBody, { headers: webhookHeaders });
        console.log('Unwrapped webhook:', unwrappedWebhook);
        console.log('✅ Webhook signature verified');
      } catch (error) {
        console.error('❌ Webhook verification failed:', error);
        return {
          statusCode: 401,
          headers: { ...corsHeaders, 'Content-Type': 'application/json' },
          body: JSON.stringify({ error: 'Webhook verification failed' })
        };
      }

      // Initialize Neon client
      const sql = neon(DATABASE_URL);

      const payload: WebhookPayload = JSON.parse(rawBody);
      const eventType = payload.type;
      const eventData = payload.data;
      const webhookId = event.headers['webhook-id'] || '';

      console.log(`📋 Webhook payload:`, JSON.stringify(payload, null, 2));

      // Check for duplicate webhook-id (idempotency)
      if (webhookId) {
        const existingEvent = await sql`
          SELECT id FROM webhook_events WHERE webhook_id = ${webhookId}
        `;

        if (existingEvent.length > 0) {
          console.log(`⚠️ Webhook ${webhookId} already processed, skipping (idempotency)`);
          return {
            statusCode: 200,
            headers: { ...corsHeaders, 'Content-Type': 'application/json' },
            body: JSON.stringify({ success: true, message: 'Webhook already processed' })
          };
        }
      }

      // Log webhook event with webhook_id for idempotency
      const logResult = await sql`
        INSERT INTO webhook_events (webhook_id, event_type, data, processed, created_at)
        VALUES (${webhookId || null}, ${eventType}, ${JSON.stringify(eventData)}, ${false}, ${new Date().toISOString()})
        RETURNING id
      `;

      const loggedEventId = logResult[0].id;
      console.log('📝 Webhook event logged with ID:', loggedEventId);

      console.log(`🔄 Processing: ${eventType} (${eventData.payload_type || 'unknown payload type'})`);

      try {
        switch (eventType) {
          case 'subscription.active':
            await handleSubscriptionEvent(sql, payload, 'active');
            break;
          case 'subscription.cancelled':
            await handleSubscriptionEvent(sql, payload, 'cancelled');
            break;
          case 'subscription.renewed':
            console.log('🔄 Subscription renewed - keeping active status and updating billing date');
            await handleSubscriptionEvent(sql, payload, 'active');
            break;
          default:
            console.log(`ℹ️ Event ${eventType} logged but not processed (no handler available)`);
        }

        await sql`
          UPDATE webhook_events 
          SET processed = ${true}, processed_at = ${new Date().toISOString()}
          WHERE id = ${loggedEventId}
        `;

        console.log('✅ Webhook marked as processed');
      } catch (processingError) {
        console.error('❌ Error processing webhook event:', processingError);

        await sql`
          UPDATE webhook_events 
          SET processed = ${false}, 
              error_message = ${processingError instanceof Error ? processingError.message : 'Unknown error'},
              processed_at = ${new Date().toISOString()}
          WHERE id = ${loggedEventId}
        `;

        throw processingError;
      }

      console.log('✅ Webhook processed successfully');

      return {
        statusCode: 200,
        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          success: true,
          event_type: eventType,
          event_id: loggedEventId
        })
      };

    } catch (error) {
      console.error('❌ Webhook processing failed:', error);
      return {
        statusCode: 500,
        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          error: 'Webhook processing failed',
          details: error instanceof Error ? error.message : 'Unknown error'
        })
      };
    }
  };
  ```
</CodeGroup>

## How It Works

The webhook handler:

1. **Verifies the signature** - Ensures the request is from DodoPayments using HMAC-SHA256
2. **Checks for duplicates** - Uses webhook ID to prevent processing the same event twice
3. **Logs the event** - Stores raw webhook in `webhook_events` table for audit trail
4. **Processes the event** - Creates or updates customers and subscriptions in Neon
5. **Handles errors** - Logs failures and marks event as unprocessed for retry

## Testing

**Local development:**

```bash theme={null}
npm run dev  # Available at http://localhost:8888/.netlify/functions/webhook
```

**View logs in Netlify Dashboard:**

1. Select your site → **Functions** tab
2. Click on the `webhook` function
3. View real-time logs and invocation history

**Configure in DodoPayments Dashboard:**

1. Go to Developers → Webhooks
2. Add endpoint with your Netlify Functions URL
3. Enable: subscription.active, subscription.cancelled, subscription.renewed

## Common Issues

| Issue                     | Solution                                                 |
| ------------------------- | -------------------------------------------------------- |
| Verification failed       | Check webhook key is correct from DodoPayments dashboard |
| Database connection error | Verify Neon connection string and use pooled connection  |
| Function not found (404)  | Run `netlify init` and `npm run deploy` again            |
| Env vars not available    | Set variables in CLI or dashboard, then redeploy         |

## Resources

* [Netlify Functions Docs](https://docs.netlify.com/functions/overview/)
* [Netlify CLI](https://docs.netlify.com/cli/get-started/)
* [Neon Docs](https://neon.com/docs/)
* [Webhook Events Guide](/developer-resources/webhooks/intents/webhook-events-guide)
* [GitHub Repo](https://github.com/dodopayments/cloud-functions/tree/main/netlify)


# Supabase Edge Functions
Source: https://docs.dodopayments.com/developer-resources/webhooks/examples/supabase-example

Deploy DodoPayments webhooks to Supabase Edge Functions

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/cloud-functions/tree/main/supabase">
  Complete source code and setup guide
</Card>

<Tip>
  <strong>Checkout the complete starter kit for supabase</strong><br />
  A minimal subscription starter kit built with Next.js, Supabase, and Dodo Payments. This boilerplate helps you quickly set up a subscription-based SaaS with authentication, payments, and webhooks.

  <a href="https://github.com/dodopayments/dodo-supabase-subscription-starter">
    Dodo Payments Supabase Subscription Starter
  </a>
</Tip>

## Quick Setup

### 1. Prerequisites

* [Supabase account](https://supabase.com/dashboard)
* A Supabase project created
* DodoPayments API key from [dashboard](https://app.dodopayments.com/)

### 2. Authenticate & Link

```bash theme={null}
npx supabase login
git clone https://github.com/dodopayments/cloud-functions.git
cd cloud-functions/supabase
npx supabase link --project-ref your-project-ref
```

Get your project ref from [Supabase Dashboard](https://supabase.com/dashboard) → Project Settings

### 3. Database Setup

1. Go to your [Supabase Dashboard](https://supabase.com/dashboard)
2. Open the SQL Editor
3. Create a new query
4. Copy and paste the entire contents of [`schema.sql`](#database-schema)
5. Run the query

### 4. Set Initial Secrets

Supabase automatically provides `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` at runtime.

```bash theme={null}
npx supabase secrets set DODO_PAYMENTS_API_KEY=your-api-key
```

> **Note:** We'll set `DODO_PAYMENTS_WEBHOOK_KEY` after deployment once you have your webhook URL.

### 5. Deploy

The function is already set up in `functions/webhook/index.ts` - just deploy it:

```bash theme={null}
npm run deploy
```

### 6. Get Your Webhook URL

Your webhook URL is:

```
https://[project-ref].supabase.co/functions/v1/webhook
```

### 7. Register Webhook in DodoPayments Dashboard

1. Go to [DodoPayments Dashboard](https://app.dodopayments.com) → Developer → Webhooks
2. Create a new webhook endpoint
3. Configure your webhook URL as the endpoint
4. Enable these subscription events:
   * `subscription.active`
   * `subscription.cancelled`
   * `subscription.renewed`
5. Copy the **Signing Secret**

### 8. Set Webhook Key & Redeploy

```bash theme={null}
npx supabase secrets set DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-signing-key
npm run deploy
```

## What It Does

Processes subscription events and stores them in Supabase PostgreSQL:

* **subscription.active** - Creates/updates customer and subscription records
* **subscription.cancelled** - Marks subscription as cancelled
* **subscription.renewed** - Updates next billing date

## Key Features

✅ **Signature verification** - Using the dodopayments library\
✅ **Idempotency** - Prevents duplicate processing with webhook IDs\
✅ **Event logging** - Complete audit trail in `webhook_events` table\
✅ **Error handling** - Logged and retryable

> **Note:** This implementation demonstrates handling three core subscription events (`subscription.active`, `subscription.cancelled`, `subscription.renewed`) with minimal fields. You can easily extend it to support additional event types and fields based on your requirements.

## Configuration Files

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "dodo-webhook-supabase",
    "version": "1.0.0",
    "type": "module",
    "description": "DodoPayments Webhook Handler for Supabase Edge Functions",
    "scripts": {
      "dev": "npx supabase functions serve webhook --no-verify-jwt --workdir ..",
      "deploy": "npx supabase functions deploy webhook --no-verify-jwt --workdir .."
    }
  }
  ```

  ```json tsconfig.json theme={null}
  {
    "compilerOptions": {
      "target": "ES2022",
      "module": "ES2022",
      "lib": ["ES2022", "DOM"],
      "moduleResolution": "bundler",
      "esModuleInterop": true,
      "strict": true,
      "skipLibCheck": true,
      "resolveJsonModule": true,
      "allowSyntheticDefaultImports": true,
      "forceConsistentCasingInFileNames": true,
      "isolatedModules": true
    },
    "include": ["functions/webhook/*.ts"],
    "exclude": ["node_modules"]
  }
  ```
</CodeGroup>

## Database Schema

<CodeGroup>
  ```sql schema.sql expandable theme={null}
  -- DodoPayments Webhook Database Schema
  -- Compatible with PostgreSQL (Supabase, Neon, etc.)

  -- Enable UUID extension (if not already enabled)
  CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

  -- Customers table
  CREATE TABLE IF NOT EXISTS customers (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email TEXT NOT NULL,
    name TEXT NOT NULL,
    dodo_customer_id TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Subscriptions table
  CREATE TABLE IF NOT EXISTS subscriptions (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
    dodo_subscription_id TEXT UNIQUE NOT NULL,
    product_id TEXT NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('pending', 'active', 'on_hold', 'cancelled', 'failed', 'expired')),
    billing_interval TEXT NOT NULL CHECK (billing_interval IN ('day', 'week', 'month', 'year')),
    amount INTEGER NOT NULL,
    currency TEXT NOT NULL,
    next_billing_date TIMESTAMP WITH TIME ZONE NOT NULL,
    cancelled_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Webhook events log
  CREATE TABLE IF NOT EXISTS webhook_events (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    webhook_id TEXT UNIQUE,
    event_type TEXT NOT NULL,
    data JSONB NOT NULL,
    processed BOOLEAN DEFAULT FALSE,
    error_message TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    processed_at TIMESTAMP WITH TIME ZONE,
    attempts INTEGER DEFAULT 0
  );

  -- Indexes for better query performance
  CREATE INDEX IF NOT EXISTS idx_customers_email ON customers(email);
  CREATE INDEX IF NOT EXISTS idx_customers_dodo_id ON customers(dodo_customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_dodo_id ON subscriptions(dodo_subscription_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_customer_id ON subscriptions(customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_status ON subscriptions(status);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_processed ON webhook_events(processed, created_at);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_type ON webhook_events(event_type);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_created_at ON webhook_events(created_at DESC);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_webhook_id ON webhook_events(webhook_id);

  -- Function to automatically update updated_at timestamp
  CREATE OR REPLACE FUNCTION update_updated_at_column()
  RETURNS TRIGGER AS $$
  BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
  END;
  $$ LANGUAGE plpgsql;

  -- Triggers to automatically update updated_at
  CREATE TRIGGER update_customers_updated_at
    BEFORE UPDATE ON customers
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  CREATE TRIGGER update_subscriptions_updated_at
    BEFORE UPDATE ON subscriptions
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  -- Comments for documentation
  COMMENT ON TABLE customers IS 'Stores customer information from DodoPayments';
  COMMENT ON TABLE subscriptions IS 'Stores subscription data from DodoPayments';
  COMMENT ON TABLE webhook_events IS 'Logs all incoming webhook events for audit and retry purposes';

  COMMENT ON COLUMN customers.dodo_customer_id IS 'Unique customer ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.dodo_subscription_id IS 'Unique subscription ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.amount IS 'Amount in smallest currency unit (e.g., cents)';
  COMMENT ON COLUMN subscriptions.currency IS 'Currency used for the subscription payments (e.g., USD, EUR, INR)';
  COMMENT ON COLUMN webhook_events.attempts IS 'Number of processing attempts for failed webhooks';
  COMMENT ON COLUMN webhook_events.data IS 'Full webhook payload as JSON';
  ```
</CodeGroup>

**Tables created:**

* **customers** - Email, name, dodo\_customer\_id
* **subscriptions** - Status, amount, next\_billing\_date, linked to customers
* **webhook\_events** - Event log with webhook\_id for idempotency

## Implementation Code

<CodeGroup>
  ```typescript functions/webhook/index.ts expandable theme={null}
  import { serve } from 'https://deno.land/std@0.208.0/http/server.ts';
  import { createClient, SupabaseClient } from 'https://esm.sh/@supabase/supabase-js@2.38.4';
  import { DodoPayments } from 'https://esm.sh/dodopayments@2.4.1';

  export const corsHeaders = {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type, webhook-id, webhook-signature, webhook-timestamp',
    'Access-Control-Allow-Methods': 'POST, OPTIONS',
  };

  interface WebhookPayload {
    business_id: string;
    type: string;
    timestamp: string;
    data: {
      payload_type:
        | "Payment"
        | "Subscription"
        | "Refund"
        | "Dispute"
        | "LicenseKey"
        | "CreditLedgerEntry"
        | "CreditBalanceLow"
        | "AbandonedCheckout"
        | "DunningAttempt"
        | "EntitlementGrant"
        | "Payout";
      subscription_id: string;
      customer: {
        customer_id: string;
        email: string;
        name: string;
      };
      product_id: string;
      status: string;
      recurring_pre_tax_amount: number;
      payment_frequency_interval: string;
      created_at: string;
      next_billing_date: string;
      cancelled_at?: string | null;
      currency: string;
    };
  }

  // Handle subscription events
  async function handleSubscriptionEvent(supabase: SupabaseClient, payload: WebhookPayload, status: string) {
    if (!payload.data.customer.customer_id || !payload.data.subscription_id) {
      throw new Error('Missing required fields: customer_id or subscription_id');
    }

    try {
      console.log('🔄 Processing subscription event:', JSON.stringify(payload, null, 2));
      
      const customer = payload.data.customer;
      
      // Upsert customer (create if doesn't exist, otherwise update)
      const customerResult = await supabase
        .from('customers')
        .upsert({
          email: customer.email,
          name: customer.name,
          dodo_customer_id: customer.customer_id
        }, {
          onConflict: 'dodo_customer_id',
          ignoreDuplicates: false
        })
        .select('id')
        .single();

      if (customerResult.error) {
        console.error('❌ Failed to upsert customer:', customerResult.error);
        throw new Error(`Failed to upsert customer: ${customerResult.error.message}`);
      }

      const customerId = customerResult.data.id;
      console.log(`✅ Customer upserted with ID: ${customerId}`);

      // Upsert subscription
      const subscriptionResult = await supabase
        .from('subscriptions')
        .upsert({
          customer_id: customerId,
          dodo_subscription_id: payload.data.subscription_id,
          product_id: payload.data.product_id,
          status,
          billing_interval: payload.data.payment_frequency_interval.toLowerCase(),
          amount: payload.data.recurring_pre_tax_amount,
          currency: payload.data.currency,
          created_at: payload.data.created_at,
          next_billing_date: payload.data.next_billing_date,
          cancelled_at: payload.data.cancelled_at ?? null,
          updated_at: new Date().toISOString()
        }, {
          onConflict: 'dodo_subscription_id',
          ignoreDuplicates: false
        })
        .select();

      if (subscriptionResult.error) {
        console.error('❌ Failed to upsert subscription:', subscriptionResult.error);
        throw new Error(`Failed to upsert subscription: ${subscriptionResult.error.message}`);
      }

      console.log(`✅ Subscription upserted with ${status} status`);

    } catch (error) {
      console.error('❌ Error in handleSubscriptionEvent:', error);
      console.error('❌ Raw webhook data:', JSON.stringify(payload, null, 2));
      throw error;
    }
  }

  serve(async (req: Request) => {
    if (req.method === 'OPTIONS') {
      return new Response('ok', { headers: corsHeaders });
    }

    // Validate required environment variables
    try {
      const supabaseUrl = Deno.env.get('SUPABASE_URL');
      const supabaseServiceKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY');
      
      if (!supabaseUrl || !supabaseServiceKey) {
        console.error('❌ Missing required environment variables');
        return new Response(
          JSON.stringify({ error: 'Server configuration error' }),
          { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }

      const rawBody = await req.text();
      console.log('📨 Webhook received');

      const apiKey = Deno.env.get('DODO_PAYMENTS_API_KEY');
      const webhookKey = Deno.env.get('DODO_PAYMENTS_WEBHOOK_KEY');

      if (!apiKey) {
        console.error('❌ DODO_PAYMENTS_API_KEY is not configured');
        return new Response(
          JSON.stringify({ error: 'API key not configured' }),
          { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }

      if (!webhookKey) {
        console.error('❌ DODO_PAYMENTS_WEBHOOK_KEY is not configured');
        return new Response(
          JSON.stringify({ error: 'Webhook verification key not configured' }),
          { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }

      // Verify webhook signature (required for security)
      const webhookHeaders = {
        'webhook-id': req.headers.get('webhook-id') || '',
        'webhook-signature': req.headers.get('webhook-signature') || '',
        'webhook-timestamp': req.headers.get('webhook-timestamp') || '',
      };

      try {
        const dodoPaymentsClient = new DodoPayments({
          bearerToken: apiKey,
          webhookKey: webhookKey,
        });
        const unwrappedWebhook = dodoPaymentsClient.webhooks.unwrap(rawBody, { headers: webhookHeaders });
        console.log('Unwrapped webhook:', unwrappedWebhook);
        console.log('✅ Webhook signature verified');
      } catch (error) {
        console.error('❌ Webhook verification failed:', error);
        return new Response(
          JSON.stringify({ 
            error: 'Webhook verification failed',
            details: error instanceof Error ? error.message : 'Invalid signature'
          }),
          { status: 401, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }

      // Initialize Supabase client
      const supabase = createClient(supabaseUrl, supabaseServiceKey);

      let payload: WebhookPayload;
      try {
        payload = JSON.parse(rawBody) as WebhookPayload;
      } catch (parseError) {
        console.error('❌ Failed to parse webhook payload:', parseError);
        return new Response(
          JSON.stringify({ error: 'Invalid JSON payload' }),
          { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }

      const eventType = payload.type;
      const eventData = payload.data;
      const webhookId = req.headers.get('webhook-id') || '';

      console.log(`📋 Webhook payload:`, JSON.stringify(payload, null, 2));

      // Check for duplicate webhook-id (idempotency)
      if (webhookId) {
        const { data: existingEvent } = await supabase
          .from('webhook_events')
          .select('id')
          .eq('webhook_id', webhookId)
          .single();

        if (existingEvent) {
          console.log(`⚠️ Webhook ${webhookId} already processed, skipping (idempotency)`);
          return new Response(
            JSON.stringify({ success: true, message: 'Webhook already processed' }),
            { status: 200, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
          );
        }
      }

      // Log webhook event with webhook_id for idempotency
      const logResult = await supabase.from('webhook_events').insert([{
        webhook_id: webhookId || null,
        event_type: eventType,
        data: eventData,
        processed: false,
        created_at: new Date().toISOString()
      }]).select('id').single();

      if (logResult.error) {
        console.error('❌ Failed to log webhook event:', logResult.error);
        return new Response(
          JSON.stringify({ error: 'Failed to log webhook event' }),
          { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }

      const loggedEventId = logResult.data.id;
      console.log('📝 Webhook event logged with ID:', loggedEventId);

      console.log(`🔄 Processing: ${eventType} (${eventData.payload_type || 'unknown payload type'})`);

      try {
        switch (eventType) {
          case 'subscription.active':
            await handleSubscriptionEvent(supabase, payload, 'active');
            break;
          case 'subscription.cancelled':
            await handleSubscriptionEvent(supabase, payload, 'cancelled');
            break;
          case 'subscription.renewed':
            console.log('🔄 Subscription renewed - keeping active status and updating billing date');
            await handleSubscriptionEvent(supabase, payload, 'active');
            break;
          default:
            console.log(`ℹ️ Event ${eventType} logged but not processed (no handler available)`);
        }
        
        const updateResult = await supabase
          .from('webhook_events')
          .update({ 
            processed: true, 
            processed_at: new Date().toISOString() 
          })
          .eq('id', loggedEventId);
        
        if (updateResult.error) {
          console.error('❌ Failed to mark webhook as processed:', updateResult.error);
        } else {
          console.log('✅ Webhook marked as processed');
        }
      } catch (processingError) {
        console.error('❌ Error processing webhook event:', processingError);
        
        await supabase
          .from('webhook_events')
          .update({ 
            processed: false,
            error_message: processingError instanceof Error ? processingError.message : 'Unknown error',
            processed_at: new Date().toISOString()
          })
          .eq('id', loggedEventId);
        
        throw processingError;
      }

      console.log('✅ Webhook processed successfully');

      return new Response(
        JSON.stringify({ 
          success: true, 
          event_type: eventType,
          event_id: loggedEventId
        }),
        { status: 200, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
      );

    } catch (error) {
      console.error('❌ Webhook processing failed:', error);
      return new Response(
        JSON.stringify({ 
          error: 'Webhook processing failed',
          details: error instanceof Error ? error.message : 'Unknown error'
        }),
        { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
      );
    }
  });
  ```
</CodeGroup>

## How It Works

The Deno-based Edge Function:

1. **Verifies signature** - Uses dodopayments library for HMAC-SHA256 verification
2. **Checks idempotency** - Looks up webhook ID to prevent duplicate processing
3. **Logs the event** - Stores raw webhook data in `webhook_events` table
4. **Processes updates** - Creates or updates customers and subscriptions via Supabase client
5. **Handles errors** - Logs failures and marks event for retry

## Testing

**Local development:**

```bash theme={null}
cd supabase
npm run dev
# Available at http://localhost:54321/functions/v1/webhook
```

<Note>
  The `--no-verify-jwt` flag is required because webhooks don't include JWT tokens. Security is provided by webhook signature verification.
</Note>

**View logs:**

```bash theme={null}
npx supabase functions logs webhook
```

Or in [Supabase Dashboard](https://supabase.com/dashboard) → Edge Functions → webhook → Logs tab

**Configure in DodoPayments Dashboard:**

1. Go to Developers → Webhooks
2. Add endpoint with your Supabase URL
3. Enable: subscription.active, subscription.cancelled, subscription.renewed

## Common Issues

| Issue                     | Solution                                                 |
| ------------------------- | -------------------------------------------------------- |
| Verification failed       | Check webhook key is correct from DodoPayments dashboard |
| Database permission error | Ensure using Service Role Key                            |
| JWT verification error    | Deploy with `--no-verify-jwt` flag                       |
| Function not found        | Verify project ref is correct and function is deployed   |

## Resources

* [Supabase Edge Functions Docs](https://supabase.com/docs/guides/functions)
* [Supabase CLI](https://supabase.com/docs/reference/cli)
* [Deno Runtime](https://deno.land/)
* [Webhook Events Guide](/developer-resources/webhooks/intents/webhook-events-guide)
* [GitHub Repo](https://github.com/dodopayments/cloud-functions/tree/main/supabase)


# Vercel Functions
Source: https://docs.dodopayments.com/developer-resources/webhooks/examples/vercel-example

Deploy DodoPayments webhooks to Vercel

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/cloud-functions/tree/main/vercel">
  Complete source code and setup guide
</Card>

## Quick Setup

### 1. Prerequisites

* [Vercel account](https://vercel.com/signup)
* [Neon database](https://neon.com) account
* DodoPayments API key from [dashboard](https://app.dodopayments.com/)

### 2. Install Dependencies

```bash theme={null}
npm install -g vercel
vercel login
git clone https://github.com/dodopayments/cloud-functions.git
cd cloud-functions/vercel
npm install
```

### 3. Database Setup

1. Sign up for [Neon](https://neon.com)
2. Create a new project
3. Open the SQL Editor
4. Copy and paste the contents of [`schema.sql`](#database-schema)
5. Run the query
6. Get your connection string from Neon → Connection Details

### 4. Set Initial Environment Variables

Via Vercel CLI:

```bash theme={null}
vercel env add DATABASE_URL
vercel env add DODO_PAYMENTS_API_KEY
```

> **Note:** We'll set `DODO_PAYMENTS_WEBHOOK_KEY` after deployment once you have your webhook URL.

### 5. Deploy

```bash theme={null}
npm run deploy
```

### 6. Get Your Webhook URL

Your webhook URL is:

```
https://[your-project].vercel.app/api/webhook
```

### 7. Register Webhook in DodoPayments Dashboard

1. Go to [DodoPayments Dashboard](https://app.dodopayments.com) → Developer → Webhooks
2. Create a new webhook endpoint
3. Configure your webhook URL as the endpoint
4. Enable these subscription events:
   * `subscription.active`
   * `subscription.cancelled`
   * `subscription.renewed`
5. Copy the **Signing Secret**

### 8. Set Webhook Key & Redeploy

```bash theme={null}
vercel env add DODO_PAYMENTS_WEBHOOK_KEY
npm run deploy
```

## What It Does

Processes subscription events and stores them in PostgreSQL:

* **subscription.active** - Creates/updates customer and subscription records
* **subscription.cancelled** - Marks subscription as cancelled
* **subscription.renewed** - Updates next billing date

## Key Features

✅ **Signature verification** - Using the dodopayments library\
✅ **Idempotency** - Prevents duplicate processing with webhook IDs\
✅ **Event logging** - Complete audit trail in `webhook_events` table\
✅ **Error handling** - Logged and retryable

> **Note:** This implementation demonstrates handling three core subscription events (`subscription.active`, `subscription.cancelled`, `subscription.renewed`) with minimal fields. You can easily extend it to support additional event types and fields based on your requirements.

## Configuration Files

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "dodo-webhook-vercel",
    "version": "1.0.0",
    "type": "module",
    "description": "DodoPayments Webhook Handler for Vercel",
    "scripts": {
      "start": "vercel dev",
      "deploy": "vercel --prod"
    },
    "dependencies": {
      "@neondatabase/serverless": "^1.0.2",
      "dodopayments": "^2.4.1"
    },
    "devDependencies": {
      "typescript": "^5.9.3",
      "vercel": "^48.4.1"
    }
  }
  ```

  ```json tsconfig.json theme={null}
  {
    "compilerOptions": {
      "target": "ES2022",
      "module": "ES2022",
      "lib": ["ES2022"],
      "moduleResolution": "node",
      "esModuleInterop": true,
      "strict": true,
      "skipLibCheck": true,
      "resolveJsonModule": true,
      "allowSyntheticDefaultImports": true,
      "forceConsistentCasingInFileNames": true,
      "isolatedModules": true,
      "types": ["node"]
    },
    "include": ["api/**/*.ts"],
    "exclude": ["node_modules"]
  }
  ```
</CodeGroup>

## Database Schema

<CodeGroup>
  ```sql schema.sql expandable theme={null}
  -- DodoPayments Webhook Database Schema
  -- Compatible with PostgreSQL (Supabase, Neon, etc.)

  -- Enable UUID extension (if not already enabled)
  CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

  -- Customers table
  CREATE TABLE IF NOT EXISTS customers (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email TEXT NOT NULL,
    name TEXT NOT NULL,
    dodo_customer_id TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Subscriptions table
  CREATE TABLE IF NOT EXISTS subscriptions (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    customer_id UUID NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
    dodo_subscription_id TEXT UNIQUE NOT NULL,
    product_id TEXT NOT NULL,
    status TEXT NOT NULL CHECK (status IN ('pending', 'active', 'on_hold', 'cancelled', 'failed', 'expired')),
    billing_interval TEXT NOT NULL CHECK (billing_interval IN ('day', 'week', 'month', 'year')),
    amount INTEGER NOT NULL,
    currency TEXT NOT NULL,
    next_billing_date TIMESTAMP WITH TIME ZONE NOT NULL,
    cancelled_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
  );

  -- Webhook events log
  CREATE TABLE IF NOT EXISTS webhook_events (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    webhook_id TEXT UNIQUE,
    event_type TEXT NOT NULL,
    data JSONB NOT NULL,
    processed BOOLEAN DEFAULT FALSE,
    error_message TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    processed_at TIMESTAMP WITH TIME ZONE,
    attempts INTEGER DEFAULT 0
  );

  -- Indexes for better query performance
  CREATE INDEX IF NOT EXISTS idx_customers_email ON customers(email);
  CREATE INDEX IF NOT EXISTS idx_customers_dodo_id ON customers(dodo_customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_dodo_id ON subscriptions(dodo_subscription_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_customer_id ON subscriptions(customer_id);
  CREATE INDEX IF NOT EXISTS idx_subscriptions_status ON subscriptions(status);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_processed ON webhook_events(processed, created_at);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_type ON webhook_events(event_type);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_created_at ON webhook_events(created_at DESC);
  CREATE INDEX IF NOT EXISTS idx_webhook_events_webhook_id ON webhook_events(webhook_id);

  -- Function to automatically update updated_at timestamp
  CREATE OR REPLACE FUNCTION update_updated_at_column()
  RETURNS TRIGGER AS $$
  BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
  END;
  $$ LANGUAGE plpgsql;

  -- Triggers to automatically update updated_at
  CREATE TRIGGER update_customers_updated_at
    BEFORE UPDATE ON customers
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  CREATE TRIGGER update_subscriptions_updated_at
    BEFORE UPDATE ON subscriptions
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

  -- Comments for documentation
  COMMENT ON TABLE customers IS 'Stores customer information from DodoPayments';
  COMMENT ON TABLE subscriptions IS 'Stores subscription data from DodoPayments';
  COMMENT ON TABLE webhook_events IS 'Logs all incoming webhook events for audit and retry purposes';

  COMMENT ON COLUMN customers.dodo_customer_id IS 'Unique customer ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.dodo_subscription_id IS 'Unique subscription ID from DodoPayments';
  COMMENT ON COLUMN subscriptions.amount IS 'Amount in smallest currency unit (e.g., cents)';
  COMMENT ON COLUMN subscriptions.currency IS 'Currency used for the subscription payments (e.g., USD, EUR, INR)';
  COMMENT ON COLUMN webhook_events.attempts IS 'Number of processing attempts for failed webhooks';
  COMMENT ON COLUMN webhook_events.data IS 'Full webhook payload as JSON';
  ```
</CodeGroup>

**Tables created:**

* **customers** - Email, name, dodo\_customer\_id
* **subscriptions** - Status, amount, next\_billing\_date, linked to customers
* **webhook\_events** - Event log with webhook\_id for idempotency

## Implementation Code

<CodeGroup>
  ```typescript api/webhook/index.ts expandable theme={null}
  import { neon, NeonQueryFunction } from '@neondatabase/serverless';
  import { DodoPayments } from 'dodopayments';

  interface WebhookPayload {
    business_id: string;
    type: string;
    timestamp: string;
    data: {
      payload_type:
        | "Payment"
        | "Subscription"
        | "Refund"
        | "Dispute"
        | "LicenseKey"
        | "CreditLedgerEntry"
        | "CreditBalanceLow"
        | "AbandonedCheckout"
        | "DunningAttempt"
        | "EntitlementGrant"
        | "Payout";
      subscription_id: string;
      customer: {
        customer_id: string;
        email: string;
        name: string;
      };
      product_id: string;
      status: string;
      recurring_pre_tax_amount: number;
      payment_frequency_interval: string;
      created_at: string;
      next_billing_date: string;
      cancelled_at?: string | null;
      currency: string;
    };
  }

  // Disable body parsing to access raw body for webhook verification
  export const config = {
    api: {
      bodyParser: false,
    },
  };

  const corsHeaders = {
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type, webhook-id, webhook-signature, webhook-timestamp',
    'Access-Control-Allow-Methods': 'POST, OPTIONS',
  };

  // Helper function for JSON responses
  function jsonResponse(data: unknown, status: number = 200) {
    return new Response(JSON.stringify(data), {
      status,
      headers: { ...corsHeaders, 'Content-Type': 'application/json' }
    });
  }

  // Handle subscription events
  async function handleSubscriptionEvent(sql: NeonQueryFunction<false, false>, payload: WebhookPayload, status: string) {
    if (!payload.data.customer.customer_id || !payload.data.subscription_id) {
      throw new Error('Missing required fields: customer_id or subscription_id');
    }

    console.log('🔄 Processing subscription event:', JSON.stringify(payload, null, 2));

    const customer = payload.data.customer;

    // Upsert customer (create if doesn't exist, otherwise use existing)
    const customerResult = await sql`
      INSERT INTO customers (email, name, dodo_customer_id, created_at)
      VALUES (${customer.email}, ${customer.name}, ${customer.customer_id}, ${new Date().toISOString()})
      ON CONFLICT (dodo_customer_id) 
      DO UPDATE SET 
        email = EXCLUDED.email,
        name = EXCLUDED.name,
        updated_at = ${new Date().toISOString()}
      RETURNING id
    `;

    const customerId = customerResult[0].id;
    console.log(`✅ Customer upserted with ID: ${customerId}`);

    // Upsert subscription
    await sql`
      INSERT INTO subscriptions (
        customer_id, dodo_subscription_id, product_id, status, 
        billing_interval, amount, currency, created_at, next_billing_date, cancelled_at, updated_at
      )
      VALUES (
        ${customerId}, ${payload.data.subscription_id},
        ${payload.data.product_id}, ${status},
        ${payload.data.payment_frequency_interval.toLowerCase()}, ${payload.data.recurring_pre_tax_amount},
        ${payload.data.currency}, ${payload.data.created_at}, ${payload.data.next_billing_date},
        ${payload.data.cancelled_at ?? null}, ${new Date().toISOString()}
      )
      ON CONFLICT (dodo_subscription_id) 
      DO UPDATE SET 
        customer_id = EXCLUDED.customer_id,
        product_id = EXCLUDED.product_id,
        status = EXCLUDED.status,
        billing_interval = EXCLUDED.billing_interval,
        amount = EXCLUDED.amount,
        currency = EXCLUDED.currency,
        created_at = EXCLUDED.created_at,
        next_billing_date = EXCLUDED.next_billing_date,
        cancelled_at = EXCLUDED.cancelled_at,
        updated_at = EXCLUDED.updated_at
    `;

    console.log(`✅ Subscription upserted with ${status} status`)
  }

  // Handle CORS preflight
  export async function OPTIONS() {
    return new Response('ok', { 
      status: 200,
      headers: corsHeaders 
    });
  }

  // Handle webhook POST request
  export async function POST(req: Request) {
    try {
      // Get raw body for webhook signature verification
      const rawBody = await req.text();
      
      console.log('📨 Webhook received');

      const DATABASE_URL = process.env.DATABASE_URL;
      const API_KEY = process.env.DODO_PAYMENTS_API_KEY;
      const WEBHOOK_KEY = process.env.DODO_PAYMENTS_WEBHOOK_KEY;

      if (!DATABASE_URL) {
        console.error('❌ Missing DATABASE_URL environment variable');
        return jsonResponse({ error: 'Server configuration error' }, 500);
      }

      // Verify required environment variables
      if (!API_KEY) {
        console.error('❌ DODO_PAYMENTS_API_KEY is not configured');
        return jsonResponse({ error: 'API key not configured' }, 500);
      }

      if (!WEBHOOK_KEY) {
        console.error('❌ DODO_PAYMENTS_WEBHOOK_KEY is not configured');
        return jsonResponse({ error: 'Webhook verification key not configured' }, 500);
      }

      // Verify webhook signature (required for security)
      const webhookHeaders = {
        'webhook-id': req.headers.get('webhook-id') || '',
        'webhook-signature': req.headers.get('webhook-signature') || '',
        'webhook-timestamp': req.headers.get('webhook-timestamp') || '',
      };

      try {
        const dodoPaymentsClient = new DodoPayments({
          bearerToken: API_KEY,
          webhookKey: WEBHOOK_KEY,
        });
        const unwrappedWebhook = dodoPaymentsClient.webhooks.unwrap(rawBody, { headers: webhookHeaders });
        console.log('Unwrapped webhook:', unwrappedWebhook);
        console.log('✅ Webhook signature verified');
      } catch (error) {
        console.error('❌ Webhook verification failed:', error);
        return jsonResponse({ error: 'Webhook verification failed' }, 401);
      }

      // Initialize Neon client
      const sql = neon(DATABASE_URL);

      const payload: WebhookPayload = JSON.parse(rawBody);
      const eventType = payload.type;
      const eventData = payload.data;
      const webhookId = req.headers.get('webhook-id') || '';

      console.log(`📋 Webhook payload:`, JSON.stringify(payload, null, 2));

      // Check for duplicate webhook-id (idempotency)
      if (webhookId) {
        const existingEvent = await sql`
          SELECT id FROM webhook_events WHERE webhook_id = ${webhookId}
        `;

        if (existingEvent.length > 0) {
          console.log(`⚠️ Webhook ${webhookId} already processed, skipping (idempotency)`);
          return jsonResponse({ success: true, message: 'Webhook already processed' });
        }
      }

      // Log webhook event with webhook_id for idempotency
      const logResult = await sql`
        INSERT INTO webhook_events (webhook_id, event_type, data, processed, created_at)
        VALUES (${webhookId || null}, ${eventType}, ${JSON.stringify(eventData)}, ${false}, ${new Date().toISOString()})
        RETURNING id
      `;

      const loggedEventId = logResult[0].id;
      console.log('📝 Webhook event logged with ID:', loggedEventId);

      console.log(`🔄 Processing: ${eventType} (${eventData.payload_type || 'unknown payload type'})`);

      try {
        switch (eventType) {
          case 'subscription.active':
            await handleSubscriptionEvent(sql, payload, 'active');
            break;
          case 'subscription.cancelled':
            await handleSubscriptionEvent(sql, payload, 'cancelled');
            break;
          case 'subscription.renewed':
            console.log('🔄 Subscription renewed - keeping active status and updating billing date');
            await handleSubscriptionEvent(sql, payload, 'active');
            break;
          default:
            console.log(`ℹ️ Event ${eventType} logged but not processed (no handler available)`);
        }

        await sql`
          UPDATE webhook_events 
          SET processed = ${true}, processed_at = ${new Date().toISOString()}
          WHERE id = ${loggedEventId}
        `;

        console.log('✅ Webhook marked as processed');
      } catch (processingError) {
        console.error('❌ Error processing webhook event:', processingError);

        await sql`
          UPDATE webhook_events 
          SET processed = ${false}, 
              error_message = ${processingError instanceof Error ? processingError.message : 'Unknown error'},
              processed_at = ${new Date().toISOString()}
          WHERE id = ${loggedEventId}
        `;

        throw processingError;
      }

      console.log('✅ Webhook processed successfully');

      return jsonResponse({
        success: true,
        event_type: eventType,
        event_id: loggedEventId
      });

    } catch (error) {
      console.error('❌ Webhook processing failed:', error);
      return jsonResponse({
        error: 'Webhook processing failed',
        details: error instanceof Error ? error.message : 'Unknown error'
      }, 500);
    }
  }
  ```
</CodeGroup>

## How It Works

The webhook handler:

1. **Disables body parsing** - To access raw body for signature verification
2. **Verifies the signature** - Ensures the request is from DodoPayments using HMAC-SHA256
3. **Checks for duplicates** - Uses webhook ID to prevent processing the same event twice
4. **Logs the event** - Stores raw webhook in `webhook_events` table for audit trail
5. **Processes the event** - Creates or updates customers and subscriptions in Neon
6. **Handles errors** - Logs failures and marks event as unprocessed for retry

## Testing

**Local development:**

```bash theme={null}
npm start
```

**View logs in Vercel Dashboard:**

1. Select your project
2. Go to **Deployments** → latest deployment
3. Click **Functions** → **Logs**

**Configure in DodoPayments Dashboard:**

1. Go to Developers → Webhooks
2. Add endpoint with your Vercel Functions URL
3. Enable: subscription.active, subscription.cancelled, subscription.renewed

## Common Issues

| Issue                     | Solution                                                            |
| ------------------------- | ------------------------------------------------------------------- |
| Verification failed       | Check webhook key is correct from DodoPayments dashboard            |
| Database connection error | Verify Neon connection string and use pooled connection             |
| Function timeout          | Optimize queries; Pro plan has longer timeout (60s)                 |
| Env vars not available    | Set in dashboard or CLI, ensure all environments selected, redeploy |

## Resources

* [Vercel Functions Docs](https://vercel.com/docs/functions)
* [Vercel CLI](https://vercel.com/docs/cli)
* [Neon Docs](https://neon.com/docs/)
* [Webhook Events Guide](/developer-resources/webhooks/intents/webhook-events-guide)
* [GitHub Repo](https://github.com/dodopayments/cloud-functions/tree/main/vercel)


# Credit-Based Billing
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/credit

The payload sent to your webhook endpoint when credit-based billing events occur — virtual credits (API calls, tokens, compute hours) granted, consumed, expired, rolled over, or balance alerts. These webhooks are not related to Customer Wallets (monetary balances).

## Credit-Based Billing Webhook Events

The following webhook events are available for tracking credit-based billing lifecycle changes. These events apply to virtual credit entitlements (API calls, tokens, compute hours), not to [Customer Wallets](/features/customer-wallet) (monetary balances).

| Event                       | Description                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `credit.added`              | Credits are granted to a customer (via subscription, one-time purchase, add-on, or API)  |
| `credit.deducted`           | Credits are consumed through usage or manual debit                                       |
| `credit.expired`            | Unused credits expired after the configured expiry period                                |
| `credit.rolled_over`        | Unused credits are carried forward to a new grant at cycle end                           |
| `credit.rollover_forfeited` | Credits forfeited because the max rollover count was reached                             |
| `credit.overage_charged`    | Overage charges applied when usage continues beyond zero balance                         |
| `credit.overage_reset`      | Accumulated overage charges are reset (for example, at the start of a new billing cycle) |
| `credit.manual_adjustment`  | Manual credit or debit adjustment made via dashboard or API                              |
| `credit.balance_low`        | Credit balance drops below the configured low balance threshold                          |

### Ledger Events

All ledger events (`credit.added` through `credit.manual_adjustment`) share the same `CreditLedgerEntryResponse` payload documented in the schema below.

The payload includes a `metadata` field resolved from the credit grant's **source** — the subscription or payment created at checkout. This lets you key wallet credits off your own checkout `metadata` (for example, an `orgId`) rather than the Dodo-issued `customer_id`: subscription-sourced grants surface the subscription's `metadata` and payment-sourced grants surface the payment's `metadata`. The field is empty when the grant has no resolvable source (for example, credits granted directly via the API).

### Balance Low Event (credit.balance\_low)

The `credit.balance_low` event uses a different payload (`CreditBalanceLowPayload`) focused on threshold alerting:

```json theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "credit.balance_low",
  "timestamp": "2025-08-04T06:15:00.000000Z",
  "data": {
    "payload_type": "CreditBalanceLow",
    "brand_id": "brd_123",
    "customer_id": "cus_8VbC6JDZzPEqfBPUdpj0K",
    "subscription_id": "sub_7EeHq2ewQuadropD2ra",
    "credit_entitlement_id": "cent_9xY2bKwQn5MjRpL8d",
    "credit_entitlement_name": "API Credits",
    "available_balance": "15",
    "subscription_credits_amount": "100",
    "threshold_percent": 20,
    "threshold_amount": "20"
  }
}
```

<ParamField type="string">
  The brand this credit entitlement belongs to.
</ParamField>

<ParamField type="string">
  The customer whose credit balance triggered the alert.
</ParamField>

<ParamField type="string">
  The subscription associated with this credit entitlement.
</ParamField>

<ParamField type="string">
  The credit entitlement that has a low balance.
</ParamField>

<ParamField type="string">
  Display name of the credit entitlement.
</ParamField>

<ParamField type="string">
  Current credit balance at the time of the alert.
</ParamField>

<ParamField type="string">
  Total credits issued per billing cycle for this subscription.
</ParamField>

<ParamField type="integer">
  The configured low balance threshold percentage.
</ParamField>

<ParamField type="string">
  The absolute credit amount that the threshold corresponds to.
</ParamField>

### Using `credit.balance_low` for Proactive Alerts

Use the `credit.balance_low` webhook to notify customers before they run out of credits:

```javascript theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'credit.balance_low') {
    const data = event.data;
    
    // Notify the customer their credits are running low
    await sendEmail(data.customer_id, {
      subject: `Your ${data.credit_entitlement_name} balance is running low`,
      body: `You have ${data.available_balance} credits remaining ` +
            `(${data.threshold_percent}% threshold reached). ` +
            `Consider upgrading your plan or purchasing additional credits.`
    });
    
    console.log(`Low balance alert for customer ${data.customer_id}`);
  }
  
  res.json({ received: true });
});
```

<Tip>
  Subscribe to `credit.balance_low` to proactively alert customers before they exhaust their credits. Combine with `credit.deducted` to track real-time consumption patterns.
</Tip>

<CardGroup>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    Check a customer's current balance via API.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    Manually credit or debit a customer's balance.
  </Card>
</CardGroup>

## Webhook Payload Schema


# Dispute
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/dispute

The payload sent to your webhook endpoint when a dispute is created or updated, and how to handle each dispute lifecycle event.

<Info>
  As your [Merchant of Record](/features/mor-introduction), Dodo Payments manages the dispute and chargeback process with the card networks on your behalf. These webhooks keep your systems in sync as a dispute moves through its lifecycle so you can revoke access, gather evidence, and reconcile your records.
</Info>

## Dispute Webhook Events

A dispute emits an event at each stage of its lifecycle:

| Event                | Fires when                                         | What it usually means                        |
| -------------------- | -------------------------------------------------- | -------------------------------------------- |
| `dispute.opened`     | A cardholder opens a dispute on a payment          | Funds are held; prepare to respond           |
| `dispute.challenged` | Evidence has been submitted to contest the dispute | The dispute is being reviewed by the network |
| `dispute.accepted`   | The dispute was accepted (not contested)           | The funds are returned to the cardholder     |
| `dispute.cancelled`  | The dispute was withdrawn or cancelled             | No further action needed                     |
| `dispute.expired`    | The response window passed without resolution      | Typically resolves against you               |
| `dispute.won`        | The dispute was resolved in your favor             | Funds are retained                           |
| `dispute.lost`       | The dispute was resolved in the cardholder's favor | Funds are returned to the cardholder         |

<Note>
  Disputes auto-resolved through [Visa Rapid Dispute Resolution (RDR)](/features/transactions/disputes#visa-rapid-dispute-resolution-rdr) appear as `dispute.lost` with `is_resolved_by_rdr: true`. This is expected — the refund was issued automatically to prevent a formal chargeback.
</Note>

## Handling Dispute Events

When `dispute.opened` fires, the disputed amount is held immediately. Use the event to update your records and, if you intend to contest it, gather evidence in the dashboard.

```javascript Handling dispute events expandable theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'dispute.opened': {
      const dispute = event.data;
      // Record the dispute and consider revoking access while it is open
      await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
      // Gather and submit evidence from the Dodo Payments dashboard (within 10 days)
      break;
    }
    case 'dispute.won': {
      // Funds retained — restore normal state in your records
      await markDisputeResolved(event.data.dispute_id, 'won');
      break;
    }
    case 'dispute.lost': {
      // Funds returned to the cardholder — reconcile and keep access revoked
      await markDisputeResolved(event.data.dispute_id, 'lost');
      break;
    }
  }

  res.json({ received: true });
});
```

<Tip>
  Always verify the webhook signature before processing — see the [Webhooks guide](/developer-resources/webhooks) for setup. The handler above omits verification for brevity.
</Tip>

<Warning>
  You have **10 days** to respond to a dispute after it is created. See [Dispute Response Best Practices](/features/transactions/disputes#dispute-response-best-practices) for the evidence to gather and how to format it.
</Warning>

## Dispute Status and Stage

The dispute object reports its progress through two fields:

| Field            | Values                                                                                                                            |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `dispute_status` | `dispute_opened`, `dispute_expired`, `dispute_accepted`, `dispute_cancelled`, `dispute_challenged`, `dispute_won`, `dispute_lost` |
| `dispute_stage`  | `pre_dispute`, `dispute`, `pre_arbitration`                                                                                       |

## Related

<CardGroup>
  <Card title="Managing Disputes" icon="gavel" href="/features/transactions/disputes">
    How to respond to disputes, submit evidence, and how RDR protects your dispute rate.
  </Card>

  <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
    Detect and recover failed payments before they become disputes.
  </Card>
</CardGroup>

## Webhook Payload Schema


# Entitlement Grant
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/entitlement-grant

The payload sent to your webhook endpoint when an entitlement grant is created, delivered, fails, or is revoked.

## Entitlement Grant Webhook Events

These events fire whenever a customer's entitlement grant changes state, for example when a license key is generated, a Discord role is assigned, a download link is provisioned, or access is revoked. Subscribe to these events to keep your application in sync with what each customer can access.

| Event                         | Description                                                                                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `entitlement_grant.created`   | A new grant row was created. Status is `Delivered` immediately for auto-fulfilled license keys, and `Pending` for manually-fulfilled license keys and every other integration. |
| `entitlement_grant.delivered` | The grant transitions to delivered. The customer now has access to the entitled platform, file, or license key.                                                                |
| `entitlement_grant.failed`    | Delivery failed and is not being retried. Inspect `error_code` and `error_message`.                                                                                            |
| `entitlement_grant.revoked`   | Access was withdrawn. Inspect `revocation_reason` to understand why.                                                                                                           |

All four events share the same `EntitlementGrantResponse` payload documented in the schema below.

***

## Event Triggers

### entitlement\_grant.created

A grant row was just inserted. The grant always has a stable `id` from this point on, even if its status changes. Use this event to record that fulfillment is in progress.

For **auto-fulfilled license keys** the row is inserted directly with `status: "Delivered"` and `delivered_at` populated, so a single `created` event is followed by no further state changes unless the grant is later revoked.

For **manually-fulfilled license keys** (entitlements with `fulfillment_mode: manual`) the row arrives with `status: "Pending"` and no `license_key` object — there is no key yet. This event is your signal that a key is awaiting fulfillment; supply it via [`POST /grants/{grant_id}/license-key`](/api-reference/entitlements/fulfill-license-key), which then fires `entitlement_grant.delivered`. See [Manual Fulfillment](/features/license-keys#manual-fulfillment).

For **every other integration** the row arrives with `status: "Pending"`. A `delivered` or `failed` event follows once delivery completes:

* **OAuth-based integrations** (Discord, GitHub, Notion) include an `oauth_url` the customer must visit to complete consent. The grant stays `Pending` until the customer authorizes.
* **Platform-direct integrations** (Telegram, Framer, Digital Files) sit in `Pending` only briefly while the platform call runs, then move to `Delivered`.

### entitlement\_grant.delivered

The grant transitioned from `Pending` to `Delivered`. The customer now has the access described by the entitlement. Use this event to unlock dependent features in your own systems, for example to provision a workspace, send a custom welcome email, or mark a "fulfilled" flag.

The payload's `delivered_at` field captures when delivery completed. For grants that arrived `Delivered` on creation, you'll receive `created` and `delivered` events back to back.

### entitlement\_grant.failed

Delivery was attempted and failed with a non-retryable error. The `error_code` and `error_message` fields explain the failure. Common causes include a revoked OAuth token, a denied platform permission, or a missing target (e.g., a deleted Discord guild).

<Tip>
  Treat `entitlement_grant.failed` as actionable. The customer paid but did not get access. Surface failures to your support team or trigger a regrant once the underlying issue is resolved.
</Tip>

### entitlement\_grant.revoked

Access was withdrawn at the platform level: Discord role removed, GitHub collaborator removed, license key disabled, file download URLs no longer issued. The `revocation_reason` field records the trigger.

| `revocation_reason`      | Trigger                                                                                                                                                                                                                                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscription_cancelled` | The customer's subscription was cancelled (`subscription.cancelled` event).                                                                                                                                                                                                                                     |
| `subscription_on_hold`   | The subscription is on hold due to failed renewal (`subscription.on_hold`). Recoverable: a successful retry produces a re-grant.                                                                                                                                                                                |
| `subscription_expired`   | The subscription reached the end of its term (`subscription.expired`).                                                                                                                                                                                                                                          |
| `plan_changed`           | The plan changed; old grants are revoked before new ones are issued (`subscription.plan_changed`).                                                                                                                                                                                                              |
| `refund`                 | A refund was processed for the original one-time payment (`refund.succeeded`).                                                                                                                                                                                                                                  |
| `manual`                 | A merchant revoked the grant via the API or dashboard. Manual revokes are not auto-regranted on subscription renewal.                                                                                                                                                                                           |
| `license_key_disabled`   | The license key behind a license-key grant was disabled. The grant is re-activated automatically if the key is re-enabled.                                                                                                                                                                                      |
| `platform_external`      | The platform side of an integration drifted out of sync (for example, a Discord role was removed manually, the GitHub App lost repository access, or a reconciliation pass detected a missing target). The grant is not auto-regranted on subscription renewal until the underlying platform issue is resolved. |

***

## Payload Variants

The `data` field is always an `EntitlementGrantResponse` object. The payload carries an `integration_type` field (for example `license_key`, `digital_files`, `discord`) so you can recognize the grant type directly. Three integration types also attach extra nested objects:

* **`license_key`** is included when `integration_type` is `license_key` **and a key has been issued**. It contains the generated key, expiry, and activation usage. For a manually-fulfilled grant still in `Pending`, this object is `null` until you fulfill the grant.
* **`digital_product_delivery`** is included when `integration_type` is `digital_files`. It contains presigned download URLs, the optional `instructions`, and the optional `external_url`.
* **`feature`** is included when `integration_type` is `feature_flag`. It contains the `feature_type` and `feature_id` of the capability conferred by the grant.

For all other integration types (Discord, GitHub, Telegram, Figma, Framer, Notion) these nested fields are `null`; the relevant configuration is captured in the entitlement itself, not the grant.

***

## Sample Payloads

### License key delivered (`entitlement_grant.delivered`)

```json theme={null} theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.delivered",
  "timestamp": "2026-05-01T10:25:33.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Delivered",
    "integration_type": "license_key",
    "license_key": {
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "expires_at": "2027-05-01T00:00:00Z",
      "activations_used": 0,
      "activations_limit": 5
    },
    "digital_product_delivery": null,
    "delivered_at": "2026-05-01T10:25:33Z",
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:25:33Z",
    "updated_at": "2026-05-01T10:25:33Z"
  }
}
```

### License key pending manual fulfillment (`entitlement_grant.created`)

Fired when a customer buys a product whose License Key entitlement uses `fulfillment_mode: manual`. The grant is `Pending` with no `license_key` object yet — the merchant must supply the key.

```json theme={null} theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.created",
  "timestamp": "2026-05-01T10:24:00.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Pending",
    "integration_type": "license_key",
    "license_key": null,
    "digital_product_delivery": null,
    "delivered_at": null,
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:24:00Z",
    "updated_at": "2026-05-01T10:24:00Z"
  }
}
```

### Digital files delivered (`entitlement_grant.delivered`)

```json theme={null} theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.delivered",
  "timestamp": "2026-05-01T10:30:12.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_2P9rQwYvMxTnKoCb4",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_files_J3kLmN4oP5",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Delivered",
    "integration_type": "digital_files",
    "license_key": null,
    "digital_product_delivery": {
      "files": [
        {
          "file_id": "df_a4f6c1de",
          "download_url": "https://files.dodopayments.com/.../pro-bundle.zip?Signature=...",
          "filename": "pro-bundle.zip",
          "content_type": "application/zip",
          "file_size": 18742390,
          "expires_in": 900
        }
      ],
      "instructions": "Unzip and run setup.sh from the project root.",
      "external_url": null
    },
    "delivered_at": "2026-05-01T10:30:12Z",
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:30:12Z",
    "updated_at": "2026-05-01T10:30:12Z"
  }
}
```

### Discord role created and pending (`entitlement_grant.created`)

```json theme={null} theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.created",
  "timestamp": "2026-05-01T10:31:00.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_DiscordPending5L",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_discord_patrons",
    "customer_id": "cus_abc123",
    "payment_id": null,
    "subscription_id": "sub_pro_monthly_001",
    "status": "Pending",
    "integration_type": "discord",
    "license_key": null,
    "digital_product_delivery": null,
    "delivered_at": null,
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": null,
    "error_message": null,
    "oauth_url": "https://discord.com/oauth2/authorize?...",
    "oauth_expires_at": "2026-05-08T10:31:00Z",
    "metadata": null,
    "created_at": "2026-05-01T10:31:00Z",
    "updated_at": "2026-05-01T10:31:00Z"
  }
}
```

### Grant revoked on subscription cancellation (`entitlement_grant.revoked`)

```json theme={null} theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.revoked",
  "timestamp": "2026-06-15T08:12:44.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_8VbC6JDZzPEqfBPUdpj0K",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_9xY2bKwQn5MjRpL8d",
    "customer_id": "cus_abc123",
    "payment_id": null,
    "subscription_id": "sub_pro_monthly_001",
    "status": "Revoked",
    "integration_type": "license_key",
    "revocation_reason": "subscription_cancelled",
    "license_key": {
      "key": "PRO-AAAA-BBBB-CCCC-DDDD",
      "expires_at": null,
      "activations_used": 1,
      "activations_limit": 5
    },
    "digital_product_delivery": null,
    "delivered_at": "2026-05-01T10:25:33Z",
    "revoked_at": "2026-06-15T08:12:44Z",
    "error_code": null,
    "error_message": null,
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:25:33Z",
    "updated_at": "2026-06-15T08:12:44Z"
  }
}
```

### Delivery failed (`entitlement_grant.failed`)

```json theme={null} theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "entitlement_grant.failed",
  "timestamp": "2026-05-01T10:36:21.000000Z",
  "data": {
    "payload_type": "EntitlementGrant",
    "id": "grant_GhFailed7Z",
    "business_id": "bus_H4ekzPSlcg",
    "brand_id": "brd_123",
    "entitlement_id": "ent_github_repo",
    "customer_id": "cus_abc123",
    "payment_id": "pay_a1b2c3d4",
    "subscription_id": null,
    "status": "Failed",
    "integration_type": "github",
    "license_key": null,
    "digital_product_delivery": null,
    "delivered_at": null,
    "revoked_at": null,
    "revocation_reason": null,
    "error_code": "github_permission_denied",
    "error_message": "Repository access could not be granted: the GitHub App installation no longer has permission on this repository.",
    "oauth_url": null,
    "oauth_expires_at": null,
    "metadata": null,
    "created_at": "2026-05-01T10:36:00Z",
    "updated_at": "2026-05-01T10:36:21Z"
  }
}
```

***

## Integration Tips

* **Wait for `entitlement_grant.delivered` before unlocking dependent features.** A `payment.succeeded` event tells you the money cleared; it does not tell you the customer has the GitHub repo or the Discord role yet. The `delivered` event is the source of truth for fulfillment.
* **Map `revocation_reason` to retention flows.** A `subscription_on_hold` revoke usually means the customer's card failed and the next renewal will re-grant access. A `manual` or `subscription_cancelled` revoke is intentional. Treat them differently in customer messaging.
* **Use the grant `id` as your idempotency key.** A single grant emits at most one `created` event and at most one terminal event (`delivered` or `failed`), and at most one `revoked` event. Re-deliveries from the webhook system can repeat events; dedupe on the grant `id` plus `type`.
* **Read `integration_type` to recognize the grant type.** The payload carries `integration_type` directly (for example `license_key`, `digital_files`, `discord`). The `license_key` and `digital_product_delivery` nested objects are populated once their respective grants are delivered; a manually-fulfilled license-key grant stays `Pending` with `integration_type: "license_key"` and a `null` `license_key` until you fulfill it.
* **For OAuth-based grants, surface `oauth_url` to the customer.** The `entitlement_grant.created` event for Discord, GitHub, or Notion subscriber flows includes an `oauth_url` and `oauth_expires_at`. Email it to the customer or display it in your app to unblock delivery.


# License Key
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/license-key

The payload sent to your webhook endpoint when a license key is created or updated.



# Payment
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/payment

The payload sent to your webhook endpoint when a payment is created or updated.



# Payout
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/payout

The payload sent to your webhook endpoint when a payout is created or changes status, and how to reconcile each payout lifecycle event.

<Info>
  Payout webhooks tell you when your own funds move from Dodo Payments to your bank account. Use them to reconcile payouts in your accounting systems without polling the [List Payouts](/api-reference/payouts/get-payouts) endpoint.
</Info>

## Payout Webhook Events

A payout emits an event at each stage of its lifecycle. The stages match the [payout statuses](/features/payouts/payout-structure) shown in your dashboard.

| Event                | Fires when                                                      | What it usually means                                |
| -------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| `payout.created`     | A payout is created, by the automatic payout cycle or off-cycle | The payout exists but has not started moving yet     |
| `payout.in_progress` | The payout due date arrives and processing starts               | Funds are on their way to your bank account          |
| `payout.on_hold`     | The payout is paused or placed under review                     | You may need to supply additional information        |
| `payout.success`     | The payout to your bank account settles                         | Funds should be available in your account            |
| `payout.failed`      | The payout fails                                                | The amount and fees are credited back to your wallet |

<Note>
  `payout.created` was previously emitted as `payout.not_initiated`. If an existing endpoint filters on `payout.not_initiated`, update the filter to `payout.created` so it keeps matching. The `status` field on the payload still reports `not_initiated` at this stage.
</Note>

## Handling Payout Events

Payouts are about your own money rather than a customer's, so these events usually feed bookkeeping and internal alerting rather than customer-facing flows.

```javascript Handling payout events expandable theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'payout.created': {
      const payout = event.data;
      // Record the expected payout so finance can reconcile it later
      await recordPayout(payout.payout_id, payout.amount, payout.currency);
      break;
    }
    case 'payout.success': {
      // Funds settled — mark the payout as received
      await markPayoutSettled(event.data.payout_id, event.data.updated_at);
      break;
    }
    case 'payout.failed': {
      // Funds and fees are credited back to your wallet — alert finance
      await alertPayoutFailed(event.data.payout_id, event.data.remarks);
      break;
    }
    case 'payout.on_hold': {
      // Review may be required before the payout can continue
      await alertPayoutOnHold(event.data.payout_id, event.data.remarks);
      break;
    }
  }

  res.json({ received: true });
});
```

<Tip>
  Always verify the webhook signature before processing — see the [Webhooks guide](/developer-resources/webhooks) for setup. The handler above omits verification for brevity.
</Tip>

<Warning>
  Payout events are neither terminal nor strictly ordered. `payout.failed` can arrive after `payout.success` when a bank returns the transfer, and `payout.success` can arrive after `payout.failed` when a failed payout is later recovered. Treat the `status` field on the payload as the current state rather than assuming the last event you received is final.
</Warning>

## Payout Status

The payout object reports its progress through a single field:

| Field    | Values                                                         |
| -------- | -------------------------------------------------------------- |
| `status` | `not_initiated`, `in_progress`, `on_hold`, `success`, `failed` |

<Note>
  `refunds`, `chargebacks`, and `tax` on the payload are deprecated. Use the [payout breakup endpoints](/api-reference/payouts/retrieve-breakup) for a detailed breakdown instead.
</Note>

## Related

<CardGroup>
  <Card title="Payout Structure" icon="money-bill-transfer" href="/features/payouts/payout-structure">
    How payouts are scheduled and calculated, and what each payout status means.
  </Card>

  <Card title="Balances & Wallets" icon="file-invoice-dollar" href="/features/account-summary-payout-wallet">
    Track wallet balances and the ledger behind each payout.
  </Card>
</CardGroup>

## Webhook Payload Schema


# Recovery
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/recovery

The payloads sent to your webhook endpoint when abandoned cart recovery or subscription dunning events occur.

## Abandoned Cart Recovery Events

The following webhook events track the abandoned cart recovery lifecycle:

| Event                          | Description                                                                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `abandoned_checkout.detected`  | An abandoned checkout has been detected. Sent when a payment is identified as abandoned (failed or incomplete) and the recovery workflow begins. |
| `abandoned_checkout.recovered` | The customer completed payment through the recovery link. The `recovered_payment_id` field contains the successful payment ID.                   |

### Abandoned Checkout Payload Fields

<ParamField type="string">
  The original payment that was abandoned. Use this to look up product, amount, and currency details.
</ParamField>

<ParamField type="string">
  The brand this abandoned checkout belongs to.
</ParamField>

<ParamField type="string">
  The customer who abandoned the checkout.
</ParamField>

<ParamField type="string">
  Why the checkout was abandoned. One of:

  * `payment_failed` — Customer attempted payment but it failed
  * `checkout_incomplete` — Customer visited checkout but never attempted payment
</ParamField>

<ParamField type="string">
  Current lifecycle state of this recovery attempt. One of:

  * `abandoned` — Detected, no emails sent yet
  * `recovering` — At least one recovery email sent
  * `recovered` — Customer completed payment
  * `exhausted` — All emails sent or newer checkout found
  * `opted_out` — Customer unsubscribed
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp of when the checkout was detected as abandoned.
</ParamField>

<ParamField type="string | null">
  The payment ID of the successful recovery payment. `null` until the checkout is recovered.
</ParamField>

### Example: Handling ACR Webhooks

```javascript theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'abandoned_checkout.detected':
      console.log(`Checkout abandoned: ${event.data.payment_id}`);
      console.log(`Reason: ${event.data.abandonment_reason}`);
      // Track abandonment in your analytics
      await trackAbandonment(event.data);
      break;

    case 'abandoned_checkout.recovered':
      console.log(`Checkout recovered: ${event.data.payment_id}`);
      console.log(`Recovery payment: ${event.data.recovered_payment_id}`);
      // Grant access, update records
      await handleRecovery(event.data);
      break;
  }

  res.json({ received: true });
});
```

***

## Dunning Events

The following webhook events track the subscription dunning lifecycle:

| Event               | Description                                                                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `dunning.started`   | A dunning attempt has been created for a subscription that entered `on_hold` or was cancelled by the customer.                            |
| `dunning.recovered` | The customer updated their payment method and the resulting payment succeeded. The `payment_id` field contains the successful payment ID. |

### Dunning Attempt Payload Fields

<ParamField type="string">
  The subscription that triggered the dunning attempt.
</ParamField>

<ParamField type="string">
  The brand this dunning attempt belongs to.
</ParamField>

<ParamField type="string">
  The customer who owns the subscription.
</ParamField>

<ParamField type="string">
  The subscription state that triggered dunning. One of:

  * `on_hold` — Subscription paused due to payment failure
  * `cancelled` — Customer cancelled from the customer portal
</ParamField>

<ParamField type="string">
  Current lifecycle state of this dunning attempt. One of:

  * `recovering` — Dunning emails are being sent
  * `recovered` — Customer updated payment method and payment succeeded
  * `exhausted` — All emails sent or subscription state changed
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp of when the dunning attempt was created.
</ParamField>

<ParamField type="string | null">
  The payment ID of the successful recovery payment. `null` while recovering.
</ParamField>

### Example: Handling Dunning Webhooks

```javascript theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'dunning.started':
      console.log(`Dunning started for subscription: ${event.data.subscription_id}`);
      console.log(`Trigger: ${event.data.trigger_state}`);
      // Track dunning in your system
      await trackDunning(event.data);
      break;

    case 'dunning.recovered':
      console.log(`Subscription recovered: ${event.data.subscription_id}`);
      console.log(`Recovery payment: ${event.data.payment_id}`);
      // Reactivate access, update records
      await handleDunningRecovery(event.data);
      break;
  }

  res.json({ received: true });
});
```

<Tip>
  Subscribe to both `dunning.started` and `dunning.recovered` to track the full dunning lifecycle. Use `dunning.started` to pause grace periods or flag at-risk subscriptions in your system.
</Tip>

<CardGroup>
  <Card title="Abandoned Cart Recovery" icon="cart-shopping" href="/features/recovery/abandoned-cart-recovery">
    Configure ACR email sequences and discount incentives.
  </Card>

  <Card title="Subscription Dunning" icon="rotate" href="/features/recovery/subscription-dunning">
    Configure dunning email sequences for lapsed subscriptions.
  </Card>

  <Card title="Subscription Webhooks" icon="repeat" href="/developer-resources/webhooks/intents/subscription">
    Related subscription lifecycle events like `subscription.on_hold` and `subscription.cancelled`.
  </Card>
</CardGroup>

## Webhook Payload Schema


# Refund
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/refund

The payload sent to your webhook endpoint when a refund is created or updated.



# Subscription
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/subscription

The payload sent to your webhook endpoint when a subscription is created, updated, or changes state.

## Subscription Webhook Events

The following webhook events are available for tracking subscription lifecycle changes:

| Event                                | Description                                                            |
| ------------------------------------ | ---------------------------------------------------------------------- |
| `subscription.active`                | Subscription is successfully activated                                 |
| `subscription.updated`               | Subscription object was updated (any field change triggers this event) |
| `subscription.on_hold`               | Subscription is put on hold due to failed renewal                      |
| `subscription.paused`                | Subscription is paused                                                 |
| `subscription.unpaused`              | Subscription is resumed after being paused                             |
| `subscription.renewed`               | Subscription is renewed for the next billing period                    |
| `subscription.plan_changed`          | Subscription plan was upgraded, downgraded, or modified                |
| `subscription.update_payment_method` | Subscription's payment method is updated                               |
| `subscription.cancelled`             | Subscription is cancelled                                              |
| `subscription.failed`                | Subscription creation failed during mandate creation                   |
| `subscription.expired`               | Subscription reached the end of its term                               |

### Using `subscription.updated` for Real-Time Sync

The `subscription.updated` webhook fires whenever any subscription field changes, allowing you to keep your application state in sync without polling:

```javascript theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.updated') {
    const subscription = event.data;
    
    // Sync subscription changes to your database
    await syncSubscription(subscription.subscription_id, {
      status: subscription.status,
      next_billing_date: subscription.next_billing_date,
      metadata: subscription.metadata,
      // ... other fields you want to track
    });
    
    console.log(`Subscription ${subscription.subscription_id} updated`);
  }
  
  res.json({ received: true });
});
```

<Tip>
  Subscribe to `subscription.updated` to get real-time notifications about any subscription changes, eliminating the need to poll the API for updates.
</Tip>

## Webhook Payload Schema


# Webhook Event Guide
Source: https://docs.dodopayments.com/developer-resources/webhooks/intents/webhook-events-guide

Understand the different webhook events triggered by Dodo Payments during payment, refund, subscription, dispute, license key, entitlement grant, credit, recovery, and dunning activities

Dodo Payments provides real-time webhook notifications to keep you informed about critical events related to transactions, subscriptions, refunds, disputes, and license key management. Below is a detailed guide to these events, categorized for clarity, along with implementation tips and considerations.

## **Payment Events**

| **Event Name**         | **Event Type**       | **Description**                                                                     |
| ---------------------- | -------------------- | ----------------------------------------------------------------------------------- |
| **Payment Succeeded**  | `payment.succeeded`  | Triggered when a payment is successfully processed.                                 |
| **Payment Failed**     | `payment.failed`     | Occurs when a payment attempt fails due to errors, declined cards, or other issues. |
| **Payment Processing** | `payment.processing` | Indicates that a payment is currently being processed.                              |
| **Payment Cancelled**  | `payment.cancelled`  | Triggered when a payment is cancelled before completion.                            |

## **Refund Events**

| **Event Name**       | **Event Type**     | **Description**                                                              |
| -------------------- | ------------------ | ---------------------------------------------------------------------------- |
| **Refund Succeeded** | `refund.succeeded` | Triggered when a refund is successfully processed.                           |
| **Refund Failed**    | `refund.failed`    | Occurs when a refund attempt fails due to processing errors or other issues. |

## **Dispute Events**

| **Event Name**         | **Event Type**       | **Description**                                               |
| ---------------------- | -------------------- | ------------------------------------------------------------- |
| **Dispute Opened**     | `dispute.opened`     | Triggered when a customer initiates a dispute.                |
| **Dispute Expired**    | `dispute.expired`    | Indicates that a dispute expired without resolution.          |
| **Dispute Accepted**   | `dispute.accepted`   | Triggered when a merchant accepts the dispute.                |
| **Dispute Cancelled**  | `dispute.cancelled`  | Occurs when a dispute is cancelled by the customer or system. |
| **Dispute Challenged** | `dispute.challenged` | Triggered when a merchant challenges a dispute.               |
| **Dispute Won**        | `dispute.won`        | Indicates that the merchant has successfully won a dispute.   |
| **Dispute Lost**       | `dispute.lost`       | Occurs when the merchant loses a dispute.                     |

## **Subscription Events**

| **Event Name**                          | **Event Type**                       | **Description**                                                                           |
| --------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------- |
| **Subscription Active**                 | `subscription.active`                | Indicates that a subscription is now active and recurring charges are scheduled.          |
| **Subscription Updated**                | `subscription.updated`               | Triggered when any subscription field is updated (real-time sync without polling).        |
| **Subscription On Hold**                | `subscription.on_hold`               | Triggered when a subscription is temporarily put on hold due to failed renewal.           |
| **Subscription Paused**                 | `subscription.paused`                | Triggered when a subscription is paused.                                                  |
| **Subscription Unpaused**               | `subscription.unpaused`              | Triggered when a paused subscription is resumed.                                          |
| **Subscription Renewed**                | `subscription.renewed`               | Occurs when a subscription is successfully renewed.                                       |
| **Subscription Plan Changed**           | `subscription.plan_changed`          | Triggered when a subscription is upgraded, downgraded, or modified with different addons. |
| **Subscription Payment Method Updated** | `subscription.update_payment_method` | Sent when a subscription's payment method is updated. Carries the Subscription payload.   |
| **Subscription Cancelled**              | `subscription.cancelled`             | Triggered when a subscription is cancelled by the merchant or customer.                   |
| **Subscription Failed**                 | `subscription.failed`                | Indicates a failed subscription. This means that we were unable to create a mandate.      |
| **Subscription Expired**                | `subscription.expired`               | Triggered when a subscription reaches the end of its term and expires.                    |

## **License Key Events**

| **Event Name**          | **Event Type**        | **Description**                                            |
| ----------------------- | --------------------- | ---------------------------------------------------------- |
| **License Key Created** | `license_key.created` | Triggered when a new license key is created for a product. |

## **Entitlement Grant Events**

| **Event Name**      | **Event Type**                | **Description**                                                                                                                                          |
| ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Grant Created**   | `entitlement_grant.created`   | A new entitlement grant is created for a customer. License-key grants arrive `delivered`; OAuth-based grants (Discord, GitHub, Notion) arrive `pending`. |
| **Grant Delivered** | `entitlement_grant.delivered` | Grant fulfilment completes — license key issued, file links resolved, or platform access granted.                                                        |
| **Grant Failed**    | `entitlement_grant.failed`    | Grant fulfilment failed; inspect `error_code` and `error_message`.                                                                                       |
| **Grant Revoked**   | `entitlement_grant.revoked`   | Access is withdrawn; inspect `revocation_reason` (subscription state, refund, plan change, or manual).                                                   |

For detailed payload schemas, sample events, and the full `revocation_reason` reference, see [Entitlement Grant Webhooks](/developer-resources/webhooks/intents/entitlement-grant).

## **Credit Events**

| **Event Name**         | **Event Type**              | **Description**                                                                                          |
| ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Credit Added**       | `credit.added`              | Triggered when credits are granted to a customer (subscription, one-time, add-on, or API).               |
| **Credit Deducted**    | `credit.deducted`           | Occurs when credits are consumed through usage or manual debit.                                          |
| **Credit Expired**     | `credit.expired`            | Triggered when unused credits expire after the configured expiry period.                                 |
| **Credit Rolled Over** | `credit.rolled_over`        | Occurs when unused credits are carried forward to a new grant at cycle end.                              |
| **Rollover Forfeited** | `credit.rollover_forfeited` | Triggered when credits are forfeited because the max rollover count was reached.                         |
| **Overage Charged**    | `credit.overage_charged`    | Occurs when overage charges are applied for usage beyond zero balance.                                   |
| **Overage Reset**      | `credit.overage_reset`      | Triggered when accumulated overage charges are reset (for example, at the start of a new billing cycle). |
| **Manual Adjustment**  | `credit.manual_adjustment`  | Triggered when a manual credit or debit adjustment is made.                                              |
| **Balance Low**        | `credit.balance_low`        | Triggered when credit balance drops below the configured threshold.                                      |

## **Recovery Events**

| **Event Name**                   | **Event Type**                 | **Description**                                                               |
| -------------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
| **Abandoned Checkout Detected**  | `abandoned_checkout.detected`  | Triggered when an incomplete or failed checkout is detected after 60 minutes. |
| **Abandoned Checkout Recovered** | `abandoned_checkout.recovered` | Occurs when a customer completes payment through a recovery link.             |

For detailed payload schemas, field descriptions, and handler examples, see [Recovery Webhooks](/developer-resources/webhooks/intents/recovery).

## **Dunning Events**

| **Event Name**        | **Event Type**      | **Description**                                                                                |
| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------- |
| **Dunning Started**   | `dunning.started`   | Triggered when a dunning attempt begins for a subscription that went on hold or was cancelled. |
| **Dunning Recovered** | `dunning.recovered` | Occurs when a customer updates their payment method and the resulting charge succeeds.         |

For detailed payload schemas, field descriptions, and handler examples, see [Recovery Webhooks](/developer-resources/webhooks/intents/recovery).

## **Payout Events**

These events track the movement of your funds from Dodo Payments to your bank account, mirroring the [payout statuses](/features/payouts/payout-structure#payout-status) shown in the dashboard. The payload is a payout object with the same shape as an entry from `GET /payouts`.

| **Event Name**         | **Event Type**       | **Description**                                                                        |
| ---------------------- | -------------------- | -------------------------------------------------------------------------------------- |
| **Payout Created**     | `payout.created`     | Triggered when a payout is created, either by the automatic payout cycle or off-cycle. |
| **Payout In Progress** | `payout.in_progress` | Occurs when the payout due date arrives and the payout starts processing.              |
| **Payout On Hold**     | `payout.on_hold`     | Triggered when a payout is paused or placed under review.                              |
| **Payout Successful**  | `payout.success`     | Occurs when the payout to your bank account is processed successfully.                 |
| **Payout Failed**      | `payout.failed`      | Triggered when a payout fails. The funds and fees are credited back to your wallet.    |

<Warning>
  Do not assume payout events are terminal or strictly ordered. `payout.failed` can legitimately arrive after `payout.success` when a bank returns the transfer, and `payout.success` can arrive after `payout.failed` when a failed payout is later recovered. Always treat the status on the payload as the current state.
</Warning>

<Note>
  `payout.created` was previously emitted as `payout.not_initiated`. If you have an existing endpoint filtering on `payout.not_initiated`, update the filter to `payout.created` so it keeps matching.
</Note>

For detailed payload schemas, field descriptions, and handler examples, see [Payout Webhooks](/developer-resources/webhooks/intents/payout).

These webhook events are designed to provide merchants with critical updates to manage their operations effectively. Implement robust handlers for each relevant event in your webhook integration to ensure smooth and reliable functionality.


# Atlas Demo Product
Source: https://docs.dodopayments.com/features/atlas-demo-website

Explore Atlas, a fully functional AI art generation demo application showcasing usage-based billing, subscriptions, and one-time payments with Dodo Payments checkout integration.

<Frame>
  <img alt="Atlas Demo Product - AI art generation platform with integrated billing" />
</Frame>

Atlas is a fully functional demo application by Dodo Payments that showcases an AI art generation platform. It demonstrates all three billing models—**usage-based billing**, **one-time payments**, and **subscriptions**—with integrated checkout flows.

<Info>
  **Live Demo**: Visit [atlas.dodopayments.com](https://atlas.dodopayments.com/) to explore the platform and test all billing flows.
</Info>

## Overview

Atlas simulates a real-world AI art generation platform where users create images from text prompts. The demo highlights three distinct purchase flows, each demonstrating different billing models and checkout experiences:

* **Usage-Based Billing**: Pay per image generated (\$0.75 per image)
* **Subscription**: Unlimited Pro plan (\$20/month)
* **One-Time Purchase**: Credit packs (\$7 for 10 credits)

After completing any purchase, users are redirected to the **Atlas Studio dashboard** where they can generate artwork and track their usage in real-time.

## Purchase Flows

Atlas demonstrates three separate billing flows. Each flow follows a similar pattern but showcases different checkout experiences and billing models.

<Tabs>
  <Tab title="Usage-Based Billing">
    <Steps>
      <Step title="Select pay-per-image pricing">
        Choose the **pay-per-image** option (\$0.75 per image) for AI art generation. This demonstrates usage-based billing where customers pay only for what they consume.
      </Step>

      <Step title="Generate artwork">
        Enter a text prompt and generate an image. The system automatically tracks usage for billing purposes.
      </Step>

      <Step title="Complete checkout">
        The checkout process includes:

        * **Branded checkout page**: Dodo Payments checkout page displays your merchant brand name and logo
        * **Customer information**: Enter user details and billing address
        * **Tax calculation**: Taxes are automatically calculated after address confirmation
        * **Payment**: Enter test card details to complete the transaction

        <Tip>
          Use test card `4242 4242 4242 4242` with any future expiry date and CVC to simulate successful transactions.
        </Tip>
      </Step>

      <Step title="View confirmation">
        After payment, Atlas displays a confirmation screen with usage details and remaining credits.
      </Step>

      <Step title="Access dashboard">
        Users are redirected back to the **Atlas Studio dashboard** where they can continue generating artwork and monitor their usage tracking.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Subscription">
    <Steps>
      <Step title="Select subscription plan">
        Choose the **Unlimited Pro** subscription plan (\$20/month) for unlimited AI art generation.
      </Step>

      <Step title="Generate artwork">
        Enter a prompt and generate an image to test the platform before subscribing.
      </Step>

      <Step title="Complete checkout">
        The subscription checkout includes:

        * **Branded checkout page**: Merchant branding is visible throughout the checkout process
        * **Customer information**: Enter user details and billing address
        * **Tax calculation**: Automatic tax calculation based on billing address
        * **Payment**: Enter test card details to activate the subscription

        <Note>
          Subscriptions automatically renew monthly. Users can manage their subscription from the dashboard after purchase.
        </Note>
      </Step>

      <Step title="View confirmation">
        Post-payment, Atlas displays a confirmation screen with subscription activation details and next billing date.
      </Step>

      <Step title="Access dashboard">
        Users are redirected to the **Atlas Studio dashboard** with unlimited access to generate artwork.
      </Step>
    </Steps>
  </Tab>

  <Tab title="One-Time Purchase">
    <Steps>
      <Step title="Select credit pack">
        Choose a **Credit Pack** (\$7 for 10 credits) for AI art generation. This demonstrates one-time purchase transactions.
      </Step>

      <Step title="Generate artwork">
        Enter a prompt and generate an image to preview the platform before purchasing credits.
      </Step>

      <Step title="Complete checkout">
        The one-time purchase checkout includes:

        * **Branded checkout page**: Dodo Payments checkout with merchant branding
        * **Customer information**: Enter user details and billing address
        * **Tax calculation**: Automatic tax calculation after address confirmation
        * **Payment**: Enter test card details to complete the purchase
      </Step>

      <Step title="View confirmation">
        Post-payment, Atlas displays a confirmation screen with a "thank you" message and purchased credit details.
      </Step>

      <Step title="Access dashboard">
        Users are redirected to the **Atlas Studio dashboard** where their purchased credits are immediately available for generating artwork.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Post-Purchase Dashboard Experience

The Atlas Studio dashboard demonstrates how to implement billing-aware features and entitlement tracking after checkout completion.

### Dashboard Features

* **Immediate access**: Users can start generating artwork immediately after purchase
* **Usage tracking**: Real-time display of remaining credits, active subscriptions, and generation history
* **Billing management**: View purchase history, subscription status, and upcoming renewals
* **Seamless integration**: Showcases how to redirect users back to your application with proper entitlement tracking

<Check>
  The dashboard experience demonstrates best practices for post-purchase user flows, including entitlement verification and usage monitoring.
</Check>

## Technical Implementation

Atlas is built using the [Dodo Payments TypeScript SDK](/developer-resources/sdks/typescript), demonstrating how to integrate billing flows with just a few lines of code.

<CardGroup>
  <Card title="Integration Guide" icon="book" href="/developer-resources/integration-guide">
    Learn how to integrate Dodo Payments checkout flows into your application.
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/developer-resources/sdks/typescript">
    Explore the TypeScript SDK documentation and API reference.
  </Card>
</CardGroup>

## Open Source

Atlas is an open-source project. Explore the codebase to see how billing flows are implemented in a real application.

<Card title="View on GitHub" icon="github" href="https://github.com/dodopayments/dodo-checkout-demo.git">
  Browse the Atlas source code and learn from the implementation.
</Card>


# Bypassing App Store & Play Store Fees using Dodo Payments
Source: https://docs.dodopayments.com/features/bypassing-app-store-fees

Learn how to legally bypass Apple and Google's 30% app store fees using Merchant of Record solutions and compliant payment strategies

## The Platform Tollbooth Problem

For over a decade, Apple and Google have operated their app stores not just as marketplaces, but as powerful toll booths. Any developer or startup offering digital goods within an app was forced to route payments through their respective billing systems: Apple's In-App Purchase (IAP) and Google's Play Billing-while forfeiting up to 30% of revenue.

If that sounds like a steep cut, it's because it absolutely is.

This "store tax" drew widespread criticism, particularly from developers from large apps like Spotify, Epic Games, and Netflix, who found the commissions not only excessive but anti-competitive. Apps couldn't even inform users about cheaper options outside the app. These policies-especially Apple's "anti-steering" rules-made app stores de facto monopolies for digital distribution.

<Warning>
  The 30% app store commission represents a significant revenue drain for digital businesses, especially for subscription-based services and SaaS applications.
</Warning>

## The Epic Games Catalyst

Epic Games' CEO, Tim Sweeney, initiated Project Liberty as a strategic legal campaign to challenge the monopolistic practices of Apple and Google's app stores, particularly their 30% commission fees on in-app purchases. The project aimed to disrupt these platforms' control over app distribution and payments, advocating for a more open environment for developers.

Tim Sweeney knew Apple would contest this and laid a bait. Epic updated Fortnite with a hidden direct-pay option, bypassing Apple's IAP. Apple fell for the bait, swiftly banned Fortnite, and Epic sued.

The Epic Games v. Apple legal battle cracked open the conversation globally.

## The Epic v. Apple Verdict

In 2021, the U.S. District Judge ruled in a landmark decision:

* **Apple did not violate antitrust laws outright**, meaning it could continue to control app distribution on iOS
* **However, Apple's anti-steering policies were deemed anti-competitive**. The court issued a permanent injunction-Apple must allow developers to direct users to external payment methods

After delays and appeals, Apple finally updated its App Store guidelines in May 2025 to allow external purchase links in U.S. apps.

<Check>
  This U.S. ruling spurred similar regulatory pressure and legal action across South Korea, Japan, the EU, and other regions. Combined with the EU's Digital Markets Act (DMA)-the tide turned decisively in favor of developers.
</Check>

## Global Overview: Where Developers Can Legally Bypass Fees

| Region          | Apple Policy (2025)                   | Google Policy (2025)            |
| --------------- | ------------------------------------- | ------------------------------- |
| **USA**         | External links allowed (no Apple fee) | UCB allowed (reduced fee)       |
| **EU (EEA)**    | Alt payments/links allowed (10–17%)   | UCB allowed for non-games       |
| **South Korea** | Apple-approved PSPs (26% fee)         | UCB mandated (26% fee)          |
| **Netherlands** | Dating apps only                      | UCB allowed                     |
| **Japan**       | Reader apps can link out              | UCB allowed                     |
| **India**       | No change                             | UCB allowed (4% fee reduction)  |
| **Other**       | No change                             | UCB allowed in select countries |
| **China**       | No external billing allowed           | Google Play not relevant        |

<Info>
  UCB stands for User Choice Billing, Google's alternative billing system that allows developers to use third-party payment processors.
</Info>

## Pre-2025 Loopholes: How Apps Circumvented App Store Rules

Before regulations loosened their grip, some apps found "creative" ways to get around the 30% cut. These hacks were rarely compliant but undeniably clever.

### Reader App Loophole

One common tactic was the "reader app loophole," where apps like Kindle or Netflix claimed they were merely displaying previously purchased content. Apple couldn't fault apps for letting users access pre-purchased content. So as long as the app didn't explicitly link to external payment or prompt an in-app purchase, it was allowed to operate.

### Hidden Payment Redirections

Others experimented with code obfuscation, embedding hidden payment redirections. A few even used email notifications post-download to nudge users to pay outside the app.

<Note>
  Spotify was one such company that implemented this strategy. If you're in India and use Spotify, you've probably noticed that you can't buy the Premium plan inside the app. You have to pay on the web. This is why.
</Note>

All of this was risky, brittle, and usually led to takedowns once discovered. But it underscored one thing: developers were desperate to reclaim control over their margins and user data.

## The Payment Gateway Trap: What Developers Often Miss

At first glance, payment gateways (PGs) like Stripe or Razorpay seem like the obvious solution. But for in-app purchases, it's not that simple.

<Warning>
  If you're on iOS outside of allowed regions (like India or China), plugging in a PG directly into the app violates Apple's policies, risking an app takedown.
</Warning>

Even where it is legal, PGs come with limitations: they don't solve for tax compliance across geographies, invoicing, refund management, or regulatory filings.

That's where Merchant-of-Record (MoR) platforms like Dodo Payments come in. We handle the full stack: payments, taxes, documentation, customer support, and legal accountability.

It's not just about collecting money. It's about doing it cleanly, globally, and without risking your App Store listing.

## Two Legal Workarounds for Developers

### 1. App-to-Web Redirect (Link Out Flow)

**What it is:** The app links users to a web-based checkout (hosted by Dodo Payments or the developer). Payment is completed outside the app, then access is granted in-app.

**Legal Status:**

* **iOS:** Legal in US, EU, South Korea, Netherlands (only dating apps), Japan (only reader apps)
* **Android:** Legal in all UCB-supported markets

**Advantages:**

* Simple to implement
* Fully compliant
* No app-side PCI burden

**Drawbacks:**

* Slight friction - user leaves app to pay

### 2. In-App SDK Integration (Third-Party SDK)

**What it is:** Embed a payment UI - such as a native third-party SDK - directly in your app to enable seamless checkout without requiring users to leave the app.

**Legal Status:**

* **iOS:** Legal only in EU (under DMA terms); elsewhere it's still a violation
* **Android:** Legal in UCB markets, if proper UX and reporting are followed

**Advantages:**

* Smooth UX
* User stays in app
* Can match IAP experience

**Drawbacks:**

* Integration complexity
* Compliance risk outside allowed regions

## Developer Strategy: Combine Legal Compliance with Revenue Efficiency

An effective global rollout strategy could look like this:

<Steps>
  <Step title="U.S. Users">
    Use App-to-Web (no Apple cut)
  </Step>

  <Step title="EU Users">
    Use In-App SDK or App-to-Web (10–17% Apple cut)
  </Step>

  <Step title="Android Users in UCB Markets">
    Use In-App SDK with Google-compliant UX
  </Step>

  <Step title="Other iOS Markets">
    Use Apple IAP (or omit in-app purchases)
  </Step>

  <Step title="Other Android Markets">
    Use Google Play billing or distribute via alt app stores
  </Step>
</Steps>

## The Biggest Opportunity

Among all the regulatory changes, the U.S. App Store presents the single largest opportunity for developers. With the 2025 guideline update following the Epic v. Apple ruling, developers can now legally include external links in their iOS apps that direct users to a web-based checkout.

This means: **no mandatory Apple IAP, no 30% fee, and full control over customer relationships and revenue.**

Given that the U.S. is the largest app revenue market globally, this change alone can significantly improve margins for any digital product business from subscriptions and SaaS tools to media and learning apps. For many, it's a 30% revenue unlock in their most lucrative geography.

<Tip>
  The U.S. market represents the largest opportunity for revenue recovery, with developers able to bypass the full 30% Apple commission through compliant external payment links.
</Tip>

## How Dodo Payments Enables This

Dodo Payments acts as a Merchant of Record, handling:

* **Global tax compliance** (VAT/GST)
* **Payment processing** (cards, UPI, wallets)
* **Invoicing, refunds, fraud prevention**
* **SDK & hosted checkout integration**

This simplifies compliance and operational load while offering fee-saving alternatives that are 100% legal in supported regions.

<CardGroup>
  <Card title="Get Started" icon="rocket" href="/introduction">
    Begin your integration with Dodo Payments
  </Card>

  <Card title="Mobile Integration" icon="mobile" href="/developer-resources/mobile-integration">
    Learn how to integrate payments in your mobile app
  </Card>
</CardGroup>

## Conclusion: A Developer-Friendly Future Is Here

For years, the 30% store tax was a take-it-or-leave-it ultimatum. Thanks to landmark cases like Epic v. Apple, regulatory pushback, and public pressure, that model is no longer universally enforceable.

In 2025, developers finally have choices.

By combining compliant workarounds like App-to-Web flows or SDK integrations with services like Merchant-of-Record platforms like Dodo Payments, it's now practically and legally feasible to retain more revenue and control.

The app stores haven't opened the gates willingly but the gates are opening. And for developers, it's time to walk through.

<Check>
  The future of app monetization is here-one where developers can legally bypass excessive platform fees while maintaining compliance and user experience.
</Check>


# Feature Request and Roadmap
Source: https://docs.dodopayments.com/features/feature-request

We value feedback from our merchants and aim to continuously improve Dodo Payments to meet your business needs. Submit feature requests, vote on existing ideas, and track our public roadmap through our feedback portal.

We use our [feedback portal](https://feedback.dodopayments.com/) to manage feature requests and maintain our public roadmap. This platform allows you to submit ideas, vote on features you'd like to see, and track the development status of upcoming improvements.

<Card title="Visit Our Public Roadmap" icon="external-link" href="https://feedback.dodopayments.com/">
  View all feature requests, vote on ideas, and track our product roadmap on our feedback portal.
</Card>

## **Request a New Feature**

If you have an idea for a feature that would enhance your experience with Dodo Payments, you can submit a feature request directly on our feedback portal.

<img alt="Feature Request" />

* **How to Request a Feature**:
  1. Visit our [feedback portal](https://feedback.dodopayments.com/).
  2. Click on **"Post an idea"** or **"Submit a feature request"**.
  3. Provide the following details:
     * **Feature Name**: A concise title for your feature idea.
     * **Feature Description**: A brief explanation of the feature, including why it's important and how it will help your business.
  4. Submit the request.
* **Tips for Effective Requests**:
  * Be clear and concise.
  * Highlight the business impact of the feature.
  * Provide examples, if applicable.
  * Include use cases that demonstrate the value.

## **Vote for Existing Feature Requests**

We prioritize features that benefit the most merchants. You can browse existing feature requests on our feedback portal and vote for those you find valuable.

* **How to Vote**:
  1. Visit our [feedback portal](https://feedback.dodopayments.com/).
  2. Browse through the list of submitted requests.
  3. Click the **upvote** button (👍) next to the feature(s) you support.
* **Benefits of Voting**:
  * Influence the development priority for features you care about.
  * Help our team identify features that have widespread demand.
  * Get notified when features you've voted for are released.

## **View the Product Roadmap**

Stay informed about the status of feature development through our public roadmap.

* **Roadmap Features**:
  * **Planned**: Features that have been approved and are scheduled for development.
  * **In Progress**: Features currently being worked on by our team.
  * **Completed**: Features that have been successfully implemented and are live.
* **How to Access**:
  * Visit our [feedback portal](https://feedback.dodopayments.com/).
  * Navigate to the **Roadmap** section to view features by status.
  * Browse the feature categories and their current statuses.
  * Filter by status, category, or search for specific features.

<Tip>
  Bookmark our [feedback portal](https://feedback.dodopayments.com/) to stay updated on new features and vote on ideas that matter to you.
</Tip>


# Mobile & Desktop Apps
Source: https://docs.dodopayments.com/features/mobile-app

Manage your Dodo Payments business from anywhere with our mobile and desktop apps. Available on iOS, Android, macOS, Windows, and Linux. Monitor transactions, receive real-time notifications, and access your dashboard wherever you work.

## Introduction

<Frame>
  <iframe title="Mobile App | Dodo Payments" />
</Frame>

Manage your payments, subscriptions, and business activity — anytime, anywhere. The **Dodo Payments apps** bring the power of the Dodo Dashboard to your phone and your desktop, so you stay connected to your revenue, customers, and activity in real time.

Whether you're commuting, traveling, or heads-down at your workstation, you'll never miss an important update again.

## Key Features

<CardGroup>
  <Card title="Real-time Notifications" icon="bell">
    Get instant alerts for new transactions, payouts, subscription renewals, and verification status updates
  </Card>

  <Card title="Dashboard Anywhere" icon="chart-line">
    View your revenue, transaction history, customer statistics, and visual performance graphs on mobile or desktop
  </Card>

  <Card title="Subscription Management" icon="repeat">
    Monitor all active subscriptions and check individual customer details
  </Card>

  <Card title="Product Management" icon="box">
    Create and manage products directly from your phone or desktop
  </Card>
</CardGroup>

## Parity with the Web Dashboard

All the features of the web dashboard are fully available across the mobile and desktop apps, including:

* Test Mode and Live Mode switching
* Verification progress and submission
* Developer settings and API key visibility
* Pricing and Discount configuration

## Download Now

### Mobile

Take Dodo Payments anywhere. Pair with the desktop app for a seamless workflow.

<CardGroup>
  <Card title="iOS" icon="apple" href="https://apps.apple.com/in/app/dodo-payments/id6743651329">
    Download from the Apple App Store
  </Card>

  <Card title="Android" icon="google-play" href="https://play.google.com/store/apps/details?id=com.dodopayments.app">
    Download from Google Play
  </Card>
</CardGroup>

### Desktop

All of Dodo Payments, in one app. Native installers for macOS, Windows, and Linux.

<CardGroup>
  <Card title="macOS" icon="apple" href="https://dodopayments.com/downloads">
    Apple Silicon and Intel builds
  </Card>

  <Card title="Windows" icon="windows" href="https://dodopayments.com/downloads">
    Setup installer and MSI
  </Card>

  <Card title="Linux" icon="linux" href="https://dodopayments.com/downloads">
    AppImage, .deb, and .rpm
  </Card>
</CardGroup>

<Tip>
  Visit [dodopayments.com/downloads](https://dodopayments.com/downloads) for the latest versions of every app, including direct links to each platform installer.
</Tip>


# Introduction
Source: https://docs.dodopayments.com/features/mor-introduction

Dodo Payments acts as your Merchant of Record, handling global payments, tax compliance, fraud protection, and regulatory liability so you can focus on building your product.

Dodo Payments operates as a **Merchant of Record (MoR)** — we become the legal seller of your digital products, taking on the responsibility for payments, taxes, fraud, and compliance so you can focus entirely on building your product.

<CardGroup>
  <Card title="220+ Regions" icon="globe">
    Tax compliance handled automatically
  </Card>

  <Card title="30+ Payment Methods" icon="credit-card">
    Cards, wallets, and local methods
  </Card>

  <Card title="Zero Tax Filing" icon="file-invoice">
    We handle all remittance
  </Card>
</CardGroup>

## What Is a Merchant of Record?

A **Merchant of Record** is the legal entity that appears on your customer's credit card statement and assumes responsibility for the transaction. When you use Dodo Payments as your MoR:

* **We are the legal seller** — Dodo appears on bank statements and receipts
* **You are the product creator** — You build, price, and deliver your product
* **We handle the back office** — Taxes, disputes, compliance, and billing support
* **You receive net payouts** — Revenue deposited directly to your account

```mermaid theme={null}
flowchart LR
    A[👤 Customer] -->|💳 Pays| B[🏦 Dodo]
    B -->|📋 Tax| C[🏛️ Tax Authority]
    B -->|💰 Payout| D[💼 You]
```

<Note>
  Think of a Merchant of Record as hiring a global finance team that handles invoicing, taxes, and billing in every country — without you lifting a finger.
</Note>

## Why Use a Merchant of Record?

Selling digital products globally means navigating VAT in Europe, GST in Australia, Sales Tax in the US, and countless other requirements. Each jurisdiction has different rules, rates, thresholds, and filing deadlines.

| Your Responsibility     |    Without MoR   | With Dodo as MoR |
| ----------------------- | :--------------: | :--------------: |
| VAT/GST Registration    |       ❌ You      |      ✅ Dodo      |
| Tax Calculation         |       ❌ You      |      ✅ Dodo      |
| Tax Filing & Remittance |       ❌ You      |      ✅ Dodo      |
| Chargeback Liability    |       ❌ You      |      ✅ Dodo      |
| PCI Compliance          |       ❌ You      |      ✅ Dodo      |
| Multi-Currency Support  |     ❌ Complex    |    ✅ Built-in    |
| Local Payment Methods   | ❌ Integrate Each |  ✅ 30+ Included  |

<Tip>
  **Example**: Selling a €50/month subscription to a French customer?

  **Without MoR**: Register for French VAT, charge €60 (20% VAT), file quarterly French returns, handle audits—in French.

  **With Dodo**: We collect €60, remit €10 VAT to France, and pay you €50 minus fees. You write code.
</Tip>

## PSP vs. MoR: Key Differences

Understanding the difference between a **Payment Service Provider** (like Stripe) and a **Merchant of Record** is essential.

### Payment Service Provider (PSP)

A PSP processes transactions but leaves you as the legal seller:

```mermaid theme={null}
flowchart LR
    A[👤 Customer] --> B[🌐 Your Site]
    B --> C[💳 PSP]
    C --> D[🏦 Your Bank]
    
    D -.->|⚠️ You Handle| E[📋 Taxes]
    D -.->|⚠️ You Handle| F[⚖️ Disputes]
    D -.->|⚠️ You Handle| G[📜 Compliance]
```

<Warning>
  With a PSP, **you** are responsible for tax registration, collection, filing, and remittance in every jurisdiction where you have customers.
</Warning>

### Merchant of Record (Dodo)

An MoR becomes the legal seller, handling compliance end-to-end:

```mermaid theme={null}
flowchart LR
    A[👤 Customer] --> B[🛒 Dodo Checkout]
    B --> C[🏦 Dodo Payments]
    C --> D[💰 Your Wallet]
    
    C -.->|✅ Handled| E[📋 Taxes]
    C -.->|✅ Handled| F[⚖️ Disputes]
    C -.->|✅ Handled| G[📜 Compliance]
```

<Check>
  With Dodo as MoR, we handle taxes, disputes, and compliance. You receive net payouts with zero paperwork.
</Check>

### Side-by-Side Comparison

| Aspect                | PSP (Stripe, etc.) | MoR (Dodo) |
| --------------------- | :----------------: | :--------: |
| Legal Seller          |    Your Company    |    Dodo    |
| On Customer Statement |      Your Name     |    Dodo    |
| Tax Registration      |        ❌ You       |   ✅ Dodo   |
| Tax Calculation       |        ❌ You       |   ✅ Dodo   |
| Tax Remittance        |        ❌ You       |   ✅ Dodo   |
| Chargeback Risk       |        ❌ You       |   ✅ Dodo   |
| PCI Compliance        |        ❌ You       |   ✅ Dodo   |
| Setup for Global      |       Complex      |   Simple   |

<Info>
  **Important**: Both PSPs and MoRs handle payment processing. The key difference is **who is legally responsible** for tax compliance and transaction liability.
</Info>

## How Tax Compliance Works

Dodo handles the entire tax lifecycle automatically:

<Steps>
  <Step title="Customer Location">
    We detect the customer's country and determine which tax rules apply — VAT, GST, Sales Tax, or other local requirements.
  </Step>

  <Step title="Rate Calculation">
    The correct tax rate is calculated based on product type, customer location, and B2B/B2C status. EU business customers with valid VAT numbers get reverse charge applied.
  </Step>

  <Step title="Collection at Checkout">
    Tax is clearly displayed and collected at checkout. Customers see exactly what they're paying.
  </Step>

  <Step title="Filing & Remittance">
    We file returns and pay collected taxes to the relevant authorities on schedule. You never see a tax form.
  </Step>
</Steps>

## Revenue Flow

Here's how money moves from customer to your account:

```mermaid theme={null}
flowchart LR
    A[👤 Customer<br/>Pays $200] -->|incl. $30 tax| B[🏦 Dodo Payments]
    B -->|$30| C[🏛️ Tax Authority]
    B -->|$162.40| D[💼 You]
```

### Example Payout Breakdown

| Line Item              |       Amount |
| ---------------------- | -----------: |
| Customer Payment       |     \$200.00 |
| Sales Tax (15% VAT)    |     −\$30.00 |
| Dodo Platform Fee (4%) |      −\$8.00 |
| Payment Processing     |      −\$0.60 |
| **Your Payout**        | **\$162.40** |

## When to Choose MoR vs. PSP

<Tabs>
  <Tab title="Choose Dodo (MoR)">
    **Dodo Payments is ideal if you:**

    * Sell digital products, SaaS, or subscriptions
    * Have customers across multiple countries
    * Want to avoid tax registration headaches
    * Prefer predictable, outsourced compliance
    * Value speed to market over maximum control
    * Don't want to manage disputes and fraud
  </Tab>

  <Tab title="Consider a PSP">
    **A PSP might suit you if you:**

    * Operate primarily in one country
    * Have in-house finance and compliance teams
    * Need absolute control over checkout UX
    * Work with extremely thin margins
    * Sell physical goods (MoRs focus on digital)
  </Tab>
</Tabs>

<Note>
  Many businesses start with a PSP and switch to an MoR as they scale internationally. Dodo offers migration support to make this transition seamless.
</Note>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What appears on my customer's credit card statement?">
    Dodo Payments appears as the merchant. We include your product/brand reference where character limits allow, and customers receive detailed receipts showing your product information.
  </Accordion>

  <Accordion title="Do I still own the customer relationship?">
    Yes. You control pricing, branding, product delivery, and direct communication. Dodo handles billing mechanics, but customers know they're buying from you. Your brand appears prominently in checkout, emails, and invoices.
  </Accordion>

  <Accordion title="How does B2B VAT reverse charge work?">
    For B2B sales in the EU, customers can enter their VAT number at checkout. We validate it and apply reverse charge automatically — the tax shifts to the buyer's VAT return instead of being collected.
  </Accordion>

  <Accordion title="Can I use my own payment processor?">
    Yes. With [Bring Your Own Processor (BYOP)](/features/byop) you can connect your own Stripe or Adyen account and route payments from selected countries through it, while Dodo Payments continues to power products, subscriptions, invoicing, and analytics. Countries you do not explicitly route keep flowing through Dodo Payments as your full-service Merchant of Record, which is what allows us to assume tax and fraud liability on those routes.
  </Accordion>

  <Accordion title="How do refunds work?">
    Initiate refunds from your dashboard. We process the refund in the customer's original payment method and currency. Tax amounts are automatically adjusted and reconciled.
  </Accordion>

  <Accordion title="What about my income tax?">
    Dodo handles **sales taxes** (VAT, GST, Sales Tax) on customer transactions. You remain responsible for your business's income tax, corporate tax, and tax obligations on the payouts you receive.
  </Accordion>

  <Accordion title="Which countries can I sell to?">
    We accept payments from 220+ countries and regions with continuous expansion. See the full list:

    <Card title="Supported Regions" icon="globe" href="/miscellaneous/list-of-countries-we-accept-payments-from">
      View all 220+ countries and regions where we accept payments.
    </Card>
  </Accordion>
</AccordionGroup>

## Get Started

<CardGroup>
  <Card title="Create Account" icon="rocket" href="https://app.dodopayments.com/signup">
    Sign up free and accept global payments in minutes.
  </Card>

  <Card title="MoR vs PG Deep Dive" icon="scale-balanced" href="/features/mor-vs-pg">
    Detailed comparison with examples and use cases.
  </Card>

  <Card title="Acceptance Policy" icon="building-shield" href="/miscellaneous/merchant-acceptance">
    Learn what businesses we support.
  </Card>

  <Card title="Talk to Us" icon="envelope" href="mailto:founders@dodopayments.com">
    Get personalized guidance from our team.
  </Card>
</CardGroup>


# MoR vs PG
Source: https://docs.dodopayments.com/features/mor-vs-pg

When it comes to processing payments globally, digital businesses and SaaS companies are often torn between two models: Merchant of Record (MoR) and Payment Gateway (PG). At Dodo Payments, we believe in simplifying global payments while taking care of compliance, taxes, and local laws - and that's why we operate as a Merchant of Record.

## Introduction

This guide compares the MoR model with the traditional Payment Gateway approach, helping you understand the advantages Dodo Payments brings to your business.

## The Core Difference

| Feature                        | MoR (Dodo Payments)                      | Payment Gateway (Traditional PG)              |
| ------------------------------ | ---------------------------------------- | --------------------------------------------- |
| Legal Seller                   | Dodo Payments (MoR)                      | Your Company                                  |
| Tax Collection & Remittance    | Handled by Dodo                          | You are responsible                           |
| Compliance & Regulatory Burden | Dodo assumes liability                   | You handle local laws and chargebacks         |
| Settlement Currency            | USD, EUR, GBP, and 25+ others supported  | Depends on your merchant account              |
| Risk Management                | Built-in fraud and chargeback protection | You set up your own tools (e.g. Stripe Radar) |
| Payouts                        | Aggregated and simplified global payouts | Direct from PG to you, with bank setup        |

## What It Means For You

With **Dodo as MoR**, we become the legal seller to your customers, allowing you to:

* Skip setting up local entities
* Avoid handling VAT, GST, or sales tax
* Offer more payment methods globally
* Reduce legal risk
* Launch faster in new markets

<Note>
  Imagine selling a digital subscription to a user in France. With Dodo Payments, we collect the payment, file VAT with French authorities, and send you the net revenue. No tax headaches. No lawyers. Just growth.
</Note>

Additionally, the MoR model simplifies your entire back office. As your MoR, Dodo handles PCI compliance, fraud detection, currency conversion, and even customer billing support, freeing your team to focus on product and growth.

## Visual Comparison

**Revenue Flow: Payment Gateway**

```mermaid theme={null}
flowchart LR
    A[Customer] --> B[Your Website]
    B --> C["Payment Gateway (e.g. Stripe)"]
    C --> D[Your Bank]
    D -.-> E["You handle: tax, support, refunds, fraud"]
```

**Revenue Flow: Merchant of Record (Dodo)**

```mermaid theme={null}
flowchart LR
    A[Customer] --> B[Dodo Checkout]
    B --> C[Dodo Payments]
    C --> D[Your Wallet]
    C -.-> E["Dodo handles: Tax, Compliance, FX, Fraud, Invoicing"]
```

## Why It Matters for SaaS & Digital Businesses

As your business scales, managing taxes, compliance, and global payment preferences can become overwhelming. With a payment gateway, you're responsible for:

* VAT/GST registration and filing in multiple jurisdictions
* Managing currency conversion and chargebacks
* Providing localized checkout and payment methods

With Dodo Payments as your MoR:

* You expand globally without setting up local entities
* Taxes are calculated, collected, and remitted on your behalf
* You gain access to a library of payment methods tailored to your customers
* We act as your legal buffer and operational partner

<Tip>
  "Think of a payment gateway as a tunnel. Now imagine the Merchant of Record as a tunnel, train, driver, and ticketing staff all-in-one."
</Tip>

## Who Should Use MoR?

Dodo Payments is perfect for:

* SaaS & digital product companies
* Indie creators and solopreneurs
* Global businesses with customers across 100+ countries
* Companies who don't want to manage taxes & compliance in-house

If you're expanding internationally, selling subscriptions, or just want to reduce operational headaches, MoR is the smarter choice.

## When to Use a Payment Gateway Instead

There are cases where using just a payment gateway might make sense:

* Your business operates only in one country
* You already have internal finance and compliance resources
* You require complete control over customer billing experience
* You are highly cost-sensitive with thin margins at scale

<Note>
  For many startups, using a gateway may suffice initially - but as complexity grows, switching to an MoR can save time, reduce risk, and accelerate international growth.
</Note>

## Why Choose Dodo Payments

Dodo Payments offers:

* All-in-one payments, tax, and compliance stack
* Real-time FX and multi-currency support
* Access to 30+ payment methods
* Seat-based billing, subscriptions, and one-time payments
* Automated tax handling in 190+ countries
* Built-in fraud prevention and PCI compliance

Whether you're a solo founder or a scaling SaaS team, Dodo simplifies the complexities of selling globally.

## Learn More

<CardGroup>
  <Card title="Adaptive Currency Support" icon="money-bill-wave" href="/features/adaptive-currency">
    Learn how Dodo automatically presents prices in your customers' local currencies
  </Card>

  <Card title="Supported Payment Methods" icon="credit-card" href="/features/payment-methods">
    Discover the 30+ payment methods available through Dodo Payments
  </Card>
</CardGroup>

## Ready to Switch?

Join 3,000+ digital businesses using Dodo Payments to sell globally, without borders or bottlenecks.

<CardGroup>
  <Card title="Sign Up Free" icon="user-plus" href="https://app.dodopayments.com/signup">
    Create your Dodo Payments account and start selling globally today
  </Card>

  <Card title="Talk to Sales" icon="envelope" href="mailto:founders@dodopayments.com">
    Get personalized guidance from our team
  </Card>
</CardGroup>

<Tip>
  Let Dodo handle the hard stuff - so you can focus on building a great product.
</Tip>


# Figma Plugin
Source: https://docs.dodopayments.com/integrations/figma-plugin

Build Figma plugins with Dodo Payments license key validation and activation

This is an example implementation and boilerplate designed as a starting point for Figma plugin developers who want to integrate Dodo Payments license key API to grant access to their plugins. The template demonstrates complete license key validation and activation functionality, providing everything you need to create premium Figma plugins with built-in licensing.

## Features

* **License Key Validation**: Validates license keys against the Dodo Payments API
* **License Key Activation**: Activates license keys with user identification
* **Environment Support**: Configurable for both test and live environments
* **CORS Proxy**: Uses a Cloudflare Worker proxy to handle CORS restrictions
* **TypeScript Support**: Fully typed implementation with proper error handling

## Getting Started

<Steps>
  <Step title="Create Base Plugin">
    Create your own Figma plugin project using [Figma's plugin quickstart guide](https://www.figma.com/plugin-docs/plugin-quickstart-guide/). This will generate a scaffold with a `manifest.json` file.

    <Tip>
      This step is just to get a unique name and ID for your plugin. You can discard the generated files after committing the ID and name to your git repository in the next step.
    </Tip>
  </Step>

  <Step title="Clone the Example Implementation">
    Clone the [dodopayments-figma repository](https://github.com/dodopayments/dodopayments-figma) and update its `manifest.json` with the name and ID from your generated plugin folder.

    ```bash theme={null}
    git clone https://github.com/dodopayments/dodopayments-figma.git
    cd dodopayments-figma
    ```

    This example serves as your starting point for integration.

    <Tip>
      You need to change the remote origin URL to your own repository for version control.
    </Tip>
  </Step>

  <Step title="Install Dependencies">
    Run the following command in your project root:

    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Configure Environment">
    Set the `API_MODE` in `src/ui/api.ts`:

    ```typescript theme={null}
    const API_MODE = "test_mode"; // for development
    // const API_MODE = "live_mode"; // for production
    ```

    <Warning>
      Always use `test_mode` during development to avoid processing real payments.
    </Warning>
  </Step>

  <Step title="Customize Components">
    Customize the plugin components to match your needs:

    * Update `Authenticated.tsx` to expose functionality for users with valid license keys
    * Customize `LicenseKeyInput.tsx` to match your design preferences

    <Note>
      The `Authenticated.tsx` component is where you'll add your plugin's premium features that require a valid license.
    </Note>
  </Step>
</Steps>

## Configuration

<Steps>
  <Step title="Configure Network Access">
    The plugin needs network access to communicate with the CORS proxy. Add the following to your `manifest.json`:

    ```json theme={null}
    {
      "networkAccess": {
        "allowedDomains": ["https://dodo-payments-proxy.aagarwal9782.workers.dev"]
      }
    }
    ```

    This allows the plugin to validate and activate license keys using the Dodo Payments API.

    <Info>
      The CORS proxy is necessary because Dodo Payments API doesn't allow API calls from browser-based applications as of now.
    </Info>
  </Step>

  <Step title="Configure API Mode">
    In `src/ui/api.ts`, configure the API mode:

    ```typescript theme={null}
    const API_MODE = "test_mode"; // or "live_mode"
    ```

    <Tip>
      Switch to `live_mode` only when you're ready for production and have tested thoroughly in test mode.
    </Tip>
  </Step>
</Steps>

## Development

<Steps>
  <Step title="Import Plugin">
    Import the plugin into Figma using "Import Manifest" from the Figma desktop app.

    <Note>
      You'll need to have the Figma desktop app installed to develop and test plugins locally.
    </Note>
  </Step>

  <Step title="Start Development Server">
    ```bash theme={null}
    npm run dev
    ```

    This starts the development server with file watching for automatic rebuilds.

    <Check>
      Your plugin will automatically rebuild when you make changes to the source code.
    </Check>
  </Step>
</Steps>

## Build Commands

| Command          | Description                                 |
| ---------------- | ------------------------------------------- |
| `npm run build`  | Build the plugin for production             |
| `npm run dev`    | Start development server with file watching |
| `npm run lint`   | Check code style and errors                 |
| `npm run format` | Format code with Prettier                   |

## License Key Integration

The example implementation includes complete license key validation and activation that you can customize for your plugin:

1. **User Input**: Users enter their license key in the plugin UI
2. **Validation**: The plugin validates the key against Dodo Payments API
3. **Activation**: Valid keys are activated with user identification
4. **Access Control**: Plugin functionality is unlocked for valid license holders

## Publishing

Once your plugin is ready:

1. Build for production: `npm run build`
2. Test thoroughly in both test and live modes
3. Follow [Figma's plugin publishing guidelines](https://www.figma.com/plugin-docs/publishing-plugins/)
4. Submit for review through the Figma Community

## Repository

The complete example implementation is available at: [github.com/dodopayments/dodopayments-figma](https://github.com/dodopayments/dodopayments-figma)

Use this as your starting point to build your own premium Figma plugin with Dodo Payments license key integration.


# Countries Eligible for Merchant Acceptance
Source: https://docs.dodopayments.com/miscellaneous/accepted-countries-and-territories

Full list of countries and territories where Dodo Payments supports merchant accounts and payouts.

## How Your Eligible Country Is Determined

Eligibility is based on **the country that issued the government-issued identity document you verify with**, not on where your company is registered or where you pay tax.

| Account Type          | Whose Identity Document Decides Eligibility                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Individual**        | Your own government-issued ID                                                                                |
| **Registered Entity** | The government-issued ID of every director and beneficial owner, in addition to the country of incorporation |

<Warning>
  Registering a company in a supported country does not by itself make an account eligible. If a director or beneficial owner can only verify with an ID issued in a country that is not listed below, the account cannot be onboarded.
</Warning>

Tax residence, a residence permit, and a local bank account are all helpful, but none of them replace a government-issued ID from a listed country.

<Info>
  Not sure how this applies to you? Contact [support@dodopayments.com](mailto:support@dodopayments.com) before you begin your integration, so you don't build against an outcome that cannot be approved.
</Info>

## Accepted Countries & Territories

1. Afghanistan
2. Albania
3. Andorra
4. Anguilla
5. Antigua and Barbuda
6. Argentina
7. Armenia
8. Aruba
9. Australia
10. Austria
11. Azerbaijan
12. Bahamas
13. Bahrain
14. Barbados
15. Belgium
16. Belize
17. Benin
18. Bermuda
19. Bhutan
20. Bolivia
21. Bosnia and Herzegovina
22. Botswana
23. Brazil
24. British Virgin Islands
25. Brunei Darussalam
26. Bulgaria
27. Burkina Faso
28. Burundi
29. Cabo Verde
30. Cambodia
31. Canada
32. Cayman Islands
33. Chad
34. Chile
35. China
36. Colombia
37. Comoros
38. Cook Islands
39. Costa Rica
40. Croatia
41. Curacao
42. Cyprus
43. Czech Republic
44. Denmark
45. Djibouti
46. Dominica
47. Dominican Republic
48. Ecuador
49. Egypt
50. El Salvador
51. Estonia
52. Eswatini
53. Ethiopia
54. Falkland Islands
55. Faroe Islands
56. Fiji
57. Finland
58. France
59. French Polynesia
60. Gabon
61. Gambia
62. Georgia
63. Germany
64. Ghana
65. Gibraltar
66. Greece
67. Greenland
68. Grenada
69. Guam
70. Guatemala
71. Guernsey
72. Guinea
73. Guinea-Bissau
74. Guyana
75. Honduras
76. Hong Kong
77. Hungary
78. Iceland
79. India
80. Indonesia
81. Ireland
82. Isle of Man
83. Israel
84. Italy
85. Jamaica
86. Japan
87. Jersey
88. Jordan
89. Kazakhstan
90. Kiribati
91. Kyrgyzstan
92. Latvia
93. Lesotho
94. Liberia
95. Liechtenstein
96. Lithuania
97. Luxembourg
98. Madagascar
99. Malawi
100. Malaysia
101. Maldives
102. Mali
103. Malta
104. Mauritania
105. Mauritius
106. Mexico
107. Moldova
108. Monaco
109. Mongolia
110. Montenegro
111. Montserrat
112. Mozambique
113. Namibia
114. Nepal
115. Netherlands
116. New Caledonia
117. New Zealand
118. Niger
119. North Macedonia
120. Norway
121. Oman
122. Palau
123. Panama
124. Paraguay
125. Peru
126. Philippines
127. Poland
128. Portugal
129. Puerto Rico
130. Qatar
131. Republic of Congo
132. Republic of Korea
133. Romania
134. Rwanda
135. Saint Kitts and Nevis
136. Saint Lucia
137. Saint Martin
138. Saint Pierre and Miquelon
139. Saint Vincent and the Grenadines
140. Samoa
141. San Marino
142. Sao Tome and Principe
143. Saudi Arabia
144. Senegal
145. Serbia
146. Seychelles
147. Sierra Leone
148. Singapore
149. Sint Maarten
150. Slovakia
151. Slovenia
152. Solomon Islands
153. South Africa
154. Spain
155. Sri Lanka
156. Suriname
157. Sweden
158. Switzerland
159. Taiwan
160. Tajikistan
161. Tanzania
162. Thailand
163. Timor-Leste
164. Togo
165. Tonga
166. Trinidad and Tobago
167. Tunisia
168. Türkiye
169. Turkmenistan
170. Turks and Caicos Islands
171. Uganda
172. United Arab Emirates
173. United Kingdom
174. United States
175. Uruguay
176. Uzbekistan
177. Vanuatu
178. Vietnam
179. Virgin Islands
180. Wallis and Futuna
181. Zambia
182. Zimbabwe

<Note>
  This policy applies to all country designations made on or after March 23, 2026. Merchants receiving services in countries supported prior to this date will not be affected, unless the relevant country is subject to active sanctions or regulatory restrictions. In such cases, Dodo Payments reserves the right to discontinue support.
</Note>

<Note>
  This list is regularly updated to reflect FATF, OFAC, UN, and EU AML/CFT directives. All merchants are responsible for ensuring ongoing compliance.

  Payouts are supported only in the countries and regions listed above. If your country is not included, payouts are not currently available from that location.

  This list may change over time in line with regulatory and compliance requirements, and we're unable to offer payouts outside of the supported regions.

  Merchant accounts are supported only where KYC documentation is issued in the countries listed above.
</Note>


# FAQs
Source: https://docs.dodopayments.com/miscellaneous/faq

Comprehensive answers to common questions about Dodo Payments, covering onboarding, payments, subscriptions, compliance, and technical integration to help you navigate and make the most of our platform.

## Getting Started & Account Setup

<Accordion title="Q1: How do I login to Dodo Payments Dashboard?">
  A: Visit our dashboard and enter your account email. Dodo Payments uses passwordless login — we send a **6-digit one-time code (OTP)** to your email, which you enter to sign in. No password is required. In case you face any issues please reach out to our support team.
</Accordion>

<Accordion title="Q2: What documents do I need to complete the verification process?">
  A: The documents required for verification include a valid government-issued ID (for identity verification) and business registration documents (for business verification). For details check the [verification process page](/miscellaneous/verification-process).
</Accordion>

<Accordion title="Q3: What happens if my verification is rejected?">
  A: If your verification is rejected, you will receive an email with the reason for rejection. You can contact our support team to resolve any issues, correct documentation, and reapply. The resubmit option will be enabled by our verification team if necessary.
</Accordion>

<Accordion title="Q4: How long does the verification process take?">
  A: The verification process typically takes **24-72 working hours**. However, if additional documents are required, the process may take longer.
</Accordion>

<Accordion title="Q5: I currently do not have a website for my business. Can I submit my company's linkedin page instead?">
  A: We need your website to understand the kind of products you are selling and verify your business for live access. If you do not have a website or are in the process of building one please reach out to us at [support@dodopayments.com](mailto:support@dodopayments.com)
</Accordion>

<Accordion title="Q6: I am an individual and I do not have a registered business. Can I still use dodo payments?">
  A: Yes, we support unregistered businesses as well. You do not need a registered business to use Dodo Payments.

  * You can onboard as an individual and start receiving international payments without any hassle
  * You will still need to submit Identity Verification and Business Verification forms as an unregistered business for us to onboard you
</Accordion>

<Accordion title="Q7: I want to integrate my other business with Dodo payments. Should I create a new account?">
  A: No, you can manage multiple businesses through a single account. To add a new business, click the + icon in the bottom left corner of the dashboard and select the Add Business option.
  You can refer to /miscellaneous/accounts#managing-multiple-businesses for more details
</Accordion>

<Accordion title="Q8: Should I wait for verification to complete before integrating dodo payments in my system?">
  A: No, there is no need for you to wait. You can start integrating using the Test mode and once your verification is successful you can start making Live payments in production. Learn more about Test and Live modes here,
  /miscellaneous/test-mode-vs-live-mode
</Accordion>

<Accordion title="Q9: How do I get live mode access?">
  A: Once your account is created, you will automatically get access to live mode.
</Accordion>

<Accordion title="Q10: Does Dodo Payments have an affiliate program?">
  A: Yes — you can run your own affiliate program through our integrations with affiliate partners **[Affonso](https://affonso.io)** and **[Dub Partners](https://dub.co)**. These integrations handle commission attribution, real-time reporting, and referral tracking on top of your Dodo Payments checkout. See the [affiliates documentation](/features/affiliates) for setup steps.
</Accordion>

<Accordion title="Q11: How can I delete the products/customers that I have created?">
  A: Currently, you cannot delete products or customers, as they must be retained for future compliance. However, you can now archive products, which removes them from the active products list while keeping the records for compliance purposes.
</Accordion>

<Accordion title="Q12: How can I have a custom UI for the payments page?">
  A: You can add your business logo and your business name to the payment page. To upload them, visit the business profile page on your dashboard.
</Accordion>

<Accordion title="Q13: Can I update the branding on the checkout page?">
  A: Yes. You can:

  * Go to Dashboard → Settings → Business
  * Update your logo, brand name, and support email.
  * Changes will reflect on both static and dynamic links
</Accordion>

<Accordion title="Q14: Can I embed Dodo Checkout in an iframe?">
  A: No. The hosted checkout flow does not support embedding in an iframe.

  Instead:

  * Redirect users to the Dodo checkout URL
  * Or use our Overlay Checkout Feature. [Overlay Checkout Docs](/developer-resources/overlay-checkout)
</Accordion>

<Accordion title="Q15: Can I create a one-time hosted checkout payment without adding products to Dodo Payments?">
  A: No. Products are mandatory in the Dodo Payments system.
</Accordion>

<Accordion title="Q16: Do you support e-commerce websites?">
  A: No, we do not support e-commerce websites.
</Accordion>

<Accordion title="Q17: Can I switch between brands in Dodo Payments?">
  A: Yes, you can switch between brands for products. You can select the desired brand when creating or editing products in your dashboard.
</Accordion>

<Accordion title="Q18: Can I delete a brand or update the Brand URL in Dodo Payments?">
  A: No, Dodo Payments currently does not support:

  * **Deleting a brand**: If a brand is not in use, you can simply ignore it — it won't affect your account or operations
  * **Changing or updating the Brand URL**: Once created, the Brand URL cannot be modified. Even if the URL is incorrect, it does not impact your setup or functionality
</Accordion>

<Accordion title="Q19: Can I integrate Dodo Payments with Shopify to sell physical products?">
  A: No, Dodo Payments currently does not support physical goods and does not offer a Shopify plugin.
</Accordion>

<Accordion title="Q20: My INR subscription product is showing USD on checkout. How do I fix that?">
  A: You can set a product's base price in any currency Dodo Payments can charge, so check that the product's base currency is INR. Customers outside your base currency are billed via Adaptive Pricing, so enable Adaptive Pricing to display prices in the customer's local currency and unlock the corresponding payment methods.
</Accordion>

<Accordion title="Q21: How do I update my brand URL for secondary brands?">
  A: Update your brand URL from the Dodo Payments dashboard under **Settings → Business**. Ensure the URL is valid and publicly accessible.
</Accordion>

<Accordion title="Q22: Can I change the primary brand in Dodo Payments?">
  A: No, changing the primary brand is not supported. As a workaround, you can swap the brand names — update your secondary brand's name to the one you want as primary, and vice versa.
</Accordion>

## Verification, Tax & Compliance

<Accordion title="Q23: Why is my verification taking so long?">
  A: Dodo Payments typically takes 24–72 working hours to process verifications. However, delays can occur due to:

  * High volume of applications
  * Weekends and public holidays
  * Incomplete or incorrect submissions
  * Manual reviews for risk or compliance

  <Note>
    If it's been more than 72 hours, please check your email or Dodo Payments dashboard for any required action. You can also DM your registered email to the team on Discord for a follow-up.
  </Note>
</Accordion>

<Accordion title="Q24: I chose the wrong registration type (business vs individual). How can I fix it?">
  A: If you selected the wrong entity type (e.g., chose "Organization" but you're an individual or a Sole Prop with GST), your verification might be On-hold, requiring you to change or update the documentation.

  Steps to fix:
  Step 1: Inform support via Intercom who will help you enable resubmission for the Payout Compliance form.
  Step 2: Choose the right registration type, and resubmit the required documents.
</Accordion>

<Accordion title="Q25: Can I use a different name (like my parent's) to sign up and get verified?">
  A: Yes, this is allowed. However, KYC, bank details, and ownership must be under the parent's name.

  If your parent is the actual business owner:

  * They should sign up using their email and mobile number.
  * All KYC documents, bank details, and ownership records must be in their name.

  <Note>
    All verification documents and bank account details must match the name used for sign-up.
  </Note>
</Accordion>

<Accordion title="Q26: How do I check the reason for verification rejection?">
  A: You can find the reason in the Dodo Payments dashboard, under the verification section.

  <Tip>
    If it's not visible, contact [compliance@dodopayments.com](mailto:compliance@dodopayments.com) for assistance.
  </Tip>
</Accordion>

<Accordion title="Q27: Can I create a new business account if my previous one was declined?">
  A: Yes — but only if:

  * You've fixed the issues that led to rejection.
  * You're not attempting to bypass risk decisions (e.g., deboarding for fraud concerns).

  <Note>
    Creating multiple accounts without resolving the underlying issue will likely result in the new account being rejected as well.
  </Note>
</Accordion>

<Accordion title="Q28: I've been told my account was previously deboarded. What does this mean?">
  A: If you see a message stating your account was previously deboarded by the risk team:

  * It means Dodo Payments found significant compliance or risk issues with your activity or business.
  * Attempting to create new accounts using the same identity or business details will likely be rejected again.

  <Note>
    If you believe this is a mistake, email [compliance@dodopayments.com](mailto:compliance@dodopayments.com) and request a review — include clear evidence to support your case.
  </Note>
</Accordion>

<Accordion title="Q29: How do I get my payout verification cleared faster?">
  A: To avoid delays:

  * Submit clear, properly formatted documents
  * Avoid repeated messages/tags in Discord — this slows the queue
  * Mention if you've crossed the payout threshold or have urgent timelines
  * DM your registered email ID if asked

  <Tip>
    Most payout reviews are completed within 72 working hours, unless there's an issue with your submission.
  </Tip>
</Accordion>

<Accordion title="Q30: I have a GST with a trade name. Is that considered an organization?">
  A: No. If you're registered with a GST as an individual (sole proprietor), you're still considered an Individual. Incorrect information provided during registration can be updated by contacting support.

  ✅ Select "Individual" in the registration
  ❌ Do not select "Organization" unless you're a registered legal entity
</Accordion>

<Accordion title="Q31: How does Dodo Payments handle GST for Indian SaaS merchants?">
  A: Dodo Payments automatically calculates and applies **GST** for Indian merchants based on your customer's location.
</Accordion>

<Accordion title="Q32: Does Dodo Payments handle international sales?">
  A: Yes, Dodo Payments supports international sales and manages all associated compliances.
</Accordion>

<Accordion title="Q33: Are address data such as city, state, zipcode fields mandatory? Can I exclude requesting those values from my customer?">
  A: Yes, they are mandatory. As we are the Merchant of Record, we require the customer's billing address to:

  * Generate invoices
  * File taxes
  * Ensure all purchases are compliant

  You can implement our API-based checkout flow to pre-fill customer details if you have already collected them, ensuring a smoother experience. However, we will need these details for every purchase.
</Accordion>

<Accordion title="Q34: Do I need to file taxes in the US if I sell there?">
  A: Not directly. Dodo Payments acts as the Merchant of Record, handles customer-side tax, and remits where applicable. We no longer require tax forms. You still need to file income tax in your home country (e.g., India).
</Accordion>

<Accordion title="Q35: Do I need a PAN or GST to receive payments? (For Indian Nationals Only)">
  A: **For Indian Individuals:**

  * PAN is mandatory (for KYC and tax purposes)

  **For registered businesses:**

  * Either Business PAN or GSTIN can be submitted
  * GST is optional unless you exceed the registration threshold or want input credit

  **For foreign nationals:**

  * Equivalent identity and tax documentation from your country of residence will be required during the verification process
</Accordion>

<Accordion title="Q36: I have a Udyam/MSME certificate. How does this affect my registration?">
  A: A Udyam/MSME certificate is applicable for both individuals and private entities. Having a Udyam/MSME certificate does not automatically make you an Organization. The registration type depends on your bank account type:

  * **If you operate with a personal bank account** (even with Udyam/MSME certificate): You're considered an **Individual**
  * **If you operate with a company bank account** (registered entity): You're an **Organization**

  <Note>
    The key factor is whether your bank account is in your personal name or your company's name, not whether you have business registration certificates.
  </Note>
</Accordion>

<Accordion title="Q37: Can I create an account if I am below 18?">
  A: Yes, Dodo Payments does support merchants who are under 18, provided that your business is signed up with a parent or guardian's details. All documents and bank account details must belong to a parent or guardian, and all payouts will be disbursed to their bank account. Once you turn 18, you can update the account details to your own information.

  To proceed with verification, the following documents are required:

  * **Proof of Identity of the Minor:** Passport, Birth Certificate, Aadhaar Card, or any valid government-issued ID
  * **Proof of Identity of the Parent/Guardian:** A valid government-issued ID (e.g., Passport, Aadhaar Card, National ID Card, or Driver's License)
  * **Proof of Relationship with the Parent/Guardian:** Birth Certificate, Aadhaar Card, Passport, or equivalent official document
  * **Website Domain Registration Certificate or Invoice:** The domain registration must be transferred to the assigned parent or guardian's name

  For any questions, please reach out to [support@dodopayments.com](mailto:support@dodopayments.com).
</Accordion>

<Accordion title="Q38: Why is my ID verification form failing?">
  A: Please ensure you are using a physical ID document (not a screenshot or photocopy) and capturing a live photo. Try switching browsers or devices, and make sure you are in a well-lit environment so the system can accurately capture your details.

  Identity Verification does not reopen automatically after a failed attempt, so you may see that resubmissions are paused. Email [support@dodopayments.com](mailto:support@dodopayments.com) from your registered email address to have the form re-enabled. See [If Identity Verification Fails](/miscellaneous/verification-process#if-identity-verification-fails) for the full list of causes and what to prepare before retrying.
</Accordion>

<Accordion title="Q39: Is there any tax form I need to submit?">
  A: The only mandatory tax form is the **W-8BEN-E**, and it is required only if you are a registered entity in the UK.
</Accordion>

<Accordion title="Q40: What details are required in the Product Verification Form (PVF)?">
  A: All details in the PVF must accurately match the information on your website. Ensure that your website is live, accessible, and reflects the same information provided in the form.

  Your site also needs to publicly show your pricing, Terms of Service, Privacy Policy, Refund and Cancellation Policy, and a contact route. See [Preparing Your Website](/miscellaneous/verification-process#preparing-your-website) for the full checklist.
</Accordion>

<Accordion title="Q41: What happens if my form is rejected?">
  A: You can view the reason for rejection on your dashboard. If you believe the rejection was incorrect, you may file an appeal (only once).
</Accordion>

<Accordion title="Q42: How do I file an appeal?">
  A: Follow the dashboard navigation to file an appeal. Ensure your explanation is detailed and not a one-liner. For additional clarification, you may contact [support@dodopayments.com](mailto:support@dodopayments.com).
</Accordion>

<Accordion title="Q43: How long does it take for an appeal to be reviewed?">
  A: Appeals typically take more than **48 working hours** to be reviewed.
</Accordion>

<Accordion title="Q44: What happens if my appeal is rejected?">
  A: An appeal rejection is considered final. Rejections usually occur if the product violates merchant acceptance policies, is incomplete, or still under development. You may create a new account after addressing the issues identified. For further clarification, please contact [support@dodopayments.com](mailto:support@dodopayments.com).
</Accordion>

<Accordion title="Q45: Can I change or update my registration type (Individual ↔ Business)?">
  A: Yes. You can switch between Individual and Business account types at any time. To do this, contact support via Intercom and request resubmission access. Once enabled, go to the verification section on your dashboard, select the correct registration type, and resubmit your documents. This change will not impact your existing subscriptions or payments.
</Accordion>

<Accordion title="Q46: My verification is On-Hold — what does that mean?">
  A: On-Hold means our compliance team needs additional information or documents from you. Check your dashboard for the specific requirement. You can also contact [support@dodopayments.com](mailto:support@dodopayments.com) with your registered email for clarification.
</Accordion>

<Accordion title="Q47: What happens to my existing subscriptions and payments if I get deboarded?">
  A: If your account is deboarded, only live payments will be disabled — you will no longer be able to receive new payments. Existing subscriptions and historical payment data will not be affected.
</Accordion>

## Payments & Transactions

<Accordion title="Q48: What types of payments can I accept with Dodo Payments?">
  A: Dodo Payments supports a variety of payment methods, including **credit cards**, **debit cards**, and **digital wallets**. We also support one-time payments and recurring subscription payments for digital products.
</Accordion>

<Accordion title="Q49: Why was the first payment marked successful with an amount of $0 for subscription?">
  A: If a product has a trial period, the first payment automatically becomes a mandate payment of \$0. This is expected behavior and confirms that the mandate has been created successfully.
</Accordion>

<Accordion title="Q50: After the trial period ends, does the customer need to pay (product price(e.g $25)) again manually?">
  A: No. Once the trial ends, the system automatically generates the product price(e.g \$25) for the customer. They do not need to pay it manually.
</Accordion>

<Accordion title="Q51: What if the trial period shows differently on my app vs. the Dodo Payments dashboard?">
  A: This usually indicates a setup or implementation issue on your end. Test the trial + subscription flow in test mode first, confirm it's working, and then switch to live mode.
</Accordion>

<Accordion title="Q52: Do I need to test the trial feature before going live?">
  A: Yes. It's recommended to fully implement and test the feature in test mode to ensure everything works correctly before switching to live mode.
</Accordion>

<Accordion title="Q53: How can I track payment statuses?">
  A: You can track the status of payments from the **Payments** section of your dashboard. Each transaction is listed with a status indicator: **In Progress**, **Failed**, or **Successful**.
</Accordion>

<Accordion title="Q54: What should I do if a payment fails?">
  A: If a payment fails, check the **Payment Details Page** for more information. Common reasons include incorrect payment details, insufficient funds, or network issues. You can resend the payment link to your customer to retry the payment.

  Look up the specific decline code in the [Transaction Failures](/api-reference/transaction-failures) reference for its meaning and recommended action, and see [Handle Payment Failures](/developer-resources/handle-payment-failures) to handle failures programmatically.
</Accordion>

<Accordion title="Q55: Do merchants get notified when a user's payment fails?">
  A: Yes. Dodo Payments notifies the merchant when a user's payment fails through multiple channels in live mode:

  * Email notifications
  * Webhook events
  * Mobile notifications
  * Dashboard notifications
    This ensures merchants stay informed about failed transactions.
</Accordion>

<Accordion title="Q56: What happens to a subscription if a payment fails?">
  A: The subscription is not cancelled immediately. Instead, it is moved to on-hold status until a successful payment is made.

  If you have an issue with the card, you can update the payment method by:

  * Clicking on the on-hold subscription in your dashboard and using the **Update Payment Method** button
  * Or using the API endpoint: [https://docs.dodopayments.com/api-reference/subscriptions/update-payment-method](https://docs.dodopayments.com/api-reference/subscriptions/update-payment-method)

  Dodo Payments can recover these failures for you automatically: [Subscription Payment Retries](/features/recovery/payment-retries) re-attempt soft declines, and [Subscription Dunning](/features/recovery/subscription-dunning) emails the customer to update their payment method.
</Accordion>

<Accordion title="Q57: If I retry payments myself, do I need the failed payment ID?">
  A: No. You only need the subscription ID to initiate a new payment attempt. If you would rather not manage retries yourself, enable [Subscription Payment Retries](/features/recovery/payment-retries) to recover failed renewals automatically.
</Accordion>

<Accordion title="Q58: How can a subscription payment fail with INCORRECT_NUMBER if previous cycles were successful?">
  A: A subscription payment can fail with `INCORRECT_NUMBER` if the customer's card was:

  * Cancelled
  * Replaced
  * Deactivated
  * Flagged by their bank or payment provider

  This can happen after the previous billing cycle. Dodo Payments simply displays the error message returned by the payment provider. See the [Transaction Failures](/api-reference/transaction-failures) reference for what `INCORRECT_NUMBER` and other decline codes mean and how to respond.
</Accordion>

<Accordion title="Q59: Does the chargeback apply for business even if my business has a no refund policy?">
  A: Yes. A "No refund" policy does not override the card network's dispute resolution process. Chargebacks are governed by the cardholder's bank and card network rules (e.g., Visa, Mastercard).

  If a customer files a dispute:

  * Your business is still subject to a chargeback investigation
  * You must respond with evidence (proof of delivery, usage logs, terms acceptance, etc.)
  * If the bank decides in favor of the cardholder, the chargeback fee and transaction reversal will apply regardless of your stated policy

  <Tip>
    We recommend having clear communications, tracking customer usage, and providing compelling evidence when chargebacks arise.
  </Tip>
</Accordion>

<Accordion title="Q60: Why is payment.status sometimes null?">
  A: payment.status can be null for a short time:

  * Right after creation but before processing completes
  * During subscription billing failures or retries

  Once set, it is one of: succeeded, failed, cancelled, processing, requires\_customer\_action, requires\_merchant\_action, requires\_payment\_method, requires\_confirmation, requires\_capture, partially\_captured, or partially\_captured\_and\_capturable. The terminal values are succeeded, failed, and cancelled.

  <Note>
    Use webhook events like payment.succeeded or payment.failed for more reliable status tracking.
  </Note>
</Accordion>

<Accordion title="Q61: Why is product_cart null even though it's a checkout in webhook payload?">
  A:

  * For subscription payments, product\_cart is empty because there's no one-time item being bought
  * product\_cart is only populated for one-time payments
</Accordion>

<Accordion title="Q62: Why was my real card blocked during testing?">
  A: You likely tested in Live Mode instead of Test Mode.

  Live payments:

  * Use real money
  * Go through real banks
  * May be flagged as suspicious if volume is low or inconsistent

  ✅ Always test using:

  * Test Mode in the dashboard
  * Test card numbers provided in the documentation
</Accordion>

<Accordion title="Q63: My customer completed payment but I didn't receive webhook?">
  A: Checklist:

  * Confirm webhook is configured in Dashboard > Developers -> Webhooks
  * Check if webhook is failing silently due to non-2xx response
  * Check logs: was a 429 or timeout returned?
</Accordion>

<Accordion title="Q64: Why is my dashboard showing success, but my app didn't update?">
  A: It's likely you're relying solely on `return_url` query params and not handling:

  * Webhooks
  * API confirmation call

  ✅ Fix:

  * Always listen for payment.succeeded webhook
  * Or query the API to confirm transaction after redirect
</Accordion>

<Accordion title="Q65: I'm not seeing UPI as a payment option — why?">
  A: UPI may not appear as a payment option for several reasons:

  * The billing country is not set to India (IN).
  * Adaptive Currency is disabled.

  Note: If you are a non-Indian merchant and Adaptive Currency is not enabled, UPI will not be available for your customers.
</Accordion>

<Accordion title="Q66: Does Dodo support UPI for subscriptions?">
  A: Yes, UPI subscriptions are supported with RBI-compliant mandates. UPI subscriptions operate under RBI (Reserve Bank of India) regulations with specific requirements:

  * **Mandate Limits**:
    * Charges below Rs 15,000: An on-demand mandate for Rs 15,000 INR is created
    * Charges Rs 15,000 or above: A subscription mandate for the exact subscription amount is created
  * **48-Hour Processing Delay**: Charges are initiated on the scheduled date, but the actual deduction occurs 48 hours after initiation (may extend up to 2-3 additional hours)
  * **Mandate Cancellation**: Customers can cancel mandates via their banking apps during the 48-hour window

  <Note>
    UPI subscriptions have the same RBI-compliant mandate requirements as Indian card subscriptions. For detailed information, see the [Payment Methods documentation](/features/payment-methods#upi-and-rupay-india).
  </Note>
</Accordion>

<Accordion title="Q67: How do I enable Google Pay / Apple Pay on static payment links?">
  A: Google Pay and Apple Pay automatically appear on static payment links in live mode. You do not need to take any additional steps to enable them.
</Accordion>

<Accordion title="Q68: How can I enable 3DS in Dodo Payments?">
  A: You can enable 3DS directly from the Dodo Payments dashboard. Simply go to **Settings → Business** and turn on the 3DS option under Payment Settings.
</Accordion>

<Accordion title="Q69: How do I collect billing details without passing them in API?">
  A: If you want users to enter billing info themselves:

  * Use static links, which automatically collect billing
  * For dynamic flows, you must collect info manually and pass it in the API

  There's no built-in UI yet for collecting billing during dynamic link creation.
</Accordion>

<Accordion title="Q70: What's the difference between static and dynamic payment links?">
  A: **Static payment links** are no-code options meant for quick use. They:

  * Are configured from the dashboard
  * Automatically collect billing info
  * Cannot be customized per customer/session

  **Dynamic payment links** are created via API. They:

  * Require you to pass billing info explicitly
  * Can be customized in real-time (price, user ID, redirect URL, etc.)

  <Tip>
    If you don't want to write code, go with static links. If you need flexibility or want to build custom workflows, use dynamic links.
  </Tip>
</Accordion>

<Accordion title="Q71: How many webhook events do I get when someone starts a subscription?">
  A: On the first successful subscription payment, you will typically receive these three webhooks if no trial period is involved:

  * `subscription.active` webhook
  * `payment.succeeded` webhook
  * `subscription.renewed` webhook
</Accordion>

<Accordion title="Q72: What does subscription.cancelled_at mean? Is it a scheduled cancellation?">
  A: Dodo supports both immediate and scheduled cancellations.

  When a cancellation request is made:

  * **Immediate cancellation**: The subscription.cancelled\_at timestamp is set immediately and the subscription ends at that moment
  * **Scheduled cancellation**: Use the `cancel_at_next_billing_date` parameter in the subscription patch API to cancel at the end of the current billing period
</Accordion>

<Accordion title="Q73: When does a subscription get charged?">
  A: Dodo Payments charges the customer immediately upon subscription creation if the product does not have a trial period.

  <Note>
    For Indian cards and UPI subscriptions, see the <a href="/features/payment-methods/india">India Payment Methods</a> page for detailed information about RBI regulations and processing delays.
  </Note>
</Accordion>

<Accordion title="Q74: Why does the Change Plan API return an empty response?">
  A: The Change Plan API returns only a 200 status code with no response body, so the response will appear empty even though the plan change is successful.
</Accordion>

<Accordion title="Q75: Why wasn't a new payment prompted when switching from a monthly to an annual plan?">
  A: When changing plans, Dodo Payments automatically charges the saved card. If the charge fails, the subscription is moved to "on hold." So no manual payment flow is triggered.
</Accordion>

<Accordion title="Q76: Why does my product price (Rs 100) show a higher amount (Rs 104) during checkout?">
  A: This happens when Adaptive Currency is enabled. The feature adds an additional 4% charge automatically.
</Accordion>

<Accordion title="Q77: Why does checkout ignore existing active subscriptions and create a new one?">
  A: Checkout always creates a new subscription. It does not check whether the customer already has an active subscription. Your application must block existing subscribers from starting a checkout session to avoid duplicate charges.
</Accordion>

<Accordion title="Q78: Why am I seeing a TRANSACTION_NOT_ALLOWED error during a subscription upgrade/downgrade?">
  A: This error comes from the card issuer, not Dodo Payments. The bank is blocking the transaction due to restrictions on that card.

  Common reasons:

  * Card not allowed for online, international, or recurring payments
  * Merchant category (MCC) is blocked
  * Bank's fraud rules prevented the charge
  * Prepaid or restricted cards may not support these payments
</Accordion>

<Accordion title="Q79: Is there a way to test in live mode without making real payments?">
  A: Yes. You can test live-mode checkout flows by creating a 100% discount code. This allows you to complete the full payment and redirect flow without being charged.
</Accordion>

<Accordion title="Q80: What is the $0 payment method?">
  A: A \$0 payment occurs when the total payable amount becomes zero (e.g., by applying a 100% discount). In such cases, no actual payment is processed, but the checkout and subscription flow still work normally.
</Accordion>

<Accordion title="Q81: It seems my account appears to be suspended, but compliance says everything is fine. What should I do?">
  A: In most cases, this happens because you've accidentally switched to an old or inactive business account. Simply switch back to your active business account in the Dodo Payments dashboard. If the issue continues after switching, contact Dodo Payments Support for assistance.
</Accordion>

<Accordion title="Q82: Do you support ACH payments?">
  A: Yes. ACH Direct Debit is supported for one-time payments from customers with a US billing address paying in USD. It is not available for subscriptions. ACH payments take 4 business days to clear, so only fulfill an order once the payment reaches a succeeded state rather than when the customer authorizes it. See the [ACH Direct Debit](/features/payment-methods/ach) page for setup and testing details.
</Accordion>

<Accordion title="Q83: Is PayPal supported?">
  A: PayPal is currently paused. We don't have an ETA for when it will be available. Once it's live, we'll update our docs.
</Accordion>

<Accordion title="Q84: What currencies does Dodo Payments natively support?">
  A: Dodo Payments natively supports three payout currencies: USD, GBP, and EUR. INR remains supported as a transaction currency (UPI, RuPay, Indian-card subscriptions) but is no longer a native payout wallet. For other currencies, you can enable Adaptive Pricing to automatically convert prices to your customer's local currency.

  If your linked bank account is credited in a currency other than the one the transfer is sent in, your bank performs that conversion on receipt at its own exchange rate and may apply its own receiving charges. Payout routes and currencies vary by country — contact [support@dodopayments.com](mailto:support@dodopayments.com) to confirm how your payouts will be sent and credited.
</Accordion>

<Accordion title="Q85: How are FX conversion charges calculated?">
  A: FX conversion charges are applied based on the exchange rate on the day the transaction is processed. Rates vary daily based on market fluctuations.
</Accordion>

<Accordion title="Q86: Which countries does Dodo Payments accept payments from?">
  A: See the full list of supported countries here: [https://docs.dodopayments.com/miscellaneous/list-of-countries-we-accept-payments-from](https://docs.dodopayments.com/miscellaneous/list-of-countries-we-accept-payments-from)
</Accordion>

<Accordion title="Q87: How do I add an addon to an existing subscription?">
  A: Use the Change Plan API with the same product\_id and include the addons array. The addon will be added without changing the base plan, and the customer will be charged a prorated amount immediately.

  Example:

  ```
  POST /subscriptions/{subscription_id}/change-plan
  {
    "product_id": "pdt_current_product",
    "quantity": 1,
    "proration_billing_mode": "prorated_immediately",
    "addons": [
      { "addon_id": "adn_your_addon", "quantity": 1 }
    ]
  }
  ```
</Accordion>

<Accordion title="Q88: How long can a subscription stay in On-Hold state?">
  A: A subscription stays On-Hold until the customer updates their payment method and a successful payment is made. The payment method can be updated at any time — from the Customer Portal or via the [Update Payment Method API](/api-reference/subscriptions/update-payment-method) — whether or not a payment has failed.
</Accordion>

<Accordion title="Q89: Can I make tax inclusive in the product price?">
  A: Yes. Go to Dashboard → Products → Edit Product → Pricing → enable Tax Inclusive Pricing. Taxes are automatically calculated based on the customer's location — there's no fixed tax list to manage.
</Accordion>

<Accordion title="Q90: Can addons have their own brand?">
  A: No. Add-ons cannot be purchased standalone and don't support branding directly. The brand is defined on the base product. Attach the brand to the main product and then add your add-ons to it.
</Accordion>

<Accordion title="Q91: Can I switch a product to a different brand?">
  A: No. Brands are selected at the Product level and cannot be switched after the product is created. Create a new product under the desired brand if needed.
</Accordion>

## Payouts & Bank Integration

<Accordion title="Q92: How do payouts work with Dodo Payments?">
  A: Payouts are the transfer of your collected sales revenue to your linked bank account. Dodo Payments supports multiple payout cycles:

  * **Bi-Monthly (Default)**:
    * Billing Period 1: 1st to 15th → Payout on 18th of same month
    * Billing Period 2: 16th to end of month → Payout on 4th of following month
  * **Weekly**: Available for businesses with higher transaction volumes (contact support to request)
  * **Monthly**:
    * Billing Period: 1st to end of month → Payout on 11th of following month

  Payouts are only initiated if all verifications are successful and the payout threshold is met. It typically takes 1-2 business days for funds to appear in your bank account after the payout is initiated.

  <Note>
    Delays may occur if payout processing dates fall on weekends or bank holidays. The default payout cycle for all businesses is bi-monthly.
  </Note>
</Accordion>

<Accordion title="Q93: What is the minimum threshold amount after fees and taxes to process payouts?">
  A: The minimum payout threshold after platform fees and taxes deduction is:

  * **USD**: \$50

  Payouts are only initiated when the overall wallet balance across all currencies exceeds **\$50 USD**. If your balance doesn't meet the threshold, it will carry forward to the next payout cycle.

  You can customize your USD wallet threshold to any amount of **\$50 or above** directly from your dashboard. You can see the exact wallet amount and manage your payout threshold in the [payouts section](https://app.dodopayments.com/business/payouts) of your dashboard.

  <Note>
    The flexible threshold feature is available for the USD/EUR/GBP wallets. Support for the INR native wallet has been discontinued.
  </Note>
</Accordion>

<Accordion title="Q94: How do I link my bank account to receive payouts?">
  A: To link your bank account, navigate to **Payouts** in your dashboard and click **Add Bank Account**. You'll need to enter your bank details and verify the account.
</Accordion>

<Accordion title="Q95: Can I track the status of my payouts?">
  A: Yes, you can track your payout status from the **Payouts** section of the dashboard.
</Accordion>

<Accordion title="Q96: What are payout fees and how much are they?">
  A: Payout fees are the transaction costs for transferring collected revenue to your bank account.

  * We constantly work to reduce fees by partnering with local partners in your country
  * Separately from our fees, your own bank and any intermediary banks may charge for receiving a cross-border transfer, reducing the amount credited to your account
  * Please refer to the [pricing page](https://dodopayments.com/pricing) for detailed information
</Accordion>

<Accordion title="Q97: I received a &#x22;payout processed&#x22; email — when will the funds arrive?">
  A: Payouts usually take 1–2 business days to reflect in your bank account.

  <Note>
    Transfers don't settle on weekends or bank holidays. If your payout was processed on Friday, expect it by Monday or Tuesday.
  </Note>
</Accordion>

<Accordion title="Q98: How do I add Payoneer as a payout account?">
  A: Just enter your Payoneer bank details in the Bank Info Form under your dashboard. There's no separate Payoneer integration yet.
</Accordion>

<Accordion title="Q99: Can I receive payouts to a Payoneer account?">
  A: Yes. You can receive payouts via Payoneer by:

  * Entering your Payoneer account details in the Bank Info Form on the Dodo dashboard
  * Ensure your account is approved and supports USD or the currency you're withdrawing

  There is no dedicated Payoneer integration — it is treated as a regular bank account.
</Accordion>

<Accordion title="Q100: My bank info is still in review — what should I do?">
  A: No compliance form is required anymore. For bank info review, just wait. Our team typically reviews bank details within 1–2 working days. If it's urgent:

  * Email [support@dodopayments.com](mailto:support@dodopayments.com)
</Accordion>

<Accordion title="Q101: What happens if my payout day falls on a Friday or weekend?">
  A: If your payout day is on a Friday, it is usually processed on the same day. However:

  * If there's a bank holiday or weekend, it may be delayed to the next working day (usually Monday).
  * The exact timing may depend on your bank's processing rules.

  <Note>
    If in doubt, check your dashboard or ask support with your registered email.
  </Note>
</Accordion>

<Accordion title="Q102: How can I expedite payout compliance if I have an urgent launch or ad campaign planned?">
  A: If you've submitted everything and are awaiting payout compliance:

  * Mention your urgency clearly in support chats (e.g., live launch, paid campaigns).
  * Include your business ID and email.
  * Avoid spamming or tagging multiple team members — this may slow down the queue.
</Accordion>

<Accordion title="Q103: I submitted the wrong bank account details. How do I update them?">
  A: Go to the **Payouts** page and open the account under **Linked Bank Accounts**. Accounts placed on hold or marked failed show the reason inline and offer a **resubmit** action, so you can correct the details yourself. You can also add a new payout account and activate it instead.

  <Note>
    If the account is not resubmittable from the dashboard, contact support via Intercom or Mail and the compliance team will reopen the section for you. See [Payout Accounts](/features/payouts/payout-structure#payout-accounts).
  </Note>
</Accordion>

<Accordion title="Q104: Can I use my personal bank account if I have a registered company?">
  A: No. If you're registered as a company or legal entity, you must use the entity's bank account.
</Accordion>

<Accordion title="Q105: My country doesn't use SWIFT codes. How will that affect my verification?">
  A: If your country does not issue SWIFT codes, this will not block your verification.

  What to do:

  * Contact support and explain that your country doesn't issue SWIFT codes
  * Submit official bank documents that confirm:
    * Your account number
    * Account holder name
    * That no SWIFT code is issued in your country
  * In some cases, a generic placeholder SWIFT may be used based on your country

  <Note>
    For faster processing, write to [compliance@dodopayments.com](mailto:compliance@dodopayments.com) for escalation.
  </Note>
</Accordion>

<Accordion title="Q106: What alternative documentation can I provide if my country doesn't use SWIFT codes?">
  A: If your country doesn't use SWIFT codes, provide the following alternative documentation:

  * Official bank statement or certificate showing your account details
  * Bank letter confirming your account number, holder name, and that SWIFT codes are not issued
  * Any government-issued document that confirms your bank's routing information format

  <Tip>
    Contact [support@dodopayments.com](mailto:support@dodopayments.com) before submitting to ensure you provide the correct documentation format for your country.
  </Tip>
</Accordion>

<Accordion title="Q107: Can I set a payout threshold lower than $50?">
  A: No. The minimum payout threshold is **\$50** and cannot be lowered.

  * You **can** increase the threshold above \$50
  * You **cannot** set it below \$50
</Accordion>

<Accordion title="Q108: Do you support daily payouts?">
  A: No, daily payouts are not available. The available payout cycles are bi-monthly (default), weekly (for high-volume businesses), and monthly. See full details: [https://docs.dodopayments.com/features/payouts/payout-structure#payout-cycles](https://docs.dodopayments.com/features/payouts/payout-structure#payout-cycles)
</Accordion>

## Invoicing & Reports

<Accordion title="Q109: Does Dodo Payments generate invoices automatically?">
  A: Yes, Dodo Payments automatically generates **invoices** for every successful transaction. These invoices include all necessary details such as tax breakdowns, customer information, and product details.
</Accordion>

<Accordion title="Q110: Can I customize the invoices?">
  A: Yes, you can customize the look of your invoices by adding your **company logo and brand name.** You can manage these settings in the Business Profile section of your dashboard.
</Accordion>

<Accordion title="Q111: How do I access or download an invoice?">
  A: You can view or download invoices from the **Invoices** section of the dashboard. Each payment will have an associated invoice that can be downloaded as a **PDF**.
</Accordion>

<Accordion title="Q112: How do I view reports on my transactions and payouts?">
  A: You can generate detailed reports from the **Reports** section of your dashboard. These reports include data on transactions, refunds, and payouts, which you can filter by date and export in CSV format.
</Accordion>

## Refunds & Disputes

<Accordion title="Q113: How do I issue a refund?">
  A: To issue a refund, go to the **Payment Details Page** of the transaction you want to refund and click the **Initiate Refund** button. You can issue a **full** or **partial** refund, provided the payment meets the refund eligibility rules.
</Accordion>

<Accordion title="Q114: How long does it take for a customer to receive their refund?">
  A: Once a refund is initiated, the customer will typically receive the refunded amount within **3-5 business days**, depending on the payment method and their bank.
</Accordion>

<Accordion title="Q115: I'm facing a dispute or chargeback. What can I do?">
  A: If a chargeback is filed against you:

  * You may lose both the transaction amount and a dispute fee
  * You can submit evidence of product delivery, usage logs, or customer communication
  * However, the final decision lies with the customer's issuing bank

  <Note>
    Email [support@dodopayments.com](mailto:support@dodopayments.com) with:

    * Dispute ID
    * Payment ID
    * Relevant proof
  </Note>
</Accordion>

<Accordion title="Q116: The customer disputed the charge after using the service. Can I appeal this?">
  A: Yes — you can:

  * Share documentation (chat logs, usage records, delivery confirmation)
  * Explain that the service was fulfilled
  * Request a waiver of the dispute fee if it's a first-time issue or if fraud is provable

  <Tip>
    There's no guarantee the fee will be waived, but our team reviews each case on merit.
  </Tip>
</Accordion>

<Accordion title="Q117: Why is my refund failing with an 'insufficient funds' error?">
  A: Refunds are checked against your available account balance, not your scheduled payout amount. If payouts are already scheduled, that amount is not counted as available. If your available balance is too low, the refund will fail. Wait for your next payout cycle to build up balance, or contact support.
</Accordion>

## Webhooks & Integration

<Accordion title="Q118: How is proration calculated — on the product price or the total amount?">
  A: Proration is calculated on the **total amount paid**, not just the base product price.
  This means if a discount is applied, the proration is calculated on the **final amount after the discount**.
</Accordion>

<Accordion title="Q119: Why do we use the `subscription.renewed` webhook for the first subscription?">
  A: After the first payment succeeds, the subscription enters its first billing period and the next billing date is set.
  The `subscription.renewed` webhook is sent to indicate that a billing period is now active and the next billing cycle has been scheduled.
  This webhook is used for every billing period—including the first one—so billing logic can be handled consistently each time.
</Accordion>

<Accordion title="Q120: Can I manually verify Dodo Payments webhooks in Python?">
  A: Yes. Manual verification is possible, but it must strictly follow the correct signing steps. For an easier and more reliable approach, Dodo Payments recommends using the standardwebhooks package:

  ```python theme={null}
  from standardwebhooks.webhooks import Webhook

  wh = Webhook(webhook_secret_key)
  payload = request.get_data(as_text=True)
  headers = request.headers

  if not wh.verify(payload, headers):
      return jsonify({'error': 'Invalid webhook signature'}), 401

  Then parse the payload as needed.
  ```
</Accordion>

<Accordion title="Q121: Where can I find official docs on manual webhook verification?">
  A: You can refer to the official Dodo Payments documentation here: [https://docs.dodopayments.com/developer-resources/webhooks#manual-verification-alternative](https://docs.dodopayments.com/developer-resources/webhooks#manual-verification-alternative)
</Accordion>

<Accordion title="Q122: My webhook isn't receiving a POST request, only a GET. Why?">
  A: You're likely confusing the redirect URL with the webhook URL. A redirect URL is where the user is sent after a payment, and it may contain `?subscription_id=...&status=active` in a GET request. This is not your webhook.

  To receive structured POST payloads from Dodo Payments:

  * Set up a webhook under Dashboard → Developers → Webhooks
  * Ensure the URL accepts POST requests and verifies the signature

  <Note>
    You can have both a webhook and a redirect URL — they serve different purposes.
  </Note>
</Accordion>

<Accordion title="Q123: I get a 401 Unauthorized error using the Python SDK. Why?">
  A: You likely forgot to pass the correct environment when initializing the DodoPayments client.

  <Check>
    **Fix:**

    ```python theme={null}
    client = DodoPayments(
    bearer_token="your_api_key",
          environment="live_mode"  # or "test_mode"
    )
    ```
  </Check>
</Accordion>

<Accordion title="Q124: Is there a way to manually trigger a webhook event for testing?">
  A: You can do it through the webhook dashboard. Go to Dashboard -> Developers -> Webhooks
</Accordion>

<Accordion title="Q125: What's the difference between webhook and redirect URL?">
  A:

  * **Webhook URL**: Configured in dashboard. Receives POST payloads about events.
  * **Redirect URL**: Sent in the payment API request. Sends user back to your app with query params (`?status=success`).

  <Tip>
    Use webhooks to automate things like DB updates, and redirects to show thank-you screens.
  </Tip>
</Accordion>

<Accordion title="Q126: Why didn't I receive the product id in the payment.succeeded webhook for a subscription product?">
  A: The payment.succeeded webhook event for subscription products does not include a product\_id. Instead, it provides the `subscription_id` associated with the subscription, along with other relevant details.
</Accordion>

<Accordion title="Q127: How do I verify the webhooks I receive are actually from dodo payments and not from any malicious actors?">
  A: To verify webhook authenticity, follow these steps:

  1. **Check the Signature**: Each webhook includes a unique signature in the `webhook-signature` header, generated using your secret key and the payload
  2. **Retrieve the Secret Key**: Found in your Dodo Payments dashboard under Webhooks settings
  3. **Recompute the Signature**: Use HMAC-SHA256 with your webhook secret key and the payload
  4. **Compare Signatures**: If they match, the webhook is authentic; if not, reject it
  5. **Use HTTPS**: Ensure your endpoint uses HTTPS to prevent tampering during transmission

  <Tip>
    We recommend using packages provided by StandardWebhooks to verify the signature rather than constructing it yourself.
  </Tip>
</Accordion>

<Accordion title="Q128: Why am I receiving a subscription.renewed webhook even for the first month payment?">
  A: For subscriptions, `subscription.renewed` will be triggered whenever the subscription amount is deducted. So yes, this is expected behavior.
</Accordion>

<Accordion title="Q129: How can I test webhooks locally?">
  A: To test webhooks locally, you can follow these steps:

  1. **Use a Tunneling Tool**: Tools like [ngrok](https://ngrok.com/), [LocalTunnel](https://localtunnel.github.io/www/), or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/) can expose your local server to the internet. This provides a public URL that Dodo Payments can use to send webhook events to your local environment.
  2. **Set Up the Webhook Endpoint**: Create a webhook endpoint in your local application to handle incoming webhook events. Ensure it listens for HTTP POST requests.
  3. **Configure the Webhook in Dodo Payments**: Go to your Dodo Payments dashboard, navigate to the Webhooks settings, and update the webhook URL to the public URL generated by the tunneling tool.
</Accordion>

<Accordion title="Q130: Why is my webhook not being called after payment?">
  A: Check the following:

  * You did not confuse the webhook URL with redirect URL
  * The webhook is configured under Developers > Webhooks
  * Your URL accepts POST requests and responds with 2xx
  * Signature validation (if enabled) is implemented correctly

  If you only see GETs with ?status=success, you are debugging the redirect URL, not the webhook.
</Accordion>

<Accordion title="Q131: Is it safe to rely on status=success in URL query params?">
  A: No. While it's a quick win, URL query params can be tampered with.

  If you're using `return_url?status=success`:

  * Double-validate the transaction with an API call
  * Or wait for payment.succeeded webhook

  <Tip>
    Treat redirects as user-facing confirmations, not proof of payment.
  </Tip>
</Accordion>

<Accordion title="Q132: Can I integrate Dodo Payments with my existing website or platform?">
  A: Yes, Dodo Payments offers **API integration** and **SDKs support** for seamless integration with your website or platform. You can find API documentation, SDK guides, and integration resources in the **Developer Section** of your dashboard.
</Accordion>

<Accordion title="Q133: Why are my webhooks always failing?">
  A: Common causes:

  * Your endpoint is unreachable or returning a non-2xx status code
  * The endpoint is timing out before responding
  * The webhook URL in your dashboard is incorrect

  Ensure your endpoint is publicly accessible, returns a 200 promptly, and the URL is correctly configured in the Dodo Payments dashboard.

  <img alt="Webhook failed attempts" />
</Accordion>

<Accordion title="Q134: Where do I find my API key?">
  A: Go to Dashboard → Developer tab → API Keys section. Make sure you're in the correct mode (Test or Live) before copying the key.
</Accordion>

<Accordion title="Q135: What are the base URLs for the Dodo Payments API?">
  A: - **Live Mode:** [https://live.dodopayments.com](https://live.dodopayments.com)

  * **Test Mode:** [https://test.dodopayments.com](https://test.dodopayments.com)
</Accordion>

## Testing & Local Development

<Accordion title="Q136: Can I test subscriptions in Test Mode?">
  A: Yes — subscriptions can be tested fully in Test Mode.

  Just don't use real card numbers.
</Accordion>

<Accordion title="Q137: How do I switch between Test and Live Mode?">
  A:

  * On your Dodo dashboard, look for a Test Mode toggle.
  * Switch it ON to use test API keys and simulate payments.

  You'll see "Test Mode" labels on all screens. Make sure to use the corresponding API key or environment when switching.
</Accordion>

<Accordion title="Q138: Can I use real customer data in Test Mode?">
  A: Yes, but keep in mind:

  * No real money will be transferred
  * You can simulate webhooks and flows
  * Card details should still be test cards

  This helps debug flows end-to-end without any financial impact.
</Accordion>

<Accordion title="Q139: Can I advance the next billing date in test mode?">
  A: Yes. Use the Update Subscription API and set the next\_billing\_date field to the date you want. See the docs: [https://docs.dodopayments.com/api-reference/subscriptions/patch-subscriptions#body-next-billing-date-one-of-0](https://docs.dodopayments.com/api-reference/subscriptions/patch-subscriptions#body-next-billing-date-one-of-0)
</Accordion>

<Accordion title="Q140: Why don't I receive emails in Test Mode?">
  A: In Test Mode, emails are **not sent** to simulate a development environment without real notifications.

  **What this means:**

  * No license keys will be generated or shared via email
  * Customer transactional emails will not be sent
  * Webhook events will still be triggered for testing

  <Tip>
    To test the complete email flow including license key generation, you can test in Live Mode using a **100% discount code**. This allows you to complete the full payment flow without being charged while receiving all transactional emails.
  </Tip>
</Accordion>

## Support & Communication

<Accordion title="Q141: How do I contact support?">
  A: You can contact our support team by sending an email to [**support@dodopayments.com**](mailto:support@dodopayments.com). We are here to assist you with any issues or questions you may have.
</Accordion>

<Accordion title="Q142: My support messages are getting no response. What should I do?">
  A: If you've messaged in:

  * Intercom with no response
  * Discord without acknowledgement

  Then:

  * Escalate via [compliance@dodopayments.com](mailto:compliance@dodopayments.com) or [support@dodopayments.com](mailto:support@dodopayments.com) with subject line Urgent: No Response – \[Your Email]
</Accordion>

<Accordion title="Q143: How do I unsubscribe a customer from Dodo Digest emails?">
  A: Share the customer's email address with us via Intercom and we'll unsubscribe them from our end.
</Accordion>

## Security & Fraud Prevention

<Accordion title="Q144: How does Dodo Payments protect my business from fraud?">
  A: Dodo Payments uses **real-time fraud detection** to monitor suspicious transactions. We also comply with **PCI-DSS standards** to ensure that all payment information is encrypted and secure.
</Accordion>

<Accordion title="Q145: Is my customer data secure with Dodo Payments?">
  A: Yes, Dodo Payments uses **data encryption** and **tokenization** to protect sensitive information. We ensure that customer payment data is never stored directly and remains secure during transactions.
</Accordion>

<Accordion title="Q146: I found a security vulnerability in Dodo Payments. How should I report it?">
  A: Please report any discovered vulnerabilities directly to our security team at [pt-team@dodopayments.com](mailto:pt-team@dodopayments.com)
</Accordion>

<Accordion title="Q147: Does Dodo Payments offer bug bounties?">
  A: We currently do not offer monetary bounties, but we do provide Dodo Payments merchandise as a token of appreciation.
</Accordion>

<Accordion title="Q148: How are customers protected from fraud on Dodo Payments?">
  A: Dodo Payments uses real-time fraud detection to analyze and block suspicious transactions before they occur. All payments are also protected through standard card network safeguards — customers can raise disputes or chargebacks for unauthorized charges. We are PCI compliant, ensuring all payment data meets the highest security standards.
</Accordion>

## Payments Failures

<Accordion title="Q149: Why is my payment status showing 'Not Initiated'?">
  A: This means the payment link was created, but the user never opened the payment page or attempted the payment.
</Accordion>

<Accordion title="Q150: Why is my payment status showing 'Requires Payment Method'?">
  A: This means the user opened the payment page and entered customer details but exited before adding card or payment details.
</Accordion>

<Accordion title="Q151: Why am I getting an 'Invalid authorization details' error?">
  A: This usually happens when the 3D Secure (3DS) authentication fails or is not completed by the user.
</Accordion>

<Accordion title="Q152: Why am I getting an 'Authentication failure' error for payments?">
  A: The payment failed due to an authentication error. Please check with your bank regarding this issue. Unfortunately, there is nothing further we can do from our side. We recommend trying a different card or a different payment method.
</Accordion>

<Accordion title="Q153: I'm seeing a 500 INTERNAL_SERVER_ERROR (&#x22;Internal Server Error&#x22;) in test mode. How do I fix it?">
  A: This typically happens when the test card does not match the billing country:

  * **US billing country** → Use a US test card
  * **India billing country** → Use an INR test card

  Refer to the [test card numbers documentation](https://docs.dodopayments.com/miscellaneous/testing-process#test-card-numbers).
</Accordion>

<Accordion title="Q154: Why am I getting PAYMENT_METHOD_UNSUPPORTED (&#x22;mode not enabled for merchant&#x22;) in test mode?">
  A: The selected payment method is not enabled for your merchant account. Ensure you are using the correct test card for your billing country:

  * **US billing country** → Use a US test card
  * **India billing country** → Use an INR test card

  Refer to the [test card numbers documentation](https://docs.dodopayments.com/miscellaneous/testing-process#test-card-numbers).
</Accordion>

<Accordion title="Q155: What does the requires_customer_action status mean?">
  A: The payment requires additional action from the customer — such as 3D Secure authentication, OTP verification, or UPI approval. The customer must complete the required action before the payment can be processed.
</Accordion>

<Accordion title="Q156: Why am I getting a SUBSCRIPTION_NOT_ACTIVE error?">
  A: This error occurs when the customer has cancelled the mandate (recurring payment authorization) from their UPI app. The subscription can no longer process payments because the underlying mandate has been revoked by the customer.
</Accordion>

<Accordion title="Q157: Why am I getting a payment failure with UNKNOWN_ERROR?">
  A: Your payment failed with error code `UNKNOWN_ERROR`. The payment was initially processed, but your bank later reversed the transaction and refunded the amount, so it was marked as failed. This issue is not from our side.

  Please try making the payment again. If it fails again, try using a different card or payment method. You may also contact your bank for further clarification.
</Accordion>

<Accordion title="Q158: I'm getting: &#x22;You must provide a mandate for off-session card payments&#x22;">
  A: It means:

  * An Indian Card is used to make the payment but the billing country is not set as IN.
  * You likely passed an incorrect billing country.
</Accordion>

## Developer & Technical Integration

<Accordion title="Q159: Is the customer portal tied to a specific customer?">
  A: Yes. The portal is customer-specific. You can either send a magic link for a specific customer (one-time, expires in 24 hours) or use the static email login where the customer enters their purchase email to get a secure link. When you create a portal session via API (customerPortal.create('cus\_123')), it's bound to that customer.
</Accordion>

<Accordion title="Q160: Can I use Laravel with Dodo Payments?">
  A: Yes, Laravel is supported. See the PHP/Laravel SDK docs: [https://docs.dodopayments.com/developer-resources/sdks/php#laravel](https://docs.dodopayments.com/developer-resources/sdks/php#laravel)
</Accordion>

<Accordion title="Q161: Does Dodo Payments support WHMCS?">
  A: WHMCS is not officially supported. You can either build a custom payment module using our API (payments + webhooks), or use Dodo checkout links in invoices as a temporary workaround.
</Accordion>

<Accordion title="Q162: Can I integrate Dodo Payments in an Android or mobile app?">
  A: Yes. Refer to the mobile integration guide: [https://docs.dodopayments.com/developer-resources/mobile-integration#mobile-integration-guide](https://docs.dodopayments.com/developer-resources/mobile-integration#mobile-integration-guide)

  You can also use the Sentra VS Code extension for integration assistance: [https://docs.dodopayments.com/developer-resources/sentra#sentra](https://docs.dodopayments.com/developer-resources/sentra#sentra)
</Accordion>

<Accordion title="Q163: How do I find my live publishable key (pk_live_...)?">
  A: Switch to Live Mode in the dashboard. Go to the Developer section → click Other → you'll see the Publishable Key. Click View to reveal it.
</Accordion>

<Accordion title="Q164: Does Dodo Payments support WooCommerce blocks (WordPress block editor)?">
  A: Not currently. The WooCommerce plugin is open source — if you'd like this feature, you're welcome to raise a pull request to implement it.
</Accordion>


# Help and Support
Source: https://docs.dodopayments.com/miscellaneous/help-support

We understand that navigating a new platform or resolving issues can sometimes require additional support. To ensure a seamless experience, we offer multiple support channels to address all your concerns.

## **Dodo Payments Centralized Support System**

The Dodo Payments Centralized Support System provides a unified support experience, offering multiple channels to assist merchants.

Merchants can access the support system through the "Get Support" icon on the Dodo Payments Dashboard, leading to a dedicated support landing page with four key options:

## 1. AI-Powered Chat Assistance

The Chat with AI feature provides instant, automated support using an AI-powered chatbot. It is designed to assist users by:

* Answering technical and business queries
* Providing guidance on API integration and setup
* Offering navigation support for product documentation

This feature ensures quick resolution of common queries, reducing the need for direct human support.

📌 Best for: Instant self-serve assistance and general troubleshooting.

## 2. Community Support via Discord

The Dodo Payments Discord Community enables merchants to engage with other users and the Dodo Payments team. Through this platform, users can:

* Discuss best practices and share experiences
* Seek peer-to-peer assistance from other merchants
* Engage with the Dodo Payments support team in an interactive environment

This feature fosters a collaborative community-driven support experience.

📌 Best for: Peer support, longer queries and networking with other merchants.

## 3. Dedicated Chat Support

The Chat Support feature provides a direct line to the Dodo Payments support team for more complex or account-specific inquiries. Key aspects include:

* Support is managed via Intercom, where merchants can submit detailed queries.
* Response time is within 24-48 business hours.
* Unresolved tickets will automatically close if there is no user response for 72 hours.

This feature ensures that merchants receive personalized assistance for critical issues requiring human intervention.

📌 Best for: Account-related concerns, technical escalations, and personalized troubleshooting.

## **4. Self-Service Documentation**

The Dodo Payments Documentation Portal serves as a comprehensive resource for merchants looking for detailed product and integration information. The portal includes:

* Detailed feature explanations
* Step-by-step implementation guides
* API documentation and integration manuals
* Frequently Asked Questions (FAQs)

This feature provides structured, self-paced learning for merchants to independently navigate the platform.

📌 Best for: In-depth learning, implementation guidance, and technical documentation.

## **Support Options Overview**

| **Support Channel**   | **Purpose**                                 | **Response Time** |
| --------------------- | ------------------------------------------- | ----------------- |
| **AI-Powered Chat**   | Automated responses, documentation guidance | Instant           |
| **Discord Community** | Peer support, community discussions         | Community-driven  |
| **Chat Support**      | Personalized assistance for complex issues  | 24-48 hours       |
| **Self-Service Docs** | Product guides, API reference, tutorials    | Self-paced        |

Merchants can choose the most suitable support channel based on the complexity of their query and the required response time. For further assistance, visit the Dodo Payments Support Center via the dashboard.


# Countries Eligible for Payment Acceptance
Source: https://docs.dodopayments.com/miscellaneous/list-of-countries-we-accept-payments-from

The list below includes the countries from which we accept payments for our SaaS and digital products.

| #   | ISO Code | Country Name                                 |
| --- | -------- | -------------------------------------------- |
| 1   | AD       | Andorra                                      |
| 2   | AE       | United Arab Emirates                         |
| 3   | AG       | Antigua and Barbuda                          |
| 4   | AI       | Anguilla                                     |
| 5   | AL       | Albania                                      |
| 6   | AM       | Armenia                                      |
| 7   | AO       | Angola                                       |
| 8   | AR       | Argentina                                    |
| 9   | AS       | American Samoa                               |
| 10  | AT       | Austria                                      |
| 11  | AU       | Australia                                    |
| 12  | AW       | Aruba                                        |
| 13  | AX       | Åland Islands                                |
| 14  | AZ       | Azerbaijan                                   |
| 15  | BA       | Bosnia and Herzegovina                       |
| 16  | BB       | Barbados                                     |
| 17  | BD       | Bangladesh                                   |
| 18  | BE       | Belgium                                      |
| 19  | BF       | Burkina Faso                                 |
| 20  | BG       | Bulgaria                                     |
| 21  | BH       | Bahrain                                      |
| 22  | BI       | Burundi                                      |
| 23  | BJ       | Benin                                        |
| 24  | BL       | Saint Barthélemy                             |
| 25  | BM       | Bermuda                                      |
| 26  | BN       | Brunei Darussalam                            |
| 27  | BO       | Bolivia                                      |
| 28  | BQ       | Caribbean Netherlands                        |
| 29  | BR       | Brazil                                       |
| 30  | BS       | Bahamas                                      |
| 31  | BT       | Bhutan                                       |
| 32  | BV       | Bouvet Island                                |
| 33  | BW       | Botswana                                     |
| 34  | BZ       | Belize                                       |
| 35  | CA       | Canada                                       |
| 36  | CC       | Cocos (Keeling) Islands                      |
| 37  | CG       | Republic of the Congo                        |
| 38  | CH       | Switzerland                                  |
| 39  | CI       | Côte d'Ivoire                                |
| 40  | CK       | Cook Islands                                 |
| 41  | CL       | Chile                                        |
| 42  | CM       | Cameroon                                     |
| 43  | CN       | China                                        |
| 44  | CO       | Colombia                                     |
| 45  | CR       | Costa Rica                                   |
| 46  | CV       | Cape Verde                                   |
| 47  | CW       | Curaçao                                      |
| 48  | CX       | Christmas Island                             |
| 49  | CY       | Cyprus                                       |
| 50  | CZ       | Czech Republic                               |
| 51  | DE       | Germany                                      |
| 52  | DJ       | Djibouti                                     |
| 53  | DK       | Denmark                                      |
| 54  | DM       | Dominica                                     |
| 55  | DO       | Dominican Republic                           |
| 56  | DZ       | Algeria                                      |
| 57  | EC       | Ecuador                                      |
| 58  | EE       | Estonia                                      |
| 59  | EG       | Egypt                                        |
| 60  | EH       | Western Sahara                               |
| 61  | ER       | Eritrea                                      |
| 62  | ES       | Spain                                        |
| 63  | ET       | Ethiopia                                     |
| 64  | FI       | Finland                                      |
| 65  | FJ       | Fiji                                         |
| 66  | FK       | Falkland Islands                             |
| 67  | FM       | Micronesia                                   |
| 68  | FO       | Faroe Islands                                |
| 69  | FR       | France                                       |
| 70  | GA       | Gabon                                        |
| 71  | GB       | United Kingdom                               |
| 72  | GD       | Grenada                                      |
| 73  | GE       | Georgia                                      |
| 74  | GF       | French Guiana                                |
| 75  | GG       | Guernsey                                     |
| 76  | GH       | Ghana                                        |
| 77  | GI       | Gibraltar                                    |
| 78  | GL       | Greenland                                    |
| 79  | GM       | Gambia                                       |
| 80  | GN       | Guinea                                       |
| 81  | GP       | Guadeloupe                                   |
| 82  | GQ       | Equatorial Guinea                            |
| 83  | GR       | Greece                                       |
| 84  | GS       | South Georgia and the South Sandwich Islands |
| 85  | GT       | Guatemala                                    |
| 86  | GU       | Guam                                         |
| 87  | GW       | Guinea-Bissau                                |
| 88  | GY       | Guyana                                       |
| 89  | HK       | Hong Kong                                    |
| 90  | HM       | Heard Island and McDonald Islands            |
| 91  | HN       | Honduras                                     |
| 92  | HR       | Croatia                                      |
| 93  | HU       | Hungary                                      |
| 94  | ID       | Indonesia                                    |
| 95  | IE       | Ireland                                      |
| 96  | IL       | Israel                                       |
| 97  | IM       | Isle of Man                                  |
| 98  | IN       | India                                        |
| 99  | IO       | British Indian Ocean Territory               |
| 100 | IQ       | Iraq                                         |
| 101 | IS       | Iceland                                      |
| 102 | IT       | Italy                                        |
| 103 | JE       | Jersey                                       |
| 104 | JM       | Jamaica                                      |
| 105 | JO       | Jordan                                       |
| 106 | JP       | Japan                                        |
| 107 | KE       | Kenya                                        |
| 108 | KG       | Kyrgyzstan                                   |
| 109 | KH       | Cambodia                                     |
| 110 | KI       | Kiribati                                     |
| 111 | KM       | Comoros                                      |
| 112 | KN       | Saint Kitts and Nevis                        |
| 113 | KR       | South Korea                                  |
| 114 | KW       | Kuwait                                       |
| 115 | KY       | Cayman Islands                               |
| 116 | KZ       | Kazakhstan                                   |
| 117 | LA       | Laos                                         |
| 118 | LB       | Lebanon                                      |
| 119 | LC       | Saint Lucia                                  |
| 120 | LI       | Liechtenstein                                |
| 121 | LK       | Sri Lanka                                    |
| 122 | LR       | Liberia                                      |
| 123 | LS       | Lesotho                                      |
| 124 | LT       | Lithuania                                    |
| 125 | LU       | Luxembourg                                   |
| 126 | LV       | Latvia                                       |
| 127 | MA       | Morocco                                      |
| 128 | MC       | Monaco                                       |
| 129 | ME       | Montenegro                                   |
| 130 | MF       | Saint Martin                                 |
| 131 | MG       | Madagascar                                   |
| 132 | MH       | Marshall Islands                             |
| 133 | MK       | North Macedonia                              |
| 134 | MP       | Northern Mariana Islands                     |
| 135 | MQ       | Martinique                                   |
| 136 | MR       | Mauritania                                   |
| 137 | MS       | Montserrat                                   |
| 138 | MT       | Malta                                        |
| 139 | MU       | Mauritius                                    |
| 140 | MV       | Maldives                                     |
| 141 | MW       | Malawi                                       |
| 142 | MX       | Mexico                                       |
| 143 | MY       | Malaysia                                     |
| 144 | MZ       | Mozambique                                   |
| 145 | MN       | Mongolia                                     |
| 146 | MO       | Macau                                        |
| 147 | NA       | Namibia                                      |
| 148 | NC       | New Caledonia                                |
| 149 | NE       | Niger                                        |
| 150 | NF       | Norfolk Island                               |
| 151 | NG       | Nigeria                                      |
| 152 | NI       | Nicaragua                                    |
| 153 | NL       | Netherlands                                  |
| 154 | NO       | Norway                                       |
| 155 | NP       | Nepal                                        |
| 156 | NR       | Nauru                                        |
| 157 | NU       | Niue                                         |
| 158 | NZ       | New Zealand                                  |
| 159 | OM       | Oman                                         |
| 160 | PA       | Panama                                       |
| 161 | PE       | Peru                                         |
| 162 | PF       | French Polynesia                             |
| 163 | PG       | Papua New Guinea                             |
| 164 | PH       | Philippines                                  |
| 165 | PK       | Pakistan                                     |
| 166 | PL       | Poland                                       |
| 167 | PM       | Saint Pierre and Miquelon                    |
| 168 | PN       | Pitcairn Islands                             |
| 169 | PR       | Puerto Rico                                  |
| 170 | PT       | Portugal                                     |
| 171 | PW       | Palau                                        |
| 172 | PY       | Paraguay                                     |
| 173 | QA       | Qatar                                        |
| 174 | RE       | Réunion                                      |
| 175 | RO       | Romania                                      |
| 176 | RS       | Serbia                                       |
| 177 | RW       | Rwanda                                       |
| 178 | SA       | Saudi Arabia                                 |
| 179 | SB       | Solomon Islands                              |
| 180 | SC       | Seychelles                                   |
| 181 | SE       | Sweden                                       |
| 182 | SG       | Singapore                                    |
| 183 | SH       | Saint Helena                                 |
| 184 | SI       | Slovenia                                     |
| 185 | SJ       | Svalbard and Jan Mayen                       |
| 186 | SK       | Slovakia                                     |
| 187 | SL       | Sierra Leone                                 |
| 188 | SM       | San Marino                                   |
| 189 | SN       | Senegal                                      |
| 190 | SR       | Suriname                                     |
| 191 | ST       | São Tomé and Príncipe                        |
| 192 | SV       | El Salvador                                  |
| 193 | SX       | Sint Maarten                                 |
| 194 | SZ       | Eswatini                                     |
| 195 | TC       | Turks and Caicos Islands                     |
| 196 | TD       | Chad                                         |
| 197 | TF       | French Southern Territories                  |
| 198 | TG       | Togo                                         |
| 199 | TH       | Thailand                                     |
| 200 | TJ       | Tajikistan                                   |
| 201 | TK       | Tokelau                                      |
| 202 | TL       | Timor-Leste                                  |
| 203 | TM       | Turkmenistan                                 |
| 204 | TN       | Tunisia                                      |
| 205 | TO       | Tonga                                        |
| 206 | TR       | Turkey                                       |
| 207 | TT       | Trinidad and Tobago                          |
| 208 | TV       | Tuvalu                                       |
| 209 | TW       | Taiwan                                       |
| 210 | TZ       | Tanzania                                     |
| 211 | UG       | Uganda                                       |
| 212 | UM       | United States Minor Outlying Islands         |
| 213 | US       | United States                                |
| 214 | UY       | Uruguay                                      |
| 215 | UZ       | Uzbekistan                                   |
| 216 | VA       | Vatican City                                 |
| 217 | VC       | Saint Vincent and the Grenadines             |
| 218 | VG       | British Virgin Islands                       |
| 219 | VI       | U.S. Virgin Islands                          |
| 220 | VN       | Vietnam                                      |
| 221 | VU       | Vanuatu                                      |
| 222 | WF       | Wallis and Futuna                            |
| 223 | WS       | Samoa                                        |
| 224 | YT       | Mayotte                                      |
| 225 | ZA       | South Africa                                 |
| 226 | ZM       | Zambia                                       |

<Tip>
  You can only accept payments from the 226 countries listed above. We regularly update this list as we expand support to more countries.
</Tip>


# Merchant Acceptance Policy
Source: https://docs.dodopayments.com/miscellaneous/merchant-acceptance

This policy will help you understand the types of businesses we support, the types we restrict or prohibit, and how we enforce our standards.

## Introduction

Dodo Payments operates as a Merchant of Record (MoR), providing an all-in-one platform for digital businesses for merchants by acting as their official reseller. As MoR, Dodo Payments assumes responsibility for payment processing, tax compliance, and chargeback handling. To protect the integrity of our platform and our global partnerships, we maintain strict standards for the products we resell on our platform.

This policy outlines the kinds of businesses we support, the types we restrict or prohibit, and how we enforce our standards. It is intended to help builders understand how to align with our platform requirements from the start.

## Businesses We Love!

We're excited to support legit builders creating digital-first products that are valuable, trustworthy, and easy to deliver. In general, we welcome:

1. SaaS & AI products
2. Digital goods
3. Templates, Plugins & Apps

<Note>
  We assess "value" based on what a customer actually gets and experiences after they buy the product. In general, we're excited about products that do what they promise, are genuinely useful, and feel worth the price to a reasonable customer. Clear functionality, honest descriptions, and a solid end-user experience go a long way.

  On the flip side, products that rely mostly on hype, vague claims, artificial urgency, or heavily repackaged free content create poor customer experiences. If something feels designed to extract payment rather than solve a real problem, we may take a closer look or decide not to support it.

  Our goal here isn't to police creativity, but to ensure our customers walk away feeling safe and satisfied, not misled. We want to back builders who care about what they're putting into the world. If you're ever unsure whether your product fits, please feel free to reach out! We're always happy to talk it through.
</Note>

## What We Look For

If your product is digital, delivered easily, and meets these qualities, we'd love to work with you:

* **Legally Compliant:** Your product complies with relevant laws (like consumer protection and data privacy) in the regions you operate.
* **Honest and Helpful:** We appreciate products that provide real value to users - things that are helpful, not deceptive or exploitative.
* **Community-friendly:** Products should adhere to our policies and ensure a smooth experience for everyone.

## Businesses We Can't Support

<Warning>
  This is not an exhaustive list. Dodo Payments reserves the right to update or enforce this policy at any time. We may place your account under review or suspend it immediately if we determine your business model is deceptive, harmful, high-risk, generates excessive refunds or chargebacks, or has been flagged by our payment partners.
</Warning>

As your MoR, we're legally and reputationally responsible for what's being sold through our platform. That means we must stay clear of anything that's:

1. **NSFW, Intimacy & Adult content or services** – This includes explicit or suggestive content whether real or AI-generated (e.g., OnlyFans-style platforms, NSFW chatbots, webcam streams, erotic games, sex toys, escort-style services).
2. **Manual Digital Services** – Selling non-automated services via digital platforms. So, selling custom design, development, coaching, freelancing or consulting services via digital platforms isn't allowed. In essence, if the majority of the value sits in the human labour rather than digital systems, it will not be accepted.
3. **Digital products with limited or unclear value** – For example, AI-generated PDFs with little value, thin templates marked up heavily, or clearly unfinished websites sold at premium prices which may lead to customer dissatisfaction. This also includes placeholder or pre-launch offerings such as holding pages, teaser sites, waitlists, or "coming soon" products that do not provide immediate, usable value after purchase.
4. **Physical goods** – We only support digital delivery. Physical goods include merchandise packaged with digital bundles. No T-shirts, mugs, books, supplements, or computer hardware. In-person services: Any service that is delivered in person, even if booking or payment happens online. So no personal training, coaching delivered physically, beauty treatments, repair or maintenance work performed at the customer's location, etc.
5. **Illegal or age-restricted** – Including but not limited to drugs, alcohol, tobacco, vapes, prescription medicines, or content that violates local laws in any region you're targeting.
6. **Restricted by payment and compliance partners** – Some business types may be subject to restrictions under the policies of our payment and compliance partners. If our financial and regulatory partners restrict certain categories, we cannot provide our support.
7. **Financial products, services & advice** – We can't support unlicensed financial tools, investment strategies, wealth-building courses, tax calculators, banking services, escrow services or anything involving stored value, lending, or managing funds.
8. **Official registration or incorporation services** – Services that process or facilitate company registration, government filings, licences, permits, or any other statutory/legal registrations.
9. **Tax Evasion, Shell Entities, or Regulatory Arbitrage** – We can't support products, services, or setups designed to evade taxes, mask ownership, or bypass financial or legal regulations—this includes using fake business entities, misleading jurisdictions, or "gray market" setups.
10. **Legal, accounting, medical, and professional services** – This includes any services that require licensing, certification or regulatory compliance. Examples include advisory work, diagnosis or treatment, document preparation, representation, financial or tax planning, or any expertise-based service that carries regulatory or liability risk.
11. **Travel, Immigration & Visa services** – This includes bookings for commercial airlines, cruises, charter or private flights, and timeshare offerings. Services that offer handling or facilitating Visa or citizenships.
12. **Health & wellness products** – Including diagnostics, weight-loss programs, supplements, or biohacking kits. This entire class of products is incompatible with our MoR obligations even if well-intentioned, or honestly marketed.
13. **Miracle, Misleading, or Unverifiable Claims** – No products making exaggerated or unverifiable claims – e.g., "cures cancer," "reverses aging," "burns fat while you sleep," "make money while you sleep."
14. **Social matching and interaction services** – This includes platforms for real-time person-to-person interactions, similar to random video- or chat-matching services, matchmaking services, dating platforms, AI-generated relationship companions.
15. **Religious or spiritual product or services** – This includes offerings of spiritual guidance, paid prayers, rituals, faith-based counselling, or similar services where users are paying for religious or spiritual interaction or access to a religious or spiritual authority.
16. **Gambling & games of chance** – Including casinos, lotteries, betting, sweepstakes, fantasy sports for cash prizes, or chance-based reward mechanics (such as loot boxes or spins).
17. **Gaming and virtual-goods environments** – This includes games of skill, online games, video games, in-game currencies, digital item sales, game boosters, or private servers - whether official or unofficial.
18. **Virtual asset services** – Crypto-related offerings, Digital wallets, NFTs, DeFi, crypto exchanges, or token launches aren't permitted.
19. **Piracy or IP violations** – Selling things you didn't create or license (e.g., pirated books, software licenses, copy-paste code packs, unauthorized media downloads).
20. **IPTV and streaming access services** – This includes IPTV subscriptions, reseller panels, or tools that provide access to third-party streaming content.
21. **Software resale or license flipping** – Including selling software licenses at a discount, or reselling AI APIs, datasets, or tools without clear rights or authorisation.
22. **Privacy Violations & Surveillance Tech** – We don't allow products that violate user privacy or enable unauthorized surveillance – this includes stalkerware, keyloggers, location tracking without consent, facial recognition tech, face-swap features or tools that scrape or collect personal data without a clear legal basis.
23. **Hosting, servers, and infrastructure services** – This includes VPN, VPS or dedicated servers, hosting plans, cloud compute credits, bandwidth reselling, or any product that provides users with persistent infrastructure or server-level access.
24. **Telecommunication services** – This includes services that offer call SPI, telecom routing, global calling to PSTN, SIM cards, e-SIMs, VoIP services, call/SMS termination, or related telecom operations (licensed or unlicensed).
25. **Spam, mass outreach or scraping tools** – Data privacy violations, including lead scraping, mass outreach or spam tools, and sensitive private information databases.
26. **Proxy, cloaking, or anti-terms tools** – Anything that helps users bypass API rate limits, captcha or authentication limits, platform terms, or geolocation restrictions.
27. **Cheating & manipulation tools** – That means hacks, mods, bots, engagement manipulation, fake reviews, or tools for bypassing platform restrictions, gameplay or API limits.
28. **Donations** – If you're collecting money without delivering something in return, for general support of your platform, we likely can't process it.
29. **Fundraising** – We don't support charity or NGO drives, political or religious donations, personal fundraisers, crowdfunding campaigns, and any contribution-based model without a defined product or service.
30. **Marketplaces, resale model** – If you're selling on behalf of others, operating a multi-vendor platform, or taking funds and forwarding them elsewhere, selling gift or other benefit cards, that's not supported under our MoR structure.
31. **Ticketing & bookings services** – Services that facilitate the sale, resale, or booking of tickets, reservations, or access to events, travel, accommodations.
32. **Weapons, Self-Defense & Violence-Oriented Content** – We don't allow content promoting weapons, combat training, DIY explosives, self-defense tools, or any content that glorifies violence or incites harm.

<Tip>
  Even if your business isn't listed above, we may still decline to work with you if we believe it poses legal, financial, or reputational risk. This includes high refunds / chargebacks, low-effort, or exploitative offerings. We assess you holistically and reserve the right to refuse or revoke access at our discretion.
</Tip>

## When in Doubt…

If your product is pushing boundaries or you're unsure whether it qualifies, we strongly recommend reaching out to us. We'd love to explore ways to help you stay compliant without compromising on your vision.

And remember: just because something is technically digital doesn't mean it's automatically okay. If it feels shady, scammy, exploitative, or like something you wouldn't explain confidently to your mother, we probably can't support it.

Some business types may fall into a restricted zone - not outright prohibited, but not immediately approved either. These cases will require enhanced due diligence, and we'll take a closer look before making a final decision. This is done on a case to case basis.

## Businesses We Might Support

To meet our compliance obligations, some business types require additional review. If your business falls into one of the categories below, we may ask for extra details such as licenses or information about how you operate.

While we aim to support a wide range of businesses, approval isn't guaranteed. If approved, access may be limited or adjusted over time in line with the Terms & Conditions, and this policy. Some types of businesses are not outright prohibited but do raise higher compliance or reputational risks. If you operate in one of these spaces, we may ask for extra details (like disclaimers, demo access, or policy links) before approving your account.

### Categories That Often Require Review

1. **AI Content Generation tools (text, image, video, voice)** – No impersonation, scraping, or deepfakes
2. **Marketing & outreach tools** – No spam, scraping, or fake engagement
3. **Resume, hiring, or exam tools** – No impersonation or cheating functionality
4. **Spiritual & Astrology services** – Entertainment only; no claims or predictions
5. **Audio / music / chatbot generators** – No voice cloning, NSFW, IP Infringements or fake claims
6. **E-books and written digital publications** – Including guides, playbooks, reports, or downloadable written content.
7. **Productised services** – A fixed, pre-defined digital product that is delivered the same way for every buyer. This may include limited, repeatable human operational work, as long as it is not customized or consultative.

**Unsure if your business qualifies?**

If your product operates near the edge of these categories, we encourage you to reach out before applying. We may still be able to support you, especially if you're transparent about your model, actively mitigate risks, and are willing to work within platform guidelines. You can reach out to [compliance@dodopayments.com](mailto:compliance@dodopayments.com) to check if you qualify.

## Fulfillment Channels & Access Delivery

Some merchants use Dodo Payments to deliver access on purchase — for example, a license key, a downloadable file bundle, a Discord role, GitHub collaborator access, a Telegram chat or channel invite, a Notion template, or a Framer remix link. Where Dodo Payments fulfils that delivery, the standards in this policy apply both to what is sold on the storefront and to what is actually delivered through the channel.

In particular:

* Communities, files, repositories, templates, and other resources made available to customers through a Dodo-fulfilled channel must align with the merchant's disclosed product and with this policy.
* A community, file bundle, repository, or template that delivers material misaligned with the disclosed product, or that contains content that would itself be ineligible under this policy (for example, adult content, piracy or unauthorised resale, deceptive claims, unlicensed financial advice, or weapons-related content), is treated as a policy breach regardless of how the storefront is positioned.
* Continued use of these channels to deliver access is conditioned on ongoing alignment with this policy. Material drift between the advertised product and the gated content may result in account review, restriction, or closure under our enforcement process.

This applies whether the channel is created and operated by the merchant or by a third party.

## Accepted Countries & Territories

<Card title="Accepted Countries & Territories" icon="globe" href="/miscellaneous/accepted-countries-and-territories">
  View the full list of countries and territories where Dodo Payments supports merchant accounts and payouts.
</Card>

## Enforcement

We take violations of our merchant policy seriously. If we determine that a merchant has onboarded in breach of this policy or our terms — including by misrepresenting their business, attempting to bypass restrictions, or engaging in prohibited activities — Dodo Payments may take appropriate action.

### Enforcement Actions May Include:

* Permanent account suspension
* Immediate halt of transactions and platform access
* Withholding of payouts or reversal of settled funds
* Refunding all transactions processed
* Fines or penalties in proportion to losses, reputational harm, or downstream risk (up to USD 425,000)
* Reporting to card networks, financial partners, or regulators where required

These measures may be taken without prior notice in cases of material breach or imminent platform risk.

### Examples of Policy Breach

The following may trigger investigation or enforcement:

1. Misclassifying your business or products to bypass category restrictions.
2. Using proxy merchants, sub-accounts, or account takeovers to avoid enforcement.
3. Selling or promoting products that are deceptive, harmful, or violate our prohibited content rules.
4. Failing to disclose essential onboarding information (e.g., website mismatch, incorrect entity type).
5. Suspicious or unusual volume of transactions.
6. High volume of refunds, disputes, or customer complaints.
7. Actions or transactions that have been flagged by our payment, financial, or regulatory platforms.
8. Requests by legal authorities upon receipt of relevant legal order.
9. Reports of fraudulent activities flagged by our regulatory and compliance partners, and customer reports.
10. Any other material breaches of our platform policies or violations of law as applicable
11. Delivering, through a Dodo-fulfilled access channel (for example, a license key, downloadable file, Discord, Telegram, GitHub, Notion, or Framer integration), content or material that is misaligned with the disclosed product or that is otherwise ineligible under this policy.

### Appeals & Resolution

If you believe enforcement was applied in error, you may submit a request for review. Please note that reviews are considered on a one-time basis only. The appeal review decision will be final.

In some cases, we may allow corrective action or resubmission for review. Voluntary disclosure of potential issues may be considered favorably. You can reach out to **[compliance@dodopayments.com](mailto:compliance@dodopayments.com)** to initiate the review process.


# Review & Monitoring Policy
Source: https://docs.dodopayments.com/miscellaneous/review-monitoring-policy

How Dodo Payments monitors merchant activity to protect customers, partners, and the payment ecosystem.

## Introduction

At Dodo Payments, we act as a Merchant of Record (MoR), managing payment processing, invoicing, taxes, refunds, and disputes on behalf of the businesses that use our platform. To safeguard customers, businesses, and partners, we operate a structured monitoring program. This program ensures that accounts on our platform remain compliant with card network rules, applicable laws, and our \[Merchant Acceptance Policy].

## Purpose

Our monitoring framework is designed to protect both businesses and customers. By identifying and addressing potential risks early, we help ensure a trusted and reliable payment environment.

## Monitoring Approach

We combine automated checks with human review to maintain oversight of business activity. Reviews focus on:

1. Compliance with our [Merchant Acceptance Policy](/miscellaneous/merchant-acceptance)
2. Consistency between what is disclosed at onboarding and what is offered live
3. Compliance with card network rules, sanctions, and applicable laws
4. Customer experience signals such as refunds and disputes
5. Use of approved brands, domains, and product lines
6. Where merchants use Dodo Payments to deliver access on purchase — for example, via license keys, downloadable files, or invites to Discord, Telegram, GitHub, Notion, or Framer — alignment between the disclosed product and what is actually delivered through these channels.

## When Reviews Occur

Reviews take place at key points in the lifecycle:

1. **Activation & First Transaction** – to confirm that products and checkout experiences match what was disclosed.
2. **Before First Payout** – to complete compliance checks and validate fulfillment.
3. **Ongoing Triggers** – when significant changes occur, such as new domains, product shifts, addition or material change to fulfillment channels (such as Discord, Telegram, GitHub, Notion, or Framer integrations), unusual transaction patterns, or rising disputes / refunds.
4. **Periodic Reviews** – regular monitoring to help ensure continued compliance.

## Outcomes of Reviews

Following a review, possible outcomes include:

1. **Continued support** – your account remains active on the platform.
2. **Remediation** – we may ask you to correct issues or provide clarifications.
3. **Deboarding** – in cases of prohibited activity, policy violations, or non-response, the account may be closed and payouts withheld in line with our enforcement process.

## Customer Protection

We take customer complaints, fraud alerts, and refund requests seriously. In such cases, we may contact both the customer and your business. If we don’t receive a response within reasonable timelines, refunds may be processed automatically and your account may be restricted or closed.

## Fulfillment Channel Checks

Some merchants use Dodo Payments to provision access to communities, files, repositories, templates, or other resources after purchase. To verify that the product disclosed at onboarding remains aligned with what is actually delivered, we may carry out periodic or for-cause checks of these channels. Checks are scoped to compliance verification.

Depending on the situation, a check may include:

* Reviewing publicly visible information about the community, repository, or template.
* Where the channel is private, requesting access for the limited purpose of confirming alignment with this policy and the Merchant Acceptance Policy.
* Reviewing samples of content or materials made available to customers through the channel.

These checks are scoped to verifying compliance. We do not monitor individual customers or their messages, do not retain personal data observed in these channels beyond what is necessary to record a compliance finding, and do not act as a content moderator on behalf of the merchant. Where access is required and is not provided within reasonable timelines, the matter is treated as unresolved under our enforcement process.

Fulfillment channel checks are one input to our broader review program; they do not displace the customer protection, transparency, or enforcement provisions in this policy.

## Transparency & Communication

If clarifications are required, we contact you at your registered email address. You’ll have the opportunity to respond and provide context. Where no response is received, accounts may be closed and funds held in line with card network and regulatory requirements.

## Enforcement

Violations of our policies, card network rules, or applicable laws may result in:

1. Suspension of payments
2. Account closure
3. Notifications to card networks, partners, or regulators as required

## Commitment to Fairness

Our monitoring standards are applied consistently across all businesses. We aim to work collaboratively to resolve issues where possible, while maintaining strong protections for customers and the payment ecosystem.


# Security Reporting Policy
Source: https://docs.dodopayments.com/miscellaneous/security-policy

Guidelines for responsible disclosure of security vulnerabilities at Dodo Payments.

## Introduction

At Dodo Payments, we take security seriously and appreciate responsible disclosure of vulnerabilities that help us improve our platform. If you discover a security vulnerability, we encourage you to report it to us following the guidelines below.

## Reporting Security Vulnerabilities

If you identify a security vulnerability in our platform, please contact us at **[pt-team@dodopayments.com](mailto:pt-team@dodopayments.com)** with the following details:

* **Description**: A clear and concise explanation of the vulnerability.
* **Steps to Reproduce**: Detailed steps to replicate the issue.
* **Impact**: The potential risk or harm that could arise from the vulnerability.
* **Suggested Mitigations**: (If available) Any recommendations on how to fix the issue.

## How We Handle Reports

1. **Acknowledgment**: Our team will confirm receipt of your report within a reasonable timeframe.
2. **Assessment**: We will review the report and prioritize it based on severity and impact.
3. **Resolution Timeline**: If the issue is already known and logged internally, we will provide an update on its expected resolution.
4. **Follow-up**: We may reach out for additional information or clarification as needed.

## No Monetary Rewards (Bug Bounty Program)

Currently, **Dodo Payments does not have an official bug bounty program**. While we deeply appreciate security researchers' efforts, we **do not offer monetary rewards** for vulnerability disclosures. This ensures fairness for all individuals who have reported similar issues in the past.

## Recognition & Appreciation

We highly value the contributions of ethical security researchers. While we do not offer financial compensation, we would be happy to send **Dodo Payments goodies/merch** as a token of appreciation for valid security reports. If you are interested, please let us know after your report has been reviewed.

## Responsible Disclosure

To ensure a responsible and ethical reporting process, please adhere to the following:

* **Do not publicly disclose** vulnerabilities until our team has had a reasonable time to address them.
* **Do not exploit** the vulnerability beyond what is necessary to demonstrate the issue.
* **Do not access, modify, or delete** data that does not belong to you.
* **Do not perform** any activity that could disrupt our services.

## Contact Us

If you have any security concerns or need further assistance, please reach out to us at **[pt-team@dodopayments.com](mailto:pt-team@dodopayments.com)**.


# Subscription Migration to Dodo Payments
Source: https://docs.dodopayments.com/miscellaneous/subscription-migration

Learn how to migrate your existing subscribers and payment methods from your current payment processor to Dodo Payments.

## What is a subscription migration?

A subscription migration transfers your existing subscribers from your legacy payment processor to Dodo Payments, giving you a single source of truth for all your customer data. Without a migration, customers you've acquired to date remain in your legacy system, and only new customers would be visible in Dodo Payments.

The migration process ensures a seamless billing experience for your customers—they won't need to re-enter their payment details or experience any interruption to their subscriptions.

<Warning>
  Currently, we only support migration for **card tokens**. Apple Pay, Google Pay, and other wallet payment methods cannot be transferred between payment processors due to tokenization restrictions imposed by these providers.
</Warning>

## Migration process overview

The subscription migration process consists of three key parts:

1. **Payment method transfer** — Secure transfer of sensitive card data from your current processor
2. **Subscriber data transfer** — Export of customer details, subscription plans, and billing schedules
3. **Import and validation** — Unifying payment methods and subscriber data in Dodo Payments

<Note>
  To begin a subscription migration, contact our [support team](mailto:support@dodopayments.com). They will connect you with a dedicated Solutions Engineer who will guide you through the entire process.
</Note>

## Requirements

Before initiating a migration, ensure you meet the following requirements:

<AccordionGroup>
  <Accordion title="PCI DSS compliance verification">
    Dodo Payments is PCI DSS Level 1 compliant. To meet compliance obligations, we can only receive card data from another PCI DSS Level 1-compliant payment processor.

    Your current processor must provide:

    * Their current PCI Attestation of Compliance (AOC), or their listing on Visa's Global Registry of Service Providers
    * Confirmation that they support secure card data exports

    View our [Attestation of Compliance (AOC)](https://pub-2a89184e4c954b599464449d23f506bb.r2.dev/dodo-payments-pci-dss-aoc.pdf) to share with your current processor.
  </Accordion>

  <Accordion title="Dodo Payments integration">
    Complete your Dodo Payments integration and ensure all new customers are being directed to Dodo Payments checkout before starting the migration. This prevents data inconsistencies during the transition period.
  </Accordion>

  <Accordion title="Data access authorization">
    Ensure you have the necessary authorization to request a data export from your current processor. This typically requires:

    * Account owner verification
    * Written authorization for sensitive data access
    * Completion of your processor's security verification steps
  </Accordion>
</AccordionGroup>

## Step-by-step migration guide

<Steps>
  <Step title="Request payment method export from your current processor">
    Contact your current payment processor's support team and submit a formal request for a complete export of your customer card tokens.

    You will need to:

    * Provide verification of your identity and authorization
    * Request they encrypt the export using Dodo Payments' PGP public key (provided below)
    * Ask them to transfer the encrypted file directly to our secure SFTP server

    <Info>
      Secure transfers are made directly from server to server via SFTP. Your Solutions Engineer will provide the SFTP credentials to share with your current processor.
    </Info>

    On average, this process takes around **2 weeks**, although timing varies depending on your current processor's policies and response times.
  </Step>

  <Step title="Prepare subscriber data export">
    While the payment method transfer is in progress, export your subscriber data from your legacy system. Your Solutions Engineer will provide a CSV template and guide you through the required fields.

    ### Required subscriber data

    | Field               | Description                                   |
    | ------------------- | --------------------------------------------- |
    | `customer_id`       | Your internal customer identifier             |
    | `email`             | Customer's email address                      |
    | `name`              | Customer's full name                          |
    | `country`           | Two-letter country code (ISO 3166-1 alpha-2)  |
    | `currency`          | Three-letter currency code (ISO 4217)         |
    | `payment_amount`    | Subscription amount in smallest currency unit |
    | `payment_interval`  | Billing frequency (monthly, yearly, etc.)     |
    | `next_billing_date` | Next scheduled billing date (ISO 8601)        |
    | `card_token`        | Unique token from your current processor      |

    <Warning>
      The `card_token` field is critical—it's used to match subscriber records with their payment methods during import. Ensure this matches exactly with the token in the payment method export.
    </Warning>

    ### Sample data format

    ```json theme={null}
    {
      "customers": [
        {
          "customer_id": "cus_abc123",
          "email": "jane.doe@example.com",
          "name": "Jane Doe",
          "country": "US",
          "currency": "USD",
          "payment_amount": 2999,
          "payment_interval": "monthly",
          "next_billing_date": "2025-01-15T00:00:00Z",
          "card_token": "tok_xyz789",
          "metadata": {
            "plan": "pro",
            "signup_source": "website"
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Validation and testing">
    Before the import date, our team will:

    * Verify file integrity and encryption of the payment method data
    * Validate your subscriber CSV for correct formatting
    * Run a test import in Test Mode
    * Identify and resolve any data mapping issues

    <Check>
      You'll receive a validation report confirming everything is ready for the production import.
    </Check>
  </Step>

  <Step title="Production import">
    On the agreed import date, our engineering team will:

    1. Import the payment method data into our PCI-compliant Card Vault
    2. Import your subscriber data
    3. Match subscribers to their payment methods using the card tokens
    4. Activate all migrated subscriptions

    <Info>
      Typical processing time is **2-3 business days** for standard migrations, depending on the volume of subscribers.
    </Info>
  </Step>

  <Step title="Post-migration verification">
    After the import completes, you'll receive:

    * A comprehensive migration report
    * A CSV mapping your old subscription IDs to new Dodo Payments IDs
    * Access to all migrated customers in your Dodo Payments dashboard

    We recommend:

    * Verifying a sample of migrated subscriptions in your dashboard
    * Testing a few subscription renewals in Test Mode
    * Updating your internal database references with the new IDs
    * Running parallel monitoring for the first billing cycle
  </Step>
</Steps>

## Migratable data

The following data can be transferred during a subscription migration:

| Data type                 | Supported | Notes                              |
| ------------------------- | --------- | ---------------------------------- |
| Credit/debit card numbers | ✅         | Encrypted via PGP                  |
| Card expiration dates     | ✅         |                                    |
| Cardholder names          | ✅         |                                    |
| Billing addresses         | ✅         |                                    |
| Customer email addresses  | ✅         |                                    |
| Customer metadata         | ✅         | Custom key-value pairs             |
| Subscription details      | ✅         | Plan, amount, interval             |
| Apple Pay tokens          | ❌         | Cannot be transferred              |
| Google Pay tokens         | ❌         | Cannot be transferred              |
| Other wallet tokens       | ❌         | Cannot be transferred              |
| Payment history           | ❌         | Export from your current processor |

<Note>
  Payment history and transaction records cannot be migrated. We recommend exporting this data from your current processor for your records before completing the transition.
</Note>

## PGP encryption

For maximum security when transferring sensitive card data, all files **must** be encrypted using our PGP public key. This provides an additional layer of protection beyond transport-level encryption.

Share this key with your current payment processor for encrypting the card data export:

<Accordion title="Dodo Payments PGP Public Key">
  ```
  -----BEGIN PGP PUBLIC KEY BLOCK-----

  mQINBGflFWEBEADA8IaeXNc9ekoyWGH6TBi3PvazDTXH9MeAIcq8tcXPjr+aDTA7
  QE0oJbnH+Zi6nP6Mh20c4bftzC890/QJmk6shdgpQuCd/80yC1TT5tyqKDV517WQ
  B7A8CmbonuZ//jS+jWrekpbLFMzoro1ZkeCRDNbhF3KSrMv1UOugBHPAchtkTur8
  2k+HtIFKVW8xQ3/nrnKGeNWdHMp3y6yATjXm0E2y9Oq83CQ1TkwwB+MI0Y/uZaXv
  3016pOos3lQFXqVAvShDRzMXxvPHc902QS47v0gSj5wsVWv3g5QP/TlAE6Pvua18
  78xoROo9RLwovMmX372JeZdqKgIV+BmxlOrGCDcNOY4Flz+NRJuKbVk0UmD8f1tW
  NL5x/r36ZNnBbzohqcwp5dktiRn0MDHUsvv8StOkbFqQ+HyYSzoO1dRYGkz5bkfI
  urv4hd26I4rdu8GTpEaBcd0rx1NcNT2lbqrcTE7rux3c3Vf1QD6lSj+VbJBxxyxO
  +fgeoVNpAi4Zfyls+VYCRolVHxxdjh/Zu6iAUrpubpgBxoxwzF3vMVWDPvZahUxY
  gt340eRr6KQUpI2TK4iNhTzc4CpYP/eKyC8TavHzpuGap0f7ojNaD1yjPxKJ9HFF
  eFde7jtoglvGrdW/GnoTVBFdN4wdcrJ6+Xthlqk5n0CZLKxZzCsnJ+Y00wARAQAB
  tFlEb2RvIFBheW1lbnRzIEltcG9ydCBLZXkgKEltcG9ydCBrZXkgZm9yIGNhcmQg
  dG9rZW4gbWlncmF0aW9uKSA8cHQtdGVhbUBkb2RvcGF5bWVudHMuY29tPokCVwQT
  AQgAQRYhBAfnpp8sSFvzQCZA9mOB38/zSlnMBQJn5RVhAhsDBQkJZgGABQsJCAcC
  AiICBhUKCQgLAgQWAgMBAh4HAheAAAoJEGOB38/zSlnMLm4QAK1sQxraYnV4OC9l
  G0LNUDRKsayJ3+5uW6gbD72NhQ1Q7GpD6J1kmoXO95ZMSV4Ev+PAdBHVnhbl+LTk
  JBZTrVszeZfmAr2D0HTdBsqlB8uUISXaffL/a0POWTLRdVzHJbTPtC23SHjW8XFu
  0ixomJxnIXu1iBccEPJTWpjYQbecfK6xMbHYvLQYBCLBWbDfr7hJ3ubnF8izo4W+
  cxYmFS5A4lKs6PHC+MlikFHtKKhDaKT+Zc5c5utcGpPEFUw1vxvQkgabOie6/ufc
  EAfzHaFklDvyovfKJ3eOrTRlOG8T0TmoccxjTtx4vboaTcnKoANO0p1G5esjkAWU
  2Bpa/hTaW3YvKBlHEPovm+E4c7OieHIvw3+BS7uyWOmNHgzJcAEVkbJAvRl9X1lQ
  LzcOqBIVMyLF5zswRBHtCWHuYsolIO8zMKHmYKV52jR7OkGcZ5ekaqIKVsOmpDCk
  Rn7RWubhglOC6e+CNK+2LEQALpDLx05F4uUSmbo0KvQtgnXJHsVsesaO/CVxvdOw
  nWv3MyZbhN+EGCKbO3eoTkaM7EHRPEsHa04a+T+TPFel1B7VlTdBikoyNQxyh4a2
  V/ERoKi1qI9DS158lkPkZt90PLhPMVyOFTmTt8ZbZhp1TndmIterWGlYFz8yXb7A
  BDeo0Xmu2rmuoG7kEihSwt0UmfMSuQINBGflFWEBEACyXdG9SjXd7dRoJ5bcs64A
  Cxea1NZ90x4NWdx0lTy8ruHBSzl2SYDGhDbAAOhVTxZHr1UeDfPBp/urYiENsFeA
  Fx2V4Pt2Jj0oBJ6IIHnf1X0U+T6JzVYraaQBHUjXsq4GVoD0bWydQwE6+PSOOZ8R
  d7GlsdDl0lM38krkN84BRI/OEfLJaUKFAN9COBnna3bpUwhrvk2o05ItYK/CPoEp
  lQAI5mvO7x+kPSsWUCW905TrQuvYuJQvhCZN/2NMn7X5NzhVLLnPW+hyBfkjkWWm
  8GQoH54AADQOKAczkXuSUuLwji+TA2ImAw9FI/S5cIjxG3z4PaAg7zVeZEpjjTWN
  7QQXEMvzDLLXRSjXHsmtWmg//pgvkTxyuzPbNKK7KY9Q+Xyqb0bP5UQKrZ9nRn4l
  MMZjC7Kj7eeMv3g/V6wH60Sle0/XW1zSX0djay/Hf99eXcfntlSW0DB2pn9fa8+W
  vdmASrLwcYyGjIROxzHIW9uUs4kdJqWatzfT/0uWWwaLayEkd/lCzITn61UAYwVt
  YIhY5u9lH0ZuQsxOm267TZrrgDbN9h+z5OVLxW9ylhvXZhMa0w87z8ZTp9wCycki
  CNCM1dP0N+lxIPnDu3MztK8u/yelcKpruY5L+gMmVcyDPSYUHDO7g764IdUmSPh4
  VfIeXAsj2r5usa4/+OcxuQARAQABiQI8BBgBCAAmFiEEB+emnyxIW/NAJkD2Y4Hf
  z/NKWcwFAmflFWECGwwFCQlmAYAACgkQY4Hfz/NKWcxoIA//edJGWP4Pu70M5IlQ
  rLRhi0+hKe0l5VrR1XYcr0EA4qiRQIouab4QvHoxNpn5RGQ+C2agwraiIwIP/nqR
  Wz1arWpea8BuSeAJCI0uVQURGexB9ZIJ4oiz8itAiHyjW6x+B4zC9RKe3xGO8KIt
  FhtGMYGP+8bZyOUnIU9ZqO+mxHc/wnwCeICzE5TpITrEERbXh0XZJJCLotpss8o8
  4F0Lb/9VwObCEdxpC6IkKW9GF5WJjmycfdcojaEr26qNSj1KsKRww7ukoVthD4aT
  KRM0j3X0UFNz522hBCV/+0+cGMSc5lIRzE+gsXM8vpCW3rmWZj9pMyL5r/RH1FFL
  9N3nFvfjoiuEqQ/DRy3jdwCHXEijjo5ym1KU9AGuo42deI0nrpvzXYSSahKMOb0/
  PbF4YlrtSbXwhIsBfCUX6njvNomu2u4wDs7gv7gyimyetMZ8EwJ3aGvXlD4kHh15
  tIo5NVXXLfslGtoL+27iW4nmoAxV1lOU2c2Wei+lXEc7t6JgeI0NTdqBnYTNHsOZ
  f+dti4KGC2Y+6QKhCgvTFHdHpBJj9DzG49C+4E5ZZL3bNdsU5eXaIuJf/KW+eVQB
  EZgHVgBRCqwrDD6SpkOT2lzNxfKI5rBV+WCT+hbu83hk2Pd1K7N3JQs1fVFffF37
  1OSDhXaPYtJnVApUzaCrC5PJCXU=
  =nHcw
  -----END PGP PUBLIC KEY BLOCK-----

  ```
</Accordion>

## Timeline expectations

| Phase                       | Duration            |
| --------------------------- | ------------------- |
| Initial setup and planning  | 1-2 days            |
| Payment method transfer     | \~2 weeks           |
| Subscriber data preparation | 3-5 days (parallel) |
| Validation and testing      | 2-3 days            |
| Production import           | 2-3 business days   |
| Post-migration verification | 1-2 days            |

<Tip>
  The total migration typically takes **3-4 weeks** from start to finish. Starting your subscriber data preparation while the payment method transfer is in progress helps minimize the overall timeline.
</Tip>

## Get started

Ready to migrate your subscriptions to Dodo Payments? Contact our team to begin the process:

<CardGroup>
  <Card title="Contact Support" icon="envelope" href="mailto:support@dodopayments.com">
    Reach out to start your migration and get connected with a Solutions Engineer.
  </Card>

  <Card title="API Documentation" icon="code" href="/api-reference/introduction">
    Explore our API to understand how subscriptions work in Dodo Payments.
  </Card>
</CardGroup>


# Test Mode vs Live Mode
Source: https://docs.dodopayments.com/miscellaneous/test-mode-vs-live-mode

Learn the difference between Test Mode and Live Mode and how to switch between them.

Find the detailed breakdown of the features which will be available in test mode vs live mode

## Feature Comparison

| **Feature**                                 | **Test Mode** | **Live Mode** | **Is Environment Dependent?** |
| ------------------------------------------- | ------------- | ------------- | ----------------------------- |
| **Create Products (One-Time/Subscription)** | ✓             | ✓             | YES                           |
| **Generate Payment Links**                  | ✓             | ✓             | YES                           |
| **Simulate Payments (Card, Wallet, etc.)**  | ✓             | x             | YES                           |
| **Process Real Payments**                   | x             | ✓             | YES                           |
| **Issue Refunds**                           | ✓ (Simulated) | ✓ (Real)      | YES                           |
| **Access Transaction History**              | ✓ (Simulated) | ✓ (Real)      | YES                           |
| **Download Invoices**                       | ✓ (Simulated) | ✓ (Real)      | YES                           |
| **Link Bank Account**                       | ✓             | ✓             | Environment Independent       |
| **Payouts to Bank Account**                 | x             | ✓             | YES                           |
| **Simulate Failed Transactions**            | ✓             | x             | YES                           |
| **Analytics Section**                       | ✓ (Simulated) | ✓ (Real)      | YES                           |
| **View Detailed Reports**                   | ✓ (Simulated) | ✓ (Real)      | YES                           |
| **Customize Invoice Templates**             | ✓             | ✓             | Environment Independent       |
| **API Keys generation**                     | ✓             | ✓             | YES                           |
| **Real-time Fraud Detection**               | x             | ✓             | YES                           |
| **Access Live Customer Support**            | ✓             | ✓             | Environment Independent       |
| **Webhook Creation**                        | ✓             | ✓             | YES                           |
| **Business Profile section**                | ✓             | ✓             | Environment Independent       |
| **My Account section**                      | ✓             | ✓             | Environment Independent       |
| **Create multiple businesses**              | ✓             | ✓             | Environment Independent       |
| **Payout Compliance**                       | ✓             | ✓             | Environment Independent       |
| **Transaction Emails**                      | x             | ✓             | YES                           |

### Environment Dependency

**Environment Dependent:** All Environment Dependent features will have independent data in Test Mode and Live Mode. Any changes made in one environment will not affect the other. Eg. API Keys generated in Test Mode will be independent of API keys generated in Live Mode and vice versa

**Environment Independent:** All Environment Independent features will have the same data in both live mode and test mode. Eg. My Account section will have the same data in test mode and live mode. Changes made in one environment will affect the other environment

Live Mode will be available only post successful completion of Identity verification and Business Verification. You can accept real payments only in \`live mode\`.

API Hostnames for Test Mode and Live Mode are below:

* Test Mode: [`https://test.dodopayments.com`](https://test.dodopayments.com/)
* Live Mode: [`https://live.dodopayments.com`](https://live.dodopayments.com/)

## Key Highlights

1. All products created in test mode or live mode will only be available in the respective environment. There is an option of copy to live mode in the test mode environment. This will copy the product with all relevant details and create the same in live mode

2. API keys and Webhooks created in test mode will only be limited to test mode environment and will not affect live mode deployment and vice versa. You can use the [CLI webhook listener](/developer-resources/sdks/cli#listen-for-webhooks) (`dodo wh listen`) to forward test mode webhooks to your local development server in real time

3. All documents submitted for verification and Bank account details submitted will be the same in test mode and live mode. A change in this information in any environment will also change it in the other environment

## Test Cards and UPI IDs

For detailed information about test cards, UPI IDs, and other testing methods, please refer to our comprehensive [Testing Process](/miscellaneous/testing-process) guide.

This guide includes:

* Test card numbers for different scenarios
* Test UPI IDs for simulating payments
* Instructions for testing various payment outcomes
* Best practices for testing your integration

<Note>
  Test payment methods are only valid in test mode. Never use them for real payments.
</Note>

## Transaction in Test Mode - Tutorial

Please watch this video on how you can perform a transaction in Test Mode.

<Frame>
  <iframe title="Test Transaction | Dodo Payments" />
</Frame>


# Testing Process
Source: https://docs.dodopayments.com/miscellaneous/testing-process

Complete guide to testing your Dodo Payments integration with test cards, UPI IDs, BNPL data, and digital wallets.

<Frame>
  <iframe title="Test Transaction | Dodo Payments" />
</Frame>

## Overview

Test mode lets you simulate payments without processing real transactions. All test credentials only work in test mode — never use them in production.

<CardGroup>
  <Card title="No Real Charges" icon="shield-check">
    Test transactions don't process actual payments or affect real accounts.
  </Card>

  <Card title="Full API Access" icon="code">
    All API endpoints work identically in test and live modes.
  </Card>

  <Card title="Webhook Testing" icon="webhook">
    Webhooks fire for test transactions just like production.
  </Card>
</CardGroup>

<Warning>
  Test credentials only work in test mode. Attempting to use them in live mode will result in payment failures.
</Warning>

## Test Cards

Use these card numbers to simulate successful and declined payments across different regions.

<Tabs>
  <Tab title="Successful Payments">
    | Region | Brand      | Card Number        | Expiry | CVV |
    | :----- | :--------- | :----------------- | :----- | :-- |
    | US     | Visa       | `4242424242424242` | 06/32  | 123 |
    | US     | Mastercard | `5555555555554444` | 06/32  | 123 |
    | India  | Visa       | `4576238912771450` | 06/32  | 123 |
    | India  | Mastercard | `5409162669381034` | 06/32  | 123 |
  </Tab>

  <Tab title="Declined Payments">
    | Region | Brand      | Card Number        | Scenario           | Resulting `error_code` |
    | :----- | :--------- | :----------------- | :----------------- | :--------------------- |
    | US     | Visa       | `4000000000000002` | Generic decline    | `GENERIC_DECLINE`      |
    | US     | Visa       | `4000000000009995` | Insufficient funds | `INSUFFICIENT_FUNDS`   |
    | India  | Visa       | `4706131211212123` | Generic decline    | `GENERIC_DECLINE`      |
    | India  | Mastercard | `5105105105105100` | Generic decline    | `GENERIC_DECLINE`      |

    When one of these cards declines, the payment's `error_code` and `error_message` reflect the scenario above. Look up any code in the [Transaction Failures](/api-reference/transaction-failures) reference for its meaning and recommended action, and see [Handle Payment Failures](/developer-resources/handle-payment-failures) for handling declines in your integration.
  </Tab>

  <Tab title="Subscription Failure Testing (Renewal/Upgrade/Downgrade)">
    | Card Number           | Expiry | CVC |
    | :-------------------- | :----- | :-- |
    | `4000 0000 0000 0341` | 12/34  | 123 |

    Use this card to test subscription Failure renewal, upgrade, and downgrade scenarios.
  </Tab>
</Tabs>

<Info>
  For all test cards, use expiry date **06/32** (or **12/34**) and CVV **123**.
</Info>

### How to Test Renewal Failure

<Steps>
  <Step title="Create a test subscription">
    Create a subscription with your test API keys using a **success** test card (for example, `4242 4242 4242 4242`). The initial charge should succeed and the subscription should become active.
  </Step>

  <Step title="Swap in the failure card via Customer Portal">
    Open the [Customer Portal](/features/customer-portal), find the subscription you just created, and click **Update Payment Method**. Enter the failure test card `4000 0000 0000 0341` (Expiry: `12/34`, CVC: `123`) and save it as the subscription's payment method.
  </Step>

  <Step title="Advance the next billing date (optional)">
    To trigger renewal immediately instead of waiting for the natural billing cycle, use the Update Subscription API to set `next_billing_date` to the current UTC time. The value must be an ISO 8601 / RFC 3339 UTC timestamp (the `Z` suffix is required).

    ```http theme={null}
    PATCH /subscriptions/{subscription_id}
    {
      "next_billing_date": "2026-05-03T00:00:00Z"
    }
    ```

    See the [Update Subscription API reference](/api-reference/subscriptions/patch-subscriptions#body-next-billing-date-one-of-0) for details.
  </Step>

  <Step title="Verify the failure">
    On the next billing attempt:

    * The renewal charge declines on the failure card
    * The subscription moves to **On-Hold** status
    * A `payment.failed` webhook event is delivered
    * The customer can return to the Customer Portal to update the payment method and retry
  </Step>
</Steps>

<Warning>
  This card is specifically for testing renewal failures. The charge will decline on the next billing date, allowing you to test payment retry logic, customer notifications, and failure handling.
</Warning>

## Test UPI

UPI testing uses special VPA (Virtual Payment Address) identifiers that simulate different payment outcomes.

| Status  | UPI ID        |
| :------ | :------------ |
| Success | `success@upi` |
| Failure | `failure@upi` |

### Requirements for UPI Testing

* Billing country must be set to `IN`
* Currency must be `INR`
* For non-Indian merchants: Adaptive Currency must be enabled

For complete UPI documentation including RBI mandate testing for subscriptions, see the [India Payment Methods](/features/payment-methods/india) page.

## Test BNPL

Buy Now Pay Later providers have specific test data requirements.

### Klarna Test Data

Use these details to simulate Klarna payments in test mode:

| Field             | Approved                                      | Denied                                                      |
| :---------------- | :-------------------------------------------- | :---------------------------------------------------------- |
| **Date of Birth** | 07-10-1970                                    | 07-10-1970                                                  |
| **First Name**    | Test                                          | Test                                                        |
| **Last Name**     | Person-us                                     | Person-us                                                   |
| **Email**         | [customer@email.us](mailto:customer@email.us) | [customer+denied@email.us](mailto:customer+denied@email.us) |
| **Street**        | Amsterdam Ave                                 | Amsterdam Ave                                               |
| **House Number**  | 509                                           | 509                                                         |
| **City**          | New York                                      | New York                                                    |
| **State**         | New York                                      | New York                                                    |
| **Postal Code**   | 10024-3941                                    | 10024-3941                                                  |
| **Phone**         | +13106683312                                  | +13106354386                                                |

<Note>
  Klarna requires a minimum transaction amount of **\$50.01** to appear as a payment option.
</Note>

### Afterpay Testing

<Steps>
  <Step title="Select Afterpay">
    Choose Afterpay as the payment method in checkout and click Pay.
  </Step>

  <Step title="Test successful payment">
    Use any valid email address and shipping address for successful payments.
  </Step>

  <Step title="Test failed authentication">
    To simulate failure, close the Afterpay modal window on the redirect page. The payment transitions from `requires_customer_action` to `requires_payment_method`.
  </Step>
</Steps>

<Note>
  Afterpay requires a minimum transaction amount of **\$50.01** to appear as a payment option.
</Note>

For complete BNPL documentation including Billie B2B testing, see the [Buy Now Pay Later](/features/payment-methods/bnpl) page.

## Test Digital Wallets

### Apple Pay

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Add a card to Apple Wallet">
    Add a real card to your Apple Wallet. In test mode, the card won't be charged.
  </Step>

  <Step title="Complete test purchase">
    Open checkout on an Apple device and complete the Apple Pay flow.
  </Step>
</Steps>

<Warning>
  Apple Pay requires HTTPS. It won't appear on `localhost` without proper SSL setup. Domain verification must also be complete.
</Warning>

### Google Pay

<Steps>
  <Step title="Join the test card group">
    [Join the Google Pay test card group](https://groups.google.com/g/googlepay-test-mode-stub-data) to get test cards automatically added to your wallet.
  </Step>

  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Complete test purchase">
    Select one of the test cards in Google Pay to complete the transaction.
  </Step>
</Steps>

### Amazon Pay, Cash App Pay & RevolutPay

Use your test API keys and follow the standard checkout flow. Test transactions are simulated without actual charges.

For complete digital wallet documentation including domain verification for Apple Pay, see the [Digital Wallets](/features/payment-methods/digital-wallets) page.

## Test ACH Direct Debit

ACH Direct Debit can be tested in Test Mode by entering test bank details at checkout.

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Set currency and billing address">
    Set the billing currency to `USD` and the billing address country to `US`. ACH is not offered outside this combination.
  </Step>

  <Step title="Use a one-time payment">
    ACH is not available on subscription checkouts, so test it against a one-time payment.
  </Step>

  <Step title="Enter the test bank details">
    Enter one of the test routing and account number pairs below, then confirm your webhook handler receives the final payment status — ACH payments confirm asynchronously rather than at checkout.
  </Step>
</Steps>

### Test Bank Accounts

Use the routing number `110000000` with any of these account numbers:

| Account Number | Behavior                                         |
| :------------- | :----------------------------------------------- |
| `000123456789` | The payment succeeds.                            |
| `000222222227` | The payment fails due to insufficient funds.     |
| `000111111113` | The payment fails because the account is closed. |
| `000555555559` | The payment succeeds, then triggers a dispute.   |
| `000000000009` | The payment stays in processing indefinitely.    |

For the full list of test accounts, see the [ACH Direct Debit](/features/payment-methods/ach#testing) page.

## Test European Methods

European payment methods (iDEAL, Bancontact, EPS, Multibanco) can be tested in Test Mode.

<Steps>
  <Step title="Enable test mode">
    Use your Dodo Payments test API keys.
  </Step>

  <Step title="Set billing address">
    Set the billing address country to match the payment method:

    * `NL` for iDEAL
    * `BE` for Bancontact
    * `AT` for EPS
    * `PT` for Multibanco
  </Step>

  <Step title="Set currency">
    European methods require EUR currency.
  </Step>

  <Step title="Complete test flow">
    Follow the simulated bank authentication flow in the test environment.
  </Step>
</Steps>

### Test SEPA Direct Debit IBANs

SEPA Direct Debit requires EUR and a Eurozone billing address. Use these test IBANs to force a specific outcome:

| Test IBAN                | Behavior                                            |
| :----------------------- | :-------------------------------------------------- |
| `DE89370400440532013000` | The payment succeeds.                               |
| `DE62370400440532013001` | The payment fails.                                  |
| `DE35370400440532013002` | The payment succeeds, then is immediately disputed. |
| `DE65370400440002222227` | The payment fails due to insufficient funds.        |

For the full list of test IBANs, including per-country values, see the [Europe](/features/payment-methods/europe#sepa-test-ibans) page.

For complete European payment methods documentation, see the [Europe](/features/payment-methods/europe) page.

## Testing Best Practices

<AccordionGroup>
  <Accordion title="Test all payment scenarios">
    Don't just test successful payments. Test declines, cancellations, and edge cases like insufficient funds.
  </Accordion>

  <Accordion title="Verify webhook handling">
    Ensure your webhook endpoints correctly process all event types, especially `payment.succeeded`, `payment.failed`, and subscription events.

    Use the [Dodo Payments CLI](/developer-resources/sdks/cli#webhooks) to test webhooks locally:

    * `dodo wh listen` forwards live test webhooks to your local server
    * `dodo wh trigger` sends mock payloads for all supported webhook event types
  </Accordion>

  <Accordion title="Test on real devices">
    For Apple Pay and Google Pay, test on actual iOS and Android devices. Simulators don't fully replicate wallet behavior.
  </Accordion>

  <Accordion title="Test regional methods with correct addresses">
    Regional payment methods (UPI, iDEAL, etc.) require matching billing addresses. A US billing address won't show iDEAL.
  </Accordion>

  <Accordion title="Verify minimum amounts">
    BNPL methods require \$50.01 minimum. Test that they correctly appear/hide based on cart total.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup>
  <Card title="Cards" icon="credit-card" href="/features/payment-methods/cards">
    Card testing, 3D Secure, and saved payment methods.
  </Card>

  <Card title="Digital Wallets" icon="wallet" href="/features/payment-methods/digital-wallets">
    Apple Pay, Google Pay, Amazon Pay testing.
  </Card>

  <Card title="BNPL" icon="calendar-days" href="/features/payment-methods/bnpl">
    Klarna, Afterpay, and Billie testing.
  </Card>

  <Card title="India" icon="indian-rupee-sign" href="/features/payment-methods/india">
    UPI and RBI mandate testing.
  </Card>

  <Card title="Europe" icon="euro-sign" href="/features/payment-methods/europe">
    iDEAL, Bancontact, EPS, Multibanco testing.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Set up webhooks for test events.
  </Card>

  <Card title="CLI Webhook Testing" icon="terminal" href="/developer-resources/sdks/cli#webhooks">
    Test webhooks locally with the Dodo Payments CLI.
  </Card>
</CardGroup>


# Create Addon
Source: https://docs.dodopayments.com/api-reference/addons/create-addon

post /addons
Create a new addon product that can be attached to your main subscription products



# Get Addon
Source: https://docs.dodopayments.com/api-reference/addons/get-addon

get /addons/{id}
Retrieve detailed information about a specific addon using its unique identifier



# List Addons
Source: https://docs.dodopayments.com/api-reference/addons/list-addons

get /addons
Retrieve a comprehensive list of all available addons



# Update Addon
Source: https://docs.dodopayments.com/api-reference/addons/update-addon

patch /addons/{id}
Modify the details of an existing addon using its unique identifier



# Update Addon Image
Source: https://docs.dodopayments.com/api-reference/addons/update-addon-images

put /addons/{id}/images
Get a presigned S3 URL to upload an image for an existing addon. Upload the image to the returned URL within 60 seconds.



# List Balance Ledger Entries
Source: https://docs.dodopayments.com/api-reference/balance-ledger/list-ledger-entries

get /balances/ledger
Retrieve a paginated list of balance ledger entries for your account. Use query parameters to filter by date range, event type, currency, or reference object.



# Create Brand
Source: https://docs.dodopayments.com/api-reference/brands/create-brand

post /brands
Create a new brand.



# Get Brand
Source: https://docs.dodopayments.com/api-reference/brands/get-brand

get /brands/{id}
Retrieve a specific brand by ID.



# List Brands
Source: https://docs.dodopayments.com/api-reference/brands/list-brands

get /brands
List all brands.



# Update Brand
Source: https://docs.dodopayments.com/api-reference/brands/update-brand

patch /brands/{id}
Update an existing brand's details.



# Update Brand Image
Source: https://docs.dodopayments.com/api-reference/brands/update-brand-images

put /brands/{id}/images
Get a presigned S3 URL to upload an image for a brand. Upload the image to the returned URL within 60 seconds.



# Create Credit Entitlement
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/create-credit-entitlement

post /credit-entitlements
Creates a new credit entitlement for the authenticated business



# Create Ledger Entry
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/create-ledger-entry

post /credit-entitlements/{credit_entitlement_id}/balances/{customer_id}/ledger-entries
Creates a ledger entry to credit or debit a customer's balance



# Delete Credit Entitlement
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/delete-credit-entitlement

delete /credit-entitlements/{id}
Soft-deletes a credit entitlement by its ID



# Get Credit Entitlement
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/get-credit-entitlement

get /credit-entitlements/{id}
Retrieves a specific credit entitlement by its ID



# Get Customer Balance
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/get-customer-balance

get /credit-entitlements/{credit_entitlement_id}/balances/{customer_id}
Gets a specific customer's balance for a credit entitlement



# List Balances
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/list-balances

get /credit-entitlements/{credit_entitlement_id}/balances
Lists all customer balances for a specific credit entitlement



# List Credit Entitlements
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/list-credit-entitlements

get /credit-entitlements
Lists all credit entitlements for the authenticated business with pagination support



# List Customer Grants
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/list-customer-grants

get /credit-entitlements/{credit_entitlement_id}/balances/{customer_id}/grants
Lists credit grants for a customer under a specific credit entitlement



# List Customer Ledger
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/list-customer-ledger

get /credit-entitlements/{credit_entitlement_id}/balances/{customer_id}/ledger
Lists ledger entries for a customer under a specific credit entitlement



# Undelete Credit Entitlement
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/undelete-credit-entitlement

post /credit-entitlements/{id}/undelete
Restores a previously deleted credit entitlement



# Update Credit Entitlement
Source: https://docs.dodopayments.com/api-reference/credit-entitlements/update-credit-entitlement

patch /credit-entitlements/{id}
Updates an existing credit entitlement with partial data



# Create Customer
Source: https://docs.dodopayments.com/api-reference/customers/create-customer

post /customers
Create a new customer in your Dodo Payments account.



# Create Customer Portal Session
Source: https://docs.dodopayments.com/api-reference/customers/create-customer-portal-session

post /customers/{customer_id}/customer-portal/session
Create a session of the Customer Portal for a specific customer.



# Delete Payment Method
Source: https://docs.dodopayments.com/api-reference/customers/delete-payment-method

delete /customers/{customer_id}/payment-methods/{payment_method_id}
Delete a payment method associated with a customer.

Remove a saved payment method from a customer's account. Use this to clean up outdated or unwanted payment methods.

<Warning>
  You cannot delete a payment method that is in use by an active subscription. The API returns `409 Conflict` with `Payment method is in use by an active subscription`. Move the subscription to another payment method first using [Update Payment Method](/api-reference/subscriptions/update-payment-method), then delete the old one.
</Warning>

A successful delete returns `204 No Content`.

## Use Cases

* **Customer request**: Remove a payment method the customer no longer wants on file
* **Expired cards**: Clean up payment methods with expired card details
* **Security**: Remove compromised payment methods immediately


# List Payment Methods
Source: https://docs.dodopayments.com/api-reference/customers/get-customer-payment-methods

get /customers/{customer_id}/payment-methods
List all payment methods associated with a specific customer.



# List Customer Wallets
Source: https://docs.dodopayments.com/api-reference/customers/get-customer-wallets

get /customers/{customer_id}/wallets
Retrieve monetary wallet balances associated with a specific customer. Wallets hold real funds in a supported currency (USD, EUR, or GBP) that can be applied to invoices and subscription payments.



# List Customer Wallet Ledger Entries
Source: https://docs.dodopayments.com/api-reference/customers/get-customer-wallets-ledger-entries

get /customers/{customer_id}/wallets/ledger-entries
List wallet ledger entries (fund additions and deductions) for a specific customer. Supports pagination and currency filter.



# List Customers
Source: https://docs.dodopayments.com/api-reference/customers/get-customers

get /customers
Get a list of all customers associated with your account.



# Get Customer Detail
Source: https://docs.dodopayments.com/api-reference/customers/get-customers-1

get /customers/{customer_id}
Get detailed information about a specific customer.



# List Customer Credit Entitlements
Source: https://docs.dodopayments.com/api-reference/customers/list-customer-credit-entitlements

get /customers/{customer_id}/credit-entitlements
Get all credit entitlements for a customer along with their current balances.



# List Customer Entitlements
Source: https://docs.dodopayments.com/api-reference/customers/list-customer-entitlements

get /customers/{customer_id}/entitlements
Get all entitlement grants that have been delivered to, or are still in flight for, a customer.



# Update Customer
Source: https://docs.dodopayments.com/api-reference/customers/patch-customer

patch /customers/{customer_id}
Update a customer's information.



# Create Customer Wallet Ledger Entry
Source: https://docs.dodopayments.com/api-reference/customers/post-customer-wallets-ledger-entries

post /customers/{customer_id}/wallets/ledger-entries
Add or deduct monetary funds in a customer's wallet. Use entry_type 'credit' to add funds or 'debit' to deduct funds. Wallet balances are real money in a supported currency (USD, EUR, or GBP) that can be applied to subscription invoices.



# Add Discount Customers
Source: https://docs.dodopayments.com/api-reference/discounts/add-discount-customers

post /discounts/{discount_id}/customers
Idempotently attach customers to a discount's allowlist, which backs a customer_eligibility of specific.



# Delete Discount
Source: https://docs.dodopayments.com/api-reference/discounts/delete-discount

delete /discounts/{discount_id}
Delete a discount from your account.



# List Discount Customers
Source: https://docs.dodopayments.com/api-reference/discounts/list-discount-customers

get /discounts/{discount_id}/customers
Get a paginated list of the customers attached to a discount's allowlist.



# Remove Discount Customer
Source: https://docs.dodopayments.com/api-reference/discounts/remove-discount-customer

delete /discounts/{discount_id}/customers/{customer_id}
Detach a single customer from a discount's allowlist so they are no longer eligible for the discount.



# Update Discount
Source: https://docs.dodopayments.com/api-reference/discounts/update-discount

patch /discounts/{discount_id}
Update a discount in your account.



# List Disputes
Source: https://docs.dodopayments.com/api-reference/disputes/get-disputes

get /disputes
Get a list of all disputes associated with your account.



# Get Dispute Detail
Source: https://docs.dodopayments.com/api-reference/disputes/get-disputes-1

get /disputes/{dispute_id}
Get detailed information about a specific dispute.



# Create Entitlement
Source: https://docs.dodopayments.com/api-reference/entitlements/create-entitlement

post /entitlements
Create a new entitlement of any integration type — License Key, Digital Files, Feature Flag, Discord, GitHub, Telegram, Figma, Framer, or Notion.



# Delete Entitlement
Source: https://docs.dodopayments.com/api-reference/entitlements/delete-entitlement

delete /entitlements/{id}
Soft-delete an entitlement. Existing grants on the entitlement are unaffected.

<Warning>
  Deleting an entitlement is a **soft-delete that hides existing grants from the customer portal**. It does not revoke platform-side access:

  * Grants linked to the entitlement remain in the database and keep their current `status`.
  * Discord roles, GitHub collaborator access, Notion access, Telegram membership, license keys, and digital file URLs stay valid.
  * No `entitlement_grant.revoked` webhook is emitted, and `revoked_at` / `revocation_reason` are not set.

  Customers stop seeing these grants in their customer portal, but their access on the underlying platform continues until the subscription/payment lifecycle revokes it (cancellation, refund) or you revoke each grant manually via [`DELETE /entitlements/{id}/grants/{grant_id}`](/api-reference/entitlements/revoke-grant).

  If you need to fully cut off access, revoke the grants first, then delete the entitlement.
</Warning>


# Delete File
Source: https://docs.dodopayments.com/api-reference/entitlements/delete-file

delete /entitlements/{id}/files/{file_id}
Remove a file from a Digital Files entitlement. The file is deleted from storage and removed from the entitlement's digital_file_ids list.



# Fulfill License Key Grant
Source: https://docs.dodopayments.com/api-reference/entitlements/fulfill-license-key

post /grants/{grant_id}/license-key
Manually fulfill a pending license-key grant by supplying the key value. Inserts the key, delivers it to the customer by email, and transitions the grant to delivered.

<Info>
  Use this endpoint only for grants created under a License Key entitlement with `fulfillment_mode: manual`. The grant must be in `Pending` status with no key attached. See [Manual Fulfillment](/features/license-keys#manual-fulfillment) and the [Manual License Key Fulfillment Integration Guide](/developer-resources/manual-license-key-fulfillment) for the full flow.
</Info>


# Get Entitlement
Source: https://docs.dodopayments.com/api-reference/entitlements/get-entitlement

get /entitlements/{id}
Retrieve a single entitlement with its resolved integration configuration. For Digital Files entitlements, file metadata and presigned download URLs are populated in the response.



# List Customer Grants
Source: https://docs.dodopayments.com/api-reference/entitlements/list-customer-grants

get /customers/{customer_id}/entitlement-grants
List all of a customer's entitlement grants across every entitlement, one row per grant, with optional filters by status and integration type. Feature-flag grants include the typed feature payload.



# List Entitlements
Source: https://docs.dodopayments.com/api-reference/entitlements/list-entitlements

get /entitlements
List all entitlements for your business with optional filtering by integration type.



# List Grants
Source: https://docs.dodopayments.com/api-reference/entitlements/list-grants

get /entitlements/{id}/grants
List all grants for an entitlement, with optional filters by status and customer ID. Each grant carries the per-customer fulfillment state, including license keys and digital file download URLs where applicable.



# Revoke Grant
Source: https://docs.dodopayments.com/api-reference/entitlements/revoke-grant

delete /entitlements/{id}/grants/{grant_id}
Manually revoke a grant. The customer's platform access is removed (for OAuth/bot integrations) and license keys are disabled. Manual revokes use revocation_reason "manual" and are not auto-regranted on subscription renewal.



# Update Entitlement
Source: https://docs.dodopayments.com/api-reference/entitlements/update-entitlement

patch /entitlements/{id}
Update an entitlement's name, description, integration configuration, or metadata.



# Upload File
Source: https://docs.dodopayments.com/api-reference/entitlements/upload-file

post /entitlements/{id}/files
Upload a file to a Digital Files entitlement. Files are streamed to storage; the maximum size is 500 MiB. The returned file ID is appended to the entitlement's digital_file_ids list.



# Activate License
Source: https://docs.dodopayments.com/api-reference/licenses/activate-license

post /licenses/activate
This endpoint allows you to activate a license for the user.

<Info>
  **No API Key Required**: This is a public endpoint that does not require authentication. You can call it directly from client applications, desktop software, or CLIs to activate license keys without exposing your API credentials.
</Info>


# Create License Key
Source: https://docs.dodopayments.com/api-reference/licenses/create-license-key

post /license_keys
Import an existing license key from another system. The key string, customer, and product are all required.

<Info>
  This endpoint imports a key you already have — `key`, `customer_id`, and `product_id` are all required. It does not generate a key value for you. Importing a `key` that already exists returns `409 Conflict`.
</Info>

<Info>
  License keys created or updated through the API do not trigger email notifications to customers. If you need to notify customers about their license key, you must handle that separately in your application.
</Info>


# Deactivate License
Source: https://docs.dodopayments.com/api-reference/licenses/deactivate-license

post /licenses/deactivate
This endpoint allows you to deactivate a license for the user.

<Info>
  **No API Key Required**: This is a public endpoint that does not require authentication. You can call it directly from client applications, desktop software, or CLIs to deactivate license keys without exposing your API credentials.
</Info>


# Get License Key
Source: https://docs.dodopayments.com/api-reference/licenses/get-license-key

get /license_keys/{id}
Retrieve the details of a specific license key by its ID.

<Warning>
  **Deprecated API**: License keys are now managed through the [Entitlements](/features/entitlements/introduction) system. Use [List Customer Grants](/api-reference/entitlements/list-customer-grants) (filter with `integration_type=license_key`) to retrieve a key's grant and its `license_key` details. This endpoint will be removed in a future release.
</Warning>


# Get License Key Instance
Source: https://docs.dodopayments.com/api-reference/licenses/get-license-key-instance

get /license_key_instances/{id}
Retrieve details of a specific license key instance by its ID.



# List License Key Instances
Source: https://docs.dodopayments.com/api-reference/licenses/get-license-key-instances

get /license_key_instances
Retrieve a list of license key instances. Optionally filter by `license_key_id` to scope results to a specific license key, or by `grant_id` to scope to an entitlement grant.



# List License Keys
Source: https://docs.dodopayments.com/api-reference/licenses/list-license-keys

get /license_keys
Retrieve a list of license keys associated with your account.

<Warning>
  **Deprecated API**: License keys are now managed through the [Entitlements](/features/entitlements/introduction) system. Use [List Customer Grants](/api-reference/entitlements/list-customer-grants) to list issued license keys (filter with `integration_type=license_key`); each grant carries its `license_key` details. This endpoint will be removed in a future release.
</Warning>


# Update License Key
Source: https://docs.dodopayments.com/api-reference/licenses/update-license-key

patch /license_keys/{id}
This endpoint allows you to update a license key by its ID.

<Warning>
  **Deprecated API**: License keys are now managed through the [Entitlements](/features/entitlements/introduction) system. Configure activation limits and durations on the [License Key entitlement](/api-reference/entitlements/update-entitlement), and use [Revoke Grant](/api-reference/entitlements/revoke-grant) to disable a customer's key. This endpoint will be removed in a future release.
</Warning>

<Info>
  Updating a license key through the API does not trigger email notifications to the customer.
</Info>


# Update License Key Instance
Source: https://docs.dodopayments.com/api-reference/licenses/update-license-key-instance

patch /license_key_instances/{id}
This endpoint allows you to update a specific license key instance by its ID.



# Validate License
Source: https://docs.dodopayments.com/api-reference/licenses/validate-license

post /licenses/validate
This endpoint allows you to validate a license for the user.

<Info>
  **No API Key Required**: This is a public endpoint that does not require authentication. You can call it directly from client applications, desktop software, or CLIs to validate license keys without exposing your API credentials.
</Info>


# Archive Meter
Source: https://docs.dodopayments.com/api-reference/meters/archive-meter

delete /meters/{id}
Archive a meter by its ID.



# Create Meter
Source: https://docs.dodopayments.com/api-reference/meters/create-meter

post /meters
Create a new meter.



# List Meters
Source: https://docs.dodopayments.com/api-reference/meters/get-meters

get /meters
Get a list of all meters.



# Get Meter
Source: https://docs.dodopayments.com/api-reference/meters/retrieve-meter

get /meters/{id}
Retrieve a meter by its ID.



# Unarchive Meter
Source: https://docs.dodopayments.com/api-reference/meters/unarchive-meter

post /meters/{id}/unarchive
Unarchive a meter by its ID.



# Download Payout Breakup CSV
Source: https://docs.dodopayments.com/api-reference/payouts/download-breakup-csv

get /payouts/{payout_id}/breakup/details/csv
Downloads the complete payout breakup as a CSV file with columns for ledger ID, event type, amounts, and more.



# List Payouts
Source: https://docs.dodopayments.com/api-reference/payouts/get-payouts

get /payouts
Get a list of all payouts associated with your account.



# List Payout Breakup Details
Source: https://docs.dodopayments.com/api-reference/payouts/list-breakup-details

get /payouts/{payout_id}/breakup/details
Returns paginated individual balance ledger entries for a payout, with each entry's amount pro-rated into the payout's currency.



# Retrieve Payout Breakup
Source: https://docs.dodopayments.com/api-reference/payouts/retrieve-breakup

get /payouts/{payout_id}/breakup
Returns the breakdown of a payout by event type (payments, refunds, disputes, fees, etc.) in the payout's currency.



# Archive Product
Source: https://docs.dodopayments.com/api-reference/products/archive-product

delete /products/{id}
Archive a product associated with your account.



# Archive Localized Price
Source: https://docs.dodopayments.com/api-reference/products/delete-products-localized-prices

delete /products/{product_id}/localized-prices/{id}
Archive a localized price rule. Idempotent soft-delete.



# List Products
Source: https://docs.dodopayments.com/api-reference/products/get-products

get /products
Get a list of all products associated with your account.



# Get Product Detail
Source: https://docs.dodopayments.com/api-reference/products/get-products-1

get /products/{id}
Get detailed information about a specific product.



# List Localized Prices
Source: https://docs.dodopayments.com/api-reference/products/get-products-localized-prices

get /products/{product_id}/localized-prices
List the active localized price rules for a product.



# Get Localized Price
Source: https://docs.dodopayments.com/api-reference/products/get-products-localized-prices-id

get /products/{product_id}/localized-prices/{id}
Retrieve a single localized price rule for a product.



# List Short Links
Source: https://docs.dodopayments.com/api-reference/products/get-products-short-links

get /products/short_links
Lists all short links created by the business. Short links provide shortened checkout URLs with custom slugs for your products.



# Update Product
Source: https://docs.dodopayments.com/api-reference/products/patch-products

patch /products/{id}
Update a product's details.



# Update Localized Price
Source: https://docs.dodopayments.com/api-reference/products/patch-products-localized-prices

patch /products/{product_id}/localized-prices/{id}
Update the amount of a localized price rule.



# Create Product
Source: https://docs.dodopayments.com/api-reference/products/post-products

post /products
Create a new product.



# Create Short Link
Source: https://docs.dodopayments.com/api-reference/products/post-products-id-short-links

post /products/{id}/short_links
Creates a short checkout URL with a custom slug for a product. Uses a Static Checkout URL under the hood.



# Create Localized Price
Source: https://docs.dodopayments.com/api-reference/products/post-products-localized-prices

post /products/{product_id}/localized-prices
Create a localized price rule for a product, by currency or by country.



# Update Product Image
Source: https://docs.dodopayments.com/api-reference/products/put-products-images

put /products/{id}/images
Get a presigned S3 URL to upload an image for a product. Upload the image to the returned URL within 60 seconds.



# Unarchive Product
Source: https://docs.dodopayments.com/api-reference/products/unarchive-product

post /products/{id}/unarchive
Unarchive a product associated with your account.



# Upload Product File
Source: https://docs.dodopayments.com/api-reference/products/update-files

put /products/{id}/files
Get a presigned S3 URL to upload a single file for a product. Upload the file to the returned URL within 60 seconds.



# Get Refund Receipt
Source: https://docs.dodopayments.com/api-reference/refunds/get-refund-receipt

get /invoices/refunds/{refund_id}
Get a refund receipt for a refund.



# List Refunds
Source: https://docs.dodopayments.com/api-reference/refunds/get-refunds

get /refunds
Get a list of all refunds associated with your account.



# Get Refund Detail
Source: https://docs.dodopayments.com/api-reference/refunds/get-refunds-1

get /refunds/{refund_id}
Get detailed information about a specific refund.



# Create Refund
Source: https://docs.dodopayments.com/api-reference/refunds/post-refunds

post /refunds
Create a refund for a payment.



# Get Event
Source: https://docs.dodopayments.com/api-reference/usage-events/get-event

get /events/{event_id}
Get an event by its ID.



# Ingest Events
Source: https://docs.dodopayments.com/api-reference/usage-events/ingest-events

post /events/ingest
Ingest events for usage-based billing.



# List Events
Source: https://docs.dodopayments.com/api-reference/usage-events/list-events

get /events
Get a list of all events.



# Create Webhook
Source: https://docs.dodopayments.com/api-reference/webhooks/create-webhook

post /webhooks
Create a new webhook for a business.



# Delete Webhook
Source: https://docs.dodopayments.com/api-reference/webhooks/delete-webhook

delete /webhooks/{webhook_id}
Delete a specific webhook.



# Get Webhook Detail
Source: https://docs.dodopayments.com/api-reference/webhooks/get-details

get /webhooks/{webhook_id}
Get detailed information about a specific webhook.



# Get Webhook Headers
Source: https://docs.dodopayments.com/api-reference/webhooks/get-webhook-headers

get /webhooks/{webhook_id}/headers
Get the headers for a specific webhook.



# List Webhooks
Source: https://docs.dodopayments.com/api-reference/webhooks/list-webhooks

get /webhooks
List all webhooks for a business.



# Update Webhook
Source: https://docs.dodopayments.com/api-reference/webhooks/update-webhook

patch /webhooks/{webhook_id}
Update a specific webhook.



# Update Webhook Headers
Source: https://docs.dodopayments.com/api-reference/webhooks/update-webhook-headers

patch /webhooks/{webhook_id}/headers
Update the headers for a specific webhook.



# Supported Countries
Source: https://docs.dodopayments.com/api-reference/misc/supported-countries

get /checkout/supported_countries
Retrieve a list of countries that are supported by the Dodo Payments for your customers.

<Tip> You will receive a list of [ISO Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes representing the countries we **currently support for payments**. You can view the full list of supported countries [here](/miscellaneous/list-of-countries-we-accept-payments-from). This list is updated regularly as we expand our coverage. </Tip>

<Tip> Note: The available options include ISO Alpha-2 codes for **all countries**, not just the ones we currently support. Please refer to the supported countries list to confirm availability. </Tip>


# Add Products to Group
Source: https://docs.dodopayments.com/api-reference/product-collections/add-group-items

post /product-collections/{id}/groups/{group_id}/items
Add one or more products to a group within a product collection.



# Archive Product Collection
Source: https://docs.dodopayments.com/api-reference/product-collections/archive-product-collection

delete /product-collections/{id}
Archive a product collection associated with your account.



# Create Product Collection Group
Source: https://docs.dodopayments.com/api-reference/product-collections/create-group

post /product-collections/{id}/groups
Add a new group to a product collection.



# Create Product Collection
Source: https://docs.dodopayments.com/api-reference/product-collections/create-product-collection

post /product-collections
Create a new product collection.



# Delete Product Collection Group
Source: https://docs.dodopayments.com/api-reference/product-collections/delete-group

delete /product-collections/{id}/groups/{group_id}
Delete a group from a product collection.



# Delete Group Item
Source: https://docs.dodopayments.com/api-reference/product-collections/delete-group-item

delete /product-collections/{id}/groups/{group_id}/items/{item_id}
Remove a product item from a product collection group.



# Get Product Collection
Source: https://docs.dodopayments.com/api-reference/product-collections/get-product-collection

get /product-collections/{id}
Get detailed information about a specific product collection.



# List Product Collections
Source: https://docs.dodopayments.com/api-reference/product-collections/list-product-collections

get /product-collections
Get a list of all product collections associated with your account.



# Unarchive Product Collection
Source: https://docs.dodopayments.com/api-reference/product-collections/unarchive-product-collection

post /product-collections/{id}/unarchive
Unarchive a product collection associated with your account.



# Update Product Collection Group
Source: https://docs.dodopayments.com/api-reference/product-collections/update-group

patch /product-collections/{id}/groups/{group_id}
Update a group within a product collection.



# Update Group Item
Source: https://docs.dodopayments.com/api-reference/product-collections/update-group-item

patch /product-collections/{id}/groups/{group_id}/items/{item_id}
Update a product item within a product collection group.



# Update Product Collection
Source: https://docs.dodopayments.com/api-reference/product-collections/update-product-collection

patch /product-collections/{id}
Update a product collection's details.



# Update Product Collection Image
Source: https://docs.dodopayments.com/api-reference/product-collections/update-product-collection-images

put /product-collections/{id}/images
Get a presigned S3 URL to upload an image for a product collection. Upload the image to the returned URL within 60 seconds.



# Get Webhook Signing Key
Source: https://docs.dodopayments.com/api-reference/webhooks/get-webhook-signing-key

get /webhooks/{webhook_id}/secret
Get the signing key for a specific webhook.



# Changelog
Source: https://docs.dodopayments.com/changelog/introduction

Track all Dodo Payments releases, new features, improvements, and platform updates. Complete version history with detailed changelogs for each release.

## Version Logs

| Version                         | Release Date       | Highlights                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [v1.112.0](/changelog/v1.112.0) | August 5, 2026     | Discount codes expanded with Amount discounts, `starts_at` scheduling, `customer_eligibility` rules, per-currency options, and `per_customer_usage_limit`, plus a rebuilt native webhooks experience with email alerting, Cash App Pay for subscriptions, SEPA Direct Debit for one-time EUR payments, customer-friendly payment failure messages across 46 unified error codes, payout webhooks, self-service login email change, an enforced setting that lets customers cancel their own subscriptions, a `currency` filter on list payments, a dispute response window extended to 10 days, and new analytics widgets |
| [v1.109.0](/changelog/v1.109.0) | July 21, 2026      | A completely rebuilt Analytics v3 dashboard with real-time revenue, one-click period comparisons, customizable layouts, and shareable chart cards, plus paid trials for subscriptions and checkout, trial-misuse prevention, Payout Accounts for managing multiple bank accounts, product and add-on pricing in any chargeable currency, a new `subscription.update_payment_method` webhook, native social login in the mobile app, `next_billing_date` in checkout preview, `cancel_at_next_billing_date` subscription filter, copy checkout design from test to live, and per-mode product drafts                       |
| [v1.106.0](/changelog/v1.106.0) | July 7, 2026       | Localized Pricing with per-currency and per-country price rules, three new payment methods (Satispay, BLIK, and Klarna for subscriptions), feature flag entitlements, Apple Pay domain registration, editable add-ons at checkout, subscription period extension, and add-on image removal                                                                                                                                                                                                                                                                                                                                |
| [v1.105.0](/changelog/v1.105.0) | June 22, 2026      | Bring Your Own Processor (BYOP), official Rust SDK release, Korean wallets and Przelewy24 payment methods, `brand_id` on every webhook payload, decimal-aware currency handling, higher entitlement limits, branded recovery emails, analytics v2.1, and dashboard polish                                                                                                                                                                                                                                                                                                                                                 |
| [v1.101.0](/changelog/v1.101.0) | June 2, 2026       | Automatic subscription payment retries to recover failed renewal revenue, business-level proration defaults with per-product-collection overrides, and business name collection for B2B invoices                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [v1.99.0](/changelog/v1.99.0)   | May 25, 2026       | Stacked discount codes (up to 20 per checkout, payment, or subscription), seven new customer notification emails for refunds and subscription lifecycle events, checkout payment page overhaul lifting success rates by 2–3%, product form rework with live preview and autosave, and Business Settings redesign                                                                                                                                                                                                                                                                                                          |
| [v1.97.6](/changelog/v1.97.6)   | May 7, 2026        | Entitlements launch with five new fulfilment integrations (Discord, GitHub, Telegram, Framer, Notion), subscription cancellation reasons in the customer portal, configurable INR e-mandate floor, adaptive currency fees inclusive setting, Dodo Payments Desktop app for macOS/Windows/Linux, stablecoin payments (USDC/USDP/USDG), import existing license keys, and require\_phone\_number for checkout sessions                                                                                                                                                                                                      |
| [v1.94.0](/changelog/v1.94.0)   | April 8, 2026      | Abandoned Cart Recovery, Subscription Dunning, discount metadata, recovery webhooks, Pix payments for Brazil, and WeChat Pay for Chinese customers                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [v1.93.0](/changelog/v1.93.0)   | March 28, 2026     | Checkout redesign with improved loading states, net revenue analytics, business-level payment method disabling, payout breakdown, Visa RDR configuration, DoNotBill proration mode, scheduled plan changes, and delete customer payment method API                                                                                                                                                                                                                                                                                                                                                                        |
| [v1.87.0](/changelog/v1.87.0)   | March 9, 2026      | Support for discounts in change plan and minor improvements across the platform                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [v1.86.0](/changelog/v1.86.0)   | March 2, 2026      | Credit-based billing with rollover, overage, and expiration controls, design and theme customization hub, refund\_status and dispute\_status in list payments API, refunds table in customer portal, and copy to live mode for meters                                                                                                                                                                                                                                                                                                                                                                                     |
| [v1.84.0](/changelog/v1.84.0)   | February 20, 2026  | Product-level analytics, Verifi RDR dispute prevention, DodoPayments CLI, customer portal UI revamp, inline checkout payment method updates, Tax ID prefill for checkout sessions, license\_key and email in return URL, customer email update API, and Bun adapter                                                                                                                                                                                                                                                                                                                                                       |
| [v1.81.0](/changelog/v1.81.0)   | February 6, 2026   | Third-party analytics (GA4, GTM, Meta Pixel), checkout theme customization, prevent plan change on payment failure, balance ledger API, and refund\_status in payment response                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [v1.78.0](/changelog/v1.78.0)   | February 2, 2026   | Communication preferences with push notifications, custom fields for checkout sessions, and expanded checkout language support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [v1.75.0](/changelog/v1.75.0)   | January 23, 2026   | Product collections, RevolutPay & Billie for GBP one-time payments, checkout session preview, metadata in change plan requests, invoice\_url in API responses, discount validation endpoint, and enhanced dashboard filtering                                                                                                                                                                                                                                                                                                                                                                                             |
| [v1.70.0](/changelog/v1.70.0)   | December 24, 2025  | Inline checkout support, use existing payment methods for instant checkouts, manage subscription plans from dashboard, generate short payment links, skip success pages with redirect\_immediately, and enable on-demand subscriptions for all businesses                                                                                                                                                                                                                                                                                                                                                                 |
| [v1.67.0](/changelog/v1.67.0)   | December 17, 2025  | Mixed cart checkout for one-time and subscription products, Unified Customer Portal, invoice\_id in Payment Response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [v1.66.0](/changelog/v1.66.0)   | December 8, 2025   | Subscription.updated webhook, minimal address checkout, read-only API keys, UPI AutoPay & RuPay subscriptions for all businesses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [v1.61.5](/changelog/v1.61.5)   | November 17, 2025  | EUR & GBP pricing full rollout, payment method management, metadata in customers and refunds, checkout session feature flags, license key/file indicators, GitHub OAuth, and Featurebase integration                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [v1.56.0](/changelog/v1.56.0)   | October 27, 2025   | Streamlined onboarding, C# SDK launch, webhook verification, Two-Factor Authentication, overlay checkout sessions, and usage-based subscription plan changes                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [v1.53.2](/changelog/v1.53.2)   | September 13, 2025 | Customer credits, enhanced refund details, higher meter limits, license activation context, and \$0 downgrades                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [v1.52.4](/changelog/v1.52.4)   | September 3, 2025  | Usage-Based Billing, public Refund Receipt API, 100% subscription discounts, and checkout session ID in payments                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [v1.51.0](/changelog/v1.51.0)   | August 23, 2025    | Powerful Checkout Sessions API, Metadata in Payments Export, and Subscription Next Billing Date Update                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [v1.47.0](/changelog/v1.47.0)   | August 11, 2025    | Dashboard UI overhaul, discount codes for subscriptions, expanded Adaptive Currency, webhook management API, and product metadata support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [v1.44.0](/changelog/v1.44.0)   | August 3, 2025     | Adaptive Currency, Turkish Language Support, and New Proration Mode                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [v1.43.0](/changelog/v1.43.0)   | July 24, 2025      | Comprehensive Webhooks Upgrade: endpoint management, security, delivery logs, debugging, and monitoring—now fully self-serve in the dashboard                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [v1.38.0](/changelog/v1.38.0)   | July 9, 2025       | Analytics Chart Sharing, Multiple Partial Refunds, Cumulative Revenue Analytics, Context7 Integration, Next.js Adapter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [v1.37.0](/changelog/v1.37.0)   | July 2, 2025       | Enhanced Analytics Dashboard with comprehensive revenue and retention insights, Reports 2.0 with detailed business reporting capabilities                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [v1.34.4](/changelog/v1.34.4)   | June 26, 2025      | Enhanced Dashboard Analytics with comprehensive new metrics across Revenue Analytics, Customer Analytics, and Payment Success Rate Analytics                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [v1.34.0](/changelog/v1.34.0)   | June 18, 2025      | Digital Product Delivery, React Native SDK beta release, new proration modes, adaptive currency for subscriptions, and enhanced verification form management                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [v1.32.0](/changelog/v1.32.0)   | June 9, 2025       | Affiliates with Affonso, multiple webhook support, enhanced fraud prevention, subscription schedule cancellation, and static payment links                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [v1.30.0](/changelog/v1.30.0)   | June 2, 2025       | Support for \$0 payments and 100% discount codes for one-time products, enabled payout threshold for USD wallet, and standardized API error codes                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [v1.27.0](/changelog/v1.27.0)   | May 26, 2025       | Partial Refunds and Multi-Brand Support, enabling merchants to manage multiple brands and websites under a single verified business account                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [v1.25.0](/changelog/v1.25.0)   | May 20, 2025       | Overlay Checkout Beta, a modern TypeScript library for embedded payments, and subscription.plan\_changed webhook event                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [v1.22.0](/changelog/v1.22.0)   | May 9, 2025        | Unified search to the dashboard, support for upgrading and downgrading subscriptions with addons, and comprehensive card information in payment responses                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [v1.21.0](/changelog/v1.21.0)   | May 3, 2025        | Support for addons to subscriptions, enhanced dispute handling, and customer billing details in payment responses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [v1.18.3](/changelog/v1.18.3)   | April 26, 2025     | Subscription Plan Change API, enhanced onboarding guidance, notification preferences center, and improved adaptive currency information                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [v1.16.1](/changelog/v1.16.1)   | April 18, 2025     | Modern verification forms, new Java and Kotlin SDKs, Afterpay/Clearpay integration, and Google Sign-In                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [v1.14.0](/changelog/v1.14.0)   | April 12, 2025     | New European payment methods, subscription billing address updates, and various improvements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [v1.13.0](/changelog/v1.13.0)   | April 9, 2025      | Adaptive Currency Support, MCP Server for AI integration, mobile apps, Custom GPT, and Dodo Dash game                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [v1.11.0](/changelog/v1.11.0)   | March 28, 2025     | Address autofill for checkout page, notifications center, payment link query builder, saved payment methods, and billing currency control                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [v1.10.1](/changelog/v1.10.1)   | March 21, 2025     | Checkout 2.0, configurable payment methods, dynamic tax calculation, and on-demand subscriptions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [v1.7.0](/changelog/v1.7.0)     | March 14, 2025     | Dedicated subscriptions page, enhanced customer details, detailed payout information, official Ruby SDK, and enhanced API filters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [v1.5.0](/changelog/v1.5.0)     | March 7, 2025      | Custom date filter for analytics, new tax category, and various improvements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [v1.4.0](/changelog/v1.4.0)     | March 6, 2025      | Storefront Feature and Amazon Pay Integration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [v1.3.2](/changelog/v1.3.2)     | February 28, 2025  | Teams Feature, enhanced success/failure screens, and minor improvements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [v1.0.0](/changelog/v1.0.0)     | February 23, 2025  | Public release of Dodo Payments with Customer Portal and Customer Portal Session API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [v0.24.0](/changelog/v0.24.0)   | February 15, 2025  | Discount coupons, support for over 25 local payment methods, customizable statement descriptors, and complete UI makeover of the login page                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [v0.22.0](/changelog/v0.22.0)   | February 6, 2025   | Subscription's first payment, UPI QR payment method, tax ID on checkout, dashboard restructure, self-serve onboarding guides, multi-language support                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [v0.20.1](/changelog/v0.20.1)   | January 31, 2025   | Pay What You Want (PWYW) pricing and expanded global payment coverage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [v0.19.0](/changelog/v0.19.0)   | January 24, 2025   | Support for UPI and Indian Rupay cards, PHP SDK release, and product archiving                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [v0.18.0](/changelog/v0.18.0)   | January 20, 2025   | AI chat support, enhanced APIs, inclusive tax pricing, automated country selection, and more                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [v0.16.1](/changelog/v0.16.1)   | January 11, 2025   | Account Summary feature, enhanced API documentation, and improved postal code validation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [v0.15.1](/changelog/v0.15.1)   | January 3, 2025    | Invoice API, subscription webhooks, comprehensive guides, Dodo Wall of Love, and social sharing features                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [v0.14.0](/changelog/v0.14.0)   | December 26, 2024  | License Key Management feature, enhancing security and control for merchants distributing digital products and services                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [v0.13.2](/changelog/v0.13.2)   | December 21, 2024  | Updated Atlas codebase, SDK updates, and minor improvements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [v0.12.0](/changelog/v0.12.0)   | December 17, 2024  | Official SDKs, metadata field, and expanded customer APIs with minor improvements and bug fixes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [v0.11.0](/changelog/v0.11.0)   | December 13, 2024  | Automated emails, webhook event logs, license key generation guide, and various minor improvements and bug fixes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [v0.10.0](/changelog/v0.10.0)   | December 8, 2024   | Open-sourced Atlas demo, feature-request section, webhook request logs API, subscription list API, and various improvements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [v0.1.0](/changelog/v0.1.0)     | November 25, 2024  | Initial release of the Dodo Payments documentation, marking the Beta launch of our product                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |


# v0.10.0 (8 Dec 2024)
Source: https://docs.dodopayments.com/changelog/v0.10.0

Open-sourced Atlas demo, feature-request section, webhook request logs API, subscription list API, and various improvements and bug fixes.

## New Features

* **Open Sourced Atlas**: A demo application written in Next.js to showcase the integration of Dodo Payments. Explore the [GitHub Repository](https://github.com/dodopayments/dodo-checkout-demo) and documentation [here](/developer-resources/integration-guide).
* **Feature-Request Section**: Introduced a feature-request section on the Dodo Payments dashboard to prioritize the product roadmap based on user feedback.
* **Webhook Request Logs API**: Added APIs for listing and detailing webhook request logs.
* **Static Payment Links**: Added more query parameters to the static payment links to provide more flexibility in the checkout process. For more details, click [here](/developer-resources/integration-guide#1-static-payment-links).
* **Subscription List API**: Added an API to fetch all subscriptions. Refer to the [API Reference](/api-reference/subscriptions/get-subscriptions-1) for details.

## Minor Improvements and Bug Fixes

* Enhanced the Product and Subscription API responses with additional parameters.
* Implemented rate limiting for API requests, currently set to 20 requests per second.
* Improved the documentation to be more user-friendly and easier to navigate.
* Various minor bug fixes and improvements.


# v0.11.0 (13 Dec 2024)
Source: https://docs.dodopayments.com/changelog/v0.11.0

Introduced automated emails, webhook event logs, a license key generation guide, and various minor improvements and bug fixes.

## New Features

* **Automated Emails**: Added automated emails for payments, subscriptions, refunds, and disputes to keep merchants and customers informed.
* **Webhook Event Log**: Added webhook event log on Dodo Payments Dashboard to track webhook events and troubleshoot issues. Navigate to `Settings > Webhooks > Webhook Logs` to access the logs.
* **License Key Generation Guide**: Added a new guide to implement license key generation for digital products. Refer to the [guide](/features/license-keys) for more information.

## Minor Improvements and Bug Fixes

* Various minor fixes and improvements.


# v0.12.0 (17 Dec 2024)
Source: https://docs.dodopayments.com/changelog/v0.12.0

Added official SDKs, metadata field, and expanded customer APIs with minor improvements and bug fixes.

## New Features

* **Official SDKs**: Introduced official Dodo Payments SDKs for **Node.js**, **Python**, and **Go**. Refer to the [SDKs](/developer-resources/dodo-payments-sdks) page for more information.
* **Metadata Field**: Added a `Metadata` field for payments and subscriptions to store additional information. Refer to the [Metadata](/api-reference/metadata) page for more details.
* **Customer APIs**: Expanded customer APIs to include the following endpoints. You can now pass `customer_id` in payments and subscriptions to prevent customer duplication:
  * **Create Customer**: [/api-reference/customers/create-customer](/api-reference/customers/create-customer)
  * **Patch Customer**: [/api-reference/customers/patch-customer](/api-reference/customers/patch-customer)

## Minor Improvements and Bug Fixes

* Various minor fixes and improvements.


# v0.13.2 (21 Dec 2024)
Source: https://docs.dodopayments.com/changelog/v0.13.2

Updated Atlas codebase, SDK updates, and minor improvements.

## New Features

* **Atlas**: The [GitHub Repository](https://github.com/dodopayments/dodo-checkout-demo) codebase has been updated to use the [Dodo Payments Node SDK](https://github.com/dodopayments/dodopayments-node).
* **SDK Update**: Bumped our SDK versions to `0.13.2` with fixes and updates.

## Minor Improvements and Bug Fixes

* **Dashboard Toggle**: Improved the Test Mode and Live Mode toggle on the dashboard to enhance UX.
* Various minor fixes and improvements.


# v0.14.0 (26 Dec 2024)
Source: https://docs.dodopayments.com/changelog/v0.14.0

Introduced the License Key Management feature, enhancing security and control for merchants distributing digital products and services.

### New Feature: License Key Management

We are excited to introduce the **License Key Management** feature, designed to help merchants secure their digital products and services by generating, managing, and tracking unique license keys. This feature ensures only authorized users access your products and provides merchants with full control over their license key usage and distribution. Ideal for SaaS businesses and digital product vendors, the tool also includes advanced tracking and revocation capabilities for enhanced security.

For more details, please visit the [License Keys Documentation](/features/license-keys).


# v0.15.1 (4 Jan 2025)
Source: https://docs.dodopayments.com/changelog/v0.15.1

Introducing Invoice API, subscription webhooks, comprehensive guides, Dodo Wall of Love, and social sharing features. Plus, enhanced subscription trial periods and customer identification.

## New Features 🚀

### API Enhancements

* Launched Invoice API, enabling merchants and customers to download invoices using `payment_id`. Visit the [Invoice API](/api-reference/payments/get-invoice) documentation for more details.
* Implemented new `subscription.renewed` webhook event for subscription renewal notifications.

### Platform Updates

* Introduced Dodo Payments [Wall of Love](https://dodopayments.com/wall-of-love), showcasing customer testimonials.
* Added social sharing functionality for successful transactions.
  <img alt="Share Transaction Feature" />
* Released Policy Generator tool for automatic generation of privacy policy, terms of service, and refund policy documents. [Try Policy Generator](https://dodopayments.com/tools/policy-generator).

### Documentation Improvements

* Published comprehensive guides:
  * [Subscription Integration Guide](/developer-resources/subscription-integration-guide)
  * [Webhook Events Guide](/developer-resources/webhooks/intents/webhook-events-guide)

## Improvements and Bug Fixes 🔧

### API Updates

* Added `trial_period_days` parameter to [Create Subscription API](/api-reference/subscriptions/post-subscriptions) to override product-level trial periods.
* Enhanced customer identification logic: now using consistent `customer_id` across payments and subscriptions for the same email.
* Implemented various performance optimizations and fixed minor bugs.


# v0.16.1 (11 Jan 2025)
Source: https://docs.dodopayments.com/changelog/v0.16.1

Added Account Summary feature, enhanced API documentation, and improved postal code validation.

## New Features 🚀

* **Account Summary Feature**: Provides detailed visibility into transaction and payout ledgers.
  <img alt="Account Summary" />
* **Enhanced API Documentation**: Includes comprehensive parameter descriptions and usage examples.

## Improvements and Bug Fixes 🔧

* **Postal Code Validation**: Updated `Zipcode` field validation to support alphanumeric postal codes.
* **System Optimizations**: Implemented various bug fixes and optimizations to improve overall performance.


# v0.18.0 (20 Jan 2025)
Source: https://docs.dodopayments.com/changelog/v0.18.0

Added AI chat support, enhanced APIs, inclusive tax pricing, automated country selection, and more.

## New Features 🚀

* **AI Chat Support**: Now you can chat with our AI assistant to get help with your technical queries or check the documentation more effectively.
  <img alt="Dodo Payments AI Chat Support" />

* **Enhanced APIs**: Added APIs to filter payments, refunds, subscriptions, and disputes based on `customer_id`, time period, and status, providing more flexibility in data retrieval.

* **Inclusive Tax Pricing**: Added support to make the product price inclusive of tax while creating/updating the product. The tax amount will be calculated automatically based on the tax rate.

* **Automated Country Selection**: Implemented IP-based country auto-selection in static payment links. The country will be auto-selected based on the user's IP address when they open the static payment links.

* **Query Parameter Removal**: Query parameters are now removed as soon as the static payment link loads, preventing end customers from changing URL parameters and tampering with the static payment link.

## Improvements and Bug Fixes 🔧

* **Minor Enhancements and Fixes**: Various minor enhancements and fixes to improve overall performance and user experience.


# v0.19.0 (24 Jan 2025)
Source: https://docs.dodopayments.com/changelog/v0.19.0

Added support for UPI and Indian Rupay cards, released PHP SDK, and introduced product archiving.

## New Features 🚀

* **UPI and Indian Rupay Card Support**: Added support for UPI and Indian Rupay cards for processing payments in India, currently limited to one-time purchases only. You can now accept payments from customers using UPI and Rupay cards. Additionally, enabled the creation of products with INR pricing on the Dodo Payments Dashboard.

  <Frame>
    <iframe title="UPI Announcement | Dodo Payments" />
  </Frame>

* **PHP SDK Release**: Launched a new PHP SDK for Dodo Payments, simplifying the integration of Dodo Payments into PHP applications.
  <Card title="View PHP SDK on GitHub →" icon="github" href="https://github.com/dodopayments/dodopayments-php"> Explore the PHP SDK for Dodo Payments on GitHub. </Card>

* **Product Archiving**: Introduced the ability to archive and unarchive products on the Dodo Payments Dashboard, helping manage clutter and maintain a clean interface.

## Improvements and Bug Fixes 🔧

* **Minor Enhancements and Fixes**: Various minor enhancements and fixes to improve overall performance and user experience.


# v0.20.1 (31 Jan 2025)
Source: https://docs.dodopayments.com/changelog/v0.20.1

Introduced Pay What You Want (PWYW) pricing and expands global payment coverage.

## New Features 🚀

* **Pay What You Want (PWYW) Pricing**: Introduced support for PWYW pricing, allowing users to choose any amount they wish to pay. This feature can be found while creating the product. For more details, please refer to the [documentation](/features/pay-what-you-want).

* **Expanded Global Coverage**: Dodo Payments now supports seamless payments from over 150 countries, enhancing global accessibility and convenience for users.
  <Frame>
    <iframe title="Global Coverage Announcement | Dodo Payments" />
  </Frame>

## Improvements and Bug Fixes 🔧

* **Minor Enhancements and Fixes**: Various minor enhancements and fixes to improve overall performance and user experience.


# v0.22.0 (6 Feb 2025)
Source: https://docs.dodopayments.com/changelog/v0.22.0

Introduced subscription's first payment, UPI QR payment method, tax ID on checkout, dashboard restructure, self-serve onboarding guides, multi-language support, invoice PDF makeover, and a centralized help widget.

## New Features 🚀

* **Subscription's First Payment**: The most requested feature is here! Now, there will be a single transaction for the first payment, combining the mandate and the actual subscription amount.

* **UPI QR Payment Method**: Added UPI QR as a payment method for the Indian market, allowing customers to pay using UPI QR codes.

  <img alt="UPI QR Feature" />

* **Tax ID on Checkout**: Customers can now add their Tax ID on the checkout page for invoicing and tax purposes.

* **Dashboard Restructure**: The entire Dodo Payments Dashboard has been restructured to be more intuitive and user-friendly.

* **Self-Serve Onboarding Guides**: New users can now get started with Dodo Payments using self-serve onboarding guides.

* **Multi-Language Support**: Added support for 14+ languages on the checkout page, allowing customers to pay in their preferred language. Supported languages include:

  * English (en)
  * العربية (ar) // Arabic
  * Català (ca) // Catalan
  * 中文 (cn) // Chinese
  * Deutsch (de) // German
  * Español (es) // Spanish
  * Français (fr) // French
  * עברית (he) // Hebrew
  * Italiano (it) // Italian
  * 日本語 (ja) // Japanese
  * Nederlands (nl) // Dutch
  * Polski (pl) // Polish
  * Português (pt) // Portuguese
  * Svenska (sv) // Swedish

  <Frame>
    <iframe title="Language Announcement | Dodo Payments" />
  </Frame>

* **Invoice PDF Makeover**: The invoice PDFs have been given a new, clearer, and more effective design.

* **Centralized Help Widget**: Added a centralized Help widget to streamline and improve support.

  <img alt="Help Widget" />

## Improvements and Bug Fixes 🔧

* **Rate Limiting**: Added rate limiting in the invoice API to prevent abuse and ensure system stability.

* **Metadata in Static Payment Links**: Added support for metadata in static payment links. For more details, refer to the [documentation](/developer-resources/integration-guide#1-static-payment-links).

* **Minor Enhancements and Fixes**: Various minor enhancements and fixes to improve overall performance and user experience.


# v0.24.0 (15 Feb 2025)
Source: https://docs.dodopayments.com/changelog/v0.24.0

Introduced discount coupons, support for over 25 local payment methods, customizable statement descriptors, and a complete UI makeover of the login page.

## New Features 🚀

* Introduced the functionality to create and add Discount Coupons to your products and services. You can create coupons with percentage discounts, set expiry dates, and more. Go to `Dashboard > Sales > Discounts` to create and manage discount coupons.

* Dodo Payments now supports over 25 local payment methods, including Apple Pay, Google Pay, Klarna, Affirm, Cash App, UPI, and all major credit/debit cards. This helps boost conversions and reduce checkout drop-offs.

  <Frame>
    <iframe title="Local Payment Methods Announcement | Dodo Payments" />
  </Frame>

* Added functionality to customize the statement descriptor that appears on your customers' bank statements when they make a payment. You can find the option to customize the statement descriptor under `Dashboard > Business > Business Profile`.

* Complete UI makeover of the Dodo Payments login page.

## Improvements and Bug Fixes 🔧

* Security enhancements, performance improvements, and minor fixes.


# v1.0.0 (23 Feb 2025)
Source: https://docs.dodopayments.com/changelog/v1.0.0

Public release of Dodo Payments with Customer Portal and Customer Portal Session API.

This marks the first changelog since Dodo Payments exited Beta and is now publicly available. 🎉

<Frame>
  <iframe title="Public Announcement | Dodo Payments" />
</Frame>

## New Features 🚀

* **Customer Portal**: Introduced the `Customer Portal` feature, allowing customers to manage their subscriptions, invoices, and payment methods. You can create static or dynamic Customer Portal links for your customers via the Dodo Payments Dashboard or through APIs. On the dashboard, navigate to `Sales > Customers > Share Invite`.

* **Customer Portal Session API**: Added the `Customer Portal Session` API to create a session of the Customer Portal for a specific customer. Note that the session is valid for only 24 hours. Check the [API Reference](/api-reference/customers/create-customer-portal-session) for more details.

* **Others**: Minor improvements and bug fixes.


# v1.10.1 (21 March 2025)
Source: https://docs.dodopayments.com/changelog/v1.10.1

Introduced Checkout 2.0, configurable payment methods, dynamic tax calculation, and on-demand subscriptions.

## New Features 🚀

* **Checkout 2.0**: Introducing a completely redesigned checkout experience featuring:

  * Streamlined, modern interface for improved user experience
  * New Query Collector System that stores parameters in session storage with unique IDs (e.g., `sess_1a2b3c4d`)
  * Persistent data availability throughout the entire checkout flow
  * More enhancements planned for future releases!

  <Frame>
    <img alt="Checkout 2.0" />
  </Frame>

* **Configurable Payment Methods**: New `allowed_payment_method_types` configuration enables merchants to customize available payment options during checkout. See the [Allowed Payment Methods](/features/payment-methods#configuring-payment-methods) documentation for implementation details.

* **Dynamic Tax Calculation**: Real-time calculation of tax rates based on customer billing addresses for more accurate pricing on the static payment links.

* **On-Demand Subscriptions**: New API endpoints for flexible subscription billing (available for select merchants).  Learn more in the [On-Demand Subscriptions](/features/subscription#enabling-on-demand-subscriptions) guide.

* **Additional Updates**:
  * Performance optimizations
  * Bug fixes
  * General system improvements


# v1.101.0 (June 2, 2026)
Source: https://docs.dodopayments.com/changelog/v1.101.0

Automatic subscription payment retries to recover failed renewal revenue, business-level proration defaults with per-product-collection overrides, and business name collection for B2B invoices — plus bug fixes and improvements.

## New Features

### 1. **Subscription Payment Retries**

Failed subscription **renewal** payments can now be retried automatically to recover revenue, with no integration work required. Enable it from **Settings → Recovery**, set a recovery window, and Dodo Payments retries the renewal on a smart schedule until it succeeds or the window closes.

<Frame>
  <img alt="Recovery Settings page with the Enable Payment Retries toggle on and a Recovery window (days) field" />
</Frame>

| Setting                    | Description                                                                  | Default      |
| -------------------------- | ---------------------------------------------------------------------------- | ------------ |
| **Enable Payment Retries** | Automatically retry failed subscription renewal payments to recover revenue. | Off (opt-in) |
| **Recovery window (days)** | How long to keep retrying a failed payment before giving up (1–30).          | 13           |

**How it works**

1. A subscription renewal payment fails and the subscription moves to `on_hold`.
2. If the decline is retryable (a soft decline such as insufficient funds or a temporary network error), the next attempt is scheduled automatically.
3. Retries fire off-session on a back-off schedule, bounded by your recovery window.
4. On the first successful retry, the subscription returns to `active` and the next billing date is advanced as normal.

**Retry schedule**

Retries back off progressively, anchored to the time the failed invoice was created. Up to **8 attempts** are made, as long as they fit inside your recovery window:

| Attempt | Delay after previous |
| ------- | -------------------- |
| 1       | 12 hours             |
| 2       | 24 hours             |
| 3       | 48 hours             |
| 4       | 72 hours             |
| 5       | 96 hours             |
| 6       | 120 hours            |
| 7       | 7 days               |
| 8       | 7 days               |

<Info>
  Only **soft declines** are retried (e.g. insufficient funds, generic decline, processing or network errors). **Hard declines** end the retry chain immediately, since retrying won't change the outcome.
</Info>

This complements the existing recovery tools — **Subscription Dunning** emails the customer to update their payment method, while Payment Retries silently re-attempts the existing one. They work well together.

Learn more: [Subscription Payment Retries](/features/recovery/payment-retries) | [Subscription Dunning](/features/recovery/subscription-dunning)

### 2. **Business Proration Settings**

You can now set **default upgrade & downgrade behavior** once at the business level instead of passing proration parameters on every plan change. These defaults apply whenever a customer changes their plan from the customer portal, and you can **override them per product collection**.

<Frame>
  <img alt="Default upgrade & downgrade behavior settings in the dashboard with separate controls for upgrades, downgrades, and payment failure" />
</Frame>

Each direction (upgrade and downgrade) has two independent controls, plus a shared payment-failure policy:

| Setting                             | Field                                                                       | Default (upgrade)        | Default (downgrade)      |
| ----------------------------------- | --------------------------------------------------------------------------- | ------------------------ | ------------------------ |
| **When the new plan starts**        | `effective_at_on_upgrade` / `effective_at_on_downgrade`                     | `immediately`            | `next_billing_date`      |
| **How the customer is charged**     | `proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade` | `difference_immediately` | `difference_immediately` |
| **If the customer's payment fails** | `on_payment_failure`                                                        | `apply_change`           | `apply_change`           |

**When the new plan starts** (`effective_at`)

| Value               | Behavior                                                                                            |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| `immediately`       | The customer moves to the new plan right away.                                                      |
| `next_billing_date` | The customer stays on their current plan until the next billing date, then switches to the new one. |

**How the customer is charged** (`proration_billing_mode`)

| Value                    | Behavior                                                                           |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `prorated_immediately`   | Charge a prorated amount now, based on the time left in the current billing cycle. |
| `full_immediately`       | Charge the full price of the new plan right now.                                   |
| `difference_immediately` | Charge only the price difference between the new plan and the current one.         |
| `do_not_bill`            | Don't charge anything now. Any adjustment is applied on the next invoice.          |

**If the customer's payment fails** (`on_payment_failure`)

| Value            | Behavior                                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `prevent_change` | Keep the customer on their current plan if the payment doesn't go through.                                  |
| `apply_change`   | Move the customer to the new plan even if the payment doesn't go through. You can collect the amount later. |

**Per-collection overrides**

Every product collection can override any of these defaults. Each field is independent — leave it on **Inherit from business** to follow the business default, or set an explicit value to override it for that collection only.

<Frame>
  <img alt="Upgrade & downgrade behavior override section on a product collection, with each field defaulting to 'Inherit from business'" />
</Frame>

Each setting resolves in this order:

```
per-request value (Change Plan API) → collection field (if set) → business field → system default
```

<Info>
  A per-request value passed to the [Change Plan API](/api-reference/subscriptions/change-plan) (`proration_billing_mode`, `effective_at`, `on_payment_failure`) always takes precedence over both the collection and business defaults. The new settings only change what happens when no explicit value is supplied — which is the case for all customer-portal plan changes.
</Info>

Learn more: [Subscription Upgrade & Downgrade](/developer-resources/subscription-upgrade-downgrade) | [Product Collections](/features/product-collections)

### 3. **Collect Business Name for B2B Invoices**

B2B customers can now have their **legal business name** rendered on the invoice instead of the buyer's personal name. When a valid Tax ID is supplied at checkout, you can also collect the associated `customer_business_name` so the invoice reflects the purchasing entity.

<Frame>
  <img alt="Checkout page with the 'Purchasing as a business' toggle enabled, showing Business Name and Tax ID Number fields" />
</Frame>

When the customer selects **Purchasing as a business** at checkout, they're prompted for both a **Business Name** and a **Tax ID Number**.

The business name appears on the invoice only when **all three** conditions are met:

1. The transaction is B2B (`b2b = true`)
2. A `tax_id` is present
3. A non-empty `customer_business_name` is supplied

Otherwise the customer's personal name is used.

**Collecting it at checkout**

Set `customer_business_name` directly, and/or enable `allow_customer_editing_business_name` to let the customer enter or edit it on the checkout page alongside their Tax ID:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: { email: 'buyer@acme.com' },
  tax_id: 'GB123456789',
  customer_business_name: 'Acme Corp Ltd',
  feature_flags: {
    allow_tax_id: true,
    allow_customer_editing_business_name: true // let the customer enter/edit it
  },
  return_url: 'https://yoursite.com/return'
});
```

**Where it applies**

| Surface           | Field                                                                          | Notes                                                     |
| ----------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Checkout Sessions | `customer_business_name`, `feature_flags.allow_customer_editing_business_name` | Max 250 chars; flag defaults to `false`                   |
| Payments          | `customer_business_name`                                                       | Max 250 chars                                             |
| Subscriptions     | `customer_business_name`                                                       | Set or clear via `PATCH /subscriptions/{subscription_id}` |

<Warning>
  `customer_business_name` cannot be set without a `tax_id`. Sending a business name with no Tax ID is rejected. Clearing the `tax_id` also clears the business name, since the two are coupled on the invoice.
</Warning>

<Note>
  Surrounding whitespace is trimmed, and whitespace-only values are treated as an explicit clear — so stored data always matches what's rendered on the invoice.
</Note>

Learn more: [B2B Payments](/features/b2b-payments) | [Invoice Management](/features/invoice-generation) | [Checkout Session](/developer-resources/checkout-session)

## Bug Fixes & Improvements

* Minor bug fixes and stability improvements across the platform.


# v1.105.0 (June 22, 2026)
Source: https://docs.dodopayments.com/changelog/v1.105.0

Bring Your Own Processor (BYOP), the official Rust SDK release, Korean payment methods (Kakao Pay, Naver Pay, PAYCO) and Przelewy24, brand_id on every webhook payload, decimal-aware currency handling, higher entitlement limits, plus checkout, analytics, and dashboard improvements.

## New Features

### 1. **Bring Your Own Processor (BYOP)**

You can now connect your own payment processor — **Stripe** or **Adyen** — and route payments through it per customer country, while Dodo Payments keeps powering everything on top of the transaction: products, subscriptions, license keys and entitlements, invoicing, the customer portal, and analytics. Countries you don't explicitly route fall back to Dodo as full-service Merchant of Record.

<Frame>
  <img alt="BYOP settings showing the Merchant of Record and Bring Your Own Processor options with a feature comparison" />
</Frame>

Set it up from **Settings → BYOP** in the dashboard: choose a processor, connect your account, define per-country routing rules, and add your own invoice issuer details.

**What changes on a BYOP route**

* **You are the Merchant of Record.** Dodo does **not** calculate or charge tax on BYOP transactions — your own invoice issuer details (business name, tax ID, and address) replace the Dodo block on invoices and refund receipts.
* **Disputes and refunds are handled in your processor.** BYOP disputes are read-only in the Dodo dashboard, since accept/challenge happens inside Stripe or Adyen.
* Payments route through Hyperswitch and currently support **credit and debit cards only**.

**For developers**

Payment and dispute responses now include a `payment_provider` discriminator (`stripe`, `adyen`, or `dodo`) so you can identify how each transaction was routed, and the checkout session preview response returns `is_byop`. The fields are additive — Merchant-of-Record traffic continues to report `payment_provider: dodo`.

Learn more: [Bring Your Own Processor](/features/byop) | [BYOP with Stripe](/features/byop/stripe) | [BYOP with Adyen](/features/byop/adyen)

### 2. **Official Rust SDK Release**

The official **Dodo Payments Rust SDK** is now available as the `dodopayments` crate on crates.io. The launch line is aligned with the Dodo Payments API version series, with `v1.105.0` as the first public API-line release and `v1.106.0` already published with the latest OpenAPI regeneration.

Install it with Cargo:

```bash theme={null}
cargo add dodopayments
```

The SDK requires **Rust 1.75+** and is built for async Rust applications with Tokio and reqwest. It includes:

* Strongly typed request and response models across the Dodo Payments API surface.
* `Client::from_env()` for reading `DODO_PAYMENTS_API_KEY` from the environment.
* Typed pagination helpers, including `get_next_page()` and `into_stream()` for list endpoints.
* Configurable environments and timeouts, including test-mode support.
* Binary response decoding for PDF-style responses such as invoices, payout invoices, and refund invoices.
* A fluent resource-chain builder API for ergonomic Rust call sites.

Learn more: [Rust SDK](/developer-resources/sdks/rust) | [Crates.io](https://crates.io/crates/dodopayments) | [GitHub](https://github.com/dodopayments/dodopayments-rust)

### 3. **New Payment Methods: Korean Wallets & Przelewy24**

Four new local payment methods are now available, expanding coverage in South Korea and Poland.

**South Korea (KRW)** — three Korean wallets surface on KRW checkouts:

| Method        | API type    | Subscriptions      |
| ------------- | ----------- | ------------------ |
| **Kakao Pay** | `kakao_pay` | Yes                |
| **Naver Pay** | `naver_pay` | Yes                |
| **PAYCO**     | `payco`     | No (one-time only) |

The Korean wallets require a billing country of `KR` and `KRW` billing — if your product is priced in another currency, enable Adaptive Currency so the customer is billed in KRW.

**Poland (PLN)** — **Przelewy24 (P24)**, Poland's leading online payment method, now settles in `PLN` (not EUR) and supports one-time payments. Pass `przelewy24` in `allowed_payment_method_types`.

Learn more: [South Korea Payment Methods](/features/payment-methods/south-korea) | [European Payment Methods](/features/payment-methods/europe) | [Payment Methods Overview](/features/payment-methods)

### 4. **`brand_id` on Every Webhook Payload**

Every webhook event payload now includes a `brand_id`, so you can attribute payments, subscriptions, refunds, disputes, license keys, credit ledger entries, entitlement grants, dunning attempts, and abandoned checkouts to a specific brand. Where an entity has no brand of its own, `brand_id` falls back to the business's primary brand.

No integration changes are required — the field is additive and appears automatically on existing webhook endpoints.

Learn more: [Multiple Brands](/features/multi-brands) | [Webhook Events](/developer-resources/webhooks/intents/webhook-events-guide)

### 5. **Decimal-Aware Currency Handling**

Currency handling has been reworked so amounts are computed and displayed with the correct precision for each currency, instead of assuming two decimals everywhere. The **16 zero-decimal currencies** — including **JPY**, **KRW**, **VND**, **CLP**, **XAF**, and **XOF** — are now handled accurately across payments, invoices, payouts, emails, and analytics, and presentment (Adaptive Currency) conversions are precision-aware end to end.

This removes a class of rounding and display errors for zero-decimal currencies and lays the groundwork for additional precisions in the future.

## Improvements

### 6. **Higher Product Entitlement & Credit Limits**

* **Product entitlements** per product raised from **20 to 50**.
* **Credit entitlements** (credits attached to a product) raised from **3 to 5**.

Learn more: [Entitlements](/features/entitlements/introduction) | [Credit-Based Billing](/features/credit-based-billing)

### 7. **Signed Customer Credits in Change Plan Preview**

The change-plan preview now returns `customer_credits` as a **signed** value: **negative** when credits are deducted to offset a charge (typical on upgrades) and **positive** when credits are added (from a downgrade proration refund or a wallet top-up), making it clear whether credits are being used or granted.

Learn more: [Subscription Upgrade & Downgrade](/developer-resources/subscription-upgrade-downgrade)

### 8. **`card_last_four` and `card_network` on List Payments**

The **List Payments** response now includes `card_last_four` and `card_network` on each payment, so you can display card details in lists without fetching each payment individually.

Learn more: [List Payments](/api-reference/payments/get-payments)

### 9. **Branded ACR & Dunning Emails**

Abandoned-cart recovery (ACR) and subscription dunning recovery emails now use the relevant **brand's name and logo** instead of the business default, so the recovery experience matches the brand the customer purchased from.

<Frame>
  <img alt="Subscription dunning recovery email rendered with the purchasing brand's name and logo" />
</Frame>

Learn more: [Subscription Dunning](/features/recovery/subscription-dunning) | [Abandoned Cart Recovery](/features/recovery/abandoned-cart-recovery)

### 10. **Improved Tax ID Validation**

Tax ID validation at checkout has been extended with **notation detection and registry lookup** (via the Tax ID Pro integration), reducing false rejections of valid IDs. The business verification form now includes a **country selector** to prevent Tax ID validation errors, and file uploads are more reliable with a **progress indicator** and a single consolidated error toast.

### 11. **Analytics Improvements**

Dashboard analytics now include corrected subscription MRR, active-subscription counts, and retention/churn calculations.

<Frame>
  <img alt="Revenue analytics with a gross/net toggle and an MRR breakdown" />
</Frame>

* **Page-wise analytics** — new tiles surface revenue and discount performance per checkout page.
* A **gross/net revenue toggle** and an **MRR breakdown** on the revenue view.
* Chart tooltips now show currency and percentage units, including zero-value points.

### 12. **Dashboard & Storefront Polish**

* **Brand filter** added to the product list, with filters combined into a single button and brands lazy-loaded.
* **Product collection, add-on, and credit forms** reworked with create / edit / duplicate flows.
* **Payout settings page** redesigned, with the ability to recover a failed payout to success.
* **Payment-provider badges** (Stripe / Adyen / Dodo) surfaced on the transactions and disputes tables.
* **Storefront** store-banner copy refined.

### Other Fixes & Improvements

* Korean and several other currencies (VND, PYG, XOF, XAF) now default to local currency at checkout.
* Minor bug fixes and stability improvements across the platform.


# v1.106.0 (July 7, 2026)
Source: https://docs.dodopayments.com/changelog/v1.106.0

Localized Pricing with per-currency and per-country price rules, three new payment methods (Satispay, BLIK, and Klarna for subscriptions), feature flag entitlements, Apple Pay domain registration, and editable add-ons at checkout — plus subscription period extension and add-on image removal.

## New Features

### 1. **Localized Pricing**

You can now set **fixed prices per currency or per country** instead of letting exchange rates decide the amount a customer sees. Turn it on by setting a `pricing_mode` on a product, then attach one price rule per market:

<Frame>
  <img alt="Localized Pricing enabled on the product form with By Country selected" />
</Frame>

| Mode          | What it does                                                                | Example                                  |
| ------------- | --------------------------------------------------------------------------- | ---------------------------------------- |
| `by_currency` | One fixed price per currency, regardless of country                         | Everyone paying in EUR sees **€9.99**    |
| `by_country`  | A price specific to a country, even when several countries share a currency | **₹999 in India** on a \$20 base product |

Manage rules through the new `/products/{product_id}/localized-prices` endpoints (create, list, get, patch, archive). Each rule's `amount` is an integer in the currency's smallest unit — a price you set, never a converted value.

When no rule matches, the product keeps its existing behavior: customers in your base currency pay the base price directly, and everyone else is converted through Adaptive Currency. When a rule **does** match, the customer pays **exactly** the amount you set — the Adaptive Currency FX fee is absorbed rather than added on top.

This is the recommended, native way to run **Purchasing Power Parity (PPP)**, charm pricing (€9.99, ¥1000, ₹499), reversible market-entry promotions, and competitive price-matching.

Learn more: [Localized Pricing](/features/localized-pricing) | [Adaptive Currency](/features/adaptive-currency) | [Purchasing Power Parity](/features/purchasing-power-parity)

### 2. **New Payment Methods: Satispay, BLIK & Klarna for Subscriptions**

Three additions expand local coverage in Europe and bring Buy Now, Pay Later to recurring billing.

| Method       | API type   | Region         | Currency | Subscriptions      |
| ------------ | ---------- | -------------- | -------- | ------------------ |
| **Satispay** | `satispay` | Europe (Italy) | EUR      | Yes                |
| **BLIK**     | `blik`     | Poland         | PLN      | No (one-time only) |
| **Klarna**   | `klarna`   | United States  | USD      | **Yes (new)**      |

* **Satispay** surfaces on EUR checkouts for both one-time and subscription payments within the supported amount range.
* **BLIK**, Poland's most popular online payment method (\~60% market share), settles in `PLN` and supports one-time payments.
* **Klarna** can now be used for **subscriptions** on USD checkouts with US billing above the \$50 minimum — previously it was limited to one-time payments.

Learn more: [European Payment Methods](/features/payment-methods/europe) | [Buy Now, Pay Later](/features/payment-methods/bnpl) | [Payment Methods Overview](/features/payment-methods)

### 3. **Feature Flag Entitlements**

A new **feature flag** entitlement type turns Dodo Payments into a billing-aware feature-flag store. Attach a flag like `advanced_reports` to a product, and every paying customer instantly gets a grant your application can check — no external platform, no OAuth, and no delivery step that can fail.

<Frame>
  <img alt="New Feature Flag form with display name, feature ID, description, and metadata key-value entries" />
</Frame>

* On purchase, the grant is created and moves straight to `delivered`. There is no `pending` phase and no customer action.
* The grant carries a typed `feature` payload — `{ "feature_type": "boolean", "feature_id": "advanced_reports" }` — and your application reads `feature_id` to decide what to unlock.
* Cancellation, refund, or manual revoke moves the grant to `revoked`, and the flag disappears automatically.

You can read a customer's grants with the new **`GET /customers/{customer_id}/entitlement-grants`** endpoint (status and integration-type filters, paginated), or keep them in sync via webhooks. Entitlement metadata now also supports a `string | number | boolean` scalar union, so you can attach limits and quotas alongside the flag.

Learn more: [Feature Flag Entitlement](/features/entitlements/feature-flags) | [Entitlements](/features/entitlements/introduction)

### 4. **Apple Pay Domain Registration**

You can now register and verify **your own domains** for Apple Pay directly from the dashboard, enabling one-tap Apple Pay on inline (embedded) checkout hosted on your site.

Set it up from **Settings → Payment Methods**: on the **Apple Pay** row, click **Manage domains**, download the domain-association file, host it on your domain, then register and verify. Domain verification is only required for inline (embedded) checkout — overlay checkout, hosted checkout, and payment links work without it.

<Frame>
  <img alt="Register a domain form with a domain entered" />
</Frame>

<Info>
  Disabling a domain is a kill switch that stops Dodo from offering Apple Pay on that domain at checkout — it does not unregister the domain with Apple.
</Info>

Learn more: [Digital Wallets](/features/payment-methods/digital-wallets)

### 5. **Editable Add-ons at Checkout**

A new `allow_editing_addons` feature flag on checkout sessions lets customers **add or remove add-ons on a subscription product during checkout**, instead of locking the cart to a fixed set of add-ons.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_editing_addons: true // customers can edit add-ons at checkout
  },
  return_url: 'https://yoursite.com/return'
});
```

The flag defaults to `false` and only applies to subscription products.

Learn more: [Checkout Session](/developer-resources/checkout-session) | [Add-ons](/features/addons)

## Improvements & Bug Fixes

### 6. **Extend a Subscription's Period via `PATCH /subscriptions/{subscription_id}`**

`PATCH /subscriptions/{subscription_id}` now accepts `subscription_period_count` and `subscription_period_interval`, so you can **extend** a subscription's current period — for example, to grant extra time. The subscription's expiry (`expires_at`) is recomputed from the new count and interval and persisted.

<Note>
  A subscription's period can only be **increased**, never shortened.
</Note>

Learn more: [Update Subscription](/api-reference/subscriptions/patch-subscriptions)

### 7. **Remove Images From Add-ons**

`PATCH /addons/{id}` now supports clearing an add-on's image by sending `image_id: null`. An explicit `null` removes the image, while omitting the field leaves it unchanged — matching the same convention used by products and product collections.

Learn more: [Update Add-on](/api-reference/addons/update-addon)

### Other Fixes & Improvements

* Minor bug fixes and stability improvements across the platform.


# v1.109.0 (July 21, 2026)
Source: https://docs.dodopayments.com/changelog/v1.109.0

A completely rebuilt Analytics v3 dashboard with real-time revenue, one-click period comparisons, customizable layouts, and shareable chart cards — plus paid trials for subscriptions and checkout, trial-misuse prevention, Payout Accounts for managing multiple bank accounts, product and add-on pricing in any chargeable currency, a new subscription.update_payment_method webhook, and native social login in the mobile app.

## New Features

### 1. **Analytics v3 — A Completely Rebuilt Dashboard**

We completely rebuilt analytics from the ground up. Your dashboard now brings every metric that matters into one place, powered by a new real-time data engine (**Analytics v3**).

<Frame>
  <img alt="Redesigned Home dashboard powered by Analytics v3" />
</Frame>

**Everything in one place**

* **Real-time revenue** — see today's revenue as it comes in, hour by hour.
* **One-click comparisons** — compare any metric against the previous period, like last month, with a single click.
* **Revenue by country** — see exactly which countries your revenue comes from.
* **Payments health** — track failed payments, refunds, and recovery together in one view.
* **Subscription insights** — built-in retention cohorts, MRR, and churn tracking.

Two things we're especially proud of:

1. **Customizable layout.** Drag widgets around and pick which metrics appear — your dashboard, your way. Your layout is saved automatically.
2. **Shareable chart cards.** Click **Share** on any metric, pick a color theme, add your logo, and download a ready-to-post image — perfect for investor updates or team reports, with no design tool needed.

Learn more: [Dashboard Analytics](/features/analytics-and-reporting)

### 2. **Paid Trials for Subscriptions & Checkout**

Trials no longer have to be free. You can now charge a **trial amount** on a subscription product's recurring price, so customers pay a reduced upfront fee for the trial window before the full price kicks in at the first renewal.

<Frame>
  <img alt="Subscription pricing form with a trial duration and an optional trial amount for a paid trial" />
</Frame>

* Set a `trial_amount` alongside `trial_period_days` on a recurring price — a paid trial requires a positive trial period.
* Choose whether checkout discounts apply to the trial charge (`trial_apply_discounts`), so the paid-trial amount can be discounted or charged in full independently of the recurring price.
* Paid trials flow through **checkout** as well: the trial amount is taxed and surfaced in checkout-session calculations and payment-link pricing, with adaptive currency markup applied per currency.

Free trials are unchanged — leaving the trial amount unset keeps the existing behavior where the first charge is `0` and occurs when the trial ends.

Learn more: [Subscriptions](/features/subscription) | [Checkout Session](/developer-resources/checkout-session)

### 3. **Prevent Trial Misuse on Subscriptions**

A new opt-in **Prevent Trial Misuse** setting stops customers from repeatedly claiming trials for the same business. When enabled, a customer who has already redeemed a trial — matched by normalized email (plus-aliases stripped) — is automatically degraded to a **paid, no-trial purchase** instead of receiving a fresh trial.

<Frame>
  <img alt="Prevent Trial Misuse toggle in the Subscriptions settings tab" />
</Frame>

Enable it from the **Subscriptions** tab in dashboard settings. The setting is **off by default**, redemptions are recorded at trial activation (so even a same-day cancel consumes the trial), and existing customers are backfilled from historical trials by email.

Learn more: [Subscriptions](/features/subscription)

### 4. **Payout Accounts**

You can now manage **multiple payout bank accounts** from the dashboard instead of a single fixed account. Add accounts per currency and transfer method, save drafts, resubmit accounts placed on hold, and see the active account and any hold or failure reason inline.

<Frame>
  <img alt="Payouts page showing balance eligible for payout, schedule settings, linked bank accounts, and payout history" />
</Frame>

* The first approved account is activated automatically, and on-hold or failed accounts show the reason inline with a resubmit action.
* Bank verification during business onboarding is now driven by the same payout-accounts flow for a single, consistent experience.

Learn more: [Payouts Process](/features/payouts/payout-structure) | [Balances](/features/account-summary-payout-wallet)

### 5. **Product & Add-on Pricing in Any Chargeable Currency**

Product and add-on **base prices** can now be set in any currency Dodo Payments can charge, not just USD. The pricing forms include a searchable currency selector with country flags, and the most common currencies — **USD, GBP, EUR, and INR** — are pinned to the top of the dropdown.

Everyone outside your base currency is still billed through Adaptive Currency, but you now have full freedom to author prices in the currency that best fits your market.

Learn more: [Products](/features/products) | [Add-ons](/features/addons) | [Adaptive Currency](/features/adaptive-currency)

### 6. **New Webhook: `subscription.update_payment_method`**

A new **`subscription.update_payment_method`** webhook event fires whenever a subscription's payment method changes — for example, when a customer switches to a different saved card. It carries the Subscription payload, so you can keep your records in sync without polling.

The event is additive and appears automatically on existing webhook endpoints.

Learn more: [Webhook Events](/developer-resources/webhooks/intents/webhook-events-guide)

### 7. **Native Social Login in the Mobile App**

The Dodo Payments mobile app now supports **native social login** — sign in with **Google** or **GitHub** through your device's secure system auth session instead of typing an email and password. The OAuth exchange uses **PKCE (S256)** bound to a per-request state nonce, so sign-in is both faster and hardened against code-injection and CSRF. The same flow is also available in the desktop app.

## Improvements & Bug Fixes

### 8. **`next_billing_date` in Checkout Session Preview**

The checkout session **preview** now returns a `next_billing_date` when the cart contains a subscription product, so you can show the upcoming billing date before the subscription is created. It is computed relative to now (`now + trial period` when a trial applies, otherwise `now + one payment frequency`) and is omitted for one-time-only carts.

Learn more: [Previewing Checkout Sessions](/developer-resources/checkout-session) | [Preview Checkout](/api-reference/checkout-sessions/preview)

### 9. **Filter Subscriptions by `cancel_at_next_billing_date`**

`GET /subscriptions` now accepts a **`cancel_at_next_billing_date`** filter, so you can list only the subscriptions scheduled to cancel at the end of their current period (or exclude them).

Learn more: [List Subscriptions](/api-reference/subscriptions/get-subscriptions-1)

### 10. **Copy Checkout Design From Test to Live Mode**

You can now **copy your custom checkout design from test mode to live mode** in one step, extended to cover all design surfaces and storefront branding — no more re-creating your theme by hand when you go live.

Learn more: [Storefront](/features/storefront)

### 11. **Per-Mode Product Drafts**

Product creation now keeps **separate drafts for test and live mode**, with a **Clear Draft** option, so an in-progress product in one mode no longer bleeds into the other. Product and collection form pages also gained header action buttons for quicker saves.

Learn more: [Products](/features/products)

### 12. **All List-API Fields as Selectable Table Columns**

Dashboard tables now expose **every field returned by the underlying list API** as a selectable column, with a scrollable column-visibility menu and humanized labels — so you can surface exactly the data you need without opening each record.

### 13. **Keyboard Accessibility Across Dashboard & Checkout**

We made a broad accessibility pass across the **dashboard, checkout, and checkout SDK**: consistent keyboard access and focus visibility, accessible names on icon controls and inputs, and a unified focus/error convention on form controls, checkboxes, radios, switches, tabs, and buttons.

### Other Fixes & Improvements

* **Fixed a checkout crash** triggered by in-browser page translation (e.g. Google Translate), which could remove DOM nodes React still owned.
* **Improved address autofill** in checkout, rebuilt on the Google Places API (New) so dropdown selections survive blur, keyboard collapse, and repositioning.
* Minor bug fixes and stability improvements across the platform.


# v1.11.0 (28 March 2025)
Source: https://docs.dodopayments.com/changelog/v1.11.0

Introduced address autofill for checkout page, notifications center, payment link query builder, saved payment methods, and billing currency control.

## New Features 🚀

* **Address Autofill**: Streamlined checkout process with smart address field auto-completion based on user input.

  <Frame>
    <img alt="Address Autofill" />
  </Frame>

* **Notifications Center**: Stay informed with a new dedicated notifications tab for important system events and updates.

  <Frame>
    <img alt="Notifications" />
  </Frame>

* **Payment Link Query Builder**: Create and customize payment links more efficiently with our new visual query builder.

  <Frame>
    <img alt="Query Builder" />
  </Frame>

* **Saved Payment Methods**: Enable display of previously used payment methods during checkout by setting `show_saved_payment_methods: true` in payment link configuration.

* **Billing Currency Control**: Enforce specific billing currencies for payment links by setting the `billing_currency` parameter.

* **Improvements**: Various improvements and bug fixes.


# v1.112.0 (August 5, 2026)
Source: https://docs.dodopayments.com/changelog/v1.112.0

Discount codes gain Amount discounts, scheduling, customer eligibility rules, and per-currency options, alongside a rebuilt native webhooks experience with email alerting — plus Cash App Pay for subscriptions, SEPA Direct Debit for one-time EUR payments, customer-friendly payment failure messages, payout webhooks, a self-service login email change, a setting that lets customers cancel their own subscriptions, and a currency filter on list payments.

## New Features

### 1. **Discount Codes: Amount Discounts, Scheduling & Eligibility Rules**

Discount codes are no longer percentage-only. A code can now deduct a fixed amount, start on a schedule, price itself differently per currency, and restrict who is allowed to redeem it.

**Amount discounts**

Set `type` to `flat` to deduct a fixed amount instead of a percentage. The deduction is pooled across the whole cart rather than applied per line item.

| Type       | API value    | Behavior                                                       |
| ---------- | ------------ | -------------------------------------------------------------- |
| Percentage | `percentage` | Reduces the price by a percent, optionally capped per currency |
| Amount     | `flat`       | Deducts a fixed amount, pooled across the cart                 |

<Frame>
  <img alt="Discount code editor with the Amount type selected, showing a flat 500 INR deduction" />
</Frame>

**Per-currency options**

`currency_options` lets one code behave correctly across every currency you sell in. Each entry sets, for a single currency, the maximum discount (the deduction itself for an Amount code, a cap for a Percentage code) and the minimum cart value. An Amount discount requires at least one currency option with a resolvable default; currency options stay optional for Percentage discounts.

**Customer eligibility**

`customer_eligibility` controls who may redeem a code:

| Value        | Who can redeem                                      |
| ------------ | --------------------------------------------------- |
| `any`        | Any customer. This is the default.                  |
| `first_time` | Customers who have not purchased from you before.   |
| `existing`   | Customers who have purchased from you before.       |
| `specific`   | Only customers you attach to the code's allow list. |

<Frame>
  <img alt="Customer eligibility dropdown showing Any, First-time, Existing, and Specific customer options" />
</Frame>

Manage the allow list from the dashboard, or with the new endpoints: `GET /discounts/{discount_id}/customers` to list the attached customers, `POST /discounts/{discount_id}/customers` to attach them, and `DELETE /discounts/{discount_id}/customers/{customer_id}` to detach one.

<Warning>
  A `specific` code starts with **zero** eligible customers and rejects every redemption until you attach customers to it.
</Warning>

**Scheduling and per-customer limits**

Set `starts_at` to schedule a code for a future launch — leaving it unset keeps the code active immediately, and it must fall strictly before `expires_at`. Use `per_customer_usage_limit` to cap how often a single customer can redeem a code, as a separate cap that cannot exceed the overall `usage_limit`.

<Info>
  A minimum cart value is always measured against the cart's original prices, never the running total part-way through a stack. Stacking order therefore never changes whether a minimum is met.
</Info>

Learn more: [Discounts](/features/discount-codes) | [Create Discount](/api-reference/discounts/create-discount)

### 2. **A Rebuilt Webhooks Experience**

The webhooks section of the dashboard has been rebuilt as a native experience, replacing the embedded portal. Everything now lives inside the dashboard with consistent tables, filters, and navigation, and it works properly on mobile.

* **Endpoints** — create and edit endpoints in a side sheet, pick event types from a searchable tree, and view the error rate for the last 24 hours at a glance.
* **Activity and logs** — watch delivery attempts over time on the **Delivery activity** chart, browse delivered messages, and open a **message detail** page to inspect the payload and every delivery attempt with its response code and duration. Each attempt can be replayed from there.
* **Event catalog** — browse every event type Dodo Payments sends, with its schema and an example payload.
* **Endpoint overview** — delivery stats for the last 24 hours, the signing secret to view or rotate, and **Replay history**.
* **Testing** — send an example event to an endpoint to verify your receiver before you go live.
* **Advanced** — throttle delivery, manage the custom headers sent with every request to that endpoint, and edit its transformation.
* **Bulk replay** — on an endpoint, recover failed messages, replay ones that were never dispatched, or replay a filtered range.
* **Email alerting** — a new **Settings** tab where you can list the addresses that should be emailed when deliveries to an endpoint start failing. Separate multiple addresses with commas, and leave it empty to turn alerts off.

<Info>
  This is a dashboard change only. Your existing endpoints, signing secrets, signature verification, event names, and payloads are all unchanged — no integration work is required.
</Info>

Learn more: [Webhooks](/developer-resources/webhooks) | [Webhook Events](/developer-resources/webhooks/intents/webhook-events-guide)

### 3. **Cash App Pay for Subscriptions**

Cash App Pay can now back a recurring subscription, not just a one-time payment. It is available on US checkouts billed in USD, alongside the existing card options.

Learn more: [Digital Wallets](/features/payment-methods/digital-wallets)

### 4. **SEPA Direct Debit**

SEPA Direct Debit is now available across the Eurozone, letting customers pay directly from their bank account instead of using a card. It is offered on EUR checkouts for one-time payments.

<Warning>
  SEPA Direct Debit is not instant. A payment takes **6 business days** to confirm, so do not treat authorization as settlement — fulfill only once the payment reaches a succeeded state.
</Warning>

Learn more: [European Payment Methods](/features/payment-methods/europe)

### 5. **Clearer Payment Failure Messages**

When a payment fails, you and your customer now see purpose-written copy instead of raw processor text. Every failure resolves through a taxonomy of **46 unified error codes**, each mapped to two audiences:

* **You** see a headline plus a recommended action on the payment, so you know whether to ask the customer to retry, contact their bank, or use another card. `error_message` on the Payment object now carries this copy whenever `error_code` is a recognized unified code.
* **Your customer** sees a plain-language explanation on the checkout failure screen, in the Customer Portal, and in dunning emails — for example, *"Your card's security code (CVC) doesn't look right. Please re-enter it and try again."*

<Warning>
  For fraud-sensitive declines — `FRAUDULENT`, `LOST_CARD`, `STOLEN_CARD`, and `PICKUP_CARD` — the customer always sees a generic message so the real reason is never leaked. You still see the true reason, flagged with a warning not to share it.
</Warning>

Learn more: [Transaction Failures](/api-reference/transaction-failures) | [Payments](/features/transactions/payments) | [Get Payment Detail](/api-reference/payments/get-payments-1)

### 6. **Let Customers Cancel Their Own Subscriptions**

**Allow Subscription Cancellation** is now a first-class setting under the **Subscriptions** tab in dashboard settings, and it is enforced end to end. When you turn it off, the Customer Portal disables the cancel button and the API rejects customer-initiated cancellation with a `403` — both the immediate cancel and the "cancel at next billing date" flow. Previously the setting only hid the button, so a determined customer could still cancel through the API.

The setting is **enabled by default**. Your own cancellations through the merchant API and dashboard are never affected, and a customer can always revoke a cancellation they already scheduled.

Learn more: [Customer Portal](/features/customer-portal) | [Subscriptions](/features/subscription)

### 7. **Payout Webhooks**

You now receive webhooks for your own payouts, so you can reconcile them in your accounting systems without polling.

| Event                | Fires when                                                                 |
| -------------------- | -------------------------------------------------------------------------- |
| `payout.created`     | A payout is created, by the automatic payout cycle or off-cycle            |
| `payout.in_progress` | The payout due date arrives and processing starts                          |
| `payout.on_hold`     | The payout is paused or placed under review                                |
| `payout.success`     | The payout to your bank account settles                                    |
| `payout.failed`      | The payout fails, and the amount and fees are credited back to your wallet |

<Note>
  `payout.created` was previously emitted as `payout.not_initiated`. If an existing endpoint filters on `payout.not_initiated`, update the filter to `payout.created` so it keeps matching. The `status` field on the payload still reports `not_initiated` at this stage.
</Note>

Learn more: [Payout Webhooks](/developer-resources/webhooks/intents/payout) | [Payouts Process](/features/payouts/payout-structure)

### 8. **Change Your Login Email From the Dashboard**

You can now change the email address you sign in with, without contacting support. The Account tab has been redesigned and includes a new **Change Email** section, with a **Change email** button that starts the flow.

Verification runs in two steps: we email a code to your **current** address to confirm it is you, then a second code to your **new** address to confirm you control it. Once both are verified:

* Sign in with the new address from then on. The previous address stops working for passwords, magic links, and emailed codes.
* Any linked identity providers, such as Google or GitHub sign-in, are unlinked and must be reconnected.
* Your password, businesses, team access, and verification status are unchanged.
* A notification goes to your previous address so an unexpected change is never silent.

Learn more: [My Account](/miscellaneous/accounts)

### 9. **Analytics: New Widgets and Refinements**

Building on the Analytics v3 rebuild, this release adds new visualizations and sharpens the existing ones.

* **Revenue by country is now a full-width choropleth map**, with the ranked country list beside it, and the card is shareable like the rest.
* **Redrawn trend charts** with crosshair hover, a rolling date pill on the x-axis, and a compact tooltip.
* **New date presets** — **Last 30 days** replaces Last 4 weeks, and **Last 6 months** joins the list.
* **Your filters stick.** The date preset and comparison mode now persist per business and follow you across devices, instead of resetting to the defaults every session.
* **Top customers are identified by name**, falling back to email.
* Revenue by country now returns up to the **top 150** countries.

Learn more: [Dashboard Analytics](/features/analytics-and-reporting)

## Improvements & Bug Fixes

### 10. **Filter Payments by Currency**

`GET /payments` accepts an optional **`currency`** query parameter, so you can list only the payments settled in a given currency — for example `GET /payments?currency=EUR`. The same filter is available on the Payments table in the dashboard.

Learn more: [List Payments](/api-reference/payments/get-payments)

### 11. **Dispute Response Window Extended to 10 Days**

You now have **10 days** to respond to a dispute after it is created, up from 4. The countdown on the dispute in your dashboard and the response deadline returned by the API both reflect the longer window.

Learn more: [Disputes](/features/transactions/disputes)

### 12. **Clearer Payout Bank Account Forms**

Adding a payout bank account is less ambiguous. Field labels, descriptions, and tooltips now adapt to your business type, so account holder and beneficiary name stop reading as duplicates for sole proprietors. Choosing **Other** as your bank lets you type the name freely, the China domestic bank code is labeled as **CNAPS**, and the payouts page stays visible in test mode so you can reach your linked accounts from either mode.

Learn more: [Payouts Process](/features/payouts/payout-structure)

### Other Fixes & Improvements

* **Plan-change credits are reversed when a payment fails.** Proration credits issued during a subscription plan change are no longer left behind if the resulting payment does not succeed.
* **Paid-trial invoices show the trial charge**, not the regular recurring price.
* **Percentage discounts honor the minimum cart value**, measured against the base price rather than the running total, and a discount lock timeout now returns a distinct error code instead of a generic `503`.
* **Deleting an already-removed payment method now succeeds** instead of returning an error, making the call safely idempotent.
* **Fixed the currency used for the India mandate floor** when updating a subscription's payment method.
* **Credit ledger entries beyond the allowed bounds** are rejected with a typed `400` instead of failing later.
* **Pay-what-you-want products support a fixed amount** in shared checkout links, and entitlement IDs are shown in the entitlement detail panel.
* Analytics fixes: lifetime-value series, add-ons included in MRR, no period comparison on all-time ranges, series that stop at the current bucket, and clearer range and comparison labels.
* Minor bug fixes and stability improvements across the platform.


# v1.13.0 (9th April 2025)
Source: https://docs.dodopayments.com/changelog/v1.13.0

New features including Adaptive Currency Support, MCP Server for AI integration, mobile apps, Custom GPT, and Dodo Dash game

## New Features 🚀

* **[Adaptive Currency Support](/features/adaptive-currency)** 💱
  * Automatically display prices in customers' local currencies based on their location.
  * Merchants receive payments in their preferred currency, while customers pay in their local currency.
  * Transparent conversion fee structure ranging from 2% to 4%, depending on the order value.
  * Support for over 25 new currencies has been added:

    * **Middle East**: AED (UAE Dirham), SAR (Saudi Riyal)
    * **Asia Pacific**: AUD (Australian Dollar), CNY (Chinese Yuan), HKD (Hong Kong Dollar), IDR (Indonesian Rupiah), KRW (South Korean Won), SGD (Singapore Dollar), TWD (New Taiwan Dollar)
    * **Europe**: ALL (Albanian Lek), CHF (Swiss Franc), CZK (Czech Koruna), DKK (Danish Krone), EUR (Euro), GBP (British Pound), HUF (Hungarian Forint), NOK (Norwegian Krone), PLN (Polish Zloty), RON (Romanian Leu), RSD (Serbian Dinar), SEK (Swedish Krona), TRY (Turkish Lira)
    * **Americas**: BRL (Brazilian Real), CAD (Canadian Dollar), MXN (Mexican Peso)

    <Frame>
      <img alt="Adaptive Currency" />
    </Frame>

* **[Dodo Payments MCP Server](/developer-resources/mcp-server)** 🤖
  * Introducing the new Model Context Protocol (MCP) Server for seamless AI model integration.
  * Provides a standardized interface for interacting with the DodoPayments API.
  * Simple installation via `npx` or through MCP client integration.
  * Offers a comprehensive tool suite for managing payments, subscriptions, and more.
  * Includes advanced features such as tool filtering and enhanced security controls.

* [Mobile App](/features/mobile-app): Now available for iOS and Android, bringing the complete dashboard experience to your mobile device. Key features include:
  * Real-time notifications for transactions, payouts, and subscription renewals
  * Full dashboard access with revenue tracking and performance graphs
  * Complete subscription and product management capabilities
  * Business operations including test/live mode switching and verification management
  * Developer tools with API key management and webhook monitoring
    Download now on the [App Store](https://apps.apple.com/in/app/dodo-payments/id6743651329) or [Google Play](https://play.google.com/store/apps/details?id=com.dodopayments.app).

* **Custom GPT for Dodo Payments**: Available on the ChatGPT Marketplace, trained on our documentation to assist with technical questions or issues. Access it here, [https://dodo.pe/custom-gpt](https://dodo.pe/custom-gpt)

* **Dodo Dash**: Experience the thrill of our endless runner game, Dodo Dash! Guide a daring dodo bird as it sprints, jumps, and dodges obstacles to survive. Give it a try here, [https://dash.dodopayments.com](https://dash.dodopayments.com).

* Various other bug fixes and improvements have been implemented.


# v1.14.0 (12th April 2025)
Source: https://docs.dodopayments.com/changelog/v1.14.0

Introduced new European payment methods, subscription billing address updates, and various improvements.

## New Features 🚀

* **New European Payment Methods**: We've expanded our payment options with four new European payment methods:

  * **iDEAL** - Netherlands
  * **Bancontact** - Belgium
  * **Przelewy24 (P24)** - Poland
  * **EPS** - Austria

  <Frame>
    <img alt="Supported European Payment Methods" />
  </Frame>

  <Note>
    These payment methods are currently limited to:

    * Euro (EUR) currency only
    * One-time payments only (not available for subscriptions)

    For detailed information about these payment methods, visit our [Payment Methods](/features/payment-methods) documentation.
  </Note>

* **Subscription Billing Address Updates**: Added the ability to update billing addresses for subscriptions through:
  * Customer portal interface
  * Patch subscription API endpoint


# v1.16.1 (18th April 2025)
Source: https://docs.dodopayments.com/changelog/v1.16.1

Introduced modern verification forms, new Java and Kotlin SDKs, Afterpay/Clearpay integration, and Google Sign-In.

## New Features 🚀

* **Modern Verification Forms**: Redesigned the verification forms with a modern, user-friendly interface featuring clearer instructions, improved visual hierarchy, and intuitive form fields for a smoother verification process.

  <Frame>
    <img alt="Verification Forms" />
  </Frame>

* **New Java and Kotlin SDKs**: Released native SDKs for Java and Kotlin to support Android development and enterprise Java applications. The SDKs include comprehensive documentation, sample code, and full support for Dodo Payments features including payments, subscriptions, and refunds. Available on GitHub: [Java SDK](https://github.com/dodopayments/dodopayments-java) and [Kotlin SDK](https://github.com/dodopayments/dodopayments-kotlin).

* **Afterpay/Clearpay Integration**: Added support for Afterpay/Clearpay as a Buy Now, Pay Later (BNPL) payment method, enabling customers to split payments into 4 interest-free installments.

* **Google Sign-In**: Implemented Google Sign-In as a new authentication option, allowing users to log in using their Google accounts. This OAuth 2.0-compliant integration supports both personal and workspace Google accounts for enhanced security and convenience.


# v1.18.3 (26th April 2025)
Source: https://docs.dodopayments.com/changelog/v1.18.3

Introduced Subscription Plan Change API, enhanced onboarding guidance, notification preferences center, and improved adaptive currency information.

## New Features 🚀

* **Subscription Plan Change API**: Launched a new API that enables seamless upgrades or downgrades of subscriptions between different product plans. For implementation details, see the [API reference](/api-reference/subscriptions/change-plan).

* **Enhanced Onboarding Guidance**: Improved sidebar nudges to provide clearer direction on next steps in your Dodo Payments onboarding journey.

  <Frame>
    <img alt="Sidebar Nudges" />
  </Frame>

* **Notification Preferences Center**: Added a dedicated section for managing your notification settings. Access it by clicking the bell icon in the top right corner and then selecting the settings icon.

  <Frame>
    <img alt="Notification Preferences" />
  </Frame>

* **Enhanced Adaptive Currency Information**: Added new fields to the payment response including `settlement_amount`, `settlement_currency`, and `settlement_tax` to provide greater transparency on settlement details.

* **General Improvements**: Various minor enhancements and bug fixes to improve overall platform performance.


# v1.21.0 (3rd May 2025)
Source: https://docs.dodopayments.com/changelog/v1.21.0

Added support for addons to subscriptions, made dispute handling more robust, and added customer billing details to payment responses.

## New Features 🚀

* **Subscription Addons**: Introduced support for addons to subscription products. In the Products section, you'll find a new Addons tab where you can create addons such as "Seats". Once created, you can edit your subscription products to include these addons. This feature is available both on the dashboard and via API.

  * [Create Addon](/api-reference/addons/create-addon)
  * [List Addons](/api-reference/addons/list-addons)
  * [Get Addon](/api-reference/addons/get-addon)
  * [Update Addon](/api-reference/addons/update-addon)
  * [Update Addon Images](/api-reference/addons/update-addon-images)

  With addons, you unlock new billing options such as seat-based billing or variable billing per customer. Get creative with addons to design flexible billing models for your business.

  <Frame>
    <img alt="Addons" />
  </Frame>

* **Enhanced Dispute Management**: Improved dispute handling to be more robust and easier to manage through your Dodo Payments dashboard.

* **Expanded Response Data**: Added customer billing details to payment responses, subscription responses, and webhooks.

* **General Improvements**: Various minor enhancements and bug fixes to improve overall platform performance.


# v1.22.0 (9th May 2025)
Source: https://docs.dodopayments.com/changelog/v1.22.0

Added unified search to the dashboard, added support for upgrading and downgrading subscriptions with addons, and added comprehensive card information to payment responses.

## New Features 🚀

* **Unified Dashboard Search**: We've implemented a powerful search functionality across the entire dashboard. You can now quickly find:

  * **Identifiers**: Payment, Refund, Dispute, Customer, Discount, Product, and Addon IDs
  * **Names**: Products, Addons, and Customers
  * **Contact Information**: Customer Email addresses
  * **Metadata**: Payment and Subscription metadata
  * **Navigation**: All pages within the Dodo Payments dashboard

  <Frame>
    <img alt="Unified Dashboard Search" />
  </Frame>

* **Addons Plan Changes**: Added support for upgrading and downgrading subscriptions that include addons.

* **Expanded Payment Card Details**: Payment responses now include comprehensive card information:
  * `card_issuing_country`: Country where the card was issued
  * `card_last_four`: Last 4 digits of the card number
  * `card_network`: Card network (Visa, Mastercard, etc.)
  * `card_type`: Card type (credit, debit, prepaid)

* **Platform Enhancements**: Various performance optimizations, bug fixes, and minor improvements across the platform.


# v1.25.0 (20th May 2025)
Source: https://docs.dodopayments.com/changelog/v1.25.0

Introduced Overlay Checkout Beta, a modern TypeScript library for embedded payments, and a new subscription.plan_changed webhook event for better subscription lifecycle management.

## New Features 🚀

* **Overlay Checkout Beta**: We're excited to announce the beta release of our new overlay checkout experience. This modern TypeScript library provides a seamless way to integrate our payment overlay into your web application with real-time event handling and customizable themes. Key features include:

  * **Real-time Event Handling**: Listen to checkout events like payment creation, success, and failure
  * **TypeScript Support**: Fully typed APIs for better developer experience
  * **Customizable Themes**: Support for light and dark themes
  * **Browser Compatibility**: Works across all modern browsers including Chrome, Firefox, Safari, Edge, and IE11+
  * **PCI Compliance**: Maintains security standards while providing an embedded experience

  <Frame>
    <img alt="Overlay Checkout Cover Image" />
  </Frame>

  Try it out:

  * Live Demo: [https://atlas.dodopayments.com](https://atlas.dodopayments.com#overlay-checkout)
  * Example Code: [https://github.com/dodopayments/dodo-checkout-demo](https://github.com/dodopayments/dodo-checkout-demo)
  * Integration Guide: [Overlay Checkout Guide](/developer-resources/overlay-checkout)

* **New Subscription Event**: Added support for the `subscription.plan_changed` webhook event that fires whenever a subscription is upgraded, downgraded, or modified. This event provides:

  * Complete subscription details after the change
  * Previous and new plan information
  * Prorated billing adjustments
  * Updated next billing date

  This event complements our existing subscription events (`subscription.active`, `subscription.on_hold`, etc.) to provide comprehensive visibility into the subscription lifecycle.

* **Platform Enhancements**: Various performance optimizations, bug fixes, and minor improvements across the platform.


# v1.27.0 (26th May 2025)
Source: https://docs.dodopayments.com/changelog/v1.27.0

Introduced Partial Refunds and Multi-Brand Support, enabling merchants to manage multiple brands and websites under a single verified business account.

## New Features 🚀

* **Partial Refunds**: We're excited to introduce our new Partial Refunds feature, now available through both our API and Dashboard. This powerful capability allows merchants to process precise refunds for specific components of a payment, whether it's a seat add-on or a portion of a subscription. The feature includes built-in validation to prevent errors and automatically generates refund receipts for your records.
  <Frame>
    <img alt="Partial Refunds Cover Image" />
  </Frame>

* **Multi-Brand Support**: We're launching Multi-Brand Support, enabling you to manage multiple brands and websites under a single verified business account. This feature is ideal for launching new product lines, creating regional microsites, or separating different offerings while maintaining a streamlined operation.

  Key features include:

  * **Rapid Verification**: Most brands are approved within 24 working hours through our streamlined website review process
  * **Branded Checkout Experience**: Customers see the specific brand's logo, name, and descriptor during checkout
  * **Seamless Brand Creation**: Create additional brands through Business Settings ▸ Brands ▸ Add Brand
  * **Detailed Transaction Analytics**: Each transaction clearly indicates its associated brand for better business insights
  * **Simplified Payouts**: All revenue consolidates into your existing account without additional verification requirements

  <Frame>
    <img alt="Multi-Brand Cover Image" />
  </Frame>

  To create additional brands, navigate to Business `Settings ▸ Brands ▸ Add Brand` and complete the required details.

* **Platform Enhancements**: Various performance optimizations, bug fixes, and minor improvements across the platform.


# v1.3.2 (28 Feb 2025)
Source: https://docs.dodopayments.com/changelog/v1.3.2

Introduced the Teams Feature, enhanced success/failure screens, and minor improvements.

## New Features 🚀

* **Teams Feature**: We have introduced the highly requested Teams Feature. Now, you can invite `Editors` and `Viewers` to your Business and collaborate with them seamlessly. To try it out, navigate to the `Business > Teams` section in the Dashboard.

  <Frame>
    <img alt="Teams Feature" />
  </Frame>

* **Enhanced Success/Failure Screens**: The default success and failure screens have been updated for cases where no `redirect_url` is provided. These screens now offer greater visibility to your customers and include an option to download the invoice.

  <Frame>
    <img alt="Success Screens" />
  </Frame>

* **Others**: Minor improvements and bug fixes.


# v1.30.0 (2nd June 2025)
Source: https://docs.dodopayments.com/changelog/v1.30.0

Added support for $0 payments and 100% discount codes for one-time products, enabling free product offerings, payout threshold for USD wallet, and standardized API error codes and messages.

## New Features 🚀

* **Zero-Dollar Payments**: Added support for \$0 payments and 100% discount codes for one-time products, enabling free product offerings and promotional campaigns.

* **Custom Payout Threshold**: Added the ability to set minimum payout amounts for USD wallets, helping merchants optimize payout processing and reduce fees for small transactions. Access this feature at `Payouts ▸ USD Wallet ▸ Edit Payout Threshold`.

  <Frame>
    <img alt="Payout Threshold Cover Image" />
  </Frame>

* **API Standardization**: Implemented standardized API error codes and messages as part of our ongoing API improvement initiative. This enhancement makes the API more consistent and developer-friendly. For detailed information, visit our [Error Codes Documentation](/api-reference/error-codes).

* **Transaction Decline Standardization**: Introduced unified transaction decline codes and messages, providing clearer insights into failure reasons and distinguishing between user errors and system issues. Learn more in our [Transaction Failures Documentation](/api-reference/transaction-failures).


# v1.32.0 (9th June 2025)
Source: https://docs.dodopayments.com/changelog/v1.32.0

Added support for Affiliates with Affonso, multiple webhook support, enhanced fraud prevention, subscription schedule cancellation, and static payment links.

## New Features 🚀

* **Affiliate Program Integration**: Launched integration with Affonso, enabling you to create and manage affiliate programs directly through Dodo Payments. Track referrals, handle commissions, and grow your revenue with trusted affiliate partnerships. Learn more in our [Affiliates](/features/affiliates) documentation.
  <Frame>
    <img alt="Affiliates Cover Image" />
  </Frame>

* **Multiple Webhook Support**: Enhanced webhook capabilities to support multiple endpoints, allowing you to send event notifications to different systems simultaneously.

* **Enhanced Fraud Prevention**: Added a new business setting to force 3D Secure authentication for all transactions, helping reduce fraud and chargebacks.

* **Subscription Schedule Cancellation**: Introduced the ability to schedule subscription cancellations to take effect at the end of the billing period, available through our API.

* **Static Payment Links**: Added two more query params for static payment links:
  * `paymentCurrency`: Specifies the payment currency. Default is set as per the billing country.
  * `showCurrencySelector`: Shows the currency selector. Default is true.


# v1.34.0 (18th June 2025)
Source: https://docs.dodopayments.com/changelog/v1.34.0

Added Digital Product Delivery, React Native SDK beta release, new proration modes, adaptive currency for subscriptions, and enhanced verification form management.

## New Features 🚀

* **Digital Product Delivery**: Streamlined digital product delivery system with automated fulfillment, ensuring customers receive their digital goods immediately after successful payment. Learn more in our [Digital Product Delivery](/features/digital-product-delivery) documentation.

  <Frame>
    <img alt="Digital product delivery configuration interface showing file upload and external link options" />
  </Frame>

* **React Native SDK (Beta)**: Released our React Native SDK in beta, enabling secure payment processing in native Android and iOS apps with customizable UI components and screens. Learn more in our [React Native SDK](/developer-resources/sdks/react-native) documentation.

  <Frame>
    <iframe title="React Native SDK Demo | Dodo Payments" />
  </Frame>

* **New Proration Mode**: Introduced `full_immediately` proration mode, allowing immediate full charges when subscription changes occur, providing more flexible billing options for your business needs.

* **Adaptive Currency for Subscriptions**: Enhanced subscription management with adaptive currency support, automatically adjusting pricing based on customer location and local currency preferences.

* **Instantaneous On-Demand Processing**: Improved processing speed for on-demand charges making it almost instant, reducing transaction times and providing faster payment confirmations.

* **Verification Form Management**: Added comprehensive verification form data viewing capabilities in the Dodo Payments Dashboard verification section, allowing you to review and manage all submitted verification documents in one centralized location.

* **Subscription Cancellation Enhancement**: Implemented subscription cancellation at the end of billing period functionality, now available in both the dashboard and customer portal for improved user experience and billing transparency.

* **General Improvements**: Various minor fixes and performance improvements to enhance overall platform stability and user experience.


# v1.34.4 (26th June 2025)
Source: https://docs.dodopayments.com/changelog/v1.34.4

Enhanced Dashboard Analytics with comprehensive new metrics across three key dashboard sections: Revenue Analytics, Customer Analytics, and Payment Success Rate Analytics.

## New Features 🚀

* **Enhanced Dashboard Analytics**: Completely redesigned the home page analytics with comprehensive new metrics across three key dashboard sections:

  * **Revenue Analytics**

    * Total Revenue overview
    * Daily Revenue tracking
    * Payment count metrics
    * Refund count tracking
    * Payout Received status
    * Top 5 revenue-generating countries
    * Revenue growth rate analysis

    <Frame>
      <img alt="Revenue Analytics dashboard showing comprehensive revenue metrics and country breakdown" />
    </Frame>

  * **Customer Analytics**

    * Average Revenue Per User (ARPU)
    * Active Customers count
    * Customer segmentation (new vs existing)
    * Top 6 customers for current month

    <Frame>
      <img alt="Customer Analytics dashboard displaying ARPU, customer counts, and top customer rankings" />
    </Frame>

  * **Payment Success Rate Analytics**

    * Payment Success Rate metrics
    * Refund Success Rate tracking
    * Failure Reasons breakdown
    * Payments status distribution
    * Monthly Success Rate trends

    <Frame>
      <img alt="Payment Success Rate Analytics showing success rates, failure reasons, and monthly trends" />
    </Frame>


# v1.37.0 (2nd July 2025)
Source: https://docs.dodopayments.com/changelog/v1.37.0

Enhanced Analytics Dashboard with comprehensive revenue and retention insights, Reports 2.0 with detailed business reporting capabilities, and improved subscription management features for better business intelligence and operational efficiency.

## New Features 🚀

### Enhanced Analytics Dashboard

We've expanded the analytics dashboard with comprehensive revenue and retention insights to help you better understand your business performance.

#### Revenue Breakdown Analytics

Track your recurring revenue metrics with detailed breakdowns:

* **Projected ARR**: Annual Recurring Revenue projections with trend analysis
* **MRR Breakdown and Growth Rate**: Monthly Recurring Revenue analysis with month-over-month growth metrics
* **New MRR Chart**: Visual representation of new customer revenue acquisition
* **Expansion MRR Chart**: Tracking revenue growth from existing customer upgrades and expansions
* **Churn MRR Chart**: Monitoring revenue lost from customer cancellations and downgrades
* **Net New MRR Chart**: Net revenue impact combining new, expansion, and churn MRR

<Frame>
  <img alt="Revenue Breakdown dashboard showing projected ARR, MRR breakdown, and growth rates" />
</Frame>

#### Retention Analytics

Monitor customer retention and churn patterns:

* **Customer Churn Rate**: Percentage of customers who cancel their subscriptions
* **Revenue Churn Rate**: Percentage of revenue lost from cancellations and downgrades
* **Churn Rate Trends**: Historical tracking of both customer and revenue churn patterns over time
* **User Retention Matrix**: Cohort analysis showing customer retention rates across different time periods

<Frame>
  <img alt="Retention Analytics dashboard showing customer churn rate, revenue churn rate, and churn rate trends" />
</Frame>

### Reports 2.0

We've completely revamped the reports section with more comprehensive and detailed reporting capabilities. Navigate to **Business > Reports** to access the new reporting suite.

Available reports include:

* **Payment Report**: Detailed record of all processed payments with transaction status tracking
* **Refund Report**: Comprehensive log of all refund activities with detailed refund information
* **Payout Report**: Summary of payouts made to your account
* **Product-wise Sales Report**: Sales performance insights with revenue and business growth metrics
* **Payment Failure Report**: Summary of failed payment attempts with failure reasons
* **Customer Report**: Payment summary organized by customer
* **Disputes Report**: Payment disputes summary with resolution status
* **Account Summary Report**: Complete account overview and summary

<Frame>
  <img alt="Reports 2.0 dashboard showing various report types" />
</Frame>

### Enhanced Payout Reporting

We've added detailed payout reports that provide clear visibility into fees and transaction details for each payout you receive from Dodo Payments. Access these enhanced reports in **Business > Payouts**.

<Frame>
  <img alt="Payout Report dashboard showing detailed payout information" />
</Frame>

### Dodo Payments Remote MCP Server

You can now use the hosted Remote MCP Server at [https://mcp.dodopayments.com](https://mcp.dodopayments.com) for instant MCP integration—no local setup required.

<Frame>
  <iframe title="Using Dodo Payment's Remote MCP Server" />
</Frame>

<Note>
  This is the fastest way to get started with Dodo Payments' MCP integration. No server installation or maintenance needed.
</Note>

<Steps>
  <Step title="Open the Remote MCP Server">
    Visit <a href="https://mcp.dodopayments.com">[https://mcp.dodopayments.com](https://mcp.dodopayments.com)</a> in your browser.
  </Step>

  <Step title="Copy the MCP JSON configuration">
    On the site, copy the MCP JSON configuration provided for your client.
  </Step>

  <Step title="Configure your AI application">
    Paste the configuration into your application's MCP settings (for example, Cursor or Claude).

    <Tip>
      For Cursor, your configuration should look like this:
    </Tip>

    ```json theme={null}
    {
      "mcpServers": {
        "dodopayments_api": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/sse"]
        }
      }
    }
    ```
  </Step>

  <Step title="Complete authentication and environment setup">
    After adding the JSON configuration, a pop-up will prompt you to:

    * Enter your Dodo Payments API key
    * Select the environment (test or live)
    * Select your MCP Client under Configuration Options
  </Step>

  <Step title="Login and Approve">
    * Click the Login and Approve button
  </Step>

  <Step title="Verify successful connection">
    Once setup is complete, you'll see a success screen.

    <Check>
      You're now ready to use the Dodo Payments MCP server!
    </Check>
  </Step>
</Steps>

### Additional Improvements

* Various minor improvements and bug fixes for enhanced stability and performance


# v1.38.0 (9th July 2025)
Source: https://docs.dodopayments.com/changelog/v1.38.0

Analytics Chart Sharing, Multiple Partial Refunds, Cumulative Revenue Analytics, Context7 Integration, Next.js Adapter

## New Features 🚀

### Analytics Chart Sharing

Share your analytics charts as images with customizable branding options. Click the share button on any chart to generate an image with multiple color variants that match your brand identity.

<Frame>
  <img alt="Analytics chart sharing interface showing share button and color variant options" />
</Frame>

### Multiple Partial Refunds

Process multiple partial refunds for a single payment through both the API and Dodo Payments Dashboard, providing greater flexibility in handling customer refund requests.

### Cumulative Revenue Analytics

Track your business growth with new cumulative revenue charts in the analytics dashboard, offering comprehensive insights into your revenue trends over time.

<Frame>
  <img alt="Cumulative revenue charts displaying revenue growth trends" />
</Frame>

### Next.js Adapter

Easily integrate Dodo Payments into your Next.js application with our official adapter. Set up payment processing in just a few lines of code. You can also use our ready-made LLM prompt with AI coding agents (such as Cursor, Windsurf, Lovable, and others) to automate the integration process.

[View the @dodopayments/nextjs package on npm](https://www.npmjs.com/package/@dodopayments/nextjs)

### Context7 Integration

Access Dodo Payments documentation through Context7 MCP, enabling AI coding agents to leverage comprehensive payment processing context. For detailed information, visit the [Context7 documentation](https://context7.com/llmstxt/dodopayments-llms-full.txt).


# v1.4.0 (6 Mar 2025)
Source: https://docs.dodopayments.com/changelog/v1.4.0

Introduced the Storefront Feature and Amazon Pay Integration.

## New Features 🚀

* **Storefront Feature**: Create a simple, branded, and mobile-friendly online store to showcase both One-Time Payment products and Subscription products. This feature eliminates the complexity of building an entire website, enabling you to quickly offer your products or services online without additional web development efforts.

  <Frame>
    <img />
  </Frame>

* **Amazon Pay Integration**: Added Amazon Pay as a payment method for One-Time Payments.

* **Improvements and Fixes**: Minor improvements and bug fixes.


# v1.43.0 (24th July 2025)
Source: https://docs.dodopayments.com/changelog/v1.43.0

Comprehensive Webhooks Upgrade: endpoint management, security, delivery logs, debugging, and monitoring—now fully self-serve in the dashboard.

## New Features 🚀

### Major Webhooks Upgrade

Gain complete control, visibility, and security with our fully reimagined webhooks system. Explore the new capabilities below.

<Steps>
  <Step title="Endpoint & Subscription Management">
    * Create, edit, pause/resume, and delete webhook endpoints (URLs)
    * Select event types for each endpoint
    * Configure custom headers per endpoint
    * Set rate limits for each endpoint
  </Step>

  <Step title="Secrets & Security">
    * View and rotate signing secrets (HMAC keys) per endpoint
    * Regenerate secrets and view last rotation timestamps
    * Copy code snippets or documentation for signature verification
  </Step>

  <Step title="Delivery History & Debugging">
    * View message logs for each endpoint (status, timestamps)
    * Inspect individual message attempts with request/response bodies and headers
    * Replay (re-send) failed or past messages
    * Filter logs by event type, status code, or time range
  </Step>

  <Step title="Testing & Troubleshooting">
    * Send test events from the portal using mock payloads
    * Inspect payload schemas and view expected fields
  </Step>

  <Step title="Monitoring & Metrics">
    * Track delivery stats: success/failure counts, latency, and recent error trends
    * Monitor endpoint health status (e.g., failing, healthy)
  </Step>
</Steps>

<Check>
  You can now manage, debug, and secure your webhooks with greater flexibility—all from the dashboard.
</Check>


# v1.44.0 (3rd August 2025)
Source: https://docs.dodopayments.com/changelog/v1.44.0

Adaptive Currency, Turkish Language Support, and New Proration Mode

## New Features 🚀

* The Adaptive Currency feature now supports additional currencies, further enhancing localized payment experiences across more regions. Newly supported currencies include:
  * MVR (Maldivian Rufiyaa)
  * MUR (Mauritian Rupee)
  * ZAR (South African Rand)
  * PHP (Philippine Peso)
  * FJD (Fijian Dollar)
  * QAR (Qatari Riyal)
  * MYR (Malaysian Ringgit)

For comprehensive details on Adaptive Currency functionality and its benefits, please visit the [Adaptive Currency documentation](/features/adaptive-currency).

* Turkish language support has been added to the Dodo Payments Checkout Page.

* A new proration mode, `difference_immediately`, has been introduced. This mode charges the difference immediately, irrespective of the remaining time in the billing cycle when changing plans via the API. [Documentation](/developer-resources/subscription-integration-guide).


# v1.47.0 (11th August 2025)
Source: https://docs.dodopayments.com/changelog/v1.47.0

Dashboard UI overhaul, discount codes for subscriptions, expanded Adaptive Currency, webhook management API, and product metadata support.

## New Features 🚀

* **Major Dashboard Enhancements**

  * **Sidebar Navigation:** Now collapsible, allowing you to minimize distractions and focus on your workflow.
  * **Dashboard Search:** Completely redesigned for faster, more relevant results with full keyboard navigation support.
  * **Tables:** Gain more control with the ability to hide or rearrange columns, pin columns left or right, and adjust rows per page for a personalized view.
  * **Transaction Details Page:** Improved layout displays more payment information, including a detailed payment breakdown for full transparency.
  * **UI & Style Updates:** Refined colors, typography, and spacing deliver a cleaner, more consistent user experience.

  <Frame>
    <img alt="Dashboard enhancements including new sidebar, search, and table controls" />
  </Frame>

* **Discount Codes for Subscriptions**\
  You can now apply discount codes to subscriptions, specifying the number of billing cycles the discount should apply. This gives you greater flexibility and control over your pricing strategies.

  <Frame>
    <img alt="Applying discount codes to subscriptions in the dashboard" />
  </Frame>

* **Adaptive Currency Expansion**\
  The Adaptive Currency feature now supports 50+ additional currencies, enabling even more localized payment experiences. See the [Adaptive Currency documentation](/features/adaptive-currency) for the complete list of supported currencies.

* **Webhook Management API**\
  Introduced webhook CRUD APIs, allowing you to programmatically create, update, and manage your webhooks.

* **Product Metadata Support**\
  You can now add metadata to your products, making it easy to store and retrieve additional information for each product.


# v1.5.0 (7 March 2025)
Source: https://docs.dodopayments.com/changelog/v1.5.0

Introduced a custom date filter for analytics, a new tax category, and various improvements.

## Minor Features 🚀

* Added a custom date filter on the home page analytics to view data for a specific date range.

* Introduced `EdTech` as a tax category for products.

* Various minor improvements and bug fixes.


# v1.51.0 (23rd August 2025)
Source: https://docs.dodopayments.com/changelog/v1.51.0

Powerful Checkout Sessions API, Metadata in Payments Export, and Subscription Next Billing Date Update

## New Features 🚀

### Checkout Sessions API

Introducing our new **Checkout Sessions API** - a powerful, hosted checkout solution that provides a complete payment flow for both one-time purchases and subscriptions. This new API replaces the previous Dynamic Links approach with enhanced flexibility and improved user experience.

**Key Benefits:**

* **Simplified Integration**: No need to provide complete billing addresses upfront - we handle missing details automatically
* **Enhanced Customization**: Full control over payment methods, currencies, themes, and feature flags
* **Better UX**: Pre-fill customer information to reduce checkout friction and improve conversion rates
* **Flexible Configuration**: Support for multi-product carts, subscription trials, discount codes, and more

**What's Changed:**

* **Before**: Required complete billing address information when creating payment links
* **Now**: Pass whatever customer information you have available - we'll collect the rest during checkout
* **Migration**: Simple API endpoint change with no additional handling required

<CardGroup>
  <Card title="Get Started with Checkout Sessions" icon="rocket" href="/developer-resources/checkout-session">
    Complete guide with code examples in Node.js, Python, and REST API
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/checkout-sessions/create">
    Full API documentation with live testing
  </Card>
</CardGroup>

### Minor Improvements

* Payments export reports now include metadata for enhanced data analysis.
* You can now update the next billing date for subscriptions directly via the API.


# v1.52.4 (3rd September 2025)
Source: https://docs.dodopayments.com/changelog/v1.52.4

Usage-Based Billing, public Refund Receipt API, 100% subscription discounts, and checkout session ID in payments

## New Features 🚀

### Usage-Based Billing

Bill customers precisely based on actual consumption. Define meters, ingest events, and convert usage into charges automatically.

* **Flexible aggregation**: count, sum (over property), max, last
* **Event filtering**: AND/OR logic with rich comparators to include only relevant events
* **Product linkage**: attach meters to products with price-per-unit and optional free thresholds
* **Analytics**: track trends, event streams, and per-customer consumption

<CardGroup>
  <Card title="Feature Overview" icon="rocket" href="/features/usage-based-billing/introduction">
    Learn the concepts, components, and the end-to-end data flow.
  </Card>

  <Card title="Integration Guide" icon="code" href="/developer-resources/usage-based-billing-guide">
    Step-by-step setup for meters, products, and event ingestion.
  </Card>
</CardGroup>

<Warning>
  Usage-Based Billing is currently in beta.
</Warning>

### 100% Discounts for Subscriptions

Apply a 100% discount for any number of billing cycles to support complimentary periods, sponsorships, or promotional campaigns. Invoices reflect the full discount and proration follows your plan settings.

### Minor Improvements

* Refund Receipt API is now publicly accessible. See the docs: [/api-reference/refunds/get-refund-receipt](/api-reference/refunds/get-refund-receipt).
* Added `checkout session ID` to the Get Payment API response and payment webhooks to help correlate payments with their originating checkout session.


# v1.53.2 (13th September 2025)
Source: https://docs.dodopayments.com/changelog/v1.53.2

Customer wallet balances, enhanced refund details, higher meter limits, license activation context, and $0 downgrades

## New Features 🚀

### Customer Wallet Balances

Wallet balances are now **automatically applied to recurring subscription invoices**, making it easy to:

* Reward loyal customers with promotional funds
* Issue service compensation as wallet balance
* Handle manual adjustments without disrupting billing cycles

<Tip>
  Use customer wallet balances for:

  * Promotional incentives
  * Compensation for service interruptions
  * Prepaid account balances
</Tip>

You can **add or deduct funds from a customer's wallet using the API**, enabling automated workflows for customer support, retention, or loyalty programs.

**Example use cases:**

* Fund a customer's wallet after a successful referral
* Deduct wallet balance as part of a custom upgrade path

Explore the new and updated customer wallet APIs:

* [Get Customer Wallets](/api-reference/customers/get-customer-wallets)
* [List Customer Wallet Ledger Entries](/api-reference/customers/get-customer-wallets-ledger-entries)
* [Create Customer Wallet Ledger Entry for Adding and Deducting Funds](/api-reference/customers/post-customer-wallets-ledger-entries)

<Info>
  Wallet balance application during Checkout will be available in the next release, allowing customers to redeem their wallet funds directly at the point of purchase.
</Info>

## Improvements & Updates ✨

* **Customer details in Get Refund API**\
  The refund retrieval endpoint now returns associated customer information, streamlining reconciliation and support workflows.\
  Learn more: [Get Refund API](/api-reference/refunds/get-refunds-1)

* **Increased meter limit to 50**\
  You can now create up to 50 meters per account, enabling more granular usage tracking across your products and features.\
  Learn more: [Get Meters API](/api-reference/meters/get-meters)

* **Product and customer context in Activate License Key API**\
  License activation responses now include detailed product and customer context, improving entitlement checks and downstream integrations.\
  Learn more: [Activate License Key API](/api-reference/licenses/activate-license)

* **Subscriptions can be downgraded to \$0**\
  You can now downgrade subscriptions to free or \$0 plans, making it easier to support trials, community tiers, and sponsorships.\
  Manage subscriptions: [Update Subscription API](/api-reference/subscriptions/patch-subscriptions)


# v1.56.0 (27 October 2025)
Source: https://docs.dodopayments.com/changelog/v1.56.0

Streamlined onboarding, C# SDK launch, webhook verification, Two-Factor Authentication, overlay checkout sessions, and usage-based subscription plan changes

## New Features 🚀

1. **New Onboarding Experience**\
   Onboarding is now streamlined so you can get started faster and begin accepting payments without unnecessary delays.
   * Faster account activation
   * Simplified verification process

2. **Two-Factor Authentication (2FA)**\
   Enhanced account security with two-factor authentication support. Protect your merchant account and team members with an additional layer of security beyond passwords.
   * Secure your account against unauthorized access
   * Support for authenticator apps
   * Required for sensitive operations

3. **Session Links in Overlay Checkout**\
   Checkout sessions now integrate seamlessly with overlay checkout, providing a smoother embedded payment experience. Create checkout sessions and display them in an overlay without redirecting customers away from your application.

4. **C# SDK**\
   The official Dodo Payments C# SDK is now available, bringing native .NET support for integrating payment functionality into your C# and .NET applications.

   * Full type safety with C# interfaces
   * Async/await support for all API operations
   * Available on NuGet for easy installation

   Learn more: [Dodo Payments SDKs](/developer-resources/dodo-payments-sdks)

5. **Webhook Verification in All SDKs**\
   All SDKs now include built-in webhook verification functions to securely validate incoming webhook events. Powered by the industry-standard [webhooks library](https://github.com/standard-webhooks), these functions make it simple to verify and process webhook payloads.

   Two methods are available:

   * `unwrap()`: Verifies webhook signatures using your webhook secret key for production use
   * `unsafe_unwrap()`: Parses webhook payloads without verification for local testing and development

   To use webhook verification, provide your `DODO_PAYMENTS_WEBHOOK_KEY` when initializing the Dodo Payments client. Both functions automatically parse the webhook payload and extract the event type, making webhook handling more secure and convenient.

***

## Improvements & Updates ✨

* **Update customer name in subscription billing details**\
  Customer names can now be modified directly in subscription billing details, making it easier to correct information or update records.

* **Get Checkout Session API**\
  Retrieve checkout session details programmatically to check status, validate sessions, or integrate with your analytics workflows.

* **Changing plan support for usage-based subscriptions**\
  Subscription plan changes are now fully supported for usage-based billing models, enabling seamless upgrades and downgrades while preserving usage tracking.

* **Tax ID in subscription responses**\
  Tax identification numbers are now included in subscription API responses, improving compliance reporting and invoice generation.

* **Force 3DS flags in APIs**\
  Enhanced 3D Secure control with force 3DS flags now available in checkout session, payment, and subscription APIs for stronger authentication requirements.

* **Filter balance ledger by currency**\
  Dashboard now supports filtering balance ledger entries by currency, simplifying reconciliation for multi-currency operations.

* **Reduced payout threshold to \$50**\
  Merchants can now set payout thresholds as low as \$50, providing more flexibility for smaller businesses and faster access to funds.

* **Minor improvements and bug fixes**\
  General enhancements and stability improvements across the platform.


# v1.61.5 (November 17, 2025)
Source: https://docs.dodopayments.com/changelog/v1.61.5

EUR & GBP pricing full rollout, payment method management, metadata in customers and refunds, checkout session feature flags, license key/file indicators, GitHub OAuth, and Featurebase integration

## New Features 🚀

1. **EUR & GBP Pricing - Full Rollout**\
   Native support for € EUR and £ GBP is now fully rolled out to all businesses worldwide, enabling seamless pricing and payment collection in these major currencies.

   You can now:

   * Price products in € and £
   * Collect payments natively in these currencies
   * Settle directly in € and £ with no forex charges

   <Check>
     Result: Higher success rates and better acceptance across the UK and Europe.
   </Check>

2. **Payment Method Management**\
   Enhanced payment method management capabilities for subscriptions and customers. You can now update payment methods for existing subscriptions and retrieve all payment methods associated with a customer, making it easier to handle expired cards, failed payments, and customer preference changes.

   **Update Payment Methods for Subscriptions:**

   * Update payment methods for active subscriptions without disruption
   * Automatically reactivate `on_hold` subscriptions by updating payment methods
   * Use existing saved payment methods or add new ones
   * Automatic charge creation for remaining dues when reactivating subscriptions

   **Fetch Customer Payment Methods:**

   * List all saved payment methods for a customer
   * Use payment method IDs when updating subscriptions
   * Improve customer experience by showing available payment options

   Learn more: [Update Payment Method API](/api-reference/subscriptions/update-payment-method) | [List Payment Methods API](/api-reference/customers/get-customer-payment-methods)

3. **Metadata Support in Customer and Refund Objects**\
   Metadata is now available on customer and refund objects, expanding your ability to store custom information and integrate with external systems.

   * Attach metadata to customers for CRM integration and custom categorization
   * Store additional context on refunds for better tracking and reporting
   * Maintain consistency with other Dodo Payments objects that support metadata

   Learn more: [Metadata Guide](/api-reference/metadata)

4. **Checkout Session Feature Flags for Customer Editing**\
   New feature flags in checkout sessions give you granular control over what customers can edit during checkout, improving flexibility and user experience.

   * `allow_customer_editing_name`: Enable customers to edit their name
   * `allow_customer_editing_email`: Allow email address modifications
   * `allow_customer_editing_street`: Permit street address editing
   * `allow_customer_editing_city`: Enable city field editing
   * `allow_customer_editing_state`: Allow state/province editing
   * `allow_customer_editing_zipcode`: Enable postal code editing
   * `allow_customer_editing_country`: Permit country selection changes

   These flags provide fine-grained control over the checkout experience, allowing you to customize which fields customers can modify based on your business requirements.

5. **Checkout License Key and File Indicators**\
   The checkout page now displays clear indicators when license keys or digital files are being purchased, improving transparency and customer confidence.
   * Visual indicators for license key purchases
   * Clear file download indicators
   * Enhanced product type visibility during checkout

6. **GitHub OAuth for Login Page**\
   Enhanced authentication options with GitHub OAuth integration, providing developers and technical users with a familiar and secure login method.
   * Sign in with GitHub account
   * Streamlined authentication for developer accounts
   * Additional security layer for team access

7. **Featurebase Integration for Feature Requests and Roadmap**\
   We've integrated Featurebase to provide a better experience for submitting feature requests and tracking our public roadmap.

   * Submit and vote on feature requests
   * View public product roadmap
   * Track feature development status
   * Community-driven prioritization

   Visit our public roadmap: [https://dodopayments.featurebase.app/](https://dodopayments.featurebase.app/)

   Learn more: [Feature Request and Roadmap](/features/feature-request)

8. **Minor improvements and bug fixes**\
   General enhancements and stability improvements across the platform.


# v1.66.0 (December 8, 2025)
Source: https://docs.dodopayments.com/changelog/v1.66.0

Subscription.updated webhook, minimal address checkout, read-only API keys, UPI AutoPay & RuPay subscriptions for all businesses

## New Features 🚀

1. **`subscription.updated` Webhook**\
   A new webhook event that fires on every subscription object update, giving you real-time notifications about any changes to your subscriptions.

   Use this webhook to:

   * Get instant notifications when subscription details change
   * Keep your application state synchronized with Dodo Payments
   * React to subscription updates without polling the API

   <Tip>
     Subscribe to `subscription.updated` to eliminate the need for polling and keep your system in sync with real-time subscription changes.
   </Tip>

   Learn more: [Subscription Webhooks](/developer-resources/webhooks/intents/subscription)

2. **Minimal Address Support in Checkout**

   <Frame>
     <img alt="Minimal Address Support in Checkout" />
   </Frame>

   Reduce checkout friction with the new minimal address collection mode. Instead of collecting full address details, minimal address mode only collects:

   * **Country**: Always required for tax determination
   * **ZIP/Postal code**: Only collected in regions where it's necessary for sales tax, VAT, or GST calculation

   <Check>
     Result: Significantly faster checkout completion with fewer form fields for customers.
   </Check>

   **Enable minimal address:**

   <Tabs>
     <Tab title="Checkout Sessions">
       ```javascript theme={null}
       const session = await client.checkoutSessions.create({
         product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
         minimal_address: true
       });
       ```
     </Tab>

     <Tab title="Static Payment Links">
       Append `minimalAddress=true` to your payment link URL:

       ```
       https://checkout.dodopayments.com/buy/pdt_123?minimalAddress=true
       ```
     </Tab>
   </Tabs>

   <Info>
     By default, checkout continues to collect complete addresses. We'll gradually transition all checkout links to minimal address mode. Enable the feature flag now to start benefiting from reduced checkout friction.
   </Info>

3. **Read-Only API Keys**\
   Create API keys with read-only permissions for safer integrations. When creating a new API key, uncheck **Enable write access** to create a read-only key.

   Read-only keys can:

   * Fetch payment, subscription, and customer data
   * List products and retrieve details
   * Access reports and analytics

   Read-only keys **cannot**:

   * Create or modify payments
   * Update subscriptions
   * Change product configurations

   <Tip>
     Uncheck "Enable write access" for dashboard integrations, analytics tools, and any system that only needs to view data without making changes.
   </Tip>

4. **UPI AutoPay & RuPay Card Subscriptions - Full Rollout**\
   UPI AutoPay and RuPay card subscriptions are now available for all businesses. This enables recurring payments for Indian customers with:

   * **UPI AutoPay**: Automated recurring charges via UPI mandate
   * **RuPay Cards**: Subscription support for India's domestic card network

   <Check>
     Result: Expanded subscription payment options for the Indian market with RBI-compliant mandate handling.
   </Check>

   Learn more: [Subscriptions with RBI-Compliant Mandates](/features/subscription#subscriptions-with-rbi-compliant-mandates)

5. **Plan Change Preview API**\
   A new API endpoint to preview subscription plan changes before committing to them. Get the exact charge amount and see how the subscription will look after the change - without making any actual modifications.

   ```javascript theme={null}
   const preview = await client.subscriptions.previewChangePlan('sub_123', {
     product_id: 'pdt_pro_plan',
     proration_billing_mode: 'prorated_immediately',
     quantity: 1
   });

   console.log('Charge amount:', preview.immediate_charge.summary);
   console.log('New plan details:', preview.new_plan);
   ```

   Use this to:

   * Show customers exactly what they'll pay before confirming upgrades/downgrades
   * Build pricing calculators and plan comparison tools
   * Reduce support tickets by improving pricing transparency

   Learn more: [Preview Plan Change API](/api-reference/subscriptions/preview-change-plan)

6. **General Bug Fixes and Enhancements**\
   This release includes UI polish, performance improvements, and resolves minor bugs for a more reliable, streamlined experience.


# v1.67.0 (December 17, 2025)
Source: https://docs.dodopayments.com/changelog/v1.67.0

Mixed cart checkout for one-time and subscription products, Unified Customer Portal, invoice_id in Payment Response

## New Features 🚀

1. **Mixed Cart Checkout: One-Time and Subscription Products in a Single Cart**\
   Checkout now supports combining both one-time payment products and subscription products in a single cart, unlocking powerful new billing use cases.

   <Frame>
     <img alt="Mixed checkout with one-time and subscription products" />
   </Frame>

   ### What This Enables

   * **Setup fees + subscriptions**: Charge a one-time setup fee alongside a recurring subscription in a single checkout
   * **Bundles with recurring components**: Sell a product (one-time) bundled with ongoing service access (subscription)
   * **Course + membership combos**: Offer a course purchase with an optional community membership subscription
   * **Lifetime + add-on subscriptions**: Combine lifetime product access with optional recurring premium features

   ### How It Works

   Simply add both one-time and subscription products to your checkout session:

   ```javascript theme={null}
   const session = await client.checkoutSessions.create({
     product_cart: [
       // One-time setup fee
       { product_id: 'pdt_setup_fee', quantity: 1 },
       // Monthly subscription
       { product_id: 'pdt_monthly_plan', quantity: 1 }
     ],
     customer: {
       email: 'customer@example.com',
       name: 'Jane Doe'
     },
     return_url: 'https://yourapp.com/success'
   });
   ```

   <Check>
     Result: A single checkout flow that processes the one-time payment and initiates the subscription — reducing friction and increasing conversion rates.
   </Check>

   <Info>
     When mixing product types, the one-time payment is charged immediately while the subscription follows its configured billing cycle (including any trial period you've set).
   </Info>

   Learn more: [Checkout Sessions](/developer-resources/checkout-session)

2. **Unified Customer Portal**

   A new centralized customer portal at [customer.dodopayments.com](https://customer.dodopayments.com) where customers can view and manage all their purchases and subscriptions across different businesses on Dodo Payments.

   <Frame>
     <img alt="Unified Customer Portal" />
   </Frame>

   ### Portal Features

   * **Cross-business visibility**: View all purchases and subscriptions from any business using Dodo Payments in one place
   * **Centralized subscription management**: Manage subscriptions across different merchants from a single dashboard
   * **Unified billing history**: Access invoices and payment history from all your purchases
   * **Single sign-on experience**: Log in once with your email to access purchases from all Dodo Payments merchants

   ### How It Works

   Customers simply visit [customer.dodopayments.com](https://customer.dodopayments.com) and enter their email address. They'll receive a secure login link that grants access to all their purchases across the Dodo Payments ecosystem.

   <Tip>
     The Unified Customer Portal complements business-specific customer portals. Customers can still access individual merchant portals for a branded experience, or use the unified portal for a consolidated view.
   </Tip>

   <Note>
     The unified portal uses the same email-based authentication as business-specific portals, ensuring a consistent and secure experience.
   </Note>

3. **Invoice ID in Payment Response**\
   The Payment response now includes an `invoice_id` field, making it easier to reconcile payments with invoices and integrate with accounting systems.

   ```json theme={null}
   {
     "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
     "status": "succeeded",
     "invoice_id": "inv_2IsUnWGtRKFLxk7xAQeyt",
     "total_amount": 9900,
     "currency": "USD",
     // ... other fields
   }
   ```

   ### Use Cases

   * **Accounting integration**: Directly link payments to invoices in your accounting software
   * **Customer support**: Quickly find the invoice associated with a payment when handling support requests
   * **Reconciliation**: Simplify financial reconciliation by matching payments to invoices programmatically
   * **Compliance**: Maintain accurate records linking payments to their corresponding tax invoices

   <Info>
     The `invoice_id` field uses India-specific invoice IDs when available, ensuring compliance with local invoicing requirements.
   </Info>

   Learn more: [Get Payment Detail API](/api-reference/payments/get-payments-1)

4. **General Bug Fixes and Enhancements**\
   This release includes performance improvements, UI polish, and resolves minor bugs for a more reliable, streamlined experience.


# v1.7.0 (14 March 2025)
Source: https://docs.dodopayments.com/changelog/v1.7.0

Introduced a dedicated subscriptions page, enhanced customer details, detailed payout information, an official Ruby SDK, enhanced API filters, and various minor improvements.

## New Features 🚀

* **Dedicated Subscriptions Page**: Manage customer subscriptions easily with the new dedicated page. Navigate to `Sales > Subscriptions` on the dashboard.

  <Frame>
    <img alt="Subscriptions Page" />
  </Frame>

* **Enhanced Customer Details**: View subscriptions, payments, and refunds for each customer in one place. Go to `Sales > Customers > arrow icon` on the dashboard.

  <Frame>
    <img alt="Customer Details" />
  </Frame>

* **Detailed Payout Information**: Get more insights on payout amounts, cycles, and dates. Visit `Business > Payouts` on the dashboard.

  <Frame>
    <img alt="Payout Information" />
  </Frame>

* **Official Ruby SDK**: Integrate Dodo Payments into your Ruby applications effortlessly. Check out the [Ruby SDK](https://github.com/dodopayments/dodopayments-ruby) for more details.

* **Enhanced API Filters**: Added filters like `customer_id`, `status`, etc., to relevant list APIs. Refer to the API documentation for more information.

* **Minor Improvements and Bug Fixes**: Various other minor improvements and bug fixes have been implemented.


# v1.70.0 (December 24, 2025)
Source: https://docs.dodopayments.com/changelog/v1.70.0

Inline checkout support, use existing payment methods for instant checkouts, manage subscription plans from dashboard, generate short payment links, skip success pages with redirect_immediately, and enable on-demand subscriptions for all businesses

## New Features 🚀

1. **Inline Checkout - Fully Embedded Checkout Experiences (BETA)**

   Embed Dodo Payments checkout directly into your website for a seamless, branded payment experience. Unlike overlay checkout which opens as a modal, inline checkout embeds the payment form directly into your page layout.

   <Frame>
     <img alt="Inline Checkout Cover Image" />
   </Frame>

   ### Benefits

   * **Fully integrated**: Create checkout experiences that blend seamlessly with your website
   * **Custom order summaries**: Build custom UI that syncs with checkout in real-time
   * **Maximum control**: Full control over checkout layout and design
   * **PCI compliant**: Dodo Payments securely handles all sensitive payment information
   * **Real-time sync**: Use SDK events to keep your UI in sync with checkout state

   ### How It Works

   Initialize the SDK with `displayType: 'inline'` and embed checkout in a container element:

   ```typescript theme={null}
   import { DodoPayments } from "dodopayments-checkout";

   // Initialize the SDK for inline mode
   DodoPayments.Initialize({
     mode: "test",
     displayType: "inline",
     onEvent: (event) => {
       if (event.event_type === "checkout.breakdown") {
         // Update your UI with real-time tax and total calculations
         const breakdown = event.data?.message;
       }
     },
   });

   // Open checkout in a specific container
   DodoPayments.Checkout.open({
     checkoutUrl: "https://test.dodopayments.com/session/cks_123",
     elementId: "dodo-inline-checkout" // ID of the container element
   });
   ```

   ### Key Features

   * **Real-time breakdown events**: Receive `checkout.breakdown` events as customers enter their details
   * **Custom order summaries**: Build your own pricing display that updates in real-time
   * **Seamless integration**: Checkout frame handles payment collection while you control the layout
   * **SDK methods**: Use `open()`, `close()`, and `isOpen()` to control checkout programmatically

   <Check>
     Result: Fully integrated checkout experiences that match your brand and provide maximum control over the payment flow.
   </Check>

   <Tip>
     Use inline checkout when you want maximum control over checkout design. Use [overlay checkout](/developer-resources/overlay-checkout) for faster integration with minimal changes to existing pages.
   </Tip>

   Learn more: [Inline Checkout Guide](/developer-resources/inline-checkout)

2. **Create Payments, Subscriptions, and Checkouts Using Existing Payment Methods**\
   Streamline checkout flows by using saved payment methods from existing customers. The new `payment_method_id` parameter allows you to create payments, subscriptions, or checkout sessions using a customer's previously saved payment method.

   ### Benefits

   * **Faster checkout**: Skip payment method collection for returning customers
   * **One-click purchases**: Enable instant purchases with saved payment methods
   * **Subscription management**: Easily create subscriptions using existing payment methods
   * **Improved conversion**: Reduce checkout friction for repeat customers

   ### How It Works

   Use `payment_method_id` when creating checkout sessions, payments, or subscriptions:

   <Tabs>
     <Tab title="Checkout Sessions">
       ```javascript theme={null}
       const session = await client.checkoutSessions.create({
         product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
         customer: {
           customer_id: 'cus_123'
         },
         payment_method_id: 'pm_abc123',
         confirm: true
       });
       ```
     </Tab>

     <Tab title="One-Time Payments">
       ```javascript theme={null}
       const payment = await client.payments.create({
         product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
         customer: { customer_id: 'cus_123' },
         billing: { country: 'US' },
         payment_method_id: 'pm_abc123'
       });
       ```
     </Tab>

     <Tab title="Subscriptions">
       ```javascript theme={null}
       const subscription = await client.subscriptions.create({
         customer: { customer_id: 'cus_123' },
         billing: { country: 'US' },
         product_id: 'pdt_subscription',
         quantity: 1,
         payment_method_id: 'pm_abc123'
       });
       ```
     </Tab>
   </Tabs>

   <Warning>
     When using `payment_method_id` in checkout sessions, `confirm` must be set to `true`, and an existing `customer_id` must be provided. The payment method will be validated for eligibility with the payment's currency.
   </Warning>

   <Info>
     The payment method must belong to the customer and be compatible with the payment currency. If validation fails, the request will return an error.
   </Info>

3. **Subscription Plan Changes in Dashboard with Next Billing Date Updates**

   Manage subscription plans directly from the dashboard with enhanced control. You can now change subscription plans and update the next billing date in a single action, giving you complete flexibility over subscription management.

   <Frame>
     <img alt="Subscription plan changes in dashboard" />
   </Frame>

   ### Dashboard Features

   * **Plan changes**: Upgrade or downgrade subscriptions with a single click
   * **Billing date control**: Update the next billing date when changing plans
   * **Proration options**: Choose how to handle proration when changing plans
   * **Visual preview**: See exactly how plan changes affect billing before confirming

   ### Use Cases

   * **Customer support**: Quickly adjust subscription plans for customer requests
   * **Promotional upgrades**: Temporarily upgrade customers with specific billing dates
   * **Plan migrations**: Smoothly transition customers between subscription tiers
   * **Billing alignment**: Align billing dates across multiple subscriptions

   <Check>
     Result: Complete subscription management control from the dashboard, reducing the need for API calls for common subscription adjustments.
   </Check>

   <Tip>
     Use the dashboard for quick subscription plan changes, and the API for programmatic subscription management in your application.
   </Tip>

4. **Short Links for Payment URLs**\
   Generate cleaner, more shareable payment links with our new short link feature. Short links provide shortened checkout URLs with custom slugs, making them easier to share with customers or embed on your website.

   <Frame>
     <img alt="Short links feature for payment URLs" />
   </Frame>

   ### Benefits

   * **Cleaner URLs**: Replace long payment URLs with short, branded links
   * **Better trust**: Professional-looking links that build customer confidence
   * **Easier sharing**: Simplified URLs perfect for SMS, email, or social media
   * **Custom slugs**: Create memorable, branded short links for your products

   ### How It Works

   Enable short links when creating checkout sessions or payment links:

   <Tabs>
     <Tab title="Checkout Sessions">
       ```javascript theme={null}
       const session = await client.checkoutSessions.create({
         product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
         short_link: true,
         return_url: 'https://yourapp.com/success'
       });
       ```
     </Tab>

     <Tab title="Payment Links">
       ```javascript theme={null}
       const payment = await client.payments.create({
         product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
         short_link: true,
         return_url: 'https://yourapp.com/success'
       });
       ```
     </Tab>
   </Tabs>

   <Check>
     Result: A shortened payment link that's easier to share and more professional-looking, improving conversion rates and customer trust.
   </Check>

   <Info>
     Short links are managed in your dashboard and can be viewed via the [List Short Links API](/api-reference/products/get-products-short-links).
   </Info>

5. **`redirect_immediately` Flag - Skip Payment Success Page**\
   Control the checkout flow with the new `redirect_immediately` flag. When enabled, customers are redirected immediately after payment completion, bypassing the default success page for a faster, more streamlined experience.

   ### Use Cases

   * **Faster checkout flow**: Reduce friction by skipping intermediate pages
   * **Custom success pages**: Redirect directly to your branded success page
   * **Mobile optimization**: Improve mobile checkout experience with immediate redirects
   * **Embedded checkouts**: Seamlessly integrate with overlay or embedded checkout flows

   ### How It Works

   Enable immediate redirects in checkout sessions, payments, or subscriptions:

<Tabs>
  <Tab title="Checkout Sessions">
    ```javascript theme={null}
    const session = await client.checkoutSessions.create({
      product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
      feature_flags: {
        redirect_immediately: true
      },
      return_url: 'https://yourapp.com/success'
    });
    ```
  </Tab>

  <Tab title="One-Time Payments">
    ```javascript theme={null}
    const payment = await client.payments.create({
      product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
      redirect_immediately: true,
      return_url: 'https://yourapp.com/success'
    });
    ```
  </Tab>

  <Tab title="Subscriptions">
    ```javascript theme={null}
    const subscription = await client.subscriptions.create({
      customer: { customer_id: 'cus_123' },
      billing: { country: 'US' },
      product_id: 'pdt_subscription',
      quantity: 1,
      redirect_immediately: true,
      return_url: 'https://yourapp.com/success'
    });
    ```
  </Tab>
</Tabs>

<Tip>
  Use `redirect_immediately: true` when you have a custom success page that provides better user experience than the default payment success page.
</Tip>

<Note>
  When `redirect_immediately` is enabled, customers are redirected to your `return_url` immediately after payment completion, skipping the default success page entirely.
</Note>

6. **On-Demand Subscriptions - Available for All Businesses**\
   On-demand subscriptions are now enabled for all businesses, giving you flexible billing control for usage-based and metered services.

   ### What This Enables

   * **Usage-based billing**: Create subscriptions and charge customers based on actual usage
   * **Flexible billing cycles**: Charge customers on-demand rather than fixed intervals
   * **Metered services**: Perfect for API usage, storage, compute time, and other metered resources
   * **Manual charge control**: Create charges manually when needed, giving you full control over billing timing

   ### How It Works

   Create an on-demand subscription and charge customers as needed:

   ```javascript theme={null}
   // Create an on-demand subscription
   const subscription = await client.subscriptions.create({
     customer: { customer_id: 'cus_123' },
     billing: { country: 'US' },
     product_id: 'pdt_api_access',
     quantity: 1,
     on_demand: { mandate_only: true }
   });

   // Charge the customer when usage occurs
   await client.subscriptions.charge(subscription.subscription_id, {
     product_price: 4900,
     product_currency: 'USD',
     product_description: 'API usage for September: 1,000 requests'
   });
   ```

   <Check>
     Result: Full control over when and how much to charge customers, perfect for usage-based business models.
   </Check>

   Learn more: [On-Demand Subscriptions](/developer-resources/ondemand-subscriptions)

7. **General Bug Fixes and Enhancements**\
   This release includes performance improvements, UI polish, and resolves minor bugs for a more reliable, streamlined experience.


# v1.75.0 (January 23, 2026)
Source: https://docs.dodopayments.com/changelog/v1.75.0

Product collections, RevolutPay & Billie payment methods for GBP one-time payments, checkout session preview, metadata in change plan requests, invoice_url field, discount validation endpoint, and enhanced dashboard filtering

## New Features

### 1. **Product Collections**

Group related products together for unified checkout experiences, plan selection, and seamless upgrade/downgrade paths within the Customer Portal.

<Frame>
  <img alt="Product Collection checkout page showing multiple plan options" />
</Frame>

**Key Benefits**

* **Collection-based checkout**: Display all products from a collection in one checkout view, letting customers compare and choose their preferred plan
* **Organized product management**: Group related products (e.g., Starter, Pro, Enterprise) under a single collection
* **Customer Portal integration**: Enable customers to upgrade or downgrade between products within the same collection
* **Merchant control**: Enable, disable, and reorder products within each collection

**How It Works**

Create a checkout session for a collection:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_collection_id: 'pdc_abc123',
  product_cart: [], // Required: pass an empty array for collection checkout
  return_url: 'https://yoursite.com/return'
});

// Redirect customer to the checkout
window.location.href = session.checkout_url;
```

<Check>
  Result: A unified checkout experience where customers can view and select from all available products in your collection.
</Check>

<Info>
  Collection checkout is ideal for subscription businesses where you want customers to compare plans side-by-side before purchasing.
</Info>

Learn more: [Product Collections Guide](/features/product-collections)

### 2. **RevolutPay & Billie Payment Methods for GBP Currency**

Expanded payment options with RevolutPay and Billie now available globally for GBP one-time payment transactions, giving your customers more flexibility in how they pay.

**New Payment Methods**

| Payment Method | Supported Countries | Currency | Subscription Support |
| -------------- | ------------------- | -------- | -------------------- |
| **RevolutPay** | Global              | GBP      | No (one-time only)   |
| **Billie**     | Global              | GBP      | No (one-time only)   |

* **RevolutPay** – Fast and seamless payments for Revolut users globally
* **Billie** – B2B Buy Now Pay Later solution enabling businesses to offer flexible payment terms to their customers

<Info>
  These payment methods are automatically available for GBP transactions. No additional configuration is required.
</Info>

Learn more: [Payment Methods](/features/payment-methods)

### 3. **Checkout Session Preview**

Preview checkout sessions before creating them to calculate accurate pricing, taxes, discounts, and totals. Display real pricing to customers before they proceed to checkout.

**How It Works**

```typescript theme={null}
const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'pdt_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_code: 'SAVE20'
});

console.log('Subtotal:', preview.current_breakup.subtotal);
console.log('Tax:', preview.current_breakup.tax);
console.log('Discount:', preview.current_breakup.discount);
console.log('Total:', preview.total_price);
```

**Use Cases**

* **Custom pricing displays**: Show accurate totals including tax before checkout
* **Discount validation**: Verify discount codes and show savings to customers
* **Multi-currency support**: Preview pricing in different currencies
* **Cart summaries**: Build custom cart UIs with real-time pricing

<Card title="Preview API Reference" icon="code" href="/api-reference/checkout-sessions/preview">
  View the complete preview endpoint documentation.
</Card>

### 4. **Metadata Support in Change Plan Requests**

Pass custom metadata when changing subscription plans, enabling better tracking and integration with your internal systems during plan transitions.

```javascript theme={null}
// 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'
  }
});
```

**Use Cases**

* **Track upgrade/downgrade reasons**: Store why customers changed plans
* **Link to CRM records**: Associate plan changes with sales activities
* **Internal categorization**: Tag plan changes for reporting and analytics
* **Audit trails**: Maintain records of who initiated plan changes

<Info>
  Metadata is included in webhook events, making it easy to process plan changes with your custom data.
</Info>

Learn more: [Metadata Guide](/api-reference/metadata) | [Change Plan API](/api-reference/subscriptions/change-plan)

### 5. **`invoice_url` Field in Payment Response and Payment Link Response**

The Payment Response and Payment Link Response now include an `invoice_url` field, providing direct access to the invoice associated with each payment.

```json theme={null}
{
  "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
  "status": "succeeded",
  "invoice_url": "https://dodopayments.com/invoices/inv_2IsUnWGtRKFLxk7xAQeyt",
  "total_amount": 9900,
  "currency": "USD",
  // ... other fields
}
```

**Use Cases**

* **Customer communication**: Send invoice links directly to customers
* **Accounting integration**: Link payments to invoices in your accounting software
* **Self-service portals**: Allow customers to access their invoices easily
* **Record keeping**: Maintain direct references to invoice documents

<Card title="Get Payment API" icon="code" href="/api-reference/payments/get-payments-1">
  View the Payment Response schema.
</Card>

### 6. **Validate Discount by Code Name Endpoint**

New API endpoint to validate and retrieve discount codes by their code name (e.g., "SAVE20") instead of using the internal discount ID. Verify discount eligibility before applying them at checkout.

```javascript theme={null}
// Validate a discount code before checkout
const discount = await client.discounts.retrieveByCode('SAVE20');

console.log('Discount type:', discount.type);
console.log('Discount value:', discount.amount);
console.log('Valid until:', discount.expires_at);
```

**Benefits**

* **Pre-checkout validation**: Verify discount codes before creating checkout sessions
* **Real-time feedback**: Show customers if their code is valid
* **Error handling**: Catch invalid or expired codes early
* **Custom discount UIs**: Build discount code input fields with instant validation

<Card title="Get Discount by Code API" icon="code" href="/api-reference/discounts/get-discount-by-code">
  View the complete endpoint documentation.
</Card>

### 7. **Enhanced Filtering Capabilities for Customers, Discounts, and License Keys**

New API filters for listing Customers, Discounts, and License Keys, making it easier to find and manage your data programmatically.

**Customers API Filters**

| Filter           | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `email`          | Filter by customer email                                  |
| `name`           | Filter by customer name (partial match, case-insensitive) |
| `created_at_gte` | Filter customers created on or after this timestamp       |
| `created_at_lte` | Filter customers created on or before this timestamp      |

```javascript theme={null}
// Find customers by name created in the last 30 days
const customers = await client.customers.list({
  name: 'John',
  created_at_gte: '2026-01-01T00:00:00Z'
});
```

**Discounts API Filters**

| Filter          | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| `code`          | Filter by discount code (partial match, case-insensitive)                 |
| `discount_type` | Filter by discount type (percentage)                                      |
| `active`        | Filter by active status (true = not expired, false = expired)             |
| `product_id`    | Filter by product restriction (only discounts that apply to this product) |

```javascript theme={null}
// Find active percentage discounts for a specific product
const discounts = await client.discounts.list({
  active: true,
  discount_type: 'percentage',
  product_id: 'pdt_123'
});
```

**License Keys API Filters**

| Filter           | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `customer_id`    | Filter by customer ID                                          |
| `status`         | Filter by license key status (`active`, `expired`, `disabled`) |
| `product_id`     | Filter by product ID                                           |
| `created_at_gte` | Filter license keys created on or after this timestamp         |
| `created_at_lte` | Filter license keys created on or before this timestamp        |

```javascript theme={null}
// Find active license keys for a specific product
const licenseKeys = await client.licenseKeys.list({
  status: 'active',
  product_id: 'pdt_123'
});
```

<CardGroup>
  <Card title="List Customers API" icon="users" href="/api-reference/customers/get-customers">
    View the complete Customers API documentation.
  </Card>

  <Card title="List Discounts API" icon="percent" href="/api-reference/discounts/list-discounts">
    View the complete Discounts API documentation.
  </Card>

  <Card title="List License Keys API" icon="key" href="/api-reference/licenses/list-license-keys">
    View the complete License Keys API documentation.
  </Card>
</CardGroup>

### 8. **UI/UX Improvements in Dashboard**

This release includes numerous UI/UX improvements across the dashboard for a more intuitive and polished experience.

**Highlights**

* Improved navigation and layout consistency
* Enhanced data table interactions
* Better loading states and feedback
* Refined visual design elements
* Improved mobile responsiveness


# v1.78.0 (February 2, 2026)
Source: https://docs.dodopayments.com/changelog/v1.78.0

Communication preferences with push notifications, custom fields for checkout sessions, and expanded checkout language support

## New Features

### 1. **Communication Preferences**

Take control of how you receive notifications with our revamped Communication Preferences. Configure email, push, and in-app notifications to match your workflow.

<Frame>
  <img alt="Communication Preferences overview showing notification settings" />
</Frame>

**Key Features**

* **Revamped email designs**: Fresh, modern email templates with clear calls-to-action and improved readability
* **Push notifications**: Get instant alerts on your mobile device for critical events like new sales, disputes, and payouts
* **Granular controls**: Choose exactly which events trigger notifications and through which channels
* **Multi-email support**: Add multiple email addresses to receive notifications
* **Customer email preferences**: Configure which emails your customers receive

**Notification Categories**

| Category              | Description                                              |
| --------------------- | -------------------------------------------------------- |
| **Sales & Payments**  | New sales, successful payments, failed payments          |
| **Payouts & Refunds** | Payout completions, refund requests, refund completions  |
| **Subscriptions**     | New subscriptions, renewals, cancellations, plan changes |
| **Disputes**          | Dispute opened, evidence required, dispute resolved      |

<Check>
  Result: Stay informed about your business with notifications delivered exactly how and when you want them.
</Check>

Learn more: [Communication Preferences Guide](/features/communication-preferences)

### 2. **Custom Fields in Checkout Sessions**

Collect additional information from customers during checkout with custom fields. Add text inputs, dropdowns, dates, and more to gather the data you need.

**Supported Field Types**

| Type       | Description                       | Use Case                            |
| ---------- | --------------------------------- | ----------------------------------- |
| `text`     | Single-line text input            | Company name, order notes           |
| `number`   | Numeric input                     | Quantity, age                       |
| `email`    | Email input with validation       | Billing contact email               |
| `url`      | URL input with validation         | Website, social profile             |
| `date`     | Date picker                       | Delivery date, event date           |
| `dropdown` | Selection from predefined options | Size, color, plan type              |
| `boolean`  | Checkbox for yes/no values        | Terms acceptance, newsletter opt-in |

**How It Works**

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      options: ['1-10', '11-50', '51-200', '200+'],
      required: true
    },
    {
      key: 'newsletter',
      label: 'Subscribe to our newsletter',
      field_type: 'boolean',
      required: false
    }
  ],
  return_url: 'https://yoursite.com/success'
});
```

**Benefits**

* **Flexible data collection**: Gather any information needed for fulfillment or personalization
* **Validation built-in**: Email and URL fields automatically validate input format
* **Required/optional control**: Mark fields as required or optional based on your needs
* **Webhook delivery**: Custom field values are included in payment webhook events

<Info>
  Custom field values are returned in the `custom_field_responses` array within payment and subscription responses.
</Info>

Learn more: [Checkout Session Custom Fields](/developer-resources/checkout-session#custom-fields)

### 3. **Expanded Checkout Language Support**

The checkout page now supports **21 languages**, up from 16. Reach more customers in their native language for a better checkout experience.

**New Languages Added**

| Language | Code |
| -------- | ---- |
| Korean   | `ko` |
| Malay    | `ms` |
| Romanian | `ro` |
| Russian  | `ru` |
| Thai     | `th` |

**All Supported Languages**

Arabic, Chinese, Dutch, English, French, German, Hindi, Indonesian, Italian, Japanese, Korean, Malay, Portuguese, Romanian, Russian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese.

**Force a Specific Language**

Use the `force_language` parameter to override automatic language detection:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  customization: {
    force_language: 'ko' // Force Korean language
  },
  return_url: 'https://yoursite.com/success'
});
```

<Tip>
  By default, the checkout page automatically detects the customer's preferred language from their browser settings. Use `force_language` when you want to ensure consistency with your website's language.
</Tip>

Learn more: [Checkout Language Support](/features/checkout#supported-languages)

### 4. **General Bug Fixes and Enhancements**

This release includes performance improvements, UI polish, and resolves minor bugs for a more reliable, streamlined experience.


# v1.81.0 (February 6, 2026)
Source: https://docs.dodopayments.com/changelog/v1.81.0

Third-party analytics, checkout theme customization, prevent plan change on payment failure, and balance ledger API

## 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.

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

Learn more: [Third-Party Analytics](/features/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                  |

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_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](/features/checkout#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) |

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});
```

<Tip>
  Use `prevent_change` for critical upgrades where you want to ensure payment before granting access to premium features.
</Tip>

Learn more: [Handling Payment Failures](/developer-resources/subscription-upgrade-downgrade#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](/api-reference/balance-ledger/list-ledger-entries)

### Payment Response: `refund_status`

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


# v1.84.0 (February 20, 2026)
Source: https://docs.dodopayments.com/changelog/v1.84.0

Product-level analytics, Verifi RDR dispute prevention, DodoPayments CLI, customer portal UI revamp, inline checkout payment method updates, Tax ID prefill, return URL query params, customer email update API, and Bun adapter

## New Features

### 1. **Product-Level Analytics**

Every product now has its own **dedicated analytics dashboard**. Navigate to **Products > \[Select a Product]** to access detailed metrics specific to that product, organized across five tabs:

<Frame>
  <img alt="Product-Level Analytics" />
</Frame>

| Tab             | What You Get                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Overview**    | Total revenue, successful payment count, 30-day revenue trend chart (daily or cumulative), and a filterable transactions table |
| **Customers**   | Top 3 customers ranked by spend with a podium view, plus a full customer breakdown table                                       |
| **Retention**   | Customer churn rate, revenue churn rate, and a dual-line trend chart to spot patterns                                          |
| **Subscribers** | All subscriptions for the product with status, start date, next billing date, and amount                                       |
| **MRR**         | Monthly Recurring Revenue stacked bar chart with New MRR, Expansion MRR, Churned MRR, and Net New MRR breakdowns               |

All tabs support a **date filter** (defaults to All Time) so you can drill into any time period.

<Tip>
  Use the Retention tab to identify products with high churn early, and the MRR tab to track whether expansion revenue is outpacing churned revenue month over month.
</Tip>

Learn more: [Product-Level Analytics](/features/analytics-and-reporting#product-level-analytics)

### 2. **Verifi RDR Support on Dodo Payments**

Dodo Payments now supports **Visa Rapid Dispute Resolution (RDR)** powered by Verifi -- an automated dispute prevention tool that resolves eligible Visa disputes **before they become formal chargebacks**. When a cardholder initiates a dispute, RDR intercepts it and automatically issues a refund if the transaction is below your configured USD threshold.

**Why It Matters**

| Benefit                        | Impact                                                                                                                     |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Lower dispute rate**         | RDR-resolved disputes don't count toward Visa's 0.9% threshold                                                             |
| **Dispute fee still applies**  | A dispute fee is still charged on RDR-resolved transactions -- this covers the cost of contesting with Visa on your behalf |
| **Zero operational overhead**  | No evidence gathering or response deadlines                                                                                |
| **Better customer experience** | Cardholders get instant refunds                                                                                            |
| **Account protection**         | Stay out of Visa's Dispute Monitoring Program (VDMP)                                                                       |

<Warning>
  Exceeding Visa's 0.9% dispute rate or 100 disputes/month triggers the VDMP, with escalating fines up to \$50,000+/month. RDR helps you stay well below these thresholds.
</Warning>

**How It Works**

1. Cardholder initiates a dispute with their bank
2. RDR intercepts the dispute before it becomes a formal chargeback
3. If the transaction amount is at or below your threshold, a refund is automatically issued
4. The dispute is resolved instantly and **does not count** against your dispute rate

<Info>
  Transactions auto-refunded through RDR appear as a **lost dispute** in your Dodo Payments dashboard. This is expected -- the refund was issued automatically to prevent a formal chargeback.
</Info>

To enable Verifi RDR on your account, contact **[support@dodopayments.com](mailto:support@dodopayments.com)** to configure your threshold.

Learn more: [Visa RDR Documentation](/features/transactions/disputes#visa-rapid-dispute-resolution-rdr)

### 3. **DodoPayments CLI**

Introducing the brand new **DodoPayments CLI** (`dodopayments-cli`) -- manage your entire Dodo Payments workflow directly from the terminal. Built for developers who prefer the command line, the CLI lets you manage products, payments, customers, discounts, licenses, addons, refunds, and even create checkout sessions without leaving your editor.

**Installation**

<CodeGroup>
  ```bash npm (Recommended) theme={null}
  npm install -g dodopayments-cli
  ```

  ```bash Bun theme={null}
  bun install -g dodopayments-cli
  ```
</CodeGroup>

**Key Commands**

| Command                 | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `dodo login`            | Authenticate with your API key (opens browser)                |
| `dodo products list`    | List all products                                             |
| `dodo payments list`    | List all payments                                             |
| `dodo customers create` | Create a new customer                                         |
| `dodo checkout new`     | Create a checkout session and get the URL                     |
| `dodo wh listen`        | Forward live test webhooks to your local server via WebSocket |
| `dodo wh trigger`       | Send mock webhook payloads to any endpoint                    |

**Webhook Testing**

The CLI includes two powerful tools for development:

* **`dodo wh listen`** -- Opens a WebSocket connection to forward real-time test webhooks to your local server, preserving original headers for signature verification testing
* **`dodo wh trigger`** -- Sends mock webhook payloads interactively, supporting all 22 event types across subscriptions, payments, refunds, disputes, and licenses

<Tip>
  The webhook listener only works with a **test mode** API key. Make sure you're logged in with a test mode key before using `dodo wh listen`.
</Tip>

Learn more: [CLI Documentation](/developer-resources/sdks/cli)

### 4. **Customer Portal UI Revamp**

The Customer Portal has been completely redesigned with a clean, unified interface. The revamped portal features a left sidebar navigation and organized sections, providing customers with a more intuitive self-service experience.

<Frame>
  <img alt="Customer Portal UI Revamp" />
</Frame>

**What's New**

| Section                  | Features                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------- |
| **Active Subscriptions** | View all active subscriptions with plan details, billing cycle, and next payment date |
| **Payment Methods**      | Manage saved payment methods, add new cards, and update payment details               |
| **Billing History**      | View past invoices with downloadable PDF receipts                                     |
| **Billing Information**  | Edit name, email, phone number, and billing address                                   |
| **Subscription Details** | View detailed subscription info with options to cancel or change plan                 |
| **Plan Changes**         | Upgrade or downgrade via Product Collections directly in the portal                   |

Customers can also update payment methods for active subscriptions or reactivate subscriptions that went on hold due to failed payments -- all from the revamped portal.

<Check>
  The revamped portal is available at `https://customer.dodopayments.com/login/{business_id}` for live mode and `https://test.customer.dodopayments.com/login/{business_id}` for test mode.
</Check>

Learn more: [Customer Portal](/features/customer-portal)

### 5. **Update Payment Method in Inline Checkout**

The [inline checkout](/developer-resources/inline-checkout) now supports **payment method updates** for subscriptions. When a customer needs to update their payment method (for an active subscription or to reactivate an on-hold subscription), the update payment method flow can now be rendered directly within your page layout using inline checkout -- providing a seamless, embedded experience.

**How It Works**

1. Call the Update Payment Method API to get a `payment_link`:

```typescript theme={null}
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});
```

2. Use the returned `payment_link` as the `checkoutUrl` in inline checkout:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: response.payment_link,
  elementId: "dodo-inline-checkout"
});
```

The inline frame renders only the payment method collection form, allowing customers to enter new card details or select a saved payment method without leaving your page.

<Tip>
  For on-hold subscriptions, the update payment method flow automatically creates a charge for remaining dues. Monitor the `payment.succeeded` and `subscription.active` webhooks to confirm reactivation.
</Tip>

Learn more: [Inline Checkout](/developer-resources/inline-checkout) | [Subscription Payment Method Updates](/features/subscription#update-payment-method-for-active-subscription)

### 6. **Tax ID Prefill Support for Checkout Sessions**

You can now **prefill the Tax ID** (e.g., VAT number, GST number) when creating a checkout session using the `tax_id` parameter. This is ideal for B2B transactions where you already know the customer's tax identification number. When a Tax ID is prefilled, the field is pre-populated and locked on the checkout form.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  billing_address: { country: 'DE' },
  tax_id: 'DE999999999',
  return_url: 'https://yoursite.com/return'
});
```

<Info>
  The `tax_id` parameter requires a `billing_address` with at least a `country` field. Tax eligibility is validated in real-time, and reverse-charge rules are applied automatically for qualifying B2B transactions.
</Info>

Use the `allow_customer_editing_tax_id` feature flag to control whether customers can modify the prefilled Tax ID, and `allow_tax_id` to toggle Tax ID visibility on checkout.

Learn more: [Checkout Sessions - Tax ID](/developer-resources/checkout-session) | [B2B Payments](/features/b2b-payments)

### 7. **License Key and Email in Return URL Redirect**

After a customer completes checkout, Dodo Payments now appends `license_key` and `email` as query parameters to your `return_url` redirect, in addition to the existing `payment_id`/`subscription_id` and `status` parameters.

**Appended Query Parameters**

| Parameter         | Type     | Condition                                                                      |
| ----------------- | -------- | ------------------------------------------------------------------------------ |
| `payment_id`      | `string` | Always present for one-time payments                                           |
| `subscription_id` | `string` | Always present for subscription payments                                       |
| `status`          | `string` | Always present                                                                 |
| `license_key`     | `string` | Present if the product has license keys enabled (comma-separated for multiple) |
| `email`           | `string` | Present if the customer has an email on record                                 |

**Example redirect URLs:**

```text theme={null}
# One-time payment with license key
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

# Subscription with multiple license keys
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com
```

<Tip>
  Use these query parameters to display license keys or send a confirmation email immediately on your return page, without needing an extra API call.
</Tip>

Learn more: [Checkout Sessions - Return URL](/developer-resources/checkout-session) | [License Keys in Return URL](/features/license-keys#license-keys-in-return-url)

### 8. **Customer Email Update API**

The `PATCH /customers/{customer_id}` endpoint now supports updating customer email addresses programmatically. Update email along with name, phone number, and metadata in a single API call.

```typescript theme={null}
await client.customers.update('cus_123', {
  email: 'newemail@example.com',
  name: 'Updated Name'
});
```

**Updatable Fields**

| Field          | Type             | Description                          |
| -------------- | ---------------- | ------------------------------------ |
| `email`        | `string \| null` | Customer's email address             |
| `name`         | `string \| null` | Customer's display name              |
| `phone_number` | `string \| null` | Phone number in international format |
| `metadata`     | `object \| null` | Custom key-value pairs               |

<Info>
  Customer email updates are also available through the Customer Portal (self-service), the dashboard, and the CLI via `dodo customers update`.
</Info>

Learn more: [Customer Update API](/api-reference/customers/patch-customer) | [Customer Management](/features/customers)

### 9. **Bun Adapter Release**

Introducing `@dodopayments/bun` -- a dedicated framework adapter for [Bun's](https://bun.sh) native server (`Bun.serve()`). Integrate checkout, customer portal, and webhooks with Bun in just a few lines of code.

**Installation**

```bash theme={null}
bun add @dodopayments/bun
```

**Quick Setup**

```typescript theme={null}
import { Checkout, CustomerPortal, Webhooks } from "@dodopayments/bun";

Bun.serve({
  routes: {
    "/api/checkout": Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL!,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT!,
    }),
    "/api/customer-portal": CustomerPortal({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT!,
    }),
    "/api/webhooks": Webhooks({
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY!,
      onPaymentSucceeded: async (payload) => {
        console.log("Payment succeeded:", payload.data.payment_id);
      },
      onSubscriptionActive: async (payload) => {
        console.log("Subscription active:", payload.data.subscription_id);
      },
    }),
  },
});
```

The Bun adapter supports all three checkout flows (static, dynamic, and session-based), customer portal session generation, and secure webhook handling with signature verification and Zod validation across 22 event types.

<Check>
  The Bun adapter joins our family of 11 framework adapters including Next.js, Nuxt, Express, Fastify, Hono, Astro, SvelteKit, Remix, TanStack Start, Better Auth, and Convex.
</Check>

Learn more: [Bun Adapter Documentation](/developer-resources/bun-adaptor) | [Framework Adapters Overview](/developer-resources/framework-adaptors)


# v1.86.0 (March 2, 2026)
Source: https://docs.dodopayments.com/changelog/v1.86.0

Credit-based billing with rollover, overage, and expiration controls, unified design and theme customization hub, refund and dispute status in list payments API, refunds table in customer portal, and copy to live mode for meters

## New Features

### 1. **Credit-Based Billing**

Dodo Payments now supports **Credit-Based Billing**, a flexible system to issue, manage, and track credit entitlements across subscriptions, one-time products, and usage-based billing. Instead of charging per-use or limiting access through feature flags, you allocate a pool of credits that customers draw from as they consume your service.

<Frame>
  <img alt="Checkout showing included credits with the product purchase" />
</Frame>

**What You Can Do**

| Capability                       | Description                                                                                                              |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Custom Units or Fiat Credits** | Define credits in your own unit (API calls, tokens, compute hours) or as actual currency value (USD, EUR)                |
| **Subscription Credits**         | Issue credits per billing cycle with automatic re-issuance on renewal                                                    |
| **One-Time Credits**             | Grant a fixed credit balance on purchase, ideal for top-up packs or promotional bundles                                  |
| **Usage-Based Deduction**        | Link credits to meters for automatic deduction based on real-time consumption events                                     |
| **Rollover**                     | Allow unused credits to carry forward with configurable max percentage, timeframe, and rollover count                    |
| **Overage Controls**             | Let customers continue using your service beyond their balance, with options to forgive, bill, or carry over the deficit |
| **Expiration**                   | Set credit validity from 7 days to never, with custom day counts                                                         |

**Credit Lifecycle**

1. **Credits Issued** - Granted when a customer purchases a product with attached credit entitlements. For subscriptions, credits are re-issued each billing cycle.
2. **Credits Consumed** - Deducted as customers use your service. Meters automatically deduct credits based on real-time events, or you can deduct manually via the dashboard or API.
3. **Credits Expire or Roll Over** - At the end of the billing cycle (or after the configured expiry period), unused credits either expire or roll over based on your settings.
4. **Overage Handling** - If credits run out mid-cycle, you can allow continued usage and choose how overage is handled at the end of the cycle.

**Attaching Credits to Products**

Credits are attached as **entitlements** in the product creation flow. You can attach up to **3 credits per product**, and credits work with all three pricing types: subscriptions, one-time payments, and usage-based billing.

```typescript theme={null}
// Create a checkout session for a product with attached credits
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_ai_pro_plan',
      quantity: 1,
    }
  ],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yourapp.com/success'
});
```

**Usage-Based Deduction**

When credits are linked to meters, the system automatically deducts credits based on ingested usage events. Configure the **meter units per credit** rate to control the conversion (e.g., 1,000 API calls = 1 credit).

```typescript theme={null}
// Send usage events that deduct credits automatically
await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [{
      event_id: `gen_${Date.now()}`,
      customer_id: 'cus_abc123',
      event_name: 'ai.generation',
      timestamp: new Date().toISOString(),
      metadata: { model: 'gpt-4', tokens: 1500 }
    }]
  })
});
```

**Customer Experience**

Customers can view and manage their credit balances in the **Customer Portal** under the Credits section, with available balance, transaction history, and usage breakdowns. Credits also appear in checkout, subscription details, and payment transaction pages.

<Frame>
  <img alt="Customer Portal credits view with balance and transaction history" />
</Frame>

**Webhooks**

Credit-Based Billing fires webhook events for every credit lifecycle change:

| Event                       | Description                                    |
| --------------------------- | ---------------------------------------------- |
| `credit.added`              | Credits granted to a customer                  |
| `credit.deducted`           | Credits consumed through usage or manual debit |
| `credit.expired`            | Unused credits expired                         |
| `credit.rolled_over`        | Credits carried forward to a new grant         |
| `credit.rollover_forfeited` | Credits forfeited at max rollover count        |
| `credit.overage_charged`    | Overage charges applied                        |
| `credit.manual_adjustment`  | Manual credit/debit adjustment made            |
| `credit.balance_low`        | Balance dropped below configured threshold     |

<Tip>
  Start with simple settings, no rollover, no overage, and add complexity as you learn how customers use credits. Most settings can be updated at any time without affecting existing grants.
</Tip>

Learn more: [Credit-Based Billing](/features/credit-based-billing) | [Credit Webhook Payloads](/developer-resources/webhooks/intents/credit) | [Credit Entitlements API](/api-reference/credit-entitlements/create-credit-entitlement)

### 2. **Design & Theme Customization**

Introducing the new **Design** page, a unified hub for customizing the look and feel of your checkout, storefront, and customer portal from a single place. Choose pre-built themes, configure typography and colors, and apply per-section overrides, all with a live preview before you save.

<Frame>
  <img alt="Design settings page with live preview of checkout, customer portal, and storefront" />
</Frame>

**Key Highlights**

| Feature                   | Description                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Unified Design Hub**    | Configure checkout, storefront, and customer portal appearance from a single page                    |
| **Pre-Built Themes**      | Start with a curated theme (Dodo Pulses, Terminal, Bumblebee, or Bubblegum) and customize from there |
| **Light & Dark Mode**     | Define separate color palettes for each mode                                                         |
| **Live Preview**          | See how your changes look across checkout, customer portal, and storefront before saving             |
| **Per-Section Overrides** | Fine-tune individual sections without affecting the others                                           |
| **Programmatic Control**  | Override themes at checkout time via the API or Checkout SDK                                         |

**Getting Started**

Navigate to **Design** in the main sidebar of your Merchant Dashboard. The page has four tabs:

| Tab                 | Purpose                                                            |
| ------------------- | ------------------------------------------------------------------ |
| **General**         | Business name, logo, theme selection, and global advanced settings |
| **Checkout**        | Override theme settings specifically for the checkout page         |
| **Storefront**      | Override theme settings and configure storefront layout            |
| **Customer Portal** | Override theme settings for the customer portal                    |

**Advanced Settings**

Expand the Advanced Settings on the General tab for granular control over typography (primary/secondary Google Fonts, font size, font weight), color configuration (separate palettes for light and dark mode covering backgrounds, text, buttons, and borders), and border radius for controlling the roundness of UI elements.

<Frame>
  <img alt="Advanced settings expanded showing full color configuration for light and dark modes" />
</Frame>

**Pre-Built Themes**

Four curated themes ship out of the box:

* **Dodo Pulses** - The default theme with lime green accents and clean sans-serif typography
* **Terminal** - Developer-oriented with monospaced typography and royal blue accents
* **Bumblebee** - Warm amber and gold accents with bold, premium styling
* **Bubblegum** - Playful pink and magenta accents with fully rounded corners

<Tip>
  After selecting a pre-built theme, you can further customize individual properties in the Advanced Settings. Any unspecified properties fall back to the theme defaults.
</Tip>

Learn more: [Design & Theme Customization](/features/design) | [Checkout Features](/features/checkout) | [Storefront](/features/storefront)

### 3. **Refund Status and Dispute Status in List Payments API**

The `GET /payments` list endpoint now includes `refund_status` and `dispute_status` fields in each payment item, so you can see refund and dispute state at a glance without fetching individual payment details.

| Field            | Type                      | Description                                                                         |
| ---------------- | ------------------------- | ----------------------------------------------------------------------------------- |
| `refund_status`  | `partial \| full \| null` | Summary of the refund status for this payment. `null` if no succeeded refunds exist |
| `dispute_status` | `string \| null`          | The most recent dispute status for this payment. `null` if no disputes exist        |

**`dispute_status` values**: `dispute_opened`, `dispute_expired`, `dispute_accepted`, `dispute_cancelled`, `dispute_challenged`, `dispute_won`, `dispute_lost`

<Tip>
  Use these fields to build dispute and refund dashboards, trigger alerts on dispute status changes, or surface payments that need attention.
</Tip>

Learn more: [List Payments API](/api-reference/payments/get-payments)

### 4. **Refunds Table in Customer Portal**

The Customer Portal now includes a dedicated **Refunds** section where customers can view all refunds associated with their payments. Each refund entry shows the refund amount, status, date, and the original payment it was issued against, giving customers full transparency into their refund history without needing to contact support.

<Check>
  The refunds table is available automatically in the customer portal for all businesses. No configuration is needed.
</Check>

Learn more: [Customer Portal](/features/customer-portal)

### 5. **Copy to Live Mode for Meters**

You can now **copy meters from test mode to live mode** directly from the dashboard. When you've finished testing a meter configuration in test mode, use the copy action to replicate it to live mode with all settings preserved: aggregation type, event name, filters, and credit associations. This eliminates the need to manually recreate meters when moving from development to production.

<Tip>
  Build and validate your meter configurations in test mode first, then copy them to live mode when you're ready to go to production. This ensures your billing setup is tested before it handles real customer usage.
</Tip>

Learn more: [Usage-Based Billing](/features/usage-based-billing/introduction) | [Meters](/features/usage-based-billing/meters)


# v1.87.0 (March 9, 2026)
Source: https://docs.dodopayments.com/changelog/v1.87.0

Support for discounts in change plan and minor improvements across the platform

## New Features

### **Discounts in Change Plan**

You can now apply **discounts when changing a customer's subscription plan**. Whether upgrading, downgrading, or switching between plans, any active or new discount can be included as part of the plan change, giving you more flexibility in how you handle subscription transitions.

<Tip>
  Use discounts during plan changes to incentivize upgrades, offer loyalty pricing, or smooth transitions for customers moving between tiers.
</Tip>

Learn more: [Discount Codes](/features/discount-codes) | [Change Plan API](/api-reference/subscriptions/change-plan) | [Subscription Upgrades & Downgrades](/developer-resources/subscription-upgrade-downgrade)

## Improvements

* Minor improvements and bug fixes across the platform


# v1.93.0 (March 28, 2026)
Source: https://docs.dodopayments.com/changelog/v1.93.0

Checkout redesign with improved loading states, net revenue analytics, business-level payment method disabling, payout breakdown, Visa RDR configuration, DoNotBill proration mode, scheduled plan changes, and delete customer payment method API

## New Features

### 1. **Checkout Redesign**

The checkout experience has been completely redesigned with **improved loading states** that prevent flickering during page transitions. Customers now see smooth skeleton loading instead of jarring content shifts, creating a more polished payment experience.

Additionally, **cancel URL support** is now available — customers can return to your site if they decide not to complete their purchase.

<Frame>
  <img alt="Redesigned checkout with improved loading states" />
</Frame>

<Tip>
  Configure the `cancel_url` when creating checkout sessions to provide customers with a clear exit path back to your site.
</Tip>

### 2. **Net Revenue Analytics**

A new **Net Revenue** metric is now available on the analytics page, giving you a clear view of your actual earnings after refunds, disputes, and fees. Track net revenue trends over time and compare across periods to understand your true business performance.

<Frame>
  <img alt="Net revenue analytics on the dashboard" />
</Frame>

### 3. **Business-Level Payment Method Disabling**

You can now **disable specific payment methods at the business level**. This gives you granular control over which payment options are available to your customers across all checkout sessions, without needing to configure it per product or session.

<Frame>
  <img alt="Business-level payment method disabling in settings" />
</Frame>

<Tip>
  Use this to disable payment methods that have high fraud rates in your region, or to limit options to only the methods your business supports operationally.
</Tip>

### 4. **Payout Breakdown**

The payouts section now includes a **detailed payout breakdown**, showing exactly how each payout amount was calculated. View the individual transactions — payments, refunds, disputes, and fees — that make up each payout directly from the dashboard.

A new **Payout Breakup API** is also available for programmatic access to payout composition data.

<Frame>
  <img alt="Payout breakdown showing transaction-level details" />
</Frame>

### 5. **Visa RDR Configuration**

You can now **configure Visa Rapid Dispute Resolution (RDR)** directly from your business settings. Set your RDR threshold and enable automatic dispute resolution without needing to contact support.

<Frame>
  <img alt="Visa RDR configuration in business settings" />
</Frame>

<Tip>
  RDR automatically resolves eligible Visa disputes before they become formal chargebacks, helping you stay below Visa's 0.9% dispute rate threshold.
</Tip>

Learn more: [Visa RDR](/features/transactions/disputes#visa-rapid-dispute-resolution-rdr)

### 6. **Back Button in Checkout & Customer Portal**

Checkout sessions and the customer portal now include a **back button**, allowing customers to navigate to previous steps without losing their progress.

<Frame>
  <img alt="Back button in checkout session" />
</Frame>

### 7. **Change Plan on Next Billing Date**

Subscription plan changes can now be **scheduled to take effect on the next billing date** instead of immediately. This gives customers a smoother transition experience, especially for downgrades, where they retain access to their current plan until the end of the billing period.

Learn more: [Change Plan API](/api-reference/subscriptions/change-plan)

### 8. **DoNotBill Proration Mode**

A new `do_not_bill` proration mode is available for subscription plan changes. When using this mode, no proration charges or credits are calculated — the customer simply moves to the new plan without any billing adjustment.

| Proration Mode           | Behavior                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `prorated_immediately`   | Bill or credit the prorated difference immediately, based on time left in the cycle |
| `difference_immediately` | Charge only the price difference between the new and current plan immediately       |
| `full_immediately`       | Charge the full price of the new plan immediately                                   |
| `do_not_bill`            | No proration — switch plans without billing adjustments                             |

Learn more: [Subscription Upgrades & Downgrades](/developer-resources/subscription-upgrade-downgrade)

### 9. **Delete Customer Payment Method**

A new API endpoint lets you **delete a customer's saved payment method** programmatically. Remove outdated or unwanted payment methods from customer accounts via the API or dashboard.

Learn more: [Customer Payment Methods](/features/customers)

## Improvements

* **Skeleton loading** implemented across the dashboard for faster perceived load times
* **Filter persistence** when navigating between pages — your selected filters are preserved when you leave and return
* **Contextual drill-down navigation** added for easier data exploration across dashboard views
* **CBB demo** added to Atlas for testing credit-based billing flows

## Bug Fixes

* Fixed incorrect expiry time display on certain subscription views
* Fixed iOS notification sound not playing for push notifications


# v1.94.0 (April 8, 2026)
Source: https://docs.dodopayments.com/changelog/v1.94.0

Abandoned Cart Recovery, Subscription Dunning, discount metadata, recovery webhooks, Pix payments for Brazil, and WeChat Pay for Chinese customers

## New Features

### 1. **Abandoned Cart Recovery**

Automatically detect incomplete or failed checkouts and send targeted email sequences to bring customers back. ACR monitors payments that haven't succeeded after 60 minutes and classifies them as either **payment failed** or **checkout incomplete**, then sends up to 3 configurable recovery emails per sequence.

<Frame>
  <img alt="Recovery analytics dashboard showing abandoned checkout counts, recovery rates, and recovered revenue" />
</Frame>

Key capabilities:

* **Two email sequences** — Payment Failed and Checkout Incomplete, each with up to 3 emails
* **Recovery discounts** — Optionally auto-generate single-use discount codes to incentivize recovery
* **Customer recovery page** — Unique recovery links take customers to a dedicated page to complete their purchase
* **Recovery analytics** — Track abandoned checkout counts, recovery rates, recovered revenue, and per-email/per-product breakdowns

<Tip>
  Start with the default email timing (1 hour, 24 hours, 72 hours) and iterate based on your recovery analytics data.
</Tip>

Learn more: [Abandoned Cart Recovery](/features/recovery/abandoned-cart-recovery)

### 2. **Subscription Dunning**

Automatically send email sequences to recover lapsed or cancelled subscriptions. Dunning is triggered when a subscription enters **on hold** (payment failure) or is **cancelled** by the customer from the customer portal.

Key capabilities:

* **Two email sequences** — On Hold and Cancelled, each with up to 4 emails
* **Automatic charging** — When a customer updates their payment method, outstanding dues are charged automatically
* **Configurable timing** — Default intervals at 1, 3, 5, and 7 days, fully customizable per email

Learn more: [Subscription Dunning](/features/recovery/subscription-dunning)

### 3. **Discount Metadata**

You can now attach **metadata** (key-value pairs) to discounts when creating or updating them via the API. Use metadata to tag discounts by campaign, source, or internal reference for tracking and reconciliation.

```typescript theme={null}
const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});
```

Learn more: [Discount Codes](/features/discount-codes) | [Metadata Guide](/api-reference/metadata)

### 4. **Recovery Webhooks**

New webhook events to track the recovery lifecycle:

| Event                          | Description                                           |
| ------------------------------ | ----------------------------------------------------- |
| `abandoned_checkout.detected`  | An abandoned checkout has been detected               |
| `abandoned_checkout.recovered` | Customer completed payment through a recovery link    |
| `dunning.started`              | A dunning attempt has been started for a subscription |
| `dunning.recovered`            | Customer updated payment method and payment succeeded |

Learn more: [Recovery Webhooks](/developer-resources/webhooks/intents/recovery)

### 5. **Pix Payments for Brazil**

Accept **Pix** — Brazil's instant payment system created by the Central Bank of Brazil — in your Dodo Payments checkout. Pix is now the most-used payment method in Brazil, surpassing both credit cards and boleto, and confirms in seconds 24/7/365.

**Coverage**

| Detail              | Value                                  |
| ------------------- | -------------------------------------- |
| Billing currency    | BRL                                    |
| Supported countries | Brazil                                 |
| Subscriptions       | Not supported (one-time payments only) |
| Minimum amount      | \$0.50                                 |
| Settlement          | Instant                                |

**Configuration**

Pass `pix` in `allowed_payment_method_types` and set the billing currency to `BRL`:

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['pix', 'credit', 'debit'],
  billing_currency: 'BRL',
  return_url: 'https://example.com/success'
});
```

The customer is shown a Pix QR code and a copy-paste key on checkout. They open their banking app, scan or paste, and the payment confirms instantly.

<Tip>
  Pix QR codes expire after a set window — design your checkout flow to allow customers to regenerate the code if needed. Always include card fallbacks for customers who prefer to pay by card.
</Tip>

Learn more: [Pix Payments](/features/payment-methods/pix)

### 6. **WeChat Pay for Chinese Customers**

Accept **WeChat Pay** — used by over a billion people across China — directly in your Dodo Payments checkout. Customers scan a QR code with their WeChat app and confirm the payment in seconds, all without leaving the WeChat ecosystem.

**Coverage**

| Detail             | Value                                  |
| ------------------ | -------------------------------------- |
| Billing currencies | USD, CNY                               |
| Subscriptions      | Not supported (one-time payments only) |
| Minimum amount     | \$0.50 / ¥1.00                         |
| Settlement         | USD                                    |

**Configuration**

Pass `we_chat_pay` in `allowed_payment_method_types` when creating a checkout session:

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['we_chat_pay', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

WeChat Pay supports both **USD** (for cross-border merchants targeting Chinese customers) and **CNY** (for domestic Chinese transactions). Settlement to merchants is in USD regardless of the billing currency.

<Tip>
  Display the checkout on a desktop or tablet so customers can scan the QR code with their phone — this is the most familiar flow for WeChat Pay users.
</Tip>

Learn more: [WeChat Pay](/features/payment-methods/wechat)


# v1.97.6 (May 7, 2026)
Source: https://docs.dodopayments.com/changelog/v1.97.6

Entitlements launch with five new fulfilment integrations (Discord, GitHub, Telegram, Framer, Notion), subscription cancellation reasons in the customer portal, configurable INR e-mandate floor, adaptive currency fees inclusive setting, Dodo Payments Desktop app for macOS/Windows/Linux, stablecoin payments (USDC/USDP/USDG), import existing license keys, require_phone_number for checkout sessions, and bug fixes

## New Features

### 1. **Entitlements**

Dodo Payments now ships with unified **Entitlements** — a single layer powering automatic delivery for every fulfilment integration. A single product can deliver multiple entitlements on every successful purchase or active subscription.

<Frame>
  <img alt="Entitlements dashboard with the list of entitlements on the left and grant activity on the right" />
</Frame>

**Five new platform integrations**

Until now, Dodo Payments delivered **license keys** and **digital files** automatically on purchase. Entitlements extend that scope to five additional platforms — so paying customers can be granted access to your community, your code, or your content the moment payment succeeds, with no manual fulfilment on your side:

| Integration  | What it delivers                                                                               | Revoke behavior                                |
| ------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Discord**  | Assigns a chosen role in your Discord server after the customer completes OAuth                | Role removed on cancel/refund                  |
| **GitHub**   | Adds the customer as a collaborator to a private repository at the permission level you choose | Collaborator removed on cancel/refund          |
| **Telegram** | Issues a one-time join-request invite link for a private chat or channel via your Telegram bot | Customer kicked from the chat on cancel/refund |
| **Framer**   | Unlocks a Framer template remix link gated by an access code                                   | Access code deactivated on cancel/refund       |
| **Notion**   | Duplicates a Notion template page into the customer's workspace after they authorise via OAuth | Delivered page archived on cancel/refund       |

These join the existing **License Keys** (unique keys with activation limits and expiry) and **Digital Files** (presigned download URLs for e-books, templates, media) integrations, all now managed through the same grant lifecycle.

**What you get out of the box**

| Capability                        | Description                                                                                                                                                                                                 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reusable templates**            | Define an entitlement once (activation limits, file bundles, Discord role, repo permission, etc.) and attach it to any product                                                                              |
| **Automatic grants**              | Issued on `payment.succeeded` and `subscription.active`, idempotent across renewals and re-activations                                                                                                      |
| **Lifecycle-aware revocation**    | Revoked on `subscription.cancelled`, `subscription.on_hold`, `subscription.expired`, `refund.succeeded`, `subscription.plan_changed`, or manual API/dashboard revoke — with a populated `revocation_reason` |
| **OAuth + platform-direct flows** | OAuth for Discord, GitHub, and Notion subscriber consent; direct platform calls for Telegram, Framer, and Digital Files                                                                                     |
| **Drift detection**               | Detects when a Discord role, GitHub collaborator, or Notion page goes out of sync at the platform level and revokes with `revocation_reason: platform_external`                                             |
| **Encryption at rest**            | All platform tokens (OAuth, bot, app installations) stored with AES-256-GCM                                                                                                                                 |

**Webhooks**

Four new lifecycle events fire for every grant:

| Event                         | Fires when                                                            |
| ----------------------------- | --------------------------------------------------------------------- |
| `entitlement_grant.created`   | A new grant is created for a customer                                 |
| `entitlement_grant.delivered` | Customer access provisioned                                           |
| `entitlement_grant.failed`    | Delivery could not complete; inspect `error_code` and `error_message` |
| `entitlement_grant.revoked`   | Access withdrawn; inspect `revocation_reason`                         |

<Tip>
  For new integrations, listen to `entitlement_grant.delivered` rather than `payment.succeeded`. Payment success doesn't mean delivery is finished, especially for OAuth-based integrations.
</Tip>

Learn more: [Entitlements](/features/entitlements/introduction) | [Entitlement Grant Webhooks](/developer-resources/webhooks/intents/entitlement-grant)

### 2. **Subscription Cancellation Reasons in the Customer Portal**

When customers cancel a subscription from the Customer Portal, they're now prompted to share **why they're cancelling** before confirming. The captured reason is stored on the subscription as `cancellation_feedback`, surfaced in the API and webhook payloads, and available in the dashboard so you can spot churn patterns at a glance.

<Frame>
  <img alt="Customer Portal cancellation modal with the 'Why are you cancelling?' dropdown showing reasons like Too expensive, Missing features, and Other" />
</Frame>

**Reason options**

| Value              | Customer-facing label       |
| ------------------ | --------------------------- |
| `too_expensive`    | Too expensive               |
| `missing_features` | Missing features            |
| `switched_service` | Switched to another service |
| `unused`           | Not using it enough         |
| `customer_service` | Poor customer service       |
| `low_quality`      | Low quality                 |
| `too_complex`      | Too complex                 |
| `other`            | Other                       |

**Where it appears**

* **Subscription object**: New `cancellation_feedback` field (one of the values above) and `cancellation_comment` (optional free-text), populated when the customer cancels
* **`subscription.cancelled` webhook**: Both fields are included in the payload
* **API**: Pass `cancellation_feedback` and `cancellation_comment` to `PATCH /subscriptions/{subscription_id}` when scheduling or executing a cancellation programmatically

```typescript theme={null}
// Reading the captured feedback
const subscription = await client.subscriptions.retrieve('sub_123');
console.log(subscription.cancellation_feedback); // e.g., "too_expensive"
console.log(subscription.cancellation_comment);  // e.g., "Switching to a competitor"
```

<Tip>
  Combine `cancellation_feedback` with [Subscription Dunning](/features/recovery/subscription-dunning) to tailor your win-back emails — e.g., send a discount code to `too_expensive` cancellers and a "what's missing?" survey to `missing_features` cancellers.
</Tip>

Learn more: [Customer Portal](/features/customer-portal#cancelling-a-subscription) | [Subscription Webhooks](/developer-resources/webhooks/intents/subscription)

### 3. **Configurable Mandate Minimum Amount for INR E-Mandates**

You can now configure the **mandate floor** for INR e-mandates on Indian-card recurring subscriptions. Previously, every Indian-card subscription below ₹15,000 used a fixed ₹15,000 on-demand mandate. Now you can override this floor at the merchant level — and per checkout session or subscription if needed.

The mandate amount registered with the customer's bank is `max(mandate_min_amount_inr_paise, billing_amount)`, so this value acts as the customer-facing **authorization ceiling** whenever billing is lower than the floor.

```typescript theme={null}
// Per-subscription override
const subscription = await client.subscriptions.create({
  product_id: 'pdt_inr_monthly',
  customer: { email: 'customer@example.in' },
  billing: { country: 'IN' /* ... */ },
  mandate_min_amount_inr_paise: 2_000_000 // ₹20,000 ceiling for this subscription
});

// Or via a checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_inr_monthly', quantity: 1 }],
  mandate_min_amount_inr_paise: 2_000_000,
  return_url: 'https://yoursite.com/return'
});
```

**Resolution priority**

1. Per-request override (`mandate_min_amount_inr_paise` on the checkout session, payment, or subscription)
2. Merchant-level setting in business settings
3. System default of **₹15,000** (1,500,000 paise)

| Field                          | Type                  | Range  | Applies to                                                |
| ------------------------------ | --------------------- | ------ | --------------------------------------------------------- |
| `mandate_min_amount_inr_paise` | `integer` (INR paise) | `>= 1` | Indian-card INR subscriptions on non-Airwallex connectors |

<Info>
  This setting only affects e-mandates registered for Indian-issued cards (Visa, Mastercard, RuPay) on INR subscriptions. UPI subscriptions follow their own AutoPay flow and are unaffected.
</Info>

Learn more: [India Payment Methods](/features/payment-methods/india#mandate-types) | [Subscriptions with RBI Mandates](/features/subscription#subscriptions-with-rbi-compliant-mandates)

### 4. **Adaptive Currency Fees Inclusive Business Setting**

Adaptive Currency is the feature that lets you charge customers in their local currency. By default, the **2–4% adaptive currency fee** is borne by the customer and added on top of your displayed price. With the new **Fees Inclusive** setting, you can flip this: keep the displayed price unchanged for the customer and absorb the fee yourself.

**Where to configure**

Go to **Settings → Business**, ensure **Adaptive Pricing** is enabled, and toggle **Fees Inclusive** in the Adaptive Currency section.

**Per-request override**

You can also override the merchant default for individual payments, on-demand subscription charges, and plan changes using the `adaptive_currency_fees_inclusive` boolean:

```typescript theme={null}
const payment = await client.payments.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  adaptive_currency_fees_inclusive: true, // override business default
  return_url: 'https://yoursite.com/return'
});
```

| Mode                | Customer sees                 | Merchant settles              |
| ------------------- | ----------------------------- | ----------------------------- |
| Exclusive (default) | Local price + 2–4% fee on top | Full base price               |
| Inclusive           | Local price (unchanged)       | Base price minus the 2–4% fee |

<Info>
  INR → INR transactions are always treated as inclusive regardless of the business setting or per-request override.
</Info>

Learn more: [Adaptive Currency](/features/adaptive-currency)

### 5. **Dodo Payments Desktop App**

The official **Dodo Payments Desktop** app is now generally available for **macOS, Windows, and Linux**. Run your payments dashboard as a fast, native app — no browser tab required.

| Platform                      | Download                                            |
| ----------------------------- | --------------------------------------------------- |
| macOS (Apple Silicon)         | `Dodo.Payments_<version>_aarch64.dmg`               |
| macOS (Intel)                 | `Dodo.Payments_<version>_x64.dmg`                   |
| Windows                       | `Dodo.Payments_<version>_x64-setup.exe` (or `.msi`) |
| Linux (Debian/Ubuntu)         | `Dodo.Payments_<version>_amd64.deb`                 |
| Linux (Fedora/RHEL)           | `Dodo.Payments-<version>-1.x86_64.rpm`              |
| Linux (AppImage, auto-update) | `Dodo.Payments_<version>_amd64.AppImage`            |

**What's inside**

* **Tiny native binary** — built with Tauri on the system's native webview, \~5 MB total (no bundled Chromium)
* **Signed and notarized** — macOS builds are signed with Apple Developer ID and notarized, so no Gatekeeper warnings
* **Auto-update** — checks every 4 hours and applies signed updates automatically from GitHub Releases (works on macOS, Windows, and Linux AppImage)
* **System tray + menu bar** — hide-to-tray on macOS, full File/Edit/View/Help menus with keyboard shortcuts (`⌘⇧H` go to dashboard, `⌘L` copy current URL, `⌘⌥I` dev tools)
* **Deep-link support** — magic-link authentication links open straight in the app
* **Multi-window** — open multiple dashboards side by side

<Tip>
  Grab the latest installer for your platform from the [Desktop App Releases page](https://github.com/dodopayments/dodo-desktop/releases/latest). The repo is fully open source.
</Tip>

### 6. **Stablecoin Payments (USDC, USDP, USDG)**

Accept **stablecoin payments globally** with USD settlement. Customers pay from their preferred stablecoin wallet on the network of their choice; you receive fiat USD with no exposure to crypto volatility, no chargebacks, and no banking infrastructure required on the customer's side.

**Supported currencies and networks**

| Stablecoin | Networks                        |
| ---------- | ------------------------------- |
| **USDC**   | Ethereum, Solana, Polygon, Base |
| **USDP**   | Ethereum, Solana                |
| **USDG**   | Ethereum                        |

**Coverage**

| Detail              | Value                                  |
| ------------------- | -------------------------------------- |
| Billing currency    | USD                                    |
| Supported countries | Global (excluding India)               |
| Subscriptions       | Not supported (one-time payments only) |
| Minimum amount      | \$0.50                                 |
| Settlement          | USD                                    |

**Configuration**

Pass `crypto_currency` in `allowed_payment_method_types` when creating a checkout session:

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['crypto_currency', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

The customer is shown a wallet address and QR code with the stablecoin amount calculated at the real-time exchange rate; once the blockchain confirms the transaction, your `payment.succeeded` webhook fires and the customer is redirected to your success page.

<Info>
  Stablecoin payments are irreversible by design — there are no chargebacks. We recommend always offering `credit` and `debit` as fallback methods for customers without a stablecoin wallet.
</Info>

Learn more: [Stablecoin Payments](/features/payment-methods/stablecoins)

### 7. **Import Existing License Keys**

You can now **import license keys from another system** into Dodo Payments using the [Create License Key API](/api-reference/licenses/create-license-key). This unlocks zero-disruption migration from any external license-key provider, so your existing customers can continue activating, validating, and deactivating their keys against Dodo Payments without re-issuance.

```typescript theme={null}
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});
```

Imported keys are tagged with `source: "import"` (vs. `source: "auto"` for keys generated automatically on payment), so you can distinguish migrated inventory from organically issued keys when querying `GET /license_keys`. The `payment_id` on imported keys is `null` because they aren't tied to a Dodo Payments transaction.

<Warning>
  License keys created or updated through the API do not trigger email notifications to customers. If you need to notify customers about an imported key, handle that separately in your application.
</Warning>

<Tip>
  Migrating from Polar.sh or Lemon Squeezy? The [`dodo-migrate` CLI](/migrate-to-dodo) automates bulk imports of products, customers, discounts, and license keys in a single command.
</Tip>

Learn more: [License Keys](/features/license-keys#import-existing-license-keys-via-api) | [Create License Key API](/api-reference/licenses/create-license-key)

### 8. **`require_phone_number` for Checkout Sessions**

Force customers to provide a phone number during checkout by setting `feature_flags.require_phone_number: true` when creating a checkout session. Phone number becomes a required field on the checkout form, with form validation surfacing "Phone number is required" if the customer leaves it blank.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_phone_number_collection: true,
    require_phone_number: true
  },
  return_url: 'https://yoursite.com/return'
});
```

| Flag                            | Default | Behavior                                 |
| ------------------------------- | ------- | ---------------------------------------- |
| `allow_phone_number_collection` | `true`  | Shows the phone number field on checkout |
| `require_phone_number`          | `false` | Makes the phone number field required    |

<Warning>
  `require_phone_number: true` requires `allow_phone_number_collection: true`. The API rejects sessions where `require_phone_number` is true while phone collection is disabled.
</Warning>

<Tip>
  Useful for B2B SaaS, regulated industries, or any flow where you need a verified contact channel for support, fraud review, or compliance.
</Tip>

Learn more: [Checkout Features](/features/checkout) | [Create Checkout Session API](/api-reference/checkout-sessions/create)

## Bug Fixes & Improvements

* Minor bug fixes and stability improvements across the platform


# v1.99.0 (May 25, 2026)
Source: https://docs.dodopayments.com/changelog/v1.99.0

Stacked discount codes (up to 20 per checkout, payment, or subscription), seven new customer notification emails for refunds and subscription lifecycle events, checkout payment page overhaul lifting success rates by 2–3%, product form rework with live preview and autosave, and Business Settings redesign

## New Features

### 1. **Stacked Discount Codes**

Checkout sessions, payments, subscriptions, and plan changes now accept **up to 20 discount codes in a single request** via the `discount_codes` array. Codes are applied **in array order** — the first eligible code reduces the base price, the second reduces the already-discounted price, and so on — so you can layer campaigns without creating bespoke combined codes.

<Frame>
  <img alt="Confirm Plan Change dialog with multiple stacked discount codes" />
</Frame>

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});
```

**Where it applies**

| Surface           | Field            | Max codes |
| ----------------- | ---------------- | --------- |
| Checkout Sessions | `discount_codes` | 20        |
| Payments          | `discount_codes` | 20        |
| Subscriptions     | `discount_codes` | 20        |
| Plan Changes      | `discount_codes` | 20        |

**Plan change behavior**

| `discount_codes` value      | Effect                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| Not provided                | Existing discounts with `preserve_on_plan_change=true` are kept if applicable to the new product |
| `[]` (empty array)          | All existing discounts are removed from the subscription                                         |
| `['CODE_A', 'CODE_B', ...]` | Replaces any existing discounts with this stacked set, applied in array order                    |

**Response shape**

The full set of applied discounts is returned under the `discounts` array on payments and subscriptions — each entry includes `discount_id`, `position`, and `cycles_remaining` (for subscriptions). The legacy singular `discount_id` field is deprecated but still present for backward compatibility.

<Info>
  The singular `discount_code` field is **deprecated** but still fully supported — existing integrations continue to work without changes. It cannot be combined with `discount_codes` in the same request. We recommend migrating to `discount_codes` when convenient, even for single codes, to take advantage of stacking and the richer response shape.
</Info>

Learn more: [Discount Codes](/features/discount-codes) | [Checkout Session](/developer-resources/checkout-session) | [Plan Changes](/developer-resources/subscription-upgrade-downgrade)

### 2. **Seven New Customer Notification Emails**

Seven new transactional emails are now sent to your customers automatically, covering refund confirmations, subscription lifecycle milestones, and payment failures. Each email is independently toggleable from **Settings → Communication** under the **Customer Emails** section.

<Frame>
  <img alt="Customer Emails settings panel with toggles for each notification email" />
</Frame>

**Opt-in (enabled by default)**

| Email                                               | When it fires                                                                      |
| --------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Refund Successful**                               | A refund is successfully processed and funds are on their way back to the customer |
| **Subscription Trial Ending**                       | \~2 days before a trial expires and the first billing charge occurs                |
| **Subscription Cancelled Immediately**              | A subscription is cancelled with immediate effect                                  |
| **Subscription Set to Cancel at Next Billing Date** | A subscription is scheduled to cancel at end of the current billing period         |

**Opt-out (disabled by default)**

| Email                           | When it fires                                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Payment Failed**              | A payment attempt fails — enable if you want Dodo Payments to notify the customer directly rather than handling it in your own system          |
| **Subscription Renewal Failed** | A subscription renewal payment fails specifically; fires instead of (not in addition to) the general Payment Failed email for renewal payments |
| **Upcoming Renewal Reminder**   | \~2 days before a subscription renews                                                                                                          |

<Tip>
  If you manage customer communication yourself via webhooks, leave the opt-out emails disabled to avoid sending customers duplicate notifications for the same event.
</Tip>

<Note>
  Customer emails are separate from the notification emails sent to your team. Disabling a customer email does not affect your team's notifications for the same event.
</Note>

Learn more: [Communication Preferences](/features/communication-preferences)

## Improvements

### 3. **Checkout Payment Page Overhaul**

The payment page on checkout has been substantially reworked end-to-end — tighter layout, faster perceived load, clearer validation states, and refined card-input UX. In aggregate, these changes lifted **observed checkout success rates by \~2–3%** across global traffic.

<div>
  <div>
    <Frame>
      <img alt="Previous checkout payment page" />
    </Frame>
  </div>

  <div>
    <Frame>
      <img alt="Redesigned checkout payment page" />
    </Frame>
  </div>
</div>

What changed:

* **Smoother field interactions** — autofocus, smarter tab order, and improved keyboard navigation on the card form
* **Cleaner error and loading states** — inline validation surfaces precisely where the customer needs to act, replacing the previous full-form error banner pattern
* **Faster paint** — skeletons and progressive hydration eliminate the brief blank-state flicker on slow networks
* **Mobile polish** — tap targets, scroll behavior, and keyboard handling tuned specifically for mobile checkout, where the majority of traffic now lives

<Tip>
  No integration changes are required. Existing checkout sessions automatically pick up the new payment page.
</Tip>

### 4. **Product Form Rework**

The product **create**, **edit**, and **duplicate** flows have been rebuilt from the ground up around a single, consistent form experience.

<Frame>
  <img alt="Unified product form with Basic Details, Media & Description, Pricing, and a live checkout preview side-by-side" />
</Frame>

Highlights:

* **Live preview** — see how your product appears on the checkout and customer portal as you edit, side-by-side with the form
* **Autosave** — drafts are persisted automatically, so navigating away or losing your tab no longer means losing your work
* **Markdown editor** — product descriptions now support a full markdown editor with live rendering, link previews, and inline formatting controls
* **Duplicate flow parity** — duplicating a product opens the same unified form pre-filled, instead of a stripped-down dialog, so you can adjust every field before saving the copy

<Tip>
  Use **Duplicate** to spin up regional or pricing-tier variants of an existing product without re-entering descriptions, metadata, or fulfilment configuration.
</Tip>

### 5. **Business Settings Page Redesign**

The **Settings → Business** page has been redesigned to make configuration easier to scan and faster to update. Settings are now grouped into clearer sections with explanatory copy that describes the impact of every toggle before you flip it.

There are **no behavioural changes** to existing settings — only the layout, grouping, and surrounding explanations have improved.

<Frame>
  <img alt="Redesigned Business Settings page with grouped sections for Business Info, Brands, currency, security, and tracking" />
</Frame>

## Improvements

* **`credits_amount` override now propagated correctly to GET checkout session and payment link routes** — when a checkout session or payment link was created with a per-checkout `credit_entitlements` override, fetching that session or link via GET was returning the product-level default `credits_amount` instead of the overridden value. This is now fixed.
* **Refund action disabled for fully refunded payments** — the Refund button on a payment is now disabled once a payment is fully refunded, with a tooltip explaining why. Previously the button remained active and returned an error only after submission.
* Minor bug fixes and stability improvements across the platform


# AutoSend
Source: https://docs.dodopayments.com/integrations/autosend

Learn how to use AutoSend's email API to send automated transactional emails for your Dodo Payments transactions, refunds, and payment events.

## Introduction

The AutoSend and Dodo Payments integration enables you to automatically send real-time email notifications for all payment events, from successful transactions to failed attempts and refund confirmations.

Send transactional emails for payment events using AutoSend's powerful email API.

<Info>
  This integration requires your AutoSend API Key for authentication. You can find your API key in the AutoSend dashboard under Settings > API Keys.
</Info>

## Getting Started

Follow these steps to integrate AutoSend with Dodo Payments:

<Steps>
  <Step title="Open Webhook Section">
    Navigate to the Webhooks section in your Dodo Payments dashboard.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select AutoSend Integration">
    Choose AutoSend from the list of available integrations.
  </Step>

  <Step title="Enter API Key">
    Provide your AutoSend API key for authentication. You can find your API key in the AutoSend dashboard under Settings > API Keys.

    <Card title="Learn how to create and manage API keys" icon="key" href="https://docs.autosend.com/api-keys">
      Visit the AutoSend documentation for detailed instructions on creating and managing API keys.
    </Card>
  </Step>

  <Step title="Configure Transformation">
    Set up JavaScript transformation handlers to customize email content based on payment events.
  </Step>

  <Step title="Test & Create">
    Test your webhook configuration to ensure emails are sent correctly, then create the integration.
  </Step>

  <Step title="Activation Complete">
    🎉 Your AutoSend integration is now active and will automatically send emails for the configured payment events.
  </Step>
</Steps>

## Code Examples

### Payment Confirmation Email

Send a confirmation email when a payment is successfully processed:

```javascript payment_confirmation.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.autosend.com/v1/mails/send";
    webhook.payload = {
      to: {
        email: p.customer.email,
        name: p.customer.name,
      },
      from: {
        email: "payments@mail.yourdomain.com",
        name: "Your Company",
      },
      subject: "Payment Successful - Thank you for your purchase!",
      templateId: "A-61522f2xxxxxxxxx",
      dynamicData: {
        customerName: p.customer.name,
        amount: p.total_amount,
        currency: p.currency,
        paymentId: p.payment_id,
        paymentDate: new Date(p.created_at).toLocaleDateString(),
      },
      replyTo: {
        email: "support@yourdomain.com",
        name: "Support Team",
      },
    };
  }
  return webhook;
}
```

### Subscription Welcome Email

Send a welcome email when a new subscription is created:

```javascript subscription_welcome.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://api.autosend.com/v1/mails/send";
    webhook.payload = {
      to: {
        email: s.customer.email,
        name: s.customer.name,
      },
      from: {
        email: "subscriptions@mail.yourdomain.com",
        name: "Your Company",
      },
      subject: "Welcome to your subscription!",
      templateId: "A-61522f2xxxxxxxxx",
      dynamicData: {
        customerName: s.customer.name,
        planName: s.product_id,
        billingInterval: s.payment_frequency_interval,
        nextBillingDate: new Date(s.next_billing_date).toLocaleDateString(),
        subscriptionId: s.subscription_id,
      },
      replyTo: {
        email: "support@yourdomain.com",
        name: "Support Team",
      },
    };
  }
  return webhook;
}
```

### Payment Failure Notification

Send a notification email when a payment fails:

```javascript payment_failure.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.failed") {
    const p = webhook.payload.data;
    webhook.url = "https://api.autosend.com/v1/mails/send";
    webhook.payload = {
      to: {
        email: p.customer.email,
        name: p.customer.name,
      },
      from: {
        email: "billing@mail.yourdomain.com",
        name: "Your Company Billing",
      },
      subject: "Payment Failed - Action Required",
      templateId: "A-61522f2xxxxxxxxx",
      dynamicData: {
        customerName: p.customer.name,
        amount: p.total_amount,
        currency: p.currency,
        failureReason: p.error_message,
        paymentId: p.payment_id,
        retryUrl: `https://yourdomain.com/billing/retry/${p.payment_id}`,
      },
      replyTo: {
        email: "billing@yourdomain.com",
        name: "Billing Support",
      },
    };
  }
  return webhook;
}
```

## Best Practices

* **Verify your sender domain**: Ensure your sender email domain is verified in AutoSend to improve deliverability and avoid authentication issues. Verified domains help prevent emails from landing in spam folders.

* **Use dynamic data for personalization**: Use the `dynamicData` field to personalize emails with customer-specific information like names, payment amounts, and subscription details. Personalized emails have higher engagement rates.

* **Write clear subject lines**: Write descriptive subject lines that clearly indicate the email's purpose. Avoid spam-trigger words and keep subjects concise (under 50 characters).

* **Test before production**: Always test your emails before sending them in production. This ensures your email content renders correctly and all dynamic data is properly mapped.

## API Reference

For complete details on the AutoSend API, including all available parameters and error codes, visit the [AutoSend API Documentation](https://docs.autosend.com/api-reference/mails/send).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Emails not being sent">
    * Verify API Key is correct and active
    * Check that sender domain is verified in AutoSend
    * Ensure recipient email addresses are valid
    * Review AutoSend sending limits and quotas
    * Verify the API endpoint URL is correct: `https://api.autosend.com/v1/mails/send`
    * Check that required parameters are present in the payload
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches AutoSend API format
    * Check that all required fields are present (`to`, `from`, `templateId` or `html`/`text`)
    * Ensure email addresses are properly formatted
    * Verify `templateId` is valid if using templates
    * Check that `dynamicData` keys match your template variables
  </Accordion>

  <Accordion title="Template issues">
    * Verify your template ID is correct and active in AutoSend
    * Ensure `dynamicData` keys match the variables used in your template
    * Check that all required template variables are provided
    * Test your template independently in the AutoSend dashboard
  </Accordion>
</AccordionGroup>


# Close CRM
Source: https://docs.dodopayments.com/integrations/close-crm

Sync Dodo Payments data with Close CRM to track leads and manage sales pipeline.

## Introduction

Connect your payment data directly to Close CRM for seamless lead management and sales tracking. Automatically create contacts and opportunities from successful payments, keeping your sales team informed of revenue-generating activities.

<Info>
  This integration requires a Close CRM API key with appropriate permissions.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Close CRM">
    Choose the <b>Close CRM</b> integration card.
  </Step>

  <Step title="Enter API Key">
    Provide your Close CRM API key in the configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to map payment data to Close CRM objects.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the sync.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now automatically create/update records in Close CRM.
  </Step>
</Steps>

## Transformation Code Examples

### Create Contact from Payment

```javascript create_contact.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.close.com/api/v1/contact/";
    webhook.payload = {
      name: p.customer.name,
      emails: [p.customer.email],
      phones: [p.customer.phone_number || ''],
      custom: {
        payment_amount: (p.total_amount / 100).toFixed(2),
        payment_method: p.payment_method || '',
        dodo_customer_id: p.customer.customer_id
      }
    };
  }
  return webhook;
}
```

### Create Opportunity from Subscription

```javascript create_opportunity.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://api.close.com/api/v1/opportunity/";
    webhook.payload = {
      lead_id: s.customer.customer_id,
      value: (s.recurring_pre_tax_amount / 100).toFixed(2),
      value_period: s.payment_frequency_interval,
      title: `Subscription - ${s.product_id}`,
      custom: {
        subscription_id: s.subscription_id,
        billing_frequency: s.payment_frequency_interval,
        next_billing: s.next_billing_date
      }
    };
  }
  return webhook;
}
```

## Tips

* Use Close CRM's API documentation to understand field mappings
* Include custom fields for payment-specific data
* Map subscription amounts to opportunity values
* Use customer IDs for proper lead associations

## Troubleshooting

<AccordionGroup>
  <Accordion title="Records not created in Close CRM">
    * Verify API key has write permissions
    * Check that required fields are included
    * Ensure email format is valid
    * Review Close CRM API rate limits
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches Close CRM API format
    * Check that all required fields are present
    * Ensure field names match Close CRM schema exactly
  </Accordion>
</AccordionGroup>


# Customer.io
Source: https://docs.dodopayments.com/integrations/customer-io

Send Dodo Payments events to Customer.io to trigger email automations and customer journeys.

## Introduction

Trigger personalized email campaigns and customer journeys based on payment events. Send welcome emails for new customers, subscription updates, and payment failure notifications automatically through Customer.io.

<Info>
  This integration requires your Customer.io Site ID and API Key.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Customer.io">
    Choose the <b>Customer.io</b> integration card.
  </Step>

  <Step title="Enter Credentials">
    Provide your Customer.io Site ID and API Key in the configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format events for Customer.io's Track API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the sync.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now trigger Customer.io email automations.
  </Step>
</Steps>

## Transformation Code Examples

### Track Payment Events

```javascript track_payments.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://track.customer.io/api/v2/entity";
    webhook.payload = {
      type: "person",
      identifiers: {
        id: p.customer.customer_id
      },
      action: "payment_completed",
      name: "Payment Completed",
      attributes: {
        email: p.customer.email,
        name: p.customer.name,
        payment_amount: (p.total_amount / 100).toFixed(2),
        payment_method: p.payment_method || "unknown",
        payment_id: p.payment_id,
        currency: p.currency || "USD"
      }
    };
  }
  return webhook;
}
```

### Track Subscription Lifecycle

```javascript track_subscriptions.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.url = "https://track.customer.io/api/v2/entity";
      webhook.payload = {
        type: "person",
        identifiers: {
          id: s.customer.customer_id
        },
        action: "subscription_started",
        name: "Subscription Started",
        attributes: {
          email: s.customer.email,
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
          frequency: s.payment_frequency_interval,
          next_billing: s.next_billing_date
        }
      };
      break;
    case "subscription.cancelled":
      webhook.url = "https://track.customer.io/api/v2/entity";
      webhook.payload = {
        type: "person",
        identifiers: {
          id: s.customer.customer_id
        },
        action: "subscription_cancelled",
        name: "Subscription Cancelled",
        attributes: {
          email: s.customer.email,
          subscription_id: s.subscription_id,
          cancelled_at: s.cancelled_at,
          cancel_at_next_billing: s.cancel_at_next_billing_date
        }
      };
      break;
  }
  return webhook;
}
```

### Track Customer Attributes

```javascript track_attributes.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://track.customer.io/api/v2/entity";
    webhook.payload = {
      type: "person",
      identifiers: {
        id: p.customer.customer_id
      },
      action: "identify",
      name: "Customer Identified",
      attributes: {
        email: p.customer.email,
        name: p.customer.name,
        total_spent: (p.total_amount / 100).toFixed(2),
        payment_method: p.payment_method || "unknown",
        last_payment_date: webhook.payload.timestamp,
        customer_since: webhook.payload.timestamp
      }
    };
  }
  return webhook;
}
```

## Tips

* Use consistent event names that match your Customer.io campaigns
* Include relevant attributes for personalization
* Set proper customer identifiers for accurate tracking
* Use meaningful event names for campaign triggers

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not triggering campaigns">
    * Verify Site ID and API Key are correct
    * Check that event names match your Customer.io campaigns
    * Ensure customer identifiers are properly set
    * Review Customer.io API rate limits
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches Customer.io API format
    * Check that all required fields are present
    * Ensure event names and attributes are properly formatted
  </Accordion>
</AccordionGroup>


# DataFast
Source: https://docs.dodopayments.com/integrations/datafast

Attribute revenue to marketing channels with DataFast analytics. Track which traffic sources drive paying customers and optimize your growth.

## Introduction

DataFast is a revenue-first analytics tool that helps you discover which marketing channels drive paying customers. By integrating Dodo Payments with DataFast, you can attribute revenue to your traffic sources, identify high-value customer segments, and make data-driven decisions to grow your business.

<Info>
  This integration requires your DataFast API Key, which you can obtain from your [DataFast dashboard](https://datafa.st/).
</Info>

## How It Works

DataFast tracks visitors through a unique visitor ID stored in a cookie. To attribute revenue to marketing channels, you need to:

1. **Capture DataFast's visitor ID** from the `datafast_visitor_id` cookie when creating checkout sessions
2. **Store the visitor ID** in your payment metadata
3. **Send payment data to DataFast** when payments succeed using their Payment API

This allows DataFast to match successful payments with the original traffic source, giving you complete revenue attribution.

## Getting Started

<Steps>
  <Step title="Install DataFast Script">
    First, install the DataFast tracking script on your website. This creates the `datafast_visitor_id` cookie that tracks your visitors.

    Visit the [DataFast documentation](https://datafa.st/docs) for installation instructions specific to your platform.
  </Step>

  <Step title="Get Your API Key">
    Log in to your [DataFast dashboard](https://datafa.st/) and navigate to your website settings to obtain your API key.

    <Warning>
      Keep your API key secure and never expose it in client-side code.
    </Warning>
  </Step>

  <Step title="Capture Visitor ID in Checkout">
    When creating a checkout session, capture the DataFast visitor ID from the cookie and add it to your payment metadata.
  </Step>

  <Step title="Send Payment Data via Webhook">
    Configure a webhook to send payment data to DataFast's Payment API when payments succeed.
  </Step>

  <Step title="Done!">
    🎉 Revenue data will now appear in your DataFast dashboard with full attribution to marketing channels.
  </Step>
</Steps>

## Implementation Guide

### Step 1: Add Visitor ID to Checkout Metadata

When creating a checkout session, capture the DataFast visitor ID from the cookie and include it in your payment metadata.

<Note>
  The examples below use `POST /payments`, which is **deprecated**. It still works for existing integrations, but new integrations should use [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`) — `metadata` is passed the same way.
</Note>

<CodeGroup>
  ```typescript Next.js theme={null}
  import { cookies } from 'next/headers';
  import { dodopayments } from '@/lib/dodopayments';

  export async function createCheckout(productId: string) {
    // Capture DataFast visitor ID from cookie
    const datafastVisitorId = cookies().get('datafast_visitor_id')?.value;

    const payment = await dodopayments.payments.create({
      product_cart: [{ product_id: productId, quantity: 1 }],
      // ... other payment configuration
      metadata: {
        datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
      },
    });

    return payment;
  }
  ```

  ```javascript Express.js theme={null}
  const express = require('express');
  const router = express.Router();

  router.post('/create-checkout', async (req, res) => {
    // Capture DataFast visitor ID from cookie
    const datafastVisitorId = req.cookies?.datafast_visitor_id;

    const payment = await dodopayments.payments.create({
      product_cart: [{ product_id: req.body.productId, quantity: 1 }],
      // ... other payment configuration
      metadata: {
        datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
      },
    });

    res.json({ payment });
  });
  ```

  ```javascript Other Frameworks theme={null}
  // Capture DataFast visitor ID from cookie
  const datafastVisitorId = getCookie('datafast_visitor_id'); // Use your framework's cookie method

  const payment = await dodopayments.payments.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });
  ```
</CodeGroup>

### Step 2: Send Payment Data to DataFast

Configure a webhook endpoint to send payment data to DataFast's Payment API when payments succeed.

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select DataFast">
    Choose the <b>DataFast</b> integration card.
  </Step>

  <Step title="Enter API Key">
    Provide your DataFast API Key in the configuration field.

    <Frame>
      <img alt="Add API Key" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format payment data for DataFast's Payment API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the integration.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Payment Attribution

```javascript basic_payment.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Only send to DataFast if visitor ID exists in metadata
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100, // Convert from cents to dollars
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}
```

### Handle Zero Decimal Currencies

Some currencies (like JPY) don't use decimal places. Adjust the amount calculation accordingly:

```javascript zero_decimal.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      // Zero decimal currencies: JPY, KRW, CLP, etc.
      const zeroDecimalCurrencies = ['JPY', 'KRW', 'CLP', 'VND', 'UGX', 'MGA'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / 100, // Convert from cents for other currencies
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}
```

### Subscription Payments

For recurring subscription payments, you can track each payment:

```javascript subscription_payment.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Check if this is a subscription payment
    const isSubscription = payment.subscription_id !== null;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100,
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
        // Optional: Add subscription context
        ...(isSubscription && {
          subscription_id: payment.subscription_id,
        }),
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}
```

## Best Practices

<Tip>
  **Capture visitor ID early**: Store the DataFast visitor ID as soon as possible in your checkout flow to ensure accurate attribution, even if the user navigates away and returns later.
</Tip>

* **Always include visitor ID in metadata**: Without the visitor ID, DataFast cannot attribute revenue to marketing channels
* **Handle zero decimal currencies**: Some currencies (JPY, KRW, etc.) don't use decimal places—adjust your amount calculation accordingly
* **Test with sample payments**: Verify the integration works correctly before going live
* **Monitor your DataFast dashboard**: Check that payments are appearing correctly with proper attribution
* **Use webhook retries**: DataFast's Payment API is idempotent, so retries are safe if a webhook fails

## Troubleshooting

<AccordionGroup>
  <Accordion title="Payments not appearing in DataFast">
    * Verify your DataFast API key is correct and active
    * Check that the `datafast_visitor_id` is being captured and stored in payment metadata
    * Ensure the webhook transformation is correctly formatting the payload
    * Verify the webhook is triggering on `payment.succeeded` events
    * Check DataFast dashboard for any error messages or API logs
  </Accordion>

  <Accordion title="Revenue attribution not working">
    * Confirm the DataFast tracking script is installed and working on your website
    * Verify the `datafast_visitor_id` cookie is being set correctly
    * Check that visitor IDs match between checkout creation and payment completion
    * Ensure you're capturing the visitor ID before creating the checkout session
    * Review DataFast's [Payment API documentation](https://datafa.st/docs/payments-api) for additional guidance
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate the JSON structure matches DataFast's Payment API format
    * Check that all required fields (`amount`, `currency`, `transaction_id`, `datafast_visitor_id`) are present
    * Ensure amount is correctly converted (divide by 100 for most currencies, except zero decimal currencies)
    * Verify the API endpoint URL is correct: `https://datafa.st/api/v1/payments`
    * Test the transformation with sample webhook payloads
  </Accordion>

  <Accordion title="Currency conversion issues">
    * For zero decimal currencies (JPY, KRW, CLP, VND, UGX, MGA), send the amount as-is without dividing by 100
    * For all other currencies, divide the amount by 100 to convert from cents to the base unit
    * Double-check the currency code matches ISO 4217 format (e.g., "USD", "EUR", "JPY")
  </Accordion>
</AccordionGroup>

## Additional Resources

<CardGroup>
  <Card title="DataFast Documentation" icon="book" href="https://datafa.st/docs/payments-api">
    Learn more about DataFast's Payment API and revenue attribution features.
  </Card>

  <Card title="DataFast Dashboard" icon="chart-bar" href="https://datafa.st/">
    Access your DataFast dashboard to view revenue analytics and attribution data.
  </Card>
</CardGroup>

<Info>
  Need help? Contact Dodo Payments support at [support@dodopayments.com](mailto:support@dodopayments.com) for assistance with the integration.
</Info>


# Discord
Source: https://docs.dodopayments.com/integrations/discord

Send real-time Dodo Payments notifications to your Discord channels.

## Introduction

Keep your team informed where they already collaborate. The Discord integration delivers payment, subscription, dispute, and other important events directly to any channel you choose—no polling or dashboards required.

<Info>
  This guide assumes you have access to the Integrations section of the Dodo Payments dashboard.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, open <b>Webhooks → + Add Endpoint</b> and expand the dropdown to reveal integrations.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Discord">
    Choose the <b>Discord</b> card then click <b>Connect your Discord workspace</b>.
  </Step>

  <Step title="Authorize the Bot">
    Grant the requested permissions so the bot can post messages in your selected channel.
  </Step>

  <Step title="Edit Transformation Code">
    Tailor the payload → embed mapping to your needs—or start with the templates below.
  </Step>

  <Step title="Test & Create">
    Use sample payloads to preview the embed, then hit <b>Create</b>.
  </Step>

  <Step title="Done!">
    🎉 Your Discord channel will now receive live Dodo Payments updates.
  </Step>
</Steps>

## Transformation Code Examples

### Minimal Payment Embed

```javascript payment_embed.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.payload = {
      embeds: [{
        title: "✅ Payment Successful",
        description: `**Amount:** $${(p.total_amount / 100).toFixed(2)}\n**Customer:** ${p.customer.email}`,
        color: 0x2ecc71 // green
      }]
    };
  }
  return webhook;
}
```

### Subscription Events

```javascript subscription_embed.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        embeds: [{
          title: "📄 Subscription Activated",
          fields: [
            { name: "Customer", value: s.customer.email, inline: true },
            { name: "Product", value: s.product_id, inline: true },
            { name: "Next Billing", value: new Date(s.next_billing_date).toLocaleDateString(), inline: true }
          ],
          color: 0x2ecc71
        }]
      };
      break;
    case "subscription.cancelled":
      webhook.payload = {
        embeds: [{
          title: "⚠️ Subscription Cancelled",
          fields: [
            { name: "Customer", value: s.customer.email, inline: true },
            { name: "Product", value: s.product_id, inline: true }
          ],
          color: 0xf1c40f
        }]
      };
      break;
  }
  return webhook;
}
```

### Dispute Alerts

```javascript dispute_embed.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType.startsWith("dispute.")) {
    const d = webhook.payload.data;
    webhook.payload = {
      embeds: [{
        title: d.dispute_status === "dispute_won" ? "🏆 Dispute Won" : d.dispute_status === "dispute_lost" ? "❌ Dispute Lost" : "🚨 Dispute Update",
        fields: [
          { name: "Payment ID", value: d.payment_id, inline: true },
          { name: "Amount", value: `$${(d.amount / 100).toFixed(2)}`, inline: true },
          { name: "Status", value: d.dispute_status, inline: true }
        ],
        color: d.dispute_status === "dispute_won" ? 0x2ecc71 : d.dispute_status === "dispute_lost" ? 0xe74c3c : 0xe67e22
      }]
    };
  }
  return webhook;
}
```

## Tips

* Prefer embeds for rich formatting and colors.
* Keep titles short; put details in fields.
* Use intuitive colors: green (success), red (failure), orange (warnings).

## Troubleshooting

<AccordionGroup>
  <Accordion title="No messages in Discord">
    * Confirm the bot has access to the channel.
    * Check that the transformation returns a JSON object with `embeds`.
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate your code in the editor – syntax errors will block delivery.
    * Ensure field names match the webhook payload structure.
  </Accordion>
</AccordionGroup>


# Dub
Source: https://docs.dodopayments.com/integrations/dub

Track sale conversion events in Dub when customers complete purchases through Dodo Payments.

## Introduction

[Dub](https://dub.co) is a powerful link management platform that helps you create, share, and track short links. By integrating Dodo Payments with Dub, you can automatically track sale conversion events when customers complete purchases, enabling you to measure the ROI of your marketing campaigns and referral programs.

A "sale" event is recorded in Dub when a customer:

* Completes a one-time payment
* Subscribes to a paid plan
* Makes a recurring subscription payment

<Info>
  This integration requires a Dub account with conversion tracking enabled on your links.
</Info>

<Tip>
  **Affiliate Program Integration**: This integration also works seamlessly with **Dub Partners** for tracking affiliate referrals and commissions. Use Dub's conversion tracking to attribute sales to your affiliate links and measure partner performance. Learn more about setting up affiliate programs in our [Affiliates feature guide](/features/affiliates).
</Tip>

## How It Works

Dub tracks visitors through a unique click ID (`dub_id`) stored in a cookie when users click your Dub short links. To attribute sales to your links, you need to:

1. **Capture Dub's click ID** from the `dub_id` cookie when creating checkout sessions
2. **Store the click ID** in your payment metadata along with the customer's external ID
3. **Send sale data to Dub** when payments succeed using their Track API

This allows Dub to match successful sales with the original link click, giving you complete conversion attribution.

## Prerequisites

Before setting up this integration, ensure you have:

1. A [Dub account](https://dub.co) with a workspace
2. Conversion tracking enabled for your links
3. Your Dub API key (available in your Dub dashboard under Settings → API Keys)

## Getting Started

<Steps>
  <Step title="Enable Conversion Tracking in Dub">
    In your Dub dashboard, enable conversion tracking for the links you want to track sales for. This allows Dub to record sale events when customers complete purchases.

    <Info>
      Learn more about enabling conversion tracking in the [Dub documentation](https://dub.co/docs/conversions/quickstart).
    </Info>
  </Step>

  <Step title="Get Your Dub API Key">
    Navigate to your [Dub dashboard](https://app.dub.co) → Settings → API Keys and create a new API key with `conversions.write` scope.

    <Warning>
      Keep your API key secure and never expose it in client-side code.
    </Warning>
  </Step>

  <Step title="Capture Click ID in Checkout">
    When creating a checkout session, capture the Dub click ID from the cookie and add it to your payment metadata.
  </Step>

  <Step title="Send Sale Data via Webhook">
    Configure a webhook to send sale data to Dub's Track API when payments succeed.
  </Step>

  <Step title="Done!">
    Sale conversion events will now appear in your Dub analytics dashboard with full attribution to your links.
  </Step>
</Steps>

## Implementation Guide

### Step 1: Add Click ID and Customer ID to Checkout Metadata

When creating a checkout session, capture the Dub click ID from the cookie and include it in your payment metadata along with your customer's external ID.

<Note>
  The examples below use `POST /payments`, which is **deprecated**. It still works for existing integrations, but new integrations should use [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`) — `metadata` is passed the same way.
</Note>

<CodeGroup>
  ```typescript Next.js theme={null}
  import { cookies } from 'next/headers';
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments();

  export async function createCheckout(productId: string, customerId: string) {
    // Capture Dub click ID from cookie
    const dubClickId = cookies().get('dub_id')?.value;

    const payment = await client.payments.create({
      billing: {
        city: 'New York',
        country: 'US',
        state: 'NY',
        street: '123 Main St',
        zipcode: '10001',
      },
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
      },
      product_cart: [{ product_id: productId, quantity: 1 }],
      metadata: {
        dub_click_id: dubClickId,           // Store Dub click ID
        dub_external_id: customerId,        // Store your customer's unique ID
      },
    });

    return payment;
  }
  ```

  ```javascript Express.js theme={null}
  const express = require('express');
  const DodoPayments = require('dodopayments').default;
  const router = express.Router();

  const client = new DodoPayments();

  router.post('/create-checkout', async (req, res) => {
    // Capture Dub click ID from cookie
    const dubClickId = req.cookies?.dub_id;

    const payment = await client.payments.create({
      billing: {
        city: 'New York',
        country: 'US',
        state: 'NY',
        street: '123 Main St',
        zipcode: '10001',
      },
      customer: {
        email: req.body.email,
        name: req.body.name,
      },
      product_cart: [{ product_id: req.body.productId, quantity: 1 }],
      metadata: {
        dub_click_id: dubClickId,           // Store Dub click ID
        dub_external_id: req.body.customerId, // Store your customer's unique ID
      },
    });

    res.json({ payment });
  });
  ```

  ```python Python (FastAPI) theme={null}
  from fastapi import FastAPI, Request
  from dodopayments import DodoPayments

  app = FastAPI()
  client = DodoPayments()

  @app.post("/create-checkout")
  async def create_checkout(request: Request):
      # Capture Dub click ID from cookie
      dub_click_id = request.cookies.get("dub_id")

      body = await request.json()

      payment = client.payments.create(
          billing={
              "city": "New York",
              "country": "US",
              "state": "NY",
              "street": "123 Main St",
              "zipcode": "10001",
          },
          customer={
              "email": body["email"],
              "name": body["name"],
          },
          product_cart=[{"product_id": body["product_id"], "quantity": 1}],
          metadata={
              "dub_click_id": dub_click_id,          # Store Dub click ID
              "dub_external_id": body["customer_id"], # Store your customer's unique ID
          },
      )

      return {"payment": payment}
  ```

  ```go Go theme={null}
  package main

  import (
      "context"

      "github.com/dodopayments/dodopayments-go"
  )

  func createCheckout(dubClickId, customerId, productId string) (*dodopayments.PaymentNewResponse, error) {
      client := dodopayments.NewClient()

      payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
          Billing: dodopayments.F(dodopayments.BillingAddressParam{
              City:    dodopayments.F("New York"),
              Country: dodopayments.F(dodopayments.CountryCodeUs),
              State:   dodopayments.F("NY"),
              Street:  dodopayments.F("123 Main St"),
              Zipcode: dodopayments.F("10001"),
          }),
          Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
              dodopayments.NewCustomerParam{
                  Email: dodopayments.F("customer@example.com"),
                  Name:  dodopayments.F("John Doe"),
              },
          ),
          ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
              ProductID: dodopayments.F(productId),
              Quantity:  dodopayments.F(int64(1)),
          }}),
          Metadata: dodopayments.F(map[string]string{
              "dub_click_id":    dubClickId, // Store Dub click ID
              "dub_external_id": customerId, // Store your customer's unique ID
          }),
      })

      return payment, err
  }
  ```
</CodeGroup>

### Step 2: Send Sale Data to Dub

Configure a webhook endpoint to send sale data to Dub's Track API when payments succeed.

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to **Webhooks → + Add Endpoint** and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Dub">
    Choose the **Dub** integration card.
  </Step>

  <Step title="Enter API Key">
    Provide your Dub API Key in the configuration field.

    <Frame>
      <img alt="Add API Key" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format payment data for Dub's Track Sale API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click **Create** to activate the integration.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Sale Tracking

Track sales when payments succeed:

```javascript basic_sale.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    // Only send to Dub if click ID exists in metadata
    if (payment.metadata && payment.metadata.dub_click_id) {
      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount, // Ensure the amount is in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          customer_email: payment.customer.email,
          customer_name: payment.customer.name,
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}
```

### Track Subscription Sales

Track both initial subscriptions and recurring payments:

```javascript subscription_sale.js icon="js" expandable theme={null}
function handler(webhook) {
  const data = webhook.payload.data;

  // Track initial subscription activation
  if (webhook.eventType === "subscription.active") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount, // Amount in cents
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: data.subscription_id,
        eventName: "Subscription Started",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          billing_interval: data.payment_frequency_interval,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  // Track recurring subscription payments
  if (webhook.eventType === "subscription.renewed") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount,
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: `${data.subscription_id}_${Date.now()}`,
        eventName: "Subscription Renewed",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  return webhook;
}
```

### Track Sales with Tax Exclusion

Send only the pre-tax amount to Dub for accurate revenue tracking:

```javascript sale_without_tax.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Calculate pre-tax amount (total minus tax)
      const preTaxAmount = payment.total_amount - (payment.tax || 0);

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: preTaxAmount, // Pre-tax amount in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          total_amount: payment.total_amount,
          tax_amount: payment.tax || 0,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}
```

### Track Sales with Custom Event Names

Use custom event names to categorize different types of sales:

```javascript custom_events.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Determine event name based on payment type
      let eventName = "Purchase";
      if (payment.subscription_id) {
        eventName = "Subscription Purchase";
      } else if (payment.metadata && payment.metadata.is_upgrade) {
        eventName = "Plan Upgrade";
      }

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount,
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        eventName: eventName,
        metadata: {
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}
```

## Alternative: Client-Side Implementation

If you prefer to track sales from your server instead of using webhooks, you can call Dub's Track API directly after a successful payment:

<CodeGroup>
  ```typescript Next.js (Server Action) theme={null}
  'use server';

  import { Dub } from 'dub';

  const dub = new Dub();

  export async function trackSale(
    paymentId: string,
    clickId: string,
    customerId: string,
    amount: number,
    currency: string
  ) {
    await dub.track.sale({
      clickId: clickId,
      externalId: customerId,
      amount: amount,
      currency: currency,
      paymentProcessor: 'dodo',
      invoiceId: paymentId,
    });
  }
  ```

  ```javascript Node.js theme={null}
  const { Dub } = require('dub');

  const dub = new Dub();

  async function trackSale(payment) {
    if (payment.metadata?.dub_click_id) {
      await dub.track.sale({
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id,
        amount: payment.total_amount,
        currency: payment.currency,
        paymentProcessor: 'dodo',
        invoiceId: payment.payment_id,
      });
    }
  }
  ```
</CodeGroup>

## Best Practices

<Tip>
  **Capture the click ID early**: Store the Dub click ID as soon as possible in your checkout flow to ensure accurate attribution, even if the user navigates away and returns later.
</Tip>

* **Always include click ID in metadata**: Without the click ID, Dub cannot attribute revenue to your links
* **Use external IDs consistently**: Pass the same customer ID you use in your system for accurate customer-level analytics
* **Handle organic traffic gracefully**: Set `webhook.cancel = true` when there's no click ID to avoid unnecessary API calls
* **Test with sample payments**: Verify the integration works correctly before going live
* **Monitor your Dub dashboard**: Check that sales are appearing correctly with proper attribution

## Important Notes

<Note>
  * **Amount format**: Dub expects amounts in cents (e.g., \$10.00 = 1000)
  * **Currency**: Use ISO 4217 currency codes (USD, EUR, GBP, etc.)
  * **Free trials**: \$0 payments are not tracked as sales
  * **Refunds**: Consider tracking refunds separately if needed for accurate revenue reporting
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sales not appearing in Dub">
    * Verify your Dub API key is correct and has `conversions.write` scope
    * Check that the `dub_click_id` is being captured and stored in payment metadata
    * Ensure the webhook transformation is correctly formatting the payload
    * Verify the webhook is triggering on `payment.succeeded` events
    * Confirm conversion tracking is enabled for your Dub links
  </Accordion>

  <Accordion title="Revenue attribution not working">
    * Confirm users are clicking through your Dub short links before checkout
    * Verify the `dub_id` cookie is being set correctly on your domain
    * Check that click IDs match between checkout creation and payment completion
    * Ensure you're capturing the click ID before creating the checkout session
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate the JSON structure matches Dub's Track Sale API format
    * Check that all required fields (`clickId`, `externalId`, `amount`) are present
    * Ensure amount is in cents (integer, not decimal)
    * Verify the API endpoint URL is correct: `https://api.dub.co/track/sale`
    * Test the transformation with sample webhook payloads
  </Accordion>

  <Accordion title="Duplicate sales being tracked">
    * Ensure you're only tracking on `payment.succeeded` events, not `payment.processing`
    * Use unique `invoiceId` values for each sale
    * For subscriptions, append timestamps or billing period to prevent duplicates on renewals
  </Accordion>
</AccordionGroup>

## Additional Resources

<CardGroup>
  <Card title="Dub Conversions Documentation" icon="book" href="https://dub.co/docs/conversions/quickstart">
    Learn more about Dub's conversion tracking and analytics features.
  </Card>

  <Card title="Dub Track Sale API" icon="code" href="https://dub.co/docs/api-reference/track/track-sale">
    View the complete API reference for Dub's Track Sale endpoint.
  </Card>

  <Card title="Dub Dashboard" icon="chart-line" href="https://app.dub.co">
    Access your Dub dashboard to view conversion analytics and attribution data.
  </Card>

  <Card title="Webhook Events Guide" icon="webhook" href="/developer-resources/webhooks/intents/webhook-events-guide">
    Learn about all available Dodo Payments webhook events.
  </Card>
</CardGroup>

<Info>
  Need help? Contact Dodo Payments support at [support@dodopayments.com](mailto:support@dodopayments.com) for assistance with the integration.
</Info>


# Framer Plugin
Source: https://docs.dodopayments.com/integrations/framer-plugin

Integrate Dodo Payments checkout functionality into your Framer projects with our powerful plugin. Accept payments with customizable checkout experiences.

## Overview

The Dodo Payments Framer Plugin seamlessly integrates payment processing into your Framer websites. Create customizable checkout experiences with support for both test and production environments.

<Card title="Official Plugin" icon="link" href="https://www.framer.com/marketplace/plugins/dodo-payments">
  Access the official Dodo Payments plugin on the Framer marketplace.
</Card>

## Features

<CardGroup>
  <Card title="Hosted or Overlay Checkout" icon="credit-card">
    Choose a full-page flow or an inline overlay that feels native to your site.
  </Card>

  <Card title="Drag-and-Drop Setup" icon="hand-pointer">
    Add the component, paste your keys, publish.
  </Card>

  <Card title="Instant Digital Delivery" icon="envelope">
    Secure download links or license keys emailed the moment payment clears.
  </Card>

  <Card title="Worldwide Coverage" icon="globe">
    Bank-level acquiring on six continents, local methods built-in.
  </Card>

  <Card title="Automatic Tax & Invoicing" icon="receipt">
    VAT, GST, sales tax, and receipts handled for every order.
  </Card>

  <Card title="No-Code Subscriptions" icon="toggle-on">
    Flip a switch to sell subscription plans for your products.
  </Card>
</CardGroup>

## Setup Guide

<Steps>
  <Step title="Generate API Key">
    Visit the [Dodo Payments Dashboard](https://app.dodopayments.com/developer/api-keys) and create a new API key.

    <Tabs>
      <Tab title="Live Mode">
        For production use with real payment processing.
      </Tab>

      <Tab title="Test Mode">
        Perfect for development and testing with no real charges.
      </Tab>
    </Tabs>

    <Check>
      Copy your API key securely - you'll need it for the next step.
    </Check>
  </Step>

  <Step title="Authenticate Plugin">
    1. Open the Dodo Payments plugin in Framer
    2. Navigate to the Authentication page
    3. Paste your API key
    4. Select the appropriate mode (Test or Live)
    5. Click **Continue** to authenticate

    <Warning>
      Keep your API keys secure and never share them publicly.
    </Warning>
  </Step>

  <Step title="Manage Products">
    After authentication, you'll see your products list:

    * **Existing products**: Displayed automatically
    * **No products**: Click the **Plus (+)** button next to 'Products'

    <Info>
      You'll be redirected to the Dodo Payments Dashboard to create products with pricing, descriptions, and settings.
    </Info>
  </Step>

  <Step title="Add Buy Buttons">
    1. Select a product from your available list
    2. Click the `Add Buy Button` button
    3. A buy button with the text `Buy {product_name}` will be added to your canvas

    <Warning>
      The Add Buy Button will be disabled if you don't have the correct project permissions.
    </Warning>
  </Step>
</Steps>

## Customization

<Steps>
  <Step title="Select Checkout Experience">
    Choose your preferred checkout experience:

    * **Overlay (Embedded)**: Checkout appears as an overlay within your Framer project, keeping users on your site.
    * **Hosted**: Users are redirected to a Dodo Payments hosted checkout page for a streamlined experience.
  </Step>

  <Step title="Customize Appearance Options">
    Customize your checkout experience with the following appearance settings:

    * **Checkout Theme**: Choose between light or dark themes to match your brand aesthetic.
    * **Button Label**: Customize text (e.g., 'Buy Now', 'Purchase', 'Get Started').
    * **Button Styles**: Adjust colors, fonts, sizes, and other styling properties.
    * **Return URL**: Set a Framer page for the user to return to after checkout.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication Issues">
    **Problem**: Plugin won't authenticate

    **Solutions**:

    * Verify your API key is correct
    * Ensure you're using the right mode (Test/Live)
    * Check your internet connection
  </Accordion>

  <Accordion title="Button Creation Issues">
    **Problem**: Add Buy Button is disabled

    **Solutions**:

    * Verify you have the correct permissions in your Framer project
    * Ensure you're authenticated properly
    * Try refreshing the plugin
  </Accordion>

  <Accordion title="Product Display Issues">
    **Problem**: Products not showing

    **Solutions**:

    * Make sure you have products created in your Dodo Payments dashboard
    * Check that your API key has the correct permissions
    * Try re-authenticating
  </Accordion>
</AccordionGroup>


# GoHighLevel
Source: https://docs.dodopayments.com/integrations/gohighlevel

Integrate Dodo Payments with GoHighLevel (GHL) using no-code payment links, overlay checkout, or inline checkout, and automate fulfillment with webhooks.

## Introduction

[GoHighLevel](https://www.gohighlevel.com/) (GHL) is an all-in-one CRM and marketing platform covering funnels, websites, email/SMS, and automation ("Workflows"). GHL does not list Dodo Payments as a built-in processor, so you connect the two in one of three ways, depending on how embedded you want checkout to feel and how much you can code.

In every approach, fulfillment is handled the same way. Dodo sends [webhook events](/developer-resources/webhooks) into a GHL **Inbound Webhook Workflow** that tags the contact, grants access, and sends confirmations.

## Choose your approach

| Approach                | Code needed                | Checkout experience                              | Best for                                                   |
| ----------------------- | -------------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
| **A. Payment Links**    | None (no-code)             | Customer is redirected to Dodo's hosted checkout | Most GHL users, fastest to launch                          |
| **B. Overlay Checkout** | Custom code plus a backend | A modal opens over your GHL page                 | Teams who want on-page checkout without leaving the funnel |
| **C. Inline Checkout**  | Custom code plus a backend | Checkout form embedded inside the page           | Fully embedded, branded UX                                 |

<Info>
  New to this? Start with **Approach A (Payment Links)**. It is no-code, works for every GHL user, and takes minutes. Approaches B and C need a backend to create [checkout sessions](/api-reference/checkout-sessions/create) and are for teams comfortable with code.
</Info>

## Prerequisites

* A Dodo Payments account with at least one **product** created.
* A GoHighLevel account with a funnel, website, or workflow.
* Access to **Settings → Webhooks** (and **Settings → Developer** for an API key) in your Dodo dashboard.
* For Approaches B and C: a small **backend or serverless endpoint** to create checkout sessions.

<Note>
  GHL requires a **connected domain** to *publish* a funnel. While building, use the funnel's **Preview** to test. Note that custom JavaScript (Approaches B and C) generally runs only on the **published page on a real domain**, not in Preview.
</Note>

## Fulfillment with webhooks (all approaches)

This is the automation layer. Set it up once and it works regardless of which checkout approach you choose.

<Steps>
  <Step title="Create the workflow">
    In your GHL **sub-account**, open **Automation** in the left menu (this lands on the **Workflows** tab). Click **Create workflow**, then choose **Start from Scratch**.
  </Step>

  <Step title="Add the Inbound Webhook trigger">
    In the builder, click **Add new trigger**. In the **Add trigger** panel, search **webhook** and select **Inbound webhook** (listed under **Triggers → Events**). Copy the **Webhook URL** it generates.
  </Step>

  <Step title="Register the webhook in Dodo">
    In the Dodo dashboard, go to **Settings → Webhooks**, add a new endpoint, and paste the GHL Inbound Webhook URL. Make a test purchase so GHL captures a sample payload and you can map fields (customer email, product, amount, status).
  </Step>

  <Step title="Add fulfillment actions">
    Back in the GHL workflow, add actions based on the event, such as **find/create contact by email**, **add a tag**, **grant course/membership access**, and **send a confirmation email**. Then **Publish** the workflow.
  </Step>
</Steps>

<Warning>
  Payments are processed on Dodo, so they will **not** appear in GHL's Payments tab. Reconcile them into GHL using the webhook workflow above, and treat the **webhook as the source of truth** for granting access, not the browser redirect, since a customer can close the tab before returning.
</Warning>

## Approach A: Payment Links (no-code)

Attach a Dodo payment link to any GHL button, funnel CTA, order-page button, email, or SMS.

<Steps>
  <Step title="Create a product and copy its payment link">
    In the Dodo dashboard, go to **Products → Add Product**, set the **name** and **price**, choose **one-time** or **subscription**, and **Save**. Open the product and copy its **Payment Link** (format: `https://checkout.dodopayments.com/buy/{product_id}`).
  </Step>

  <Step title="Add the link to your GHL button">
    Edit your funnel or website page, select the **Buy / Checkout button**, set its action to **Open URL / Website**, and paste your Dodo payment link.
  </Step>

  <Step title="Set a success page (optional)">
    Set the product's **return URL** in Dodo to a GHL thank-you page so customers land back in your funnel after paying.
  </Step>
</Steps>

<Tip>
  You can prefill and lock customer details, or add tracking, using [payment-link query parameters](/features/checkout). This is useful for passing a funnel or offer ID as metadata you can read back from the webhook.
</Tip>

## Approach B: Overlay Checkout (custom code)

Opens Dodo checkout as a **modal overlay** on your GHL page using the [Checkout SDK](/developer-resources/overlay-checkout) via CDN. Requires a backend to create a [checkout session](/api-reference/checkout-sessions/create) and return its `checkoutUrl`.

<Steps>
  <Step title="Create a backend endpoint that calls the Checkout Sessions API">
    This step is **not optional**. The SDK needs a live `checkoutUrl`, and creating one requires your **secret API key**. GHL only hosts static pages, it cannot run this server-side call for you, and you must never call the [Create Checkout Session API](/api-reference/checkout-sessions/create) directly from the browser, since that would expose your secret key in the page's source. So overlay and inline checkout **cannot work with GHL alone**: you need a backend you control that creates the session and hands back just the URL.

    Any small backend works: a serverless function (Cloudflare Workers, Vercel Functions, AWS Lambda, Supabase Edge Functions, and similar), or an endpoint on a server you already run. The logic is the same everywhere: receive the request, call Dodo's API with your secret key, return the `checkout_url`.

    Example handler logic (adapt to your platform of choice):

    ```js theme={null}
    async function createCheckout(env) {
      const res = await fetch("https://test.dodopayments.com/checkouts", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${env.DODO_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          product_cart: [{ product_id: "pdt_your_product_id", quantity: 1 }],
        }),
      });

      const data = await res.json();
      return { checkoutUrl: data.checkout_url };
    }
    ```

    Store your Dodo API key as a secret on whichever platform you deploy to (never commit it to code), allow requests from your GHL domain (CORS), and route the endpoint under a domain you control, e.g. `https://api.example.com/create-checkout`. Switch to `https://live.dodopayments.com/checkouts` once you move to live mode.
  </Step>

  <Step title="Add a Custom Code element in the GHL page builder">
    Open your funnel step or website page in the GHL page builder, then:

    1. Click the **+** icon at the top-left of the builder to open **Quick Add**.
    2. Select **Elements** from the left category list.
    3. Find **Custom Code** (also shown as HTML) and drag it onto the page.
    4. Paste the code below into the element's code editor, then save it.

    ```html theme={null}
    <!-- Load the Dodo Checkout SDK -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
      DodoPaymentsCheckout.DodoPayments.Initialize({
        mode: "test", // change to "live" in production
        displayType: "overlay",
        onEvent: (event) => console.log("Checkout event:", event),
      });

      async function openDodoCheckout() {
        // calls the backend endpoint from the previous step, creating a fresh session per click
        const res = await fetch("https://api.example.com/create-checkout", { method: "POST" });
        const { checkoutUrl } = await res.json();

        DodoPaymentsCheckout.DodoPayments.Checkout.open({ checkoutUrl });
      }
    </script>

    <button onclick="openDodoCheckout()">Pay Now</button>
    ```
  </Step>

  <Step title="Publish and test on your domain">
    Custom JS runs on the **published** page (connected domain), not always in Preview. Publish, then click **Pay Now** to confirm the overlay opens.
  </Step>
</Steps>

## Approach C: Inline (embedded) Checkout

Embeds the checkout form **inside** your GHL page (no redirect, no popup) using the same SDK with a mount container. Like Approach B, it needs a backend to create the session.

<Steps>
  <Step title="Create a backend endpoint that calls the Checkout Sessions API">
    Same requirement as overlay, and equally **not optional**: creating a session needs your secret API key, so it must happen server-side. GHL cannot do this on its own. Reuse the same backend endpoint described in the **Overlay Checkout** section above (any small serverless function or server you control) that calls the [Create Checkout Session API](/api-reference/checkout-sessions/create) and returns `{ checkoutUrl }`.
  </Step>

  <Step title="Add a container and SDK via Custom Code">
    In the GHL page builder:

    1. Click the **+** icon at the top-left of the builder to open **Quick Add**.
    2. Select **Elements** from the left category list.
    3. Find **Custom Code** (also shown as HTML) and drag it onto the page where you want the checkout form to appear.
    4. Paste the code below into the element's code editor, then save it.

    ```html theme={null}
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>

    <div id="dodo-inline-checkout"></div>

    <script>
      DodoPaymentsCheckout.DodoPayments.Initialize({
        mode: "test",
        displayType: "inline",
        onEvent: (event) => console.log("Checkout event:", event),
      });

      async function mountDodoCheckout() {
        // calls the backend endpoint from the previous step
        const res = await fetch("https://api.example.com/create-checkout", { method: "POST" });
        const { checkoutUrl } = await res.json();

        DodoPaymentsCheckout.DodoPayments.Checkout.open({
          checkoutUrl,
          elementId: "dodo-inline-checkout",
        });
      }

      mountDodoCheckout();
    </script>
    ```
  </Step>

  <Step title="Verify your domain for wallets (Apple Pay)">
    For Apple Pay on inline checkout, [verify your domain](/features/payment-methods/digital-wallets#apple-pay). Host the association file and register the domain in the dashboard.
  </Step>
</Steps>

<Warning>
  Inline is the most involved option in GHL. It needs custom code, a backend, a published page on a real domain, and (for Apple Pay) domain verification. If you do not need a fully embedded form, prefer Approach A or B.
</Warning>

## Events to Handle

| Dodo event                                        | When it fires               | Suggested GHL action                                     |
| ------------------------------------------------- | --------------------------- | -------------------------------------------------------- |
| `payment.succeeded`                               | A payment is captured       | Tag the contact as paid, grant access, send confirmation |
| `subscription.active`                             | A subscription is activated | Grant membership, start onboarding workflow              |
| `subscription.renewed`                            | A renewal payment is taken  | Extend access for the next cycle                         |
| `subscription.on_hold`                            | A renewal failed            | Trigger a dunning or reminder workflow                   |
| `subscription.cancelled` / `subscription.expired` | Subscription ends           | Remove access, tag as churned                            |

Every webhook includes the **customer email**. Use GHL's **find/create contact by email** action to tie the payment to the right contact. For a full list, see the [Webhook Event Guide](/developer-resources/webhooks/intents/webhook-events-guide).

## Testing & Going Live

<Steps>
  <Step title="Test in test mode">
    Keep Dodo in **Test Mode**, use the test card `4242 4242 4242 4242` (any future expiry and any CVC), complete a purchase, and confirm the GHL workflow fires and applies the tag or access.
  </Step>

  <Step title="Go live">
    Switch Dodo to **Live Mode** and update the live-mode webhook endpoint. What else changes depends on your approach:

    * **Payment Links (A):** swap in the product's **live** payment link.
    * **Overlay checkout (B):** point your backend at `https://live.dodopayments.com/checkouts` with your **live** API key, and set the SDK's `mode` to `"live"` in the `Initialize` call.
    * **Inline checkout (C):** same as overlay, since it uses the same backend endpoint and SDK initialization.

    Then run one real end-to-end purchase to confirm.
  </Step>
</Steps>

## Tips

<Tip>
  Treat the **webhook as the source of truth** for granting access. Act on `payment.succeeded` / `subscription.active`, not on the browser redirect.
</Tip>

<Tip>
  Verify webhook authenticity using the `webhook-signature` header ([Standard Webhooks](/developer-resources/webhooks)), so only genuine Dodo events trigger fulfillment in GHL.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Payment succeeded but nothing happened in GHL">
    Check that the Dodo webhook endpoint points to the correct GHL Inbound Webhook URL, the workflow is **published**, and the trigger captured a sample payload so the field mapping exists.
  </Accordion>

  <Accordion title="Overlay or inline button does nothing">
    Custom JS usually runs only on the **published page (real domain)**, not in Preview. Confirm the page is published, the SDK `<script>` loaded, and `checkoutUrl` is a valid session URL from your backend.
  </Accordion>

  <Accordion title="Contact not created or not matched">
    Ensure your workflow uses **find/create contact by email** and the email field is mapped from the webhook payload.
  </Accordion>

  <Accordion title="Payment isn't showing in GHL's Payments tab">
    This is expected. Payments are processed on Dodo, so reconcile them into GHL using the webhook workflow.
  </Accordion>
</AccordionGroup>


# HubSpot
Source: https://docs.dodopayments.com/integrations/hubspot

Automatically create and update contacts, companies, and deals in HubSpot from Dodo Payments events.

## Introduction

Sync your payment data directly to HubSpot CRM. Create contacts from successful payments, track subscription lifecycle, and build comprehensive customer profiles—all automatically triggered by Dodo Payments events.

<Info>
  This integration requires HubSpot admin access to configure OAuth scopes and API permissions.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, go to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select HubSpot">
    Choose the <b>HubSpot</b> integration card.
  </Step>

  <Step title="Connect HubSpot">
    Click <b>Connect to HubSpot</b> and authorize the required OAuth scopes.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to map payment data to HubSpot CRM objects.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the sync.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now automatically create/update records in your HubSpot CRM.
  </Step>
</Steps>

## Transformation Code Examples

### Create Contact from Payment

```javascript create_contact.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.hubapi.com/crm/v3/objects/contacts";
    webhook.payload = {
      properties: {
        email: p.customer.email,
        firstname: p.customer.name.split(' ')[0] || '',
        lastname: p.customer.name.split(' ').slice(1).join(' ') || '',
        phone: p.customer.phone_number || '',
        amount: (p.total_amount / 100).toString(),
        payment_method: p.payment_method || '',
        currency: p.currency || 'USD'
      }
    };
  }
  return webhook;
}
```

### Update Contact with Subscription

```javascript update_contact.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = `https://api.hubapi.com/crm/v3/objects/contacts/${s.customer.customer_id}`;
    webhook.method = "PATCH";
    webhook.payload = {
      properties: {
        subscription_status: "active",
        subscription_amount: (s.recurring_pre_tax_amount / 100).toString(),
        subscription_frequency: s.payment_frequency_interval,
        next_billing_date: s.next_billing_date,
        product_id: s.product_id
      }
    };
  }
  return webhook;
}
```

### Create Deal from Payment

```javascript create_deal.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.hubapi.com/crm/v3/objects/deals";
    webhook.payload = {
      properties: {
        dealname: `Payment - ${p.customer.email}`,
        amount: (p.total_amount / 100).toString(),
        dealstage: "closedwon",
        closedate: new Date().toISOString(),
        hs_currency: p.currency || "USD"
      },
      associations: [
        {
          to: {
            id: p.customer.customer_id
          },
          types: [
            {
              associationCategory: "HUBSPOT_DEFINED",
              associationTypeId: 3
            }
          ]
        }
      ]
    };
  }
  return webhook;
}
```

## Tips

* Use HubSpot's API explorer to test object creation
* Map payment amounts to HubSpot currency fields
* Include customer IDs for proper associations
* Set appropriate deal stages based on payment status

## Troubleshooting

<AccordionGroup>
  <Accordion title="Records not created in HubSpot">
    * Verify OAuth scopes include write permissions
    * Check that required HubSpot properties exist
    * Ensure customer email is valid and unique
    * Review HubSpot API rate limits
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches HubSpot API format
    * Check that all required properties are included
    * Ensure property names match HubSpot field names exactly
  </Accordion>
</AccordionGroup>


# Inngest
Source: https://docs.dodopayments.com/integrations/inngest

Trigger serverless functions and background jobs in Inngest based on Dodo Payments events.

## Introduction

Execute serverless functions and background jobs automatically when payment events occur. Process payments, send notifications, update databases, and run complex workflows with Inngest's reliable function execution platform.

<Info>
  This integration requires your Inngest webhook URL from your function configuration.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Inngest">
    Choose the <b>Inngest</b> integration card.
  </Step>

  <Step title="Create Inngest Function">
    In Inngest, create a new function and copy the webhook URL from the function configuration.
  </Step>

  <Step title="Paste Webhook URL">
    Paste the Inngest webhook URL into the endpoint configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format events for your Inngest function.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the integration.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now trigger your Inngest functions automatically.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Event Payload

```javascript basic_event.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.payload = {
      name: "payment.succeeded",
      data: {
        payment_id: p.payment_id,
        amount: (p.total_amount / 100).toFixed(2),
        currency: p.currency || "USD",
        customer_email: p.customer.email,
        customer_name: p.customer.name,
        payment_method: p.payment_method || "unknown"
      },
      user: {
        email: p.customer.email
      },
      ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
    };
  }
  return webhook;
}
```

### Subscription Event Handler

```javascript subscription_event.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        name: "subscription.started",
        data: {
          subscription_id: s.subscription_id,
          customer_email: s.customer.email,
          customer_name: s.customer.name,
          product_id: s.product_id,
          amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
          frequency: s.payment_frequency_interval,
          next_billing: s.next_billing_date
        },
        user: {
          email: s.customer.email
        },
        ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
      };
      break;
    case "subscription.cancelled":
      webhook.payload = {
        name: "subscription.cancelled",
        data: {
          subscription_id: s.subscription_id,
          customer_email: s.customer.email,
          cancelled_at: s.cancelled_at,
          cancel_at_next_billing: s.cancel_at_next_billing_date
        },
        user: {
          email: s.customer.email
        },
        ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
      };
      break;
  }
  return webhook;
}
```

### Dispute Event Handler

```javascript dispute_event.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType.startsWith("dispute.")) {
    const d = webhook.payload.data;
    webhook.payload = {
      name: webhook.eventType,
      data: {
        dispute_id: d.dispute_id,
        payment_id: d.payment_id,
        amount: (d.amount / 100).toFixed(2),
        status: d.dispute_status,
        stage: d.dispute_stage,
        remarks: d.remarks || "",
        urgent: webhook.eventType === "dispute.opened"
      },
      user: {
        email: d.customer?.email || "unknown"
      },
      ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
    };
  }
  return webhook;
}
```

## Common Inngest Use Cases

<AccordionGroup>
  <Accordion title="Payment Processing">
    * Send confirmation emails
    * Update customer records
    * Process refunds
    * Generate invoices
    * Update inventory
  </Accordion>

  <Accordion title="Subscription Management">
    * Welcome new subscribers
    * Process cancellations
    * Send renewal reminders
    * Update billing cycles
    * Handle failed payments
  </Accordion>

  <Accordion title="Analytics & Reporting">
    * Update revenue metrics
    * Track customer behavior
    * Generate reports
    * Sync data to analytics platforms
    * Calculate churn rates
  </Accordion>
</AccordionGroup>

## Tips

* Use descriptive event names for better function organization
* Include user context for function execution
* Set proper timestamps for event ordering
* Structure data consistently across events
* Use Inngest's retry and error handling features

## Troubleshooting

<AccordionGroup>
  <Accordion title="Functions not triggering">
    * Verify webhook URL is correct and active
    * Check that Inngest function is deployed and active
    * Ensure event names match function triggers
    * Review Inngest function logs for errors
  </Accordion>

  <Accordion title="Data not received correctly">
    * Check payload structure matches Inngest expectations
    * Verify event names are properly formatted
    * Ensure all required fields are included
    * Test with Inngest's webhook testing tool
  </Accordion>
</AccordionGroup>


# External Integrations
Source: https://docs.dodopayments.com/integrations/introduction

Connect Dodo Payments with your favorite tools and platforms to automate workflows and enhance your payment experience.

## Overview

Dodo Payments offers native integrations with popular platforms and tools to help you streamline your payment operations and automate your workflows. Whether you need to send notifications to your team, sync customer data to your CRM, trigger email campaigns, or connect with your favorite development tools, we have an integration that fits your needs.

Our integrations are designed to be easy to set up and require minimal configuration. Most integrations can be connected directly from your Dodo Payments dashboard with just a few clicks, allowing you to start automating your payment workflows immediately.

<Info>
  Browse the available integrations below or use the search to quickly find the integration you're looking for. Each integration includes step-by-step setup instructions to get you started.
</Info>

## Benefits of Integrations

<CardGroup>
  <Card title="Real-time Notifications" icon="bell">
    Stay informed about important payment events as they happen, ensuring you never miss critical updates about your business.
  </Card>

  <Card title="Automated Workflows" icon="bolt">
    Reduce manual tasks by automatically triggering actions based on payment events, saving time and reducing errors.
  </Card>

  <Card title="Enhanced Visibility" icon="chart-bar">
    Get better insights into your payment operations with centralized notifications and reporting across your favorite tools.
  </Card>

  <Card title="Improved Customer Experience" icon="face-smile">
    Provide seamless payment experiences by integrating with your existing tools and workflows.
  </Card>
</CardGroup>

<Tip>
  Each integration includes detailed setup instructions and example configurations to help you get started quickly.
</Tip>

## Available Integrations

Connect Dodo Payments with the following platforms and tools:

<CardGroup>
  <Card title="N8N" icon="diagram-project" href="/integrations/n8n">
    Connect Dodo Payments to 5000+ apps through N8N webhooks for unlimited automation possibilities with self-hosted or cloud workflows.
  </Card>

  <Card title="Slack" icon="slack" href="/integrations/slack">
    Receive real-time notifications about your payments directly in your Slack workspace.
  </Card>

  <Card title="HubSpot" icon="hubspot" href="/integrations/hubspot">
    Automatically create and update contacts, companies, and deals in HubSpot from Dodo Payments events.
  </Card>

  <Card title="WooCommerce Plugin" icon="wordpress" href="/integrations/woocommerce-plugin">
    Integrate Dodo Payments seamlessly with your WooCommerce store to accept global payments.
  </Card>

  <Card title="Discord" icon="discord" href="/integrations/discord">
    Send real-time Dodo Payments notifications to your Discord channels.
  </Card>

  <Card title="Microsoft Teams" icon="microsoft" href="/integrations/microsoft-teams">
    Send Dodo Payments notifications to Microsoft Teams channels with rich Adaptive Cards.
  </Card>

  <Card title="Resend" icon="envelope" href="/integrations/resend">
    Send transactional emails through Resend based on Dodo Payments events with high deliverability.
  </Card>

  <Card title="SendGrid" icon="inbox" href="/integrations/sendgrid">
    Send transactional emails based on Dodo Payments events using SendGrid's Mail Send API.
  </Card>

  <Card title="Customer.io" icon="chart-area" href="/integrations/customer-io">
    Send Dodo Payments events to Customer.io to trigger email automations and customer journeys.
  </Card>

  <Card title="Loops" icon="infinity" href="/integrations/loops">
    Send transactional emails and manage customer communication through Loops based on Dodo Payments events.
  </Card>

  <Card title="MailerLite" icon="check-circle" href="/integrations/mailerlite">
    Automatically add customers to MailerLite subscriber lists and trigger email automations based on Dodo Payments events.
  </Card>

  <Card title="AutoSend" icon="paper-plane" href="/integrations/autosend">
    Send automated transactional emails for your Dodo Payments transactions, refunds, and payment events using AutoSend's email API.
  </Card>

  <Card title="Keplars" icon="envelope-circle-check" href="/integrations/keplars">
    Send transactional emails through Keplars based on Dodo Payments events using priority-based delivery queues.
  </Card>

  <Card title="Segment" icon="chart-line" href="/integrations/segment">
    Send Dodo Payments events to Segment for analytics and customer data platform integration.
  </Card>

  <Card title="DataFast" icon="chart-bar" href="/integrations/datafast">
    Attribute revenue to marketing channels with DataFast analytics. Track which traffic sources drive paying customers and optimize your growth.
  </Card>

  <Card title="Dub" icon="link" href="/integrations/dub">
    Track sale conversion events in Dub when customers complete purchases. Measure ROI of marketing campaigns and referral programs.
  </Card>

  <Card title="Inngest" icon="cloud" href="/integrations/inngest">
    Trigger serverless functions and background jobs in Inngest based on Dodo Payments events.
  </Card>

  <Card title="Zapier" icon="diagram-project" href="/integrations/zapier">
    Connect Dodo Payments to 5000+ apps through Zapier for unlimited automation possibilities.
  </Card>

  <Card title="Windmill" icon="wind" href="/integrations/windmill">
    Trigger Windmill workflows and scripts based on Dodo Payments events for custom automation.
  </Card>

  <Card title="Close CRM" icon="handshake" href="/integrations/close-crm">
    Sync Dodo Payments data with Close CRM to track leads and manage sales pipeline.
  </Card>

  <Card title="GoHighLevel" icon="link" href="/integrations/gohighlevel">
    Sell through GoHighLevel funnels and websites using Dodo Payments payment links, overlay checkout, or inline checkout, then automate fulfillment with webhooks.
  </Card>

  <Card title="Figma Plugin" icon="figma" href="/integrations/figma-plugin">
    Build Figma plugins with Dodo Payments license key validation and activation.
  </Card>

  <Card title="Framer Plugin" icon="puzzle-piece" href="/integrations/framer-plugin">
    Integrate Dodo Payments checkout functionality into your Framer projects with customizable checkout experiences.
  </Card>

  <Card title="Raycast Extension" icon="puzzle-piece" href="/integrations/raycast-extension">
    Install the Raycast extension to browse and manage Dodo Payments resources from your keyboard.
  </Card>
</CardGroup>

## Integration Categories

Our integrations are organized into several categories to help you find what you need:

* **Communication & Collaboration**: Keep your team informed with real-time notifications in Slack, Discord, and Microsoft Teams
* **Email Services**: Automate transactional emails and customer communication with Resend, SendGrid, Customer.io, Loops, MailerLite, AutoSend, and Keplars
* **CRM & Sales**: Sync payment data and customer information with HubSpot, Close CRM, and GoHighLevel
* **Automation Platforms**: Connect with Zapier, N8N, Inngest, and Windmill to build custom workflows
* **Analytics**: Track and analyze payment events with Segment and DataFast
* **E-commerce**: Seamlessly integrate payments into your WooCommerce store
* **Design Tools**: Build plugins and extensions for Figma and Framer
* **Developer Tools**: Access Dodo Payments functionality from Raycast

## Need a Different Integration?

Don't see the platform you're looking for? We're constantly adding new integrations based on user feedback.

* **Request a new integration** by contacting the Dodo Payments team at [support@dodopayments.com](mailto:support@dodopayments.com). Let us know which platform you want to connect, and our team will review your request.
* **Build a custom integration** using our webhook system if you need a solution right away. Our webhook documentation provides all the details you need to get started.

<Card title="Webhook Documentation" icon="webhook" href="/developer-resources/webhooks">
  Learn how to build custom integrations using our webhook system.
</Card>


# Keplars
Source: https://docs.dodopayments.com/integrations/keplars

Send transactional emails through Keplars based on Dodo Payments events.

## Introduction

Send professional transactional emails automatically when payment and subscription events occur. Deliver payment confirmations, subscription updates, and failure notifications through Keplars with no middleware server required. Dodo Payments calls the Keplars API directly using a JavaScript transformation handler.

<Info>
  This integration requires your Keplars API Key for authentication. Find it in the Keplars dashboard under **Settings → API Keys**, and verify a sender domain or address under **Domains**.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.
  </Step>

  <Step title="Select Keplars">
    Choose the <b>Keplars</b> integration card.

    <Frame>
      <img alt="Select the Keplars integration card" />
    </Frame>
  </Step>

  <Step title="Enter API Key">
    Provide your Keplars API Key. It is sent as a Bearer token on every request.

    <Frame>
      <img alt="Enter the Keplars API URL, API Key, and subscribe to events" />
    </Frame>
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format emails for Keplars. Replace the placeholder sender address and template IDs with your own.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate email sending.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now automatically trigger transactional emails via Keplars.
  </Step>
</Steps>

## Transformation Code Examples

Each handler sets `webhook.url` to the Keplars high-priority send endpoint and rewrites `webhook.payload` into a Keplars request (the API key is sent automatically as a Bearer token). Replace `payments@mail.yourdomain.com` with your verified sender and `your-keplars-*-template-id` with your actual template IDs.

<Warning>
  `to` must be an **array**, even for a single recipient. When using `template_id`, do **not** also send `subject` or `body`. The template supplies them.
</Warning>

### Payment Confirmation Email

```javascript payment_succeeded.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "payment.succeeded") return webhook;

  const data = webhook.payload.data || {};
  const paymentDate = new Date(webhook.payload.timestamp).toLocaleDateString("en-US", {
    year: "numeric", month: "long", day: "numeric",
  });

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-payment-success-template-id",
    params: {
      customer_name: data.customer?.name,
      amount: ((data.total_amount || 0) / 100).toFixed(2),
      currency: data.currency || "USD",
      payment_id: data.payment_id,
      payment_method: data.payment_method,
      payment_date: paymentDate,
    },
  };
  return webhook;
}
```

### Payment Failure Notification

```javascript payment_failed.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "payment.failed") return webhook;

  const data = webhook.payload.data || {};
  const paymentDate = new Date(webhook.payload.timestamp).toLocaleDateString("en-US", {
    year: "numeric", month: "long", day: "numeric",
  });

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-payment-failed-template-id",
    params: {
      customer_name: data.customer?.name,
      amount: ((data.total_amount || 0) / 100).toFixed(2),
      currency: data.currency || "USD",
      payment_id: data.payment_id,
      error_message: data.error_message || "Your payment could not be processed.",
      payment_date: paymentDate,
    },
  };
  return webhook;
}
```

### Subscription Welcome Email

```javascript subscription_active.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "subscription.active") return webhook;

  const data = webhook.payload.data || {};
  const nextBilling = data.next_billing_date
    ? new Date(data.next_billing_date).toLocaleDateString("en-US", {
        year: "numeric", month: "long", day: "numeric",
      })
    : "";

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-subscription-active-template-id",
    params: {
      customer_name: data.customer?.name,
      subscription_id: data.subscription_id,
      product_id: data.product_id,
      amount: ((data.recurring_pre_tax_amount || 0) / 100).toFixed(2),
      currency: data.currency || "USD",
      billing_interval: data.payment_frequency_interval || "month",
      next_billing_date: nextBilling,
    },
  };
  return webhook;
}
```

### Subscription Cancellation Email

```javascript subscription_cancelled.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType !== "subscription.cancelled") return webhook;

  const data = webhook.payload.data || {};
  const cancellationDate = new Date(webhook.payload.timestamp).toLocaleDateString("en-US", {
    year: "numeric", month: "long", day: "numeric",
  });

  webhook.url = "https://api.keplars.com/api/v1/send-email/high";
  webhook.payload = {
    to: [data.customer?.email],
    from: "payments@mail.yourdomain.com",
    template_id: "your-keplars-subscription-cancelled-template-id",
    params: {
      customer_name: data.customer?.name,
      subscription_id: data.subscription_id,
      cancellation_date: cancellationDate,
    },
  };
  return webhook;
}
```

## Tips

* Use a verified sender domain or address for better deliverability.
* Create a dedicated Keplars template per event type so each email stays on-brand and on-message.
* Personalize each email by passing customer data like name, amount, and payment ID through `params`.
* Test in sandbox mode first. Sandbox sends are captured in the Keplars Test Inbox rather than delivered.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Emails not being sent">
    * Verify your API key is correct and active in Keplars under **Settings → API Keys**.
    * Verify your sender domain or address is verified.
    * Dodo Payments shows the raw Keplars error response in the webhook delivery log. Check it for details.
  </Accordion>

  <Accordion title="Template not found">
    * The `template_id` in your handler must match an active template in your Keplars account. Verify the ID (and that it's active) in the dashboard.
  </Accordion>

  <Accordion title="Wrong event triggered">
    * Each handler checks `webhook.eventType` and returns early if it does not match. Make sure the correct events are subscribed on the Dodo Payments webhook endpoint.
  </Accordion>
</AccordionGroup>


# Loops
Source: https://docs.dodopayments.com/integrations/loops

Send transactional emails and manage customer communication through Loops based on Dodo Payments events.

## Introduction

Send transactional emails and manage customer communication automatically when payment events occur. Deliver payment confirmations, subscription updates, and important notifications with Loops' email infrastructure.

<Info>
  This integration requires your Loops API Key for authentication.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Loops">
    Choose the <b>Loops</b> integration card.
  </Step>

  <Step title="Enter API Key">
    Provide your Loops API Key in the configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format emails for Loops' API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the email sending.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now automatically trigger transactional emails via Loops.
  </Step>
</Steps>

## Transformation Code Examples

### Payment Confirmation Email

```javascript payment_confirmation.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.loops.so/v1/events/send";
    webhook.payload = {
      eventName: "payment_confirmation",
      email: p.customer.email,
      properties: {
        customer_name: p.customer.name,
        payment_id: p.payment_id,
        amount: (p.total_amount / 100).toFixed(2),
        currency: p.currency || "USD",
        payment_method: p.payment_method || "unknown",
        payment_date: new Date(webhook.payload.timestamp).toLocaleDateString()
      }
    };
  }
  return webhook;
}
```

### Subscription Welcome Email

```javascript subscription_welcome.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://api.loops.so/v1/events/send";
    webhook.payload = {
      eventName: "subscription_welcome",
      email: s.customer.email,
      properties: {
        customer_name: s.customer.name,
        subscription_id: s.subscription_id,
        product_id: s.product_id,
        amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
        frequency: s.payment_frequency_interval,
        next_billing: s.next_billing_date
      }
    };
  }
  return webhook;
}
```

### Payment Failure Notification

```javascript payment_failure.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.failed") {
    const p = webhook.payload.data;
    webhook.url = "https://api.loops.so/v1/events/send";
    webhook.payload = {
      eventName: "payment_failed",
      email: p.customer.email,
      properties: {
        customer_name: p.customer.name,
        payment_id: p.payment_id,
        amount: (p.total_amount / 100).toFixed(2),
        error_message: p.error_message || "Payment processing failed",
        retry_link: `https://yourdomain.com/retry-payment/${p.payment_id}`
      }
    };
  }
  return webhook;
}
```

## Tips

* Use descriptive event names for better email template organization
* Include relevant customer properties for personalization
* Set up email templates in Loops dashboard for each event
* Use consistent property naming across events
* Test email delivery before going live

## Troubleshooting

<AccordionGroup>
  <Accordion title="Emails not being sent">
    * Verify API Key is correct and active
    * Check that event names match your Loops templates
    * Ensure recipient email addresses are valid
    * Review Loops sending limits and quotas
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches Loops API format
    * Check that all required fields are present
    * Ensure event names are properly formatted
    * Verify API key permissions
  </Accordion>
</AccordionGroup>


# MailerLite
Source: https://docs.dodopayments.com/integrations/mailerlite

Automatically add customers to MailerLite subscriber lists and trigger email automations based on Dodo Payments events.

## Introduction

Automatically sync your paying customers to MailerLite subscriber lists when payment events occur. Add customers to specific groups, trigger automation workflows, and keep your email marketing lists up-to-date with real payment data.

MailerLite is a powerful email marketing platform for newsletters, campaigns, and automations. This integration helps you automatically manage subscribers based on payment activity - perfect for onboarding sequences, customer segmentation, and targeted marketing campaigns.

<Info>
  This integration requires your MailerLite API Key for authentication. You can generate one from your [MailerLite Integrations page](https://dashboard.mailerlite.com/integrations/api).
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select MailerLite">
    Choose the <b>MailerLite</b> integration card.
  </Step>

  <Step title="Enter API Key">
    Provide your MailerLite API Key in the configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format subscriber data for MailerLite's API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the subscriber sync.
  </Step>

  <Step title="Done!">
    Payment events will now automatically sync customers to your MailerLite lists.
  </Step>
</Steps>

## Transformation Code Examples

### Add Customer on Successful Payment

```javascript add_customer.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://connect.mailerlite.com/api/subscribers";
    webhook.payload = {
      email: p.customer.email,
      fields: {
        name: p.customer.name,
        last_name: ""
      },
      groups: ["your-group-id-here"],
      status: "active"
    };
  }
  return webhook;
}
```

### Add Subscriber to Multiple Groups Based on Product

```javascript product_segmentation.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    
    // Determine groups based on product or amount
    const groups = ["customers-group-id"];
    
    // Add to premium group if high-value purchase
    if (p.total_amount >= 10000) { // $100+
      groups.push("premium-customers-group-id");
    }
    
    webhook.url = "https://connect.mailerlite.com/api/subscribers";
    webhook.payload = {
      email: p.customer.email,
      fields: {
        name: p.customer.name,
        last_purchase_amount: (p.total_amount / 100).toFixed(2),
        last_purchase_date: new Date(webhook.payload.timestamp).toISOString().split('T')[0],
        payment_id: p.payment_id
      },
      groups: groups,
      status: "active"
    };
  }
  return webhook;
}
```

### Add New Subscriber on Subscription Activation

```javascript subscription_subscriber.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://connect.mailerlite.com/api/subscribers";
    webhook.payload = {
      email: s.customer.email,
      fields: {
        name: s.customer.name,
        subscription_plan: s.product_id,
        subscription_amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
        billing_frequency: s.payment_frequency_interval,
        subscription_start: new Date().toISOString().split('T')[0]
      },
      groups: ["subscribers-group-id", "active-subscriptions-group-id"],
      status: "active"
    };
  }
  return webhook;
}
```

### Update Subscriber on Subscription Cancellation

```javascript subscription_cancelled.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.cancelled") {
    const s = webhook.payload.data;
    // Use PUT to update existing subscriber
    webhook.url = "https://connect.mailerlite.com/api/subscribers/" + encodeURIComponent(s.customer.email);
    webhook.method = "PUT";
    webhook.payload = {
      fields: {
        subscription_status: "cancelled",
        cancellation_date: new Date().toISOString().split('T')[0]
      },
      groups: ["churned-customers-group-id"]
    };
  }
  return webhook;
}
```

### Add Customer with Custom Fields

```javascript custom_fields.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://connect.mailerlite.com/api/subscribers";
    webhook.payload = {
      email: p.customer.email,
      fields: {
        name: p.customer.name,
        country: p.billing?.country || "",
        city: p.billing?.city || "",
        phone: p.customer.phone_number || "",
        // Custom fields (must be created in MailerLite first)
        total_spent: (p.total_amount / 100).toFixed(2),
        customer_since: new Date().toISOString().split('T')[0],
        payment_method: p.payment_method || "unknown",
        currency: p.currency || "USD"
      },
      groups: ["paying-customers-group-id"],
      status: "active",
      subscribed_at: new Date().toISOString().replace('T', ' ').split('.')[0]
    };
  }
  return webhook;
}
```

### Trigger Automation via Event

```javascript trigger_automation.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    
    // First, ensure subscriber exists
    webhook.url = "https://connect.mailerlite.com/api/subscribers";
    webhook.payload = {
      email: p.customer.email,
      fields: {
        name: p.customer.name,
        // Add a trigger field that your automation watches
        last_payment_trigger: new Date().toISOString(),
        last_payment_amount: (p.total_amount / 100).toFixed(2)
      },
      status: "active"
    };
    
    // Tip: Create an automation in MailerLite that triggers
    // when 'last_payment_trigger' field is updated
  }
  return webhook;
}
```

## Tips

* Create custom fields in MailerLite before using them in your transformations
* Use groups to segment customers by product, plan tier, or purchase behavior
* Set up automation workflows in MailerLite that trigger on field updates
* Use the upsert behavior (POST to /subscribers) to avoid duplicate subscriber errors
* Store payment metadata in custom fields for better customer insights
* Test with a small group before enabling for all payments

## Custom Fields Setup

Before using custom fields, you need to create them in MailerLite:

1. Go to your MailerLite dashboard
2. Navigate to **Subscribers Fields**
3. Click **Create field** and add fields like:
   * `total_spent` (Number)
   * `customer_since` (Date)
   * `subscription_plan` (Text)
   * `payment_method` (Text)
   * `last_payment_amount` (Number)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Subscribers not being added">
    * Verify API Key is correct and active
    * Check that the email address is valid (RFC 2821 compliant)
    * Ensure group IDs are correct and exist in your account
    * Note: Unsubscribed, bounced, or junk subscribers cannot be reactivated via API
  </Accordion>

  <Accordion title="Custom fields not updating">
    * Verify custom fields exist in MailerLite before using them
    * Check that field names match exactly (case-sensitive)
    * Ensure field values match the expected type (text, number, date)
  </Accordion>

  <Accordion title="Rate limit errors">
    * MailerLite API has a rate limit of 120 requests per minute
    * Use batch endpoints if processing many subscribers
    * Implement backoff strategies for high-volume scenarios
  </Accordion>

  <Accordion title="Group assignment not working">
    * Verify group IDs are numeric strings
    * Check that groups exist in your MailerLite account
    * Note: Using PUT with groups will remove subscriber from unlisted groups
  </Accordion>
</AccordionGroup>

## API Reference

MailerLite Subscribers API accepts the following key parameters:

| Parameter          | Type   | Required | Description                                              |
| ------------------ | ------ | -------- | -------------------------------------------------------- |
| `email`            | string | Yes      | Valid email address (RFC 2821)                           |
| `fields`           | object | No       | Object with field name/value pairs                       |
| `fields.name`      | string | No       | Subscriber's first name                                  |
| `fields.last_name` | string | No       | Subscriber's last name                                   |
| `fields.company`   | string | No       | Company name                                             |
| `fields.country`   | string | No       | Country                                                  |
| `fields.city`      | string | No       | City                                                     |
| `fields.phone`     | string | No       | Phone number                                             |
| `groups`           | array  | No       | Array of group IDs to add subscriber to                  |
| `status`           | string | No       | One of: active, unsubscribed, unconfirmed, bounced, junk |
| `subscribed_at`    | string | No       | Date in format `yyyy-MM-dd HH:mm:ss`                     |
| `ip_address`       | string | No       | Subscriber's IP address                                  |

For complete API documentation, visit [MailerLite Developers](https://developers.mailerlite.com/docs/subscribers.html).


# Microsoft Teams
Source: https://docs.dodopayments.com/integrations/microsoft-teams

Send Dodo Payments notifications to Microsoft Teams channels with rich Adaptive Cards.

## Introduction

Keep your business team in the loop with real-time payment notifications in Microsoft Teams. The integration delivers payment events as rich Adaptive Cards—perfect for enterprise environments where Teams is the primary collaboration tool.

<Info>
  This guide assumes you have admin access to create webhooks in your Microsoft Teams workspace.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Microsoft Teams">
    Choose the <b>Microsoft Teams</b> integration card.
  </Step>

  <Step title="Create Teams Webhook">
    In Teams, go to your channel → ⋯ → Connectors → Incoming Webhook → Configure. Copy the webhook URL.
  </Step>

  <Step title="Paste Webhook URL">
    Paste the Teams webhook URL into the endpoint configuration.
  </Step>

  <Step title="Customize Transformation">
    Edit the transformation code to format messages as Adaptive Cards for Teams.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate.
  </Step>

  <Step title="Done!">
    🎉 Your Teams channel will now receive Dodo Payments updates as Adaptive Cards.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Payment Card

```javascript payment_card.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.payload = {
      type: "message",
      attachments: [{
        contentType: "application/vnd.microsoft.card.adaptive",
        content: {
          type: "AdaptiveCard",
          body: [
            {
              type: "TextBlock",
              text: "✅ Payment Successful",
              weight: "Bolder",
              size: "Medium"
            },
            {
              type: "FactSet",
              facts: [
                { title: "Amount", value: `$${(p.total_amount / 100).toFixed(2)}` },
                { title: "Customer", value: p.customer.email },
                { title: "Payment ID", value: p.payment_id }
              ]
            }
          ]
        }
      }]
    };
  }
  return webhook;
}
```

### Subscription Management

```javascript subscription_card.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        type: "message",
        attachments: [{
          contentType: "application/vnd.microsoft.card.adaptive",
          content: {
            type: "AdaptiveCard",
            body: [
              {
                type: "TextBlock",
                text: "📄 Subscription Activated",
                weight: "Bolder",
                color: "Good"
              },
              {
                type: "FactSet",
                facts: [
                  { title: "Customer", value: s.customer.email },
                  { title: "Product", value: s.product_id },
                  { title: "Amount", value: `$${(s.recurring_pre_tax_amount / 100).toFixed(2)}/${s.payment_frequency_interval}` },
                  { title: "Next Billing", value: new Date(s.next_billing_date).toLocaleDateString() }
                ]
              }
            ]
          }
        }]
      };
      break;
    case "subscription.cancelled":
      webhook.payload = {
        type: "message",
        attachments: [{
          contentType: "application/vnd.microsoft.card.adaptive",
          content: {
            type: "AdaptiveCard",
            body: [
              {
                type: "TextBlock",
                text: "⚠️ Subscription Cancelled",
                weight: "Bolder",
                color: "Warning"
              },
              {
                type: "FactSet",
                facts: [
                  { title: "Customer", value: s.customer.email },
                  { title: "Product", value: s.product_id },
                  { title: "Cancelled At", value: new Date(s.cancelled_at).toLocaleDateString() }
                ]
              }
            ]
          }
        }]
      };
      break;
  }
  return webhook;
}
```

### Dispute Alerts

```javascript dispute_card.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType.startsWith("dispute.")) {
    const d = webhook.payload.data;
    const color = d.dispute_status === "dispute_won" ? "Good" : d.dispute_status === "dispute_lost" ? "Attention" : "Warning";
    const title = d.dispute_status === "dispute_won" ? "🏆 Dispute Won" : d.dispute_status === "dispute_lost" ? "❌ Dispute Lost" : "🚨 Dispute Update";
    
    webhook.payload = {
      type: "message",
      attachments: [{
        contentType: "application/vnd.microsoft.card.adaptive",
        content: {
          type: "AdaptiveCard",
          body: [
            {
              type: "TextBlock",
              text: title,
              weight: "Bolder",
              color: color
            },
            {
              type: "FactSet",
              facts: [
                { title: "Payment ID", value: d.payment_id },
                { title: "Amount", value: `$${(d.amount / 100).toFixed(2)}` },
                { title: "Status", value: d.dispute_status },
                { title: "Stage", value: d.dispute_stage }
              ]
            }
          ]
        }
      }]
    };
  }
  return webhook;
}
```

## Tips

* Use Adaptive Cards for rich, interactive formatting
* Choose appropriate colors: Good (green), Warning (yellow), Attention (red)
* Keep fact sets concise and readable
* Test with Teams webhook tester before deploying

## Troubleshooting

<AccordionGroup>
  <Accordion title="No messages in Teams">
    * Verify the webhook URL is correct and active
    * Check that the transformation returns valid Adaptive Card JSON
    * Ensure the webhook has permission to post in the channel
  </Accordion>

  <Accordion title="Card formatting issues">
    * Validate Adaptive Card schema in Teams webhook tester
    * Check that all required fields are present
    * Ensure color values are valid (Good, Warning, Attention, Default)
  </Accordion>
</AccordionGroup>


# N8N
Source: https://docs.dodopayments.com/integrations/n8n

Integrate Dodo Payments with N8N to automate workflows and connect with over 5,000 apps using webhooks—power powerful, customizable automation in self-hosted or cloud N8N environments.

## Introduction

Connect Dodo Payments to thousands of apps and services through N8N. Automate workflows by triggering N8N workflows when payment events occur, from sending emails to updating spreadsheets, creating tasks, database operations, and much more.

<Info>
  This integration requires an N8N webhook URL from your workflow configuration.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select N8N">
    Choose the <b>N8N</b> integration card.
  </Step>

  <Step title="Create Webhook in N8N">
    In N8N, create a new workflow and add a <b>Webhook</b> node as the trigger. Configure it as a POST webhook and copy the webhook URL.
  </Step>

  <Step title="Paste Webhook URL">
    Paste the N8N webhook URL into the endpoint configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format data for your N8N workflow.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the integration.
  </Step>

  <Step title="Activate Workflow">
    In N8N, activate your workflow to start receiving webhook events.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now trigger your N8N workflows automatically.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Webhook Payload

```javascript basic_webhook.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      payment_id: p.payment_id,
      amount: (p.total_amount / 100).toFixed(2),
      currency: p.currency || "USD",
      customer_email: p.customer.email,
      customer_name: p.customer.name,
      payment_method: p.payment_method || "unknown",
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}
```

### Subscription Event Handler

```javascript subscription_webhook.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        event_type: "subscription_started",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        customer_name: s.customer.name,
        product_id: s.product_id,
        amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
        frequency: s.payment_frequency_interval,
        next_billing: s.next_billing_date,
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.payload = {
        event_type: "subscription_cancelled",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        cancelled_at: s.cancelled_at,
        cancel_at_next_billing: s.cancel_at_next_billing_date,
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}
```

### Dispute Alert Handler

```javascript dispute_webhook.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType.startsWith("dispute.")) {
    const d = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      dispute_id: d.dispute_id,
      payment_id: d.payment_id,
      amount: (d.amount / 100).toFixed(2),
      status: d.dispute_status,
      stage: d.dispute_stage,
      remarks: d.remarks || "",
      urgent: webhook.eventType === "dispute.opened",
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}
```

## Popular N8N Use Cases

<AccordionGroup>
  <Accordion title="Email Notifications">
    * Send Gmail/Outlook emails for payment confirmations
    * Create email sequences in Mailchimp/ConvertKit
    * Send Slack/Discord notifications via webhooks
    * Create Google Sheets records automatically
    * Send Telegram/WhatsApp messages
  </Accordion>

  <Accordion title="CRM Updates">
    * Add contacts to HubSpot/Salesforce
    * Create deals in Pipedrive/Close
    * Update customer records in Airtable
    * Log activities in Monday.com
    * Sync data to PostgreSQL/MySQL databases
  </Accordion>

  <Accordion title="Task Management">
    * Create tasks in Asana/Trello
    * Add to-do items in Notion
    * Create calendar events in Google Calendar
    * Send SMS notifications via Twilio
    * Create GitHub issues for disputes
  </Accordion>

  <Accordion title="Data Processing">
    * Transform and enrich payment data
    * Store events in databases (PostgreSQL, MongoDB)
    * Aggregate metrics and analytics
    * Generate reports and exports
    * Trigger complex multi-step workflows
  </Accordion>
</AccordionGroup>

## Tips

* Keep payload structure simple for easy N8N node parsing
* Use consistent field names across all events
* Include timestamps for workflow timing and scheduling
* Test your workflow with sample data before activating
* Use N8N's IF node for conditional logic and routing
* Leverage N8N's Code node for custom data transformations
* Use the Switch node to route different event types to different paths
* Set up error workflows to handle failed webhook deliveries

## Troubleshooting

<AccordionGroup>
  <Accordion title="Workflow not triggering">
    * Verify webhook URL is correct and accessible
    * Check that workflow is activated in N8N
    * Ensure webhook node is configured as POST method
    * Test webhook delivery in N8N's execution history
    * Verify firewall/network settings allow incoming webhooks
    * Check N8N webhook authentication settings if configured
  </Accordion>

  <Accordion title="Data not mapping correctly">
    * Check field names in N8N node configurations
    * Verify data types match expected formats in nodes
    * Use N8N's test feature to inspect incoming data
    * Ensure transformation code returns valid JSON
    * Check the webhook node's response format settings
    * Use the Set node to rename or restructure fields
  </Accordion>

  <Accordion title="Workflow execution errors">
    * Review execution logs in N8N for detailed error messages
    * Check node connection settings and credentials
    * Verify all required fields are present in the payload
    * Test individual nodes with sample data
    * Enable error workflows to catch and handle failures
    * Check rate limits and API quotas for connected services
  </Accordion>
</AccordionGroup>


# Raycast Extension
Source: https://docs.dodopayments.com/integrations/raycast-extension

Install the Raycast extension to browse and manage Dodo Payments resources from your keyboard.

<Frame>
  <img alt="Raycast extension home showing Dodo Payments commands" />
</Frame>

Your Dodo Payments dashboard, a few keystrokes away. Use Raycast to quickly view payments, subscriptions, customers, products, discount codes, license keys, and refunds without opening the dashboard.

## Install

<Card title="Install from Raycast Store →" icon="puzzle-piece" href="https://www.raycast.com/dodopayments/dodo-payments">
  Open the Dodo Payments extension page in the Raycast Store.
</Card>

<Info>
  Requires Raycast on macOS and a Dodo Payments API key.
</Info>

## Setup

<Steps>
  <Step title="Get your API Key">
    1. Log in to your Dodo Payments dashboard.
    2. Go to Developer › API Keys.
    3. Copy your API key.
  </Step>

  <Step title="Configure the Extension">
    1. Open Raycast.
    2. Search for "Dodo Payments" and select any command.
    3. When prompted, enter your API key in the API Key field.
    4. Choose the API mode:
       * Test: use for development and testing.
       * Live: use for production data.
    5. Save the settings.
  </Step>
</Steps>

<Tip>
  Start in Test mode to validate your setup, then switch to Live.
</Tip>

<Warning>
  Treat your API key like a password. Do not share it or store it in plaintext.
</Warning>

## Use the extension

* **Search**: open Raycast, type "Dodo Payments", and pick a command.
* **Filter**: narrow results by typing parts of IDs, emails, names, or statuses.
* **Open details**: press Enter on a list item to view more information.

## Commands and views

### Payments

Browse recent payments and jump into detailed views in seconds.

<Frame>
  <img alt="Payments list view in the Raycast extension" />
</Frame>

### Subscriptions

Quickly scan active, on-hold, and cancelled subscriptions.

<Frame>
  <img alt="Subscriptions list view in the Raycast extension" />
</Frame>

### Customers

Find customers fast and open full profiles.

<Frame>
  <img alt="Customers list view in the Raycast extension" />
</Frame>

### Products

Review and manage your product catalog at a glance.

<Frame>
  <img alt="Products list view in the Raycast extension" />
</Frame>

### Discount Codes

Search and reference active discount codes quickly.

<Frame>
  <img alt="Discount codes list view in the Raycast extension" />
</Frame>

### License Keys

Look up and manage license keys without leaving Raycast.

<Frame>
  <img alt="License keys list view in the Raycast extension" />
</Frame>

### Refunds

See recent refunds and drill into their details.

<Frame>
  <img alt="Refunds list view in the Raycast extension" />
</Frame>

<Info>
  Additional live-only views: disputes and payouts.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed or 401/403 errors">
    Confirm the API key and mode (Test vs Live) match your dashboard data. Reopen the command and re-enter the key if needed.
  </Accordion>

  <Accordion title="No results appear">
    Ensure your selected mode has data. Try switching between Test and Live.
  </Accordion>

  <Accordion title="Rate limits or timeouts">
    Wait a moment and try again. If the issue persists, check your network connectivity.
  </Accordion>
</AccordionGroup>

<Card title="Need help? Contact support →" icon="life-ring" href="/miscellaneous/help-support">
  Get assistance from the Dodo Payments team.
</Card>


# Rekomi
Source: https://docs.dodopayments.com/integrations/rekomi

Run an affiliate program on your Dodo Payments store with Rekomi. One pasted API key connects the two, and Rekomi tracks sales and pays your affiliates.

## Introduction

[Rekomi](https://rekomi.com) is an affiliate tracking and management platform with a native Dodo Payments integration. Someone shares an affiliate link, Rekomi records the click, and when that visitor buys, the sale arrives from Dodo Payments and the right affiliate is credited automatically. Rekomi calculates the commission and also pays your affiliates for you, in 150+ countries, tax forms included.

The connection is a single paste: you give Rekomi a Dodo Payments API key with write access enabled, and Rekomi validates it, creates the webhook endpoint in your Dodo Payments account itself, and fetches the signing secret directly. There is no webhook form to fill in and nothing to paste back into Dodo Payments.

<Info>
  A "sale" is credited to an affiliate when a referred customer completes a one-time payment, starts a paid subscription, or pays a renewal. Refunds and disputes claw the commission back automatically.
</Info>

## How It Works

Dodo Payments hosts checkout on its own domain, so the affiliate referral travels into the sale as checkout metadata:

1. A visitor clicks an affiliate link and lands on your site, where the Rekomi script stores the referral in their browser.
2. They go to checkout, and you attach that referral to the payment as `rekomi_ref` metadata.
3. Dodo Payments processes the payment and delivers a signed `payment.succeeded` webhook to the endpoint Rekomi created.
4. Rekomi matches the referral to the affiliate, calculates the commission on the pre-tax sale amount, and records it.

Subscription renewals arrive the same way, so recurring commissions need no extra work, and refunds and disputes flow through the same endpoint.

## Prerequisites

Before setting up this integration, ensure you have:

1. A [Dodo Payments account](https://app.dodopayments.com) in live mode
2. A [Rekomi account](https://app.rekomi.com/sign-up)
3. A Dodo Payments API key with **write access** enabled (read-only keys cannot create webhooks)

## Getting Started

<Steps>
  <Step title="Create an API Key with Write Access">
    In your Dodo Payments dashboard, go to **Developer → API Keys** and create a key (name it "Rekomi") with **Enable write access** checked. See the [API key guide](/api-reference/introduction#api-key-management-and-authentication) for detailed instructions.

    <Warning>
      Enable write access on the key: read-only keys pass validation but cannot create the webhook endpoint, so the connection would fail partway.
    </Warning>
  </Step>

  <Step title="Paste the Key into Rekomi">
    In Rekomi, open **Setup → Connect payment processor**, choose Dodo Payments, and paste the key. Rekomi validates it live, creates the webhook endpoint in your account, and fetches its signing secret itself.

    <Frame>
      <img alt="Rekomi's Dodo Payments setup page with the single API key field and connect button" />
    </Frame>

    <Info>
      After connecting, the key is only used to manage the webhook endpoint and run periodic health checks. Your sales arrive through the signed webhook, never through the API.
    </Info>
  </Step>

  <Step title="Install the Rekomi Script">
    Add the Rekomi tracking script to your marketing site so affiliate clicks are captured. Your snippet with the program ID filled in is under **Setup → Install** in Rekomi.

    ```html theme={null}
    <script
      async
      src="https://api.rekomi.com/api/v1/r/loader.js"
      data-program-id="YOUR_PROGRAM_ID"
    ></script>
    ```
  </Step>

  <Step title="Pass the Referral into Checkout">
    Attach the captured referral to each payment as `rekomi_ref` metadata. See the implementation examples below.
  </Step>

  <Step title="Done!">
    Sales, renewals, refunds, and disputes now credit and claw back affiliate commissions automatically, and Rekomi handles paying your affiliates.
  </Step>
</Steps>

## Implementation Guide

### Checkout Sessions via the API

Read the referral on your frontend with `window.Rekomi.getReferral()`, send it to your backend with the checkout request, and set it in `metadata`:

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createCheckout(productId: string, rekomiRef?: string) {
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    return_url: 'https://yoursite.com/success',
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return session.checkout_url;
}
```

The same `metadata.rekomi_ref` field works on subscription products, so the initial charge and every renewal credit the same affiliate.

### Payments API

<Note>
  The example below uses `POST /payments`, which is **deprecated**. It still works for existing integrations, but new integrations should use [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`) — `metadata` is passed the same way.
</Note>

```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createPayment(productId: string, rekomiRef?: string) {
  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    product_cart: [{ product_id: productId, quantity: 1 }],
    payment_link: true,
    metadata: {
      ...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
    },
  });

  return payment;
}
```

### Static Payment Links

Decorate the link with the flat metadata query parameter (not the bracket form):

```javascript theme={null}
const ref = window.Rekomi?.getReferral?.();
let url = 'https://checkout.dodopayments.com/buy/YOUR_PRODUCT_ID';
if (ref) url += `?metadata_rekomi_ref=${encodeURIComponent(ref)}`;
// use url as the href on your Buy button
```

Dodo Payments folds `metadata_*` query parameters into the payment's metadata, where Rekomi reads them.

## What Gets Tracked

| Event                | What happens                                                        |
| -------------------- | ------------------------------------------------------------------- |
| One-time payment     | Commission credited on the pre-tax sale amount                      |
| Subscription renewal | Recurring commission, every charge arrives as its own payment event |
| Refund               | Commission clawed back automatically, never past what was credited  |
| Dispute              | Commission clawed back the moment the dispute opens                 |

<Tip>
  Commissions are calculated on the pre-tax sale amount: Dodo Payments is a Merchant of Record and collects the tax, so your affiliates earn on the sale itself, never on the tax a buyer's country happened to add.
</Tip>

## Important Notes

* Rekomi registers the webhook endpoint with exactly the events it needs. Avoid editing that endpoint's event list in the Dodo Payments dashboard; Rekomi's health checks will flag the connection if events are removed.
* Trials fire no payment until the trial ends, so no commission exists until the first real charge.
* Disconnecting in Rekomi deletes the webhook endpoint from your Dodo Payments account again.

## Additional Resources

<CardGroup>
  <Card title="Rekomi's Dodo Payments Guide" icon="book-open" href="https://rekomi.com/docs/brands/install/dodo">
    The full setup walkthrough, troubleshooting, and security details on Rekomi's docs.
  </Card>

  <Card title="Affiliates Feature Guide" icon="users" href="/features/affiliates">
    All affiliate integration options for Dodo Payments.
  </Card>
</CardGroup>

<Info>
  Need help? Contact Rekomi support at [support@rekomi.com](mailto:support@rekomi.com) or Dodo Payments support at [support@dodopayments.com](mailto:support@dodopayments.com) for assistance with the integration.
</Info>


# Resend
Source: https://docs.dodopayments.com/integrations/resend

Send transactional emails through Resend based on Dodo Payments events with high deliverability.

## Introduction

Send professional transactional emails automatically when payment events occur. Deliver payment confirmations, subscription updates, and important notifications with Resend's reliable email infrastructure and excellent deliverability rates.

<Info>
  This integration requires your Resend API Key for authentication.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Resend">
    Choose the <b>Resend</b> integration card.
  </Step>

  <Step title="Enter API Key">
    Provide your Resend API Key in the configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format emails for Resend's API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the email sending.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now automatically trigger transactional emails via Resend.
  </Step>
</Steps>

## Transformation Code Examples

### Payment Confirmation Email

```javascript payment_confirmation.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.resend.com/emails";
    webhook.payload = {
      from: "payments@yourdomain.com",
      to: [p.customer.email],
      subject: "Payment Confirmation - $" + (p.total_amount / 100).toFixed(2),
      html: `
        <h2>Payment Successful!</h2>
        <p>Hi ${p.customer.name},</p>
        <p>Your payment of $${(p.total_amount / 100).toFixed(2)} has been processed successfully.</p>
        <ul>
          <li><strong>Payment ID:</strong> ${p.payment_id}</li>
          <li><strong>Amount:</strong> $${(p.total_amount / 100).toFixed(2)}</li>
          <li><strong>Date:</strong> ${new Date(webhook.payload.timestamp).toLocaleDateString()}</li>
          <li><strong>Method:</strong> ${p.payment_method || "Unknown"}</li>
        </ul>
        <p>Thank you for your business!</p>
      `,
      text: `Payment Successful! Your payment of $${(p.total_amount / 100).toFixed(2)} has been processed. Payment ID: ${p.payment_id}`
    };
  }
  return webhook;
}
```

### Subscription Welcome Email

```javascript subscription_welcome.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://api.resend.com/emails";
    webhook.payload = {
      from: "welcome@yourdomain.com",
      to: [s.customer.email],
      subject: "Welcome to Your Subscription!",
      html: `
        <h2>Welcome to Your Subscription!</h2>
        <p>Hi ${s.customer.name},</p>
        <p>Your subscription has been activated successfully.</p>
        <ul>
          <li><strong>Subscription ID:</strong> ${s.subscription_id}</li>
          <li><strong>Product:</strong> ${s.product_id}</li>
          <li><strong>Amount:</strong> $${(s.recurring_pre_tax_amount / 100).toFixed(2)}/${s.payment_frequency_interval}</li>
          <li><strong>Next Billing:</strong> ${new Date(s.next_billing_date).toLocaleDateString()}</li>
        </ul>
        <p>You can manage your subscription anytime from your account dashboard.</p>
      `,
      text: `Welcome! Your subscription is now active. Amount: $${(s.recurring_pre_tax_amount / 100).toFixed(2)}/${s.payment_frequency_interval}`
    };
  }
  return webhook;
}
```

### Payment Failure Notification

```javascript payment_failure.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.failed") {
    const p = webhook.payload.data;
    webhook.url = "https://api.resend.com/emails";
    webhook.payload = {
      from: "support@yourdomain.com",
      to: [p.customer.email],
      subject: "Payment Failed - Action Required",
      html: `
        <h2>Payment Failed</h2>
        <p>Hi ${p.customer.name},</p>
        <p>We were unable to process your payment of $${(p.total_amount / 100).toFixed(2)}.</p>
        <ul>
          <li><strong>Payment ID:</strong> ${p.payment_id}</li>
          <li><strong>Amount:</strong> $${(p.total_amount / 100).toFixed(2)}</li>
          <li><strong>Error:</strong> ${p.error_message || "Payment processing failed"}</li>
        </ul>
        <p>Please update your payment method or contact support for assistance.</p>
        <a href="https://yourdomain.com/update-payment">Update Payment Method</a>
      `,
      text: `Payment Failed: We couldn't process your $${(p.total_amount / 100).toFixed(2)} payment. Please update your payment method.`
    };
  }
  return webhook;
}
```

## Tips

* Use verified sender domains for better deliverability
* Include both HTML and text versions of emails
* Personalize content with customer data
* Use clear, action-oriented subject lines
* Include unsubscribe links for compliance
* Test email templates before going live

## Troubleshooting

<AccordionGroup>
  <Accordion title="Emails not being sent">
    * Verify API Key is correct and active
    * Check that sender domain is verified in Resend
    * Ensure recipient email addresses are valid
    * Review Resend sending limits and quotas
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches Resend API format
    * Check that all required fields are present
    * Ensure HTML content is properly formatted
    * Verify from email address is verified
  </Accordion>
</AccordionGroup>


# Segment
Source: https://docs.dodopayments.com/integrations/segment

Send Dodo Payments events to Segment for analytics and customer data platform integration.

## Introduction

Track payment events in Segment to power your analytics, marketing automation, and customer data platform. Send payment, subscription, and customer lifecycle events to 300+ downstream tools automatically.

<Info>
  This integration requires a Segment Write Key from your Segment workspace.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Segment">
    Choose the <b>Segment</b> integration card.
  </Step>

  <Step title="Enter Write Key">
    Provide your Segment Write Key in the configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format events for Segment's Track API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the sync.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now be tracked in Segment and sent to your connected tools.
  </Step>
</Steps>

## Transformation Code Examples

### Track Payment Events

```javascript track_payments.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/track";
    webhook.payload = {
      userId: p.customer.customer_id,
      event: "Payment Completed",
      properties: {
        amount: (p.total_amount / 100).toFixed(2),
        currency: p.currency || "USD",
        payment_method: p.payment_method || "unknown",
        payment_id: p.payment_id,
        customer_email: p.customer.email,
        customer_name: p.customer.name
      },
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}
```

### Track Subscription Lifecycle

```javascript track_subscriptions.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Started",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
          frequency: s.payment_frequency_interval,
          next_billing: s.next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.url = "https://api.segment.io/v1/track";
      webhook.payload = {
        userId: s.customer.customer_id,
        event: "Subscription Cancelled",
        properties: {
          subscription_id: s.subscription_id,
          product_id: s.product_id,
          cancelled_at: s.cancelled_at,
          cancel_at_next_billing: s.cancel_at_next_billing_date,
          customer_email: s.customer.email
        },
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}
```

### Identify Customer Properties

```javascript identify_customer.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.segment.io/v1/identify";
    webhook.payload = {
      userId: p.customer.customer_id,
      traits: {
        email: p.customer.email,
        name: p.customer.name,
        total_spent: (p.total_amount / 100).toFixed(2),
        payment_method: p.payment_method || "unknown",
        last_payment_date: webhook.payload.timestamp,
        customer_since: webhook.payload.timestamp
      }
    };
  }
  return webhook;
}
```

## Tips

* Use consistent event names across your integration
* Include relevant properties for analytics and segmentation
* Set proper timestamps for accurate event tracking
* Use customer IDs as userId for proper user identification

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not appearing in Segment">
    * Verify Write Key is correct and active
    * Check that event names follow Segment naming conventions
    * Ensure userId is properly set for user identification
    * Review Segment API rate limits
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches Segment API format
    * Check that all required fields are present
    * Ensure event names are strings, not objects
  </Accordion>
</AccordionGroup>


# SendGrid
Source: https://docs.dodopayments.com/integrations/sendgrid

Send transactional emails based on Dodo Payments events using SendGrid's Mail Send API.

## Introduction

Automatically send transactional emails for payment confirmations, subscription updates, and important notifications using SendGrid. Trigger personalized emails based on payment events with dynamic content and professional templates.

<Info>
  This integration requires a SendGrid API Key with Mail Send permissions.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select SendGrid">
    Choose the <b>SendGrid</b> integration card.
  </Step>

  <Step title="Enter API Key">
    Provide your SendGrid API Key in the configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format emails for SendGrid's Mail Send API.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the email sending.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now automatically trigger transactional emails via SendGrid.
  </Step>
</Steps>

## Transformation Code Examples

### Payment Confirmation Email

```javascript payment_confirmation.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: p.customer.email }],
          dynamic_template_data: {
            customer_name: p.customer.name,
            payment_amount: (p.total_amount / 100).toFixed(2),
            payment_id: p.payment_id,
            payment_date: new Date(webhook.payload.timestamp).toLocaleDateString(),
            currency: p.currency || "USD"
          }
        }
      ],
      from: {
        email: "payments@yourdomain.com",
        name: "Your Company"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}
```

### Subscription Welcome Email

```javascript subscription_welcome.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "subscription.active") {
    const s = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: s.customer.email }],
          dynamic_template_data: {
            customer_name: s.customer.name,
            subscription_id: s.subscription_id,
            product_name: s.product_id,
            amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
            frequency: s.payment_frequency_interval,
            next_billing: new Date(s.next_billing_date).toLocaleDateString()
          }
        }
      ],
      from: {
        email: "welcome@yourdomain.com",
        name: "Your Company"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}
```

### Payment Failure Notification

```javascript payment_failure.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.failed") {
    const p = webhook.payload.data;
    webhook.url = "https://api.sendgrid.com/v3/mail/send";
    webhook.payload = {
      personalizations: [
        {
          to: [{ email: p.customer.email }],
          dynamic_template_data: {
            customer_name: p.customer.name,
            payment_amount: (p.total_amount / 100).toFixed(2),
            error_message: p.error_message || "Payment processing failed",
            payment_id: p.payment_id,
            retry_link: `https://yourdomain.com/retry-payment/${p.payment_id}`
          }
        }
      ],
      from: {
        email: "support@yourdomain.com",
        name: "Your Company Support"
      },
      template_id: "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    };
  }
  return webhook;
}
```

## Tips

* Use SendGrid dynamic templates for personalized content
* Include relevant payment data in template variables
* Set proper from addresses and sender names
* Use template IDs for consistent email formatting
* Include unsubscribe links for compliance

## Troubleshooting

<AccordionGroup>
  <Accordion title="Emails not being sent">
    * Verify API Key has Mail Send permissions
    * Check that template IDs are valid and active
    * Ensure recipient email addresses are valid
    * Review SendGrid sending limits and quotas
  </Accordion>

  <Accordion title="Transformation errors">
    * Validate JSON structure matches SendGrid API format
    * Check that all required fields are present
    * Ensure template data variables are properly formatted
    * Verify from email addresses are verified in SendGrid
  </Accordion>
</AccordionGroup>


# Slack
Source: https://docs.dodopayments.com/integrations/slack

Integrate Dodo Payments with Slack to receive real-time notifications about your payments.

## Introduction

The Dodo Payments Slack integration allows you to receive real-time notifications about your payments directly in your Slack workspace. This integration enables you to stay updated on the status of your payments, track transactions, and manage your payments more efficiently.

<Info>
  This integration uses our webhook management portal to automatically transform Dodo Payments webhook events into Slack-compatible messages. No additional coding is required - just configure the connector and start receiving notifications.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    Go to the <b>Webhook</b> section in your Dodo Payments dashboard. Click the <b>+ Add Endpoint</b> button, then open the webhook dropdown to reveal other integrations.

    <Frame>
      <img alt="Dodo Payments dashboard showing Add Endpoint button and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Slack Integration">
    Select the <b>Slack</b> integration and click <b>Connect your Slack workspace</b>.

    <Frame>
      <img alt="Slack integration card and connect button" />
    </Frame>
  </Step>

  <Step title="Grant Slack Permissions">
    Grant the necessary permissions to the Incoming Webhooks Slack App so it can post messages in your chosen channel.

    <Frame>
      <img alt="Slack OAuth permissions screen for Incoming Webhooks app" />
    </Frame>
  </Step>

  <Step title="Customize Transformation Code">
    Add or edit the transformation code to customize your Slack notifications for your use case. You can use the pre-made templates or write your own logic.

    <Frame>
      <img alt="Transformation code editor for Slack integration" />
    </Frame>
  </Step>

  <Step title="Test and Create">
    Test your transformation code with custom or pre-made event payloads. Once you're satisfied, click <b>Create</b> to activate the integration.

    <Frame>
      <img alt="Test transformation and create button" />
    </Frame>
  </Step>

  <Step title="Integration Complete!">
    🎉 You have successfully created the Slack integration! Your Dodo Payments events will now be delivered to your selected Slack channel in real time.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Payment Notifications

This transformation sends simple text messages for payment events:

```javascript payment_notifs.js icon="js" expandable theme={null}
function handler(webhook) {
  switch (webhook.eventType) {
    case "payment.succeeded":
      webhook.payload = {
        text: `✅ Payment Successful\nAmount: $${(webhook.payload.data.total_amount / 100).toFixed(2)}\nCustomer: ${webhook.payload.data.customer.email}\nPayment ID: ${webhook.payload.data.payment_id}`
      };
      break;
      
    case "payment.failed":
      webhook.payload = {
        text: `❌ Payment Failed\nAmount: $${(webhook.payload.data.total_amount / 100).toFixed(2)}\nCustomer: ${webhook.payload.data.customer.email}\nReason: ${webhook.payload.data.error_message || 'Unknown'}`
      };
      break;
      
    case "payment.processing":
      webhook.payload = {
        text: `⏳ Payment Processing\nAmount: $${(webhook.payload.data.total_amount / 100).toFixed(2)}\nCustomer: ${webhook.payload.data.customer.email}`
      };
      break;
  }

  return webhook;
}
```

### Rich Subscription Notifications

This transformation creates rich Slack messages with attachments for subscription events:

```javascript subscription_notifs.js icon="js" expandable theme={null}
function handler(webhook) {
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        attachments: [{
          color: "good",
          title: "🎉 Subscription Activated",
          fields: [
            {
              title: "Customer",
              value: webhook.payload.data.customer.email,
              short: true
            },
            {
              title: "Product ID",
              value: webhook.payload.data.product_id,
              short: true
            },
            {
              title: "Amount",
              value: `$${(webhook.payload.data.recurring_pre_tax_amount / 100).toFixed(2)}/${webhook.payload.data.payment_frequency_interval}`,
              short: true
            },
            {
              title: "Next Billing",
              value: new Date(webhook.payload.data.next_billing_date).toLocaleDateString(),
              short: true
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "subscription.cancelled":
      webhook.payload = {
        attachments: [{
          color: "warning",
          title: "⚠️ Subscription Cancelled",
          fields: [
            {
              title: "Customer",
              value: webhook.payload.data.customer.email,
              short: true
            },
            {
              title: "Product ID",
              value: webhook.payload.data.product_id,
              short: true
            },
            {
              title: "Cancellation Date",
              value: new Date(webhook.payload.data.cancelled_at).toLocaleDateString(),
              short: true
            },
            {
              title: "Cancel at Next Billing",
              value: webhook.payload.data.cancel_at_next_billing_date ? "Yes" : "No",
              short: true
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "subscription.renewed":
      webhook.payload = {
        attachments: [{
          color: "good",
          title: "🔄 Subscription Renewed",
          fields: [
            {
              title: "Customer",
              value: webhook.payload.data.customer.email,
              short: true
            },
            {
              title: "Product ID",
              value: webhook.payload.data.product_id,
              short: true
            },
            {
              title: "Amount",
              value: `$${(webhook.payload.data.recurring_pre_tax_amount / 100).toFixed(2)}`,
              short: true
            },
            {
              title: "Next Billing",
              value: new Date(webhook.payload.data.next_billing_date).toLocaleDateString(),
              short: true
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
  }

  return webhook;
}
```

### Dispute Management Notifications

This transformation handles dispute events with appropriate colors and urgency:

```javascript dispute_notifs.js icon="js" expandable theme={null}
function handler(webhook) {
  switch (webhook.eventType) {
    case "dispute.opened":
      webhook.payload = {
        attachments: [{
          color: "danger",
          title: "🚨 New Dispute Opened",
          fields: [
            {
              title: "Payment ID",
              value: webhook.payload.data.payment_id,
              short: true
            },
            {
              title: "Amount",
              value: `$${(webhook.payload.data.amount / 100).toFixed(2)}`,
              short: true
            },
            {
              title: "Status",
              value: webhook.payload.data.dispute_status,
              short: true
            },
            {
              title: "Stage",
              value: webhook.payload.data.dispute_stage,
              short: true
            },
            {
              title: "Remarks",
              value: webhook.payload.data.remarks || "No remarks",
              short: false
            }
          ],
          footer: "Dodo Payments - Action Required",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "dispute.won":
      webhook.payload = {
        attachments: [{
          color: "good",
          title: "✅ Dispute Won",
          fields: [
            {
              title: "Payment ID",
              value: webhook.payload.data.payment_id,
              short: true
            },
            {
              title: "Amount",
              value: `$${(webhook.payload.data.amount / 100).toFixed(2)}`,
              short: true
            },
            {
              title: "Status",
              value: webhook.payload.data.dispute_status,
              short: true
            },
            {
              title: "Resolution",
              value: "Dispute resolved in your favor",
              short: false
            }
          ],
          footer: "Dodo Payments",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
      
    case "dispute.lost":
      webhook.payload = {
        attachments: [{
          color: "danger",
          title: "❌ Dispute Lost",
          fields: [
            {
              title: "Payment ID",
              value: webhook.payload.data.payment_id,
              short: true
            },
            {
              title: "Amount",
              value: `$${(webhook.payload.data.amount / 100).toFixed(2)}`,
              short: true
            },
            {
              title: "Status",
              value: webhook.payload.data.dispute_status,
              short: true
            },
            {
              title: "Impact",
              value: "Funds will be debited from your account",
              short: false
            }
          ],
          footer: "Dodo Payments - Review Required",
          ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
        }]
      };
      break;
  }

  return webhook;
}
```

### Comprehensive All-Events Handler

This transformation handles all event types with consistent formatting:

```javascript all_events_notifs.js icon="js" expandable  theme={null}
function handler(webhook) {
  const event = webhook.payload.data;
  const timestamp = new Date(webhook.payload.timestamp).toLocaleString();
  
  let color, emoji, title, fields = [];
  
  switch (webhook.eventType) {
    case "payment.succeeded":
      color = "good";
      emoji = "✅";
      title = "Payment Successful";
      fields = [
        { title: "Amount", value: `$${(event.total_amount / 100).toFixed(2)}`, short: true },
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Payment ID", value: event.payment_id, short: true },
        { title: "Method", value: event.payment_method || "Unknown", short: true }
      ];
      break;
      
    case "payment.failed":
      color = "danger";
      emoji = "❌";
      title = "Payment Failed";
      fields = [
        { title: "Amount", value: `$${(event.total_amount / 100).toFixed(2)}`, short: true },
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Reason", value: event.error_message || "Unknown", short: false }
      ];
      break;
      
    case "subscription.active":
      color = "good";
      emoji = "🎉";
      title = "Subscription Activated";
      fields = [
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Product ID", value: event.product_id, short: true },
        { title: "Amount", value: `$${(event.recurring_pre_tax_amount / 100).toFixed(2)}/${event.payment_frequency_interval}`, short: true },
        { title: "Next Billing", value: new Date(event.next_billing_date).toLocaleDateString(), short: true }
      ];
      break;
      
    case "subscription.cancelled":
      color = "warning";
      emoji = "⚠️";
      title = "Subscription Cancelled";
      fields = [
        { title: "Customer", value: event.customer.email, short: true },
        { title: "Product ID", value: event.product_id, short: true },
        { title: "Cancellation Date", value: new Date(event.cancelled_at).toLocaleDateString(), short: true },
        { title: "Cancel at Next Billing", value: event.cancel_at_next_billing_date ? "Yes" : "No", short: true }
      ];
      break;
      
    case "refund.succeeded":
      color = "good";
      emoji = "💰";
      title = "Refund Processed";
      fields = [
        { title: "Amount", value: `$${(event.amount / 100).toFixed(2)}`, short: true },
        { title: "Refund ID", value: event.refund_id, short: true },
        { title: "Payment ID", value: event.payment_id, short: true },
        { title: "Reason", value: event.reason || "Not specified", short: true }
      ];
      break;
      
    case "dispute.opened":
      color = "danger";
      emoji = "🚨";
      title = "New Dispute Opened";
      fields = [
        { title: "Payment ID", value: event.payment_id, short: true },
        { title: "Amount", value: `$${(event.amount / 100).toFixed(2)}`, short: true },
        { title: "Status", value: event.dispute_status, short: true },
        { title: "Stage", value: event.dispute_stage, short: true },
        { title: "Remarks", value: event.remarks || "No remarks", short: false }
      ];
      break;
      
    case "license_key.created":
      color = "good";
      emoji = "🔑";
      title = "License Key Created";
      fields = [
        { title: "License ID", value: event.id, short: true },
        { title: "Product ID", value: event.product_id, short: true },
        { title: "License Key", value: event.key.substring(0, 8) + "...", short: true },
        { title: "Expires", value: event.expires_at ? new Date(event.expires_at).toLocaleDateString() : "Never", short: true }
      ];
      break;
      
    default:
      // Handle any other events with a generic format
      color = "warning";
      emoji = "ℹ️";
      title = webhook.eventType.replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
      fields = [
        { title: "Event Type", value: webhook.eventType, short: true },
        { title: "Timestamp", value: timestamp, short: true }
      ];
  }
  
  webhook.payload = {
    attachments: [{
      color: color,
      title: `${emoji} ${title}`,
      fields: fields,
      footer: "Dodo Payments",
      ts: Math.floor(new Date(webhook.payload.timestamp).getTime() / 1000)
    }]
  };

  return webhook;
}
```

## Best Practices

To make your Slack notifications effective:

* Use rich message attachments with colors, fields, and formatting for clarity and actionability.
* Always include key data such as amounts, customer emails, and IDs for quick identification.
* Choose colors that match the event type: green (`good`) for success, red (`danger`) for disputes or failures, yellow (`warning`) for cancellations, and blue (`#3aa3e3`) for informational events.
* Add timestamps to help track when each event occurred.

<Warning>
  **Handle Sensitive Data**: Be careful not to include sensitive information like full license keys or personal data in Slack messages. Consider truncating or masking sensitive values.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Notifications not appearing in Slack">
    * Verify that the Slack webhook URL is correct and active
    * Check that the transformation code is valid JavaScript
    * Ensure the selected event types are being triggered
    * Verify that your Slack app has the necessary permissions
  </Accordion>

  <Accordion title="Transformation errors">
    * Check the webhook management portal for transformation error logs
    * Verify that the webhook payload structure matches your transformation code
    * Test your transformation code with sample data
    * Ensure all required fields are present in the webhook payload
  </Accordion>

  <Accordion title="Missing event types">
    * Confirm that the events you want to receive are enabled in your Dodo Payments webhook configuration
    * Check that the event types are selected in your Slack connector configuration
    * Verify that your endpoint is properly configured to receive the events
  </Accordion>
</AccordionGroup>


# Windmill
Source: https://docs.dodopayments.com/integrations/windmill

Trigger Windmill workflows and scripts based on Dodo Payments events for custom automation.

## Introduction

Execute custom workflows and scripts in Windmill when payment events occur. Run database operations, send notifications, process data, and automate complex business logic with Windmill's powerful workflow engine.

<Info>
  This integration requires your Windmill webhook URL from your workflow configuration.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Windmill">
    Choose the <b>Windmill</b> integration card.
  </Step>

  <Step title="Create Windmill Workflow">
    In Windmill, create a new workflow and copy the webhook URL from the trigger configuration.
  </Step>

  <Step title="Paste Webhook URL">
    Paste the Windmill webhook URL into the endpoint configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format events for your Windmill workflow.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the integration.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now trigger your Windmill workflows automatically.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Workflow Payload

```javascript basic_workflow.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      payment_id: p.payment_id,
      amount: (p.total_amount / 100).toFixed(2),
      currency: p.currency || "USD",
      customer_email: p.customer.email,
      customer_name: p.customer.name,
      payment_method: p.payment_method || "unknown",
      timestamp: webhook.payload.timestamp,
      metadata: {
        business_id: p.business_id,
        product_id: p.product_cart ? p.product_cart.map(i => i.product_id).join(', ') : undefined
      }
    };
  }
  return webhook;
}
```

### Subscription Workflow Handler

```javascript subscription_workflow.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        event_type: "subscription_started",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        customer_name: s.customer.name,
        product_id: s.product_id,
        amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
        frequency: s.payment_frequency_interval,
        next_billing: s.next_billing_date,
        customer_id: s.customer.customer_id,
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.payload = {
        event_type: "subscription_cancelled",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        cancelled_at: s.cancelled_at,
        cancel_at_next_billing: s.cancel_at_next_billing_date,
        customer_id: s.customer.customer_id,
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}
```

### Dispute Workflow Handler

```javascript dispute_workflow.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType.startsWith("dispute.")) {
    const d = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      dispute_id: d.dispute_id,
      payment_id: d.payment_id,
      amount: (d.amount / 100).toFixed(2),
      status: d.dispute_status,
      stage: d.dispute_stage,
      remarks: d.remarks || "",
      urgent: webhook.eventType === "dispute.opened",
      business_id: d.business_id,
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}
```

## Common Windmill Use Cases

<AccordionGroup>
  <Accordion title="Database Operations">
    * Update customer records in PostgreSQL/MySQL
    * Log payment events to data warehouses
    * Sync data to external systems
    * Update inventory levels
    * Track analytics metrics
  </Accordion>

  <Accordion title="Business Logic">
    * Calculate revenue metrics
    * Process refunds and adjustments
    * Handle subscription lifecycle
    * Generate reports and exports
    * Validate payment data
  </Accordion>

  <Accordion title="External Integrations">
    * Send data to analytics platforms
    * Update CRM systems
    * Trigger email campaigns
    * Create calendar events
    * Send SMS notifications
  </Accordion>
</AccordionGroup>

## Tips

* Structure payload data for easy workflow processing
* Include all relevant metadata for business logic
* Use consistent field naming across events
* Include timestamps for workflow timing
* Leverage Windmill's built-in error handling

## Troubleshooting

<AccordionGroup>
  <Accordion title="Workflows not triggering">
    * Verify webhook URL is correct and active
    * Check that Windmill workflow is published and active
    * Ensure payload structure matches workflow expectations
    * Review Windmill execution logs for errors
  </Accordion>

  <Accordion title="Data processing issues">
    * Check workflow input parameter mapping
    * Verify data types match expected formats
    * Test workflow with sample data
    * Review Windmill script execution logs
  </Accordion>
</AccordionGroup>


# WooCommerce Plugin
Source: https://docs.dodopayments.com/integrations/woocommerce-plugin

Integrate Dodo Payments seamlessly with your WooCommerce store to accept global payments through UPI, cards, and more.

## Introduction

The Dodo Payments WooCommerce plugin provides a seamless integration with your store, enabling you to accept payments through multiple methods including UPI, cards, net banking, and digital wallets. This comprehensive guide will walk you through the installation and configuration process.

## Step-by-Step Installation Guide

1. Download the latest zip of the WooCommerce payment plugin.

   <Card title="Download Plugin" icon="download" href="https://github.com/dodopayments/dodo-woocommerce/releases">
     Get the latest version of our WooCommerce plugin
   </Card>

   Alternatively, you can install directly from the WordPress plugin directory:

   <Card title="WordPress Plugin Directory" icon="wordpress" href="https://wordpress.org/plugins/dodo-payments-for-woocommerce/">
     Install Dodo Payments for WooCommerce from WordPress.org
   </Card>

2. Log in to your WordPress website as an administrator (we assume you already have WooCommerce set up)

3. Navigate to **Plugins → Add New Plugin**

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

4. Click on the **Upload Plugin** button and a file selection dialog will appear

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

5. Click **Browse…** and select the zip file you downloaded

6. Click the **Install Now** button to begin the installation process

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

7. After installation completes, click **Activate Plugin** or activate it from the **Installed Plugins** section

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

8. The plugin is now installed, but configuration is still required. Continue to the setup guide below.

## Configuration Guide

### Setting Up API Keys and Webhooks

1. Navigate to **WooCommerce → Settings → Payments** or click the **Payments** button in the left sidebar below the WooCommerce menu item

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

2. Enable the **Dodo Payments** payment provider if not already enabled, then click **Manage** to configure the plugin

3. You'll see various configuration options, each with helpful explanatory text. Begin by setting up your Live API Key

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

4. Log in to your Dodo Payments dashboard in **Live Mode**, then navigate to **Dodo Payments (Live Mode) > Developer > API Keys** or visit [this direct link](https://app.dodopayments.com/developer/api-keys) and click **Add API Key**

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

5. Give your API Key a descriptive name and click **Create**

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

6. Copy the generated API Key and paste it into the **Live API Key** field in your WooCommerce plugin settings

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

7. Next, set up the Webhook Signing Key to enable payment status synchronization between Dodo Payments and WooCommerce

8. Scroll to the bottom of the plugin settings page and copy the webhook URL displayed there

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

9. Return to your Dodo Payments dashboard and navigate to **Dodo Payments (Live Mode) > Developer > Webhooks** and click **Add Webhook**

   <Frame>
     <img alt="Dodo Payments for WooCommerce Plugin" />
   </Frame>

10. Paste the URL you copied in step 8 into the dialog and click **Add Webhook**

    <Frame>
      <img alt="Dodo Payments for WooCommerce Plugin" />
    </Frame>

11. After creating the webhook, click the eye icon next to the redacted **Signing Key** to reveal and copy it

    <Frame>
      <img alt="Dodo Payments for WooCommerce Plugin" />
    </Frame>

12. Paste the Signing Key into the **Live Webhook Signing Key** field in your plugin settings and save the changes

    <Frame>
      <img alt="Dodo Payments for WooCommerce Plugin" />
    </Frame>

13. Review the remaining settings such as **Global Tax Category** and **All Prices are Tax Inclusive**, as these options determine how products sync from WooCommerce to Dodo Payments. Note that **Test API Key** and **Test Webhook Signing Key** are only needed if you plan to use Test Mode

    <Frame>
      <img alt="Dodo Payments for WooCommerce Plugin" />
    </Frame>

## You're All Set!

Your WooCommerce store is now integrated with Dodo Payments! Customers can select Dodo Payments at checkout to access all supported payment methods.

<Frame>
  <img alt="Dodo Payments checkout option in WooCommerce" />
</Frame>

When customers choose Dodo Payments, they'll be seamlessly redirected to the Dodo Payments checkout page to complete their transaction.

<Frame>
  <img alt="Dodo Payments checkout page" />
</Frame>

## Key Features

* **Seamless Checkout Experience**: Redirect customers to a secure, optimized checkout page
* **Multiple Payment Methods**: Support for various local and international payment options
* **Real-time Status Updates**: Instant order status synchronization via webhooks
* **Detailed Transaction Records**: Comprehensive payment history in your WooCommerce dashboard
* **Multi-currency Support**: Accept payments in multiple currencies

## Troubleshooting

### Common Issues

1. **Payment Processing Failures**
   * Verify API keys are correctly configured
   * Ensure webhook URL is properly set up
   * Check that your SSL certificate is valid

2. **Webhook Synchronization Problems**
   * Confirm webhook signing key matches
   * Review server logs for potential errors
   * Verify your server can receive incoming webhook requests

### Support Resources

For additional assistance:

* Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* Refer to our [comprehensive documentation](https://docs.dodopayments.com)

## Maintenance Best Practices

1. Regularly update the plugin for security patches and new features
2. Test all payment flows in Test Mode before processing live transactions
3. Keep WordPress and WooCommerce updated to the latest versions
4. Implement regular site backups
5. Monitor transaction logs for any unusual activity
6. Store API keys securely and never share them publicly


# Zapier
Source: https://docs.dodopayments.com/integrations/zapier

Connect Dodo Payments to 5000+ apps through Zapier webhooks for unlimited automation possibilities.

## Introduction

Connect Dodo Payments to thousands of apps and services through Zapier. Automate workflows by triggering Zaps when payment events occur, from sending emails to updating spreadsheets, creating tasks, and much more.

<Info>
  This integration requires a Zapier webhook URL from your Zap configuration.
</Info>

## Getting Started

<Steps>
  <Step title="Open the Webhook Section">
    In your Dodo Payments dashboard, navigate to <b>Webhooks → + Add Endpoint</b> and expand the integrations dropdown.

    <Frame>
      <img alt="Add Endpoint and integrations dropdown" />
    </Frame>
  </Step>

  <Step title="Select Zapier">
    Choose the <b>Zapier</b> integration card.
  </Step>

  <Step title="Create Zap in Zapier">
    In Zapier, create a new Zap with "Webhooks by Zapier" as the trigger. Copy the webhook URL.
  </Step>

  <Step title="Paste Webhook URL">
    Paste the Zapier webhook URL into the endpoint configuration.
  </Step>

  <Step title="Configure Transformation">
    Edit the transformation code to format data for your Zapier workflow.
  </Step>

  <Step title="Test & Create">
    Test with sample payloads and click <b>Create</b> to activate the integration.
  </Step>

  <Step title="Done!">
    🎉 Payment events will now trigger your Zapier workflows automatically.
  </Step>
</Steps>

## Transformation Code Examples

### Basic Webhook Payload

```javascript basic_webhook.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const p = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      payment_id: p.payment_id,
      amount: (p.total_amount / 100).toFixed(2),
      currency: p.currency || "USD",
      customer_email: p.customer.email,
      customer_name: p.customer.name,
      payment_method: p.payment_method || "unknown",
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}
```

### Subscription Event Handler

```javascript subscription_webhook.js icon="js" expandable theme={null}
function handler(webhook) {
  const s = webhook.payload.data;
  switch (webhook.eventType) {
    case "subscription.active":
      webhook.payload = {
        event_type: "subscription_started",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        customer_name: s.customer.name,
        product_id: s.product_id,
        amount: (s.recurring_pre_tax_amount / 100).toFixed(2),
        frequency: s.payment_frequency_interval,
        next_billing: s.next_billing_date,
        timestamp: webhook.payload.timestamp
      };
      break;
    case "subscription.cancelled":
      webhook.payload = {
        event_type: "subscription_cancelled",
        subscription_id: s.subscription_id,
        customer_email: s.customer.email,
        cancelled_at: s.cancelled_at,
        cancel_at_next_billing: s.cancel_at_next_billing_date,
        timestamp: webhook.payload.timestamp
      };
      break;
  }
  return webhook;
}
```

### Dispute Alert Handler

```javascript dispute_webhook.js icon="js" expandable theme={null}
function handler(webhook) {
  if (webhook.eventType.startsWith("dispute.")) {
    const d = webhook.payload.data;
    webhook.payload = {
      event_type: webhook.eventType,
      dispute_id: d.dispute_id,
      payment_id: d.payment_id,
      amount: (d.amount / 100).toFixed(2),
      status: d.dispute_status,
      stage: d.dispute_stage,
      remarks: d.remarks || "",
      urgent: webhook.eventType === "dispute.opened",
      timestamp: webhook.payload.timestamp
    };
  }
  return webhook;
}
```

## Popular Zapier Use Cases

<AccordionGroup>
  <Accordion title="Email Notifications">
    * Send Gmail/Outlook emails for payment confirmations
    * Create email sequences in Mailchimp/ConvertKit
    * Send Slack/Discord notifications
    * Create Google Sheets records
  </Accordion>

  <Accordion title="CRM Updates">
    * Add contacts to HubSpot/Salesforce
    * Create deals in Pipedrive/Close
    * Update customer records in Airtable
    * Log activities in Monday.com
  </Accordion>

  <Accordion title="Task Management">
    * Create tasks in Asana/Trello
    * Add to-do items in Notion
    * Create calendar events
    * Send SMS notifications via Twilio
  </Accordion>
</AccordionGroup>

## Tips

* Keep payload structure simple for easy Zapier parsing
* Use consistent field names across all events
* Include timestamps for workflow timing
* Test your Zap with sample data before going live
* Use Zapier's built-in filters for conditional logic

## Troubleshooting

<AccordionGroup>
  <Accordion title="Zap not triggering">
    * Verify webhook URL is correct and active
    * Check that Zap is turned on in Zapier
    * Ensure payload structure matches Zapier expectations
    * Test webhook delivery in Zapier dashboard
  </Accordion>

  <Accordion title="Data not mapping correctly">
    * Check field names in Zapier action steps
    * Verify data types match expected formats
    * Use Zapier's test feature to debug mapping
    * Ensure transformation code returns valid JSON
  </Accordion>
</AccordionGroup>


# v0.1.0 (25 Nov 2024)
Source: https://docs.dodopayments.com/changelog/v0.1.0

This is the initial release of the Dodo Payments documentation, marking the Beta launch of our product. Explore the features and improvements designed to enhance your payment processing experience.

## Smooth Onboarding

* Comprehensive onboarding tracker to monitor merchant progress.
* Support for document resubmission and live-mode activation upon verification.

## Product Catalogue Management

* Easy creation, editing, and deletion of one-time and subscription products.

## Payment Link

* Generate payment links for one-time and subscription products.
* Includes configurable quantities and redirection options for post-payment customer journeys.

## Customizable Checkout Page

* Branded checkout experiences with localized payment options available.
* Real-time tax and total amount calculation displayed on checkout.

## Automated Invoice Generation

* Automatic invoice generation for payments, refunds, and payouts.

## Refund Management

* Seamless partial and full refund management from the dashboard.
* Introduced dispute tracking for effective resolutions.

## Transparent Payouts

* Flexible payout mechanisms with transparent policies and fees.

## Analytics and Reporting

* Advanced analytics dashboard to showcase total revenue, transaction breakdown, customer insights, and top-performing product types.

## API and Webhook Generation

* Easy-to-generate API keys to integrate Dodo Payments into your website or application.
* Webhook setup for real-time notifications about transactions, refunds, and disputes.


# Community Projects
Source: https://docs.dodopayments.com/community/overview

Discover community-built SDKs, plugins, and boilerplates for Dodo Payments.

<Info>
  This is a curated list of open-source projects created by the community. These projects are not affiliated with or endorsed by Dodo Payments unless explicitly stated.
</Info>

* **What you'll find**: SDKs, webhook handlers, plugins, and starters across languages
* **How to use**: Evaluate licensing, maintenance status, and security for your use case
* **How to contribute**: Submit your project via our template on the "Submit your project" page

<Warning>
  Use at your own risk. Review code, licenses, and security posture before production use.
</Warning>

<CardGroup>
  <Card title="Projects Directory" icon="grid" href="/community/projects">
    Browse by type and language with links to code and docs.
  </Card>

  <Card title="Submit Your Project" icon="plus" href="/community/submit">
    Add your project with a short PR using our template.
  </Card>
</CardGroup>


# Projects Directory
Source: https://docs.dodopayments.com/community/projects

Community-maintained libraries, plugins, and boilerplates for Dodo Payments.

Browse community projects by category. Each card links directly to the repository.

<Tabs>
  <Tab title="Libraries & SDKs">
    <CardGroup>
      <Card title="dodopayments-webhooks (TypeScript)" href="https://github.com/sancho1952007/dodopayments-webhooks" icon="node-js">
        Universal webhook verification and handlers for multiple frameworks.
        <br />Includes signature verification and typed event handling for Express, Hono, Elysia, and more.
        <br /><br />By <a href="https://github.com/sancho1952007">@sancho1952007</a> (Sancho Godinho)
        <br /><br />`TypeScript` `Webhooks` `Node`
      </Card>

      <Card title="dodpayments_rust_sdk (Rust)" href="https://github.com/Muhammad-Owais-Warsi/dodpayments_rust_sdk" icon="rust">
        Rust SDK for interacting with Dodo Payments APIs.
        <br />Provides typed models and helpers to call core endpoints from Rust services.
        <br /><br />By <a href="https://github.com/Muhammad-Owais-Warsi">@Muhammad-Owais-Warsi</a>
        <br /><br />`Rust` `SDK`
      </Card>

      <Card title="Dodo Payments Laravel SDK (PHP)" href="https://github.com/codeplugtech/dodo-payments" icon="php">
        Laravel SDK for Dodo Payments.
        <br />Easily integrate Dodo Payments APIs into your Laravel applications with ready-made service classes and helpers.
        <br /><br />By <a href="https://github.com/codeplugtech">@codeplugtech</a>
        <br /><br />`PHP` `Laravel` `SDK`
      </Card>

      <Card title="dodo-payments-rs (Rust)" href="https://github.com/PiyushXCoder/dodo-payments-rs" icon="rust">
        Easy-to-use SDK for interacting with Dodo Payments APIs.
        <br />It comes with predefined structures for requests and responses and uses a builder pattern to simplify constructing and sending payment-related API calls.
        <br /><br />By <a href="https://github.com/PiyushXCoder">@PiyushXCoder</a>
        <br /><br />`Rust` `SDK`
      </Card>

      <Card title="multi-app-dodo-payments (Python)" href="https://github.com/aniketkarne/multi-app-dodo-payments" icon="python">
        Handle Dodo Payments for multiple applications using single microservice application:
        <br />Production-ready payment microservice built with FastAPI that handles payments for multiple applications using Dodo Payments.
        <br />Features include <br /> `credit management`, `subscription support`, `webhook processing with idempotency`, `complete audit trails`, `MixPanel Analytics`, `Backend-to-backend architecture with API key authentication`.
        <br /><br />By <a href="https://github.com/aniketkarne">@aniketkarne</a> (Aniket Karne)
        <br /><br />`Python` `Fast-API` `Library`
      </Card>

      <Card title="Dodo Payments Flutter SDK (Dart)" href="https://github.com/MrPrinceRawat/dodopayments-flutter" icon="mobile">
        Flutter/Dart SDK for Dodo Payments with full API coverage.
        <br />20 resources, 60+ methods, typed models, and a drop-in DodoCheckoutButton widget with WebView.
        <br /><br />By <a href="https://github.com/MrPrinceRawat">@MrPrinceRawat</a>
        <br /><br />`Dart` `Flutter` `SDK`
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Plugins & Extensions">
    <CardGroup>
      <Card title="Dodo WHMCS (PHP)" href="https://github.com/Akash123a5/dodo-whmcs" icon="php">
        WHMCS payment gateway module integration.
        <br />Drop-in provider to accept payments in WHMCS using Dodo Payments.
        <br /><br />By <a href="https://github.com/Akash123a5">@Akash123a5</a>
        <br /><br />`PHP` `WHMCS` `Plugin`
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Boilerplates & Starters">
    <CardGroup>
      <Card title="DodoPayments Boilerplate" href="https://github.com/snehalsaurabh/DodoPayments-Boilerplate" icon="rocket">
        Starter boilerplate for integrating Dodo Payments quickly.
        <br />Includes example checkout flow, API wiring, and environment configuration.
        <br /><br />By <a href="https://github.com/snehalsaurabh">@snehalsaurabh</a>
        <br /><br />`Boilerplate`
      </Card>

      <Card title="Dodo Payments Boilerplate" href="https://github.com/vanshcodeworks/dodo_payments_boilerplate" icon="rocket">
        Lightweight starter for common flows.
        <br />Minimal setup to create and confirm payments with example pages.
        <br /><br />By <a href="https://github.com/vanshcodeworks">@vanshcodeworks</a>
        <br /><br />`Boilerplate`
      </Card>

      <Card title="PaymentService" href="https://github.com/rasadov/PaymentService" icon="rocket">
        Service template with payment flows.
        <br />Demonstrates clean architecture around payment intents and webhooks.
        <br /><br />By <a href="https://github.com/rasadov">@rasadov</a>
        <br /><br />`Template`
      </Card>

      <Card title="DodoStarter Boilerplate" href="https://github.com/AINotSoSmart/dodostarter" icon="rocket">
        Next.js SaaS starter with Supabase authentication and Dodo Payments integration.
        <br />You can go from an empty folder to a working app in an afternoon.
        <br /><br />By <a href="https://github.com/KissuChaudhary">@KissuChaudhary</a>
        <br /><br />`TypeScript` `Next.js` `Boilerplate`
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

<Note>
  Want your project listed? See <a href="/community/submit">Submit your project</a>.
</Note>


# Submit Your Project
Source: https://docs.dodopayments.com/community/submit

How to add your open-source project to the Dodo Payments community directory.

<Steps>
  <Step title="Check eligibility">
    * The project is open-source with a permissive license.
    * It’s relevant to Dodo Payments (SDK, plugin, integration, template).
    * Has a README with install, usage, and maintenance status.
  </Step>

  <Step title="Add entry via PR">
    Edit `community/projects.mdx` and add a new `<Card>` under the most relevant tab.

    ```mdx theme={null}
    <Card title="PROJECT_NAME (LANG)" href="REPO_URL" icon="code">
      One-sentence description of your project.
      <br/>By <a href="GITHUB_PROFILE_URL">@github_username</a>
      <br/><br/>`LANGUAGE` `FRAMEWORK` `CATEGORY`
    </Card>
    ```
  </Step>

  <Step title="Open submission issue (optional)">
    If you prefer, open an issue using the "Community Project Submission" template with:

    * Repo URL, description, category (SDK/Plugin/Boilerplate)
    * Primary language/framework
    * Install/usage snippet link
    * Maintenance status and last update
  </Step>

  <Step title="Review & publish">
    We review for relevance, clarity, and safety. Approved entries are merged and published.
  </Step>
</Steps>

<Warning>
  We may remove entries that are unmaintained, insecure, misleading, or violate policy.
</Warning>