Next.js route handlers

​

Before you start

1. In the dashboard, create the products you sell. Copy each product’s link ID from the product page.
2. Open Developers → API keys and create a key. A key that starts with sk_test_ works in test mode.
3. Open Settings → Developers → Webhooks and set the URL to https://your-domain.com/api/webhooks/agentaos. Click Reveal signing secret and copy the secret.
4. Add both values to your environment:

AGENTAOS_API_KEY=sk_test_...
AGENTAOS_WEBHOOK_SECRET=whsec_...

​

Install

npm install @agentaos/nextjs

​

Add the checkout route

import { Checkout } from '@agentaos/nextjs';

export const GET = Checkout({
  products: { pro: 'your-pro-link-id', team: 'your-team-link-id' },
  successUrl: 'https://your-domain.com/thanks',
  // Optional: who is buying, read from your own session on the server
  customer: async () => {
    const user = await getCurrentUser();
    return user ? { email: user.email, name: user.name, metadata: { userId: user.id } } : null;
  },
});

<a href="/checkout?product=pro">Buy Pro</a>

• A buyer can only buy a product that is in products, by its slug. The route adds the slug to the checkout metadata as product.
• The buyer’s details, the metadata and the return URLs come from your server, never from the link.
• The route ignores prefetch requests, so a link that scrolls into view does not start a checkout. With the Next.js <Link> component, set prefetch={false}.
• After paying, the buyer returns to successUrl with ?sessionId=... added.

​

Add the webhook route

import { Webhooks } from '@agentaos/nextjs';

export const POST = Webhooks({
  webhookSecret: process.env.AGENTAOS_WEBHOOK_SECRET!,
  onCheckoutCompleted: async (event) => {
    const { userId, product } = event.data.metadata;
    // Renewals and upgrade charges arrive here too, without your metadata.
    if (typeof userId !== 'string') return;
    await grantAccess(userId, product);
  },
  onSubscriptionCanceled: async (event) => {
    // event.data.customerEmail identifies the buyer
  },
});

​

Handle events

• Use event.data.metadata.product to know what was bought. On checkout.session.completed, event.data.linkId is the payment link’s public token, not the link ID in products.
• Expect your metadata on the first checkout.session.completed only. Renewals and upgrade charges also arrive as checkout.session.completed, with AgentaOS’s subscriptionId in the metadata instead. Save the link from subscriptionId to your user from the first event.
• Read metadata keys in camelCase. A key you send as user_id arrives as userId.
• Ignore test events in live mode: check event.data.livemode.
• Give access only once, because an event can arrive more than once. For checkouts, save event.data.sessionId.

​

Use your own client

import { AgentaOS } from '@agentaos/pay';
import { Checkout } from '@agentaos/nextjs';

export const GET = Checkout({
  client: new AgentaOS(process.env.AGENTAOS_API_KEY!, { timeout: 10_000 }),
  products: { pro: 'your-pro-link-id' },
  successUrl: 'https://your-domain.com/thanks',
});