Developer Documentation

Integrate in 5 Minutes

Copy-paste ready code examples, detailed API reference, and AI-friendly prompts to get cart recovery running in your Next.js app instantly.

3 lines of code
AES-256 encrypted
500+ developers

Quick Start

1

Get Your API Key

Sign up for free and grab your API key from the dashboard. No credit card required.

Start Free Trial
2

Track Cart Updates

Send cart data when users add items. We'll handle the rest.

await fetch('https://retakeapi.com/api/v1/track', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.RETAKE_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event: 'CART_UPDATE',
    sessionId: user.sessionId,
    items: cart.items,
    total: cart.total,
    currency: 'USD',           // optional, defaults to USD
    customerEmail: user.email, // optional, see note below
    customerName: user.name    // optional
  })
});
typescript
3

Track Order Completion

When a purchase is made, we automatically cancel pending recovery emails.

await fetch('https://retakeapi.com/api/v1/track', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.RETAKE_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event: 'ORDER_COMPLETE',
    sessionId: user.sessionId,
    orderId: order.id,  // optional
    total: order.total
  })
});
typescript

AI IDE Integration

Copy & Paste for AI Assistants
Use this prompt with Cursor, Windsurf, Antigravity, Claude, or any AI coding assistant
Act as a Senior Full-Stack Engineer. Your task is to integrate Retake (Cart Recovery System) into a Next.js/React e-commerce application.

Implementation Specs:
1. CART_UPDATE Event:
   - Trigger: Whenever the cart state updates (add/remove item, qty change).
   - Endpoint: POST https://retakeapi.com/api/v1/track
   - Headers: 
     - 'Content-Type': 'application/json'
     - 'X-API-Key': process.env.RETAKE_API_KEY
   - Payload:
     {
       "event": "CART_UPDATE",
       "sessionId": "Unique session ID (cookie/localStorage)",
       "items": [{ "id": "sku_1", "name": "Product", "price": 100, "quantity": 1 }],
       "total": 100.00,
       "currency": "USD",
       "customerEmail": "[email protected]" // Optional but recommended
     }

2. ORDER_COMPLETE Event:
   - Trigger: Immediately after successful payment/order placement.
   - Endpoint: POST https://retakeapi.com/api/v1/track
   - Payload:
     {
       "event": "ORDER_COMPLETE",
       "sessionId": "Same session ID as above",
       "orderId": "INV-123",
       "total": 100.00
     }

3. Important Considerations:
   - Debounce the CART_UPDATE calls (e.g., 500ms) to avoid rate limiting during rapid quantity changes.
   - Ensure 'sessionId' is consistent across the session.
   - 'customerEmail' is optional. If missing, Retake will rely on Webhooks (cart.abandoned) for you to handle email sending.

💡 Tip: Paste this into your AI IDE and it will implement cart recovery automatically.

API Reference

POST
/api/v1/track
Track cart events and trigger recovery workflows

Headers

X-API-KeyYour API key from dashboard
Content-Typeapplication/json

Request Body Parameters

ParameterTypeRequiredDescription
eventstring✓ YesEvent type: 'CART_UPDATE' or 'ORDER_COMPLETE'
sessionIdstring✓ YesUnique session/user identifier for cart tracking
itemsarray✓ YesArray of cart items with id, name, price, quantity
totalnumber✓ YesTotal cart value in your currency
currencystringNoCurrency code (default: 'USD')
customerEmailstringNoCustomer email for direct recovery emails
customerNamestringNoCustomer name for personalized emails
orderIdstringNoOrder ID (for ORDER_COMPLETE event)
Success Response (CART_UPDATE)
{
  "success": true,
  "cartId": "cart_abc123",
  "scheduledAt": "2024-01-01T01:00:00Z"
}
json
Success Response (ORDER_COMPLETE)
{
  "success": true,
  "message": "Order completed, recovery emails cancelled"
}
json

Webhooks & Email Handling

💡 Don't have customer email at cart time?

If you can't capture the customer's email during cart updates (common in guest checkout flows), you can use webhooks to receive abandoned cart notifications and send recovery emails from your own system.

Configure your webhook URL in the dashboard settings, then handle the cart.abandoned event to look up the customer email from your database and send emails through your preferred service.

Webhook Handler Example
Handle abandoned cart webhooks when customerEmail is not provided
// Handle Retake webhooks with signature verification
// app/api/webhooks/retake/route.ts
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

// Verify webhook signature
function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

export async function POST(request: NextRequest) {
  const body = await request.text();
  const signature = request.headers.get('X-Webhook-Signature');
  
  // Verify signature if you configured a webhook secret in dashboard
  if (process.env.RETAKE_WEBHOOK_SECRET && signature) {
    if (!verifySignature(body, signature, process.env.RETAKE_WEBHOOK_SECRET)) {
      return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
    }
  }
  
  const payload = JSON.parse(body);
  // Payload structure: { event, timestamp, data: { cartId, sessionId, ... } }
  
  switch (payload.event) {
    case 'cart.abandoned':
      // Fired when no customerEmail provided - send email yourself
      const customer = await db.customers.findBySession(payload.data.sessionId);
      await sendRecoveryEmail({ to: customer.email, cartItems: payload.data.items });
      break;
      
    case 'email.sent':
      // Fired after Retake successfully sends recovery email
      await analytics.track('recovery_email_sent', payload.data);
      break;
      
    case 'cart.recovered':
      // Fired when ORDER_COMPLETE received after recovery email was sent
      await analytics.track('cart_recovered', { revenue: payload.data.total });
      break;
  }
  
  return NextResponse.json({ received: true });
}
typescript
Webhook Events
EventDescription
cart.abandonedFired when a cart is marked as abandoned (after delay period)
email.sentFired when a recovery email is successfully sent
cart.recoveredFired when an abandoned cart is converted to an order
email.clickedFired when customer clicks the recovery link in email

Framework Examples

Next.js App Router
Complete API route example for Next.js 13+
// app/api/cart/update/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const { cart, user } = await request.json();
  
  await fetch('https://retakeapi.com/api/v1/track', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.RETAKE_API_KEY!,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      event: 'CART_UPDATE',
      sessionId: user.sessionId,
      items: cart.items,
      total: cart.total,
      customerEmail: user.email
    })
  });
  
  return NextResponse.json({ success: true });
}
typescript

Email Providers (BYOK)

📧

Resend

Modern email API with great developer experience. Just add your API key.

☁️

AWS SES

Amazon Simple Email Service. Great for high-volume sending at low cost.

🔷

SendGrid

Reliable email delivery at scale. Just provide your API key.

📨

Mailgun

Powerful email APIs. Configure with your API Key and Domain.

🔌

Any SMTP

Connect any custom SMTP server. Supports standard auth and TLS.

📧 Resend Configuration

Get your API key from resend.com.

API Key: re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
☁️ AWS SES Configuration

Create an IAM user with SES permissions. You'll need:

Access Key ID: AKIAIOSFODNN7EXAMPLE
Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Default region: us-east-1

🔷 SendGrid Configuration

Create an API Key with "Mail Send" permissions in SendGrid.

API Key: SG.xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx
📨 Mailgun Configuration

Enter your sending domain and private API key from Mailgun.

Domain: mg.yourdomain.com
API Key: key-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
🔌 SMTP Configuration

Enter connection details for your SMTP server.

Host: smtp.provider.com
Port: 587 (TLS) or 465 (SSL)
Username/Password: Your credentials

Your Keys Stay Safe

All email provider credentials are encrypted with AES-256 before storage. We never see your raw API keys, and you can revoke access anytime from the dashboard.

Frequently Asked Questions

How does cart recovery work?

When you track a CART_UPDATE event, Retake schedules recovery emails based on your configured delay (default: 60 minutes). If an ORDER_COMPLETE event is received before the email is sent, we automatically cancel the job—no duplicate emails ever.

What if I don't have the customer's email?

No problem! The customerEmail field is optional. Configure webhooks in your dashboard to receive cart.abandoned events, then look up the email from your database and send recovery emails through your own system.

Is my data secure?

Absolutely. All email provider credentials are encrypted with AES-256 before storage. You own your data, we never see your raw email provider keys, and you can delete everything anytime.

Can I customize email templates?

Yes! We provide 4 professionally designed templates included with all plans. You can customize colors, logo, and messaging from the dashboard. Growth and Lifetime plans include full white-label customization.

Recovery URL Parameter?

We automatically append ?session_id=... to your Recovery URL. You should use this parameter to restore the user's cart session when they land on your checkout page.

Ready to Recover Lost Sales?

Join 500+ developers building better e-commerce experiences with Retake. Start for free today.

Start Free Trial
Retake - Recover Abandoned Carts