Information on how AI Docs integrates with payment providers and handles billing-related webhooks.
AI Docs provides a robust system for managing user subscriptions and billing, leveraging a dedicated Billing API and real-time webhooks from our payment provider, Dodo. This ensures that your subscription status, plan details, and payment history are always accurate and up-to-date, facilitating a seamless experience for upgrading, managing, and monitoring your AI Docs plan.
The AI Docs application exposes several API endpoints to handle various aspects of billing and subscription management. These endpoints interact with Dodo, our payment provider, to process transactions and retrieve subscription information.
POST /api/billing/checkout)This endpoint allows users to initiate a secure checkout process to upgrade to a Pro plan. When a user selects a plan (monthly or annual) from the AI Docs dashboard, a request is sent to this endpoint to create a Dodo checkout session.
Method: POST
Endpoint: /api/billing/checkout
Headers:
Content-Type: application/jsonAuthorization: Bearer YOUR_AUTH_TOKEN (required for user authentication)Body: JSON object with the desired planType.
{
"planType": "monthly"
}
planType: (string, required) Specifies the billing cycle. Accepted values are "monthly" or "annual".Status: 200 OK on success, 503 Service Unavailable if the payment system is not configured.
Body: JSON object containing the checkout_url.
{
"checkout_url": "https://checkout.dodopayments.com/session/..."
}
checkout_url: (string) The URL to which the user should be redirected to complete the payment via Dodo's secure payment page.curl -X POST \
https://app.aidocs.com/api/billing/checkout \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
-d '{
"planType": "annual"
}'
The return_url specified during session creation ensures that users are redirected back to their AI Docs billing page after completing the payment, where their Pro plan will be activated.
POST /api/billing/sync)This endpoint allows for the manual synchronization of a user's subscription status from Dodo to the AI Docs database. It is particularly useful as a fallback mechanism if real-time webhooks are missed due to network issues, application downtime, or local development environments (e.g., when using ngrok which might be down).
Method: POST
Endpoint: /api/billing/sync
Headers:
Content-Type: application/json (optional, if body is empty)Authorization: Bearer YOUR_AUTH_TOKEN (required for user authentication)Body: Optional JSON object with a subscription_id.
{
"subscription_id": "sub_xxxxxxxxxxxxxx"
}
subscription_id: (string, optional) The Dodo subscription ID to synchronize. If omitted, the system attempts to retrieve the user's existing Dodo subscription ID from the AI Docs database.Status: 200 OK on success, 404 Not Found if no subscription is found, 403 Forbidden if the subscription does not belong to the authenticated user.
Body: JSON object indicating the synchronization status.
{
"ok": true,
"plan": "pro",
"status": "active"
}
ok: (boolean) Indicates if the synchronization was successful.plan: (string) The synchronized plan type ("pro" or "free").status: (string) The synchronized subscription status (e.g., "active", "cancelled", "on_hold", "expired").The endpoint includes a critical security check to ensure that the retrieved subscription's user_id metadata matches the ID of the authenticated user making the request. This prevents users from querying or modifying subscriptions that do not belong to them.
AI Docs also provides endpoints for managing active subscriptions, such as cancelling or resuming a plan. While the specific code for these is not detailed here, they follow a similar pattern of authenticated API calls to Dodo. For more information on how to use these features, refer to Managing Your Subscription.
POST /api/webhooks/dodo)Webhooks are a fundamental part of AI Docs' billing system, enabling Dodo to notify the application in real-time about significant events related to subscriptions and payments. This ensures that your subscription status within AI Docs is always current, reflecting changes like plan activations, renewals, cancellations, or payment issues without requiring manual checks.
POST/api/webhooks/dodoTo ensure the integrity and authenticity of incoming webhook events, AI Docs verifies the signature of each request using the DODO_WEBHOOK_SECRET environment variable. This prevents malicious actors from sending forged webhook payloads. If the signature verification fails, the webhook request is rejected with a 400 Bad Request status.
It is crucial to configure DODO_WEBHOOK_SECRET in your Environment Configuration. Without it, webhook processing will fail, leading to discrepancies in subscription statuses.
The webhook handler processes various Dodo event types, updating the local AI Docs database accordingly.
// Simplified webhook event handling logic
switch (event.type) {
case "subscription.active": {
// A new subscription is active or a plan has been changed to active.
// Upsert the subscription record, setting status to "active".
break;
}
case "subscription.renewed": {
// An active subscription has successfully renewed.
// Update the currentPeriodEnd and status to "active".
break;
}
case "subscription.plan_changed": {
// A user's plan has been upgraded or downgraded.
// Update billingPeriod, currentPeriodEnd, and cancelAtPeriodEnd.
break;
}
case "subscription.cancelled": {
// A user has cancelled their subscription.
// Set status to "cancelled" and cancelAtPeriodEnd to true.
break;
}
case "subscription.on_hold": {
// The subscription is temporarily paused, often due to payment failure.
// Set status to "on_hold".
break;
}
case "subscription.expired": {
// The subscription period has ended without renewal.
// Set status to "expired" and revert plan to "free".
break;
}
default:
// Ignore other event types not relevant to AI Docs' core billing logic.
break;
}
If an error occurs during the processing of a webhook event (e.g., a database update fails), the AI Docs webhook handler returns a 500 Internal Server Error. This signals to Dodo that the event was not successfully processed, prompting Dodo to retry sending the webhook event later.
The Billing API and Dodo Webhooks work in concert to power the subscription management features within AI Docs. For instance, when you upgrade to a Pro plan, the /api/billing/checkout endpoint facilitates the payment, and Dodo webhooks (subscription.active) then confirm the activation of your Pro plan within AI Docs. Similarly, actions like cancelling or resuming your subscription, as detailed in Managing Your Subscription, rely on corresponding API calls and subsequent webhook notifications to keep your status accurate.
While not directly part of the Billing API or Webhooks for modifying subscriptions, the AI Docs dashboard fetches your payment history by querying Dodo's payment API. This allows you to view past transactions, amounts, and statuses, and access invoices. For more details on accessing your payment records, refer to Payment History.
DODO_WEBHOOK_SECRET is set securely in your production environment variables, as outlined in Environment Configuration./api/billing/sync endpoint.