@dodopayments/nuxt module gives your Nuxt app three server route handlers. checkoutHandler returns checkout URLs, customerPortalHandler sends a customer to the Customer Portal, and Webhooks verifies webhook events and routes them to your code.
Checkout API Route
Create checkout URLs from a Nuxt server route.
Customer Portal API Route
Let customers manage their subscriptions and details from a Nuxt server route.
Webhooks API Route
Receive and verify Dodo Payments webhook events in Nuxt.
Overview
The module registers its handlers as Nuxt server auto-imports, so your server routes call
checkoutHandler, customerPortalHandler, and Webhooks without import statements. Each route reads your credentials from runtimeConfig. Nuxt exposes only runtimeConfig.public to the browser, so the API key and webhook secret stay on the server.Installation
1
Install the Nuxt Module
Run this command in your project root:The module lists Nuxt 3 (3.13.1 or later) and
zod 3.25 or later as peer dependencies.2
Register the Module in nuxt.config.ts
Add Set these environment variables, for example in a
@dodopayments/nuxt to your modules array, and map your credentials into runtimeConfig:nuxt.config.ts
.env file in your project root:A built Nuxt server doesn’t read your
.env file. At runtime, Nuxt overrides a runtimeConfig value only from the variable that matches its path, such as NUXT_PRIVATE_RETURN_URL for private.returnUrl, so set these variables in your hosting environment too.API Route Handler Examples
The examples create server routes in the
server/routes/api/ directory. Nuxt routes each file by its name and method suffix, so checkout.get.ts handles GET /api/checkout.- Checkout API Route
- Customer Portal API Route
- Webhook API Route
Use this handler to add Dodo Payments checkout to your Nuxt app. A GET route serves static checkout. A POST route serves checkout sessions.
Checkout Route Handler
The checkout handler supports all three ways to take payments with Dodo Payments:- Static Payment Links: Shareable URLs that collect payments without code.
- Dynamic Payment Links (deprecated): Payment links you generate with custom details. They use deprecated endpoints.
- Checkout Sessions: Hosted checkout with a product cart, customer details, and customization options. This is the recommended flow.
checkoutHandler takes these options:
Static Checkout (GET)
Static Checkout (GET)
Supported Query Parameters
Fixes the amount charged, in major currency units, for example
12.5 for $12.50. Works with Pay What You Want products only, and is ignored if it’s below the product’s minimum price.returnUrl from its config to the link as redirect_url.Response Format
Static checkout returns a JSON response with the checkout URL. In test mode, the URL usestest.checkout.dodopayments.com.Dynamic Checkout (POST)
Dynamic Checkout (POST)
Checkout Sessions (POST)
Checkout Sessions (POST)
Checkout sessions create a hosted checkout for one-time purchases and subscriptions, with full control over customization.
product_cart is the only required field, and it needs at least one product. If the body has no return_url, the handler uses returnUrl from its config.For more details and every supported field, see the Checkout Sessions Integration Guide.A session created with payment_method_id returns no checkout URL, so the handler responds with 400. To charge a saved payment method, create the session with the SDK instead.Response Format
Checkout sessions return a JSON response with the checkout URL:Customer Portal Route Handler
The Customer Portal route handler creates a Customer Portal session for the customer you pass and redirects the browser to it.Query Parameters
Webhook Route Handler
The webhook route handler verifies each request before it runs your code:- Method: Only POST requests are supported. Other methods return 405.
- Signature Verification: Verifies the raw request body and the
webhook-id,webhook-timestamp, andwebhook-signatureheaders withwebhookKey, following the Standard Webhooks specification. Returns 401 if verification fails. - Payload Validation: Validates the payload with Zod. Returns 400 for an invalid payload.
- Error Handling:
- 401: Invalid signature
- 400: Invalid payload
- 500: Internal error during verification
- Event Routing: Calls
onPayloadfor every event, then the handler for the event’s type, and returns 200.