1. Customer completes checkout
        │
        v
2. Create upsell session with offers
        │
        v
3. Customer sees first offer
        │
    ┌───┴───┐
    │       │
 Accept   Decline
    │       │
    v       v
4. Charge   Next offer
   saved    (or exit)
   payment
        │
        v
5. Repeat until no more offers

POST /api/upsell/create-session
Content-Type: application/json

interface CreateSessionRequest {
  orderId: string;              // New order ID for upsells
  originalOrderId: string;      // Original checkout order ID
  customerEmail: string;
  customerId?: string;
  paymentMethodToken?: string;  // Token from checkout completion
  provider: PaymentProviderType;
  currency?: string;            // Default: "USD"
  offers: UpsellOffer[];
  metadata?: Record<string, string>;

  // For targeting rules
  cartTotal?: number;           // Original cart total in cents
  purchasedProductIds?: string[];
  
  // Theming
  themeId?: string;             // Theme to apply to upsell pages
}

interface UpsellOffer {
  id: string;
  name: string;
  description?: string;
  price: number;                // In cents
  originalPrice?: number;       // For showing discount
  image?: string;
  showIf?: TargetingRules;
}

interface TargetingRules {
  minCartValue?: number;        // Minimum cart value in cents
  productIds?: string[];        // Show only if purchased these
  excludeProductIds?: string[]; // Hide if purchased these
}

{
  "orderId": "upsell_order_123",
  "originalOrderId": "order_abc123",
  "customerEmail": "customer@example.com",
  "paymentMethodToken": "pm_1ABC|cus_XYZ",
  "provider": "stripe",
  "currency": "USD",
  "offers": [
    {
      "id": "offer_1",
      "name": "Premium Upgrade",
      "description": "Upgrade to premium for 50% off",
      "price": 4999,
      "originalPrice": 9999,
      "image": "https://example.com/upgrade.jpg",
      "showIf": {
        "minCartValue": 2500
      }
    },
    {
      "id": "offer_2",
      "name": "Extended Warranty",
      "description": "2-year extended warranty",
      "price": 1999,
      "showIf": {
        "productIds": ["prod_123"]
      }
    }
  ],
  "cartTotal": 9999,
  "purchasedProductIds": ["prod_123"],
  "themeId": "theme_xyz123"
}

{
  "success": true,
  "sessionId": "sess_abc123",
  "upsellUrl": "/upsell/sess_abc123",
  "expiresAt": 1704110400000,
  "totalOffers": 2
}

{
  "success": true,
  "skipUpsell": true,
  "message": "No eligible upsell offers for this customer"
}

POST /api/upsell/accept
Content-Type: application/json

{
  "sessionId": "sess_abc123",
  "offerId": "offer_1"
}

{
  "success": true,
  "transactionId": "pi_upsell_123",
  "offerAccepted": "offer_1",
  "amountCharged": 4999,
  "hasMoreOffers": true,
  "totalUpsellAmount": 4999
}

POST /api/upsell/decline
Content-Type: application/json

{
  "sessionId": "sess_abc123",
  "offerId": "offer_1"
}

{
  "success": true,
  "hasMoreOffers": true,
  "nextOfferId": "offer_2"
}

GET /api/upsell/session/:id

{
  "success": true,
  "session": {
    "id": "sess_abc123",
    "status": "active",
    "currentStep": 1,
    "totalOffers": 2,
    "acceptedOffers": ["offer_1"],
    "declinedOffers": [],
    "totalUpsellAmount": 4999,
    "expiresAt": 1704110400000
  }
}

https://[YOUR_DOMAIN]/upsell/action/[ACTION]/[SESSION_ID]

<!-- On your external landing page -->
<a href="https://checkout.mysite.com/upsell/action/accept/sess_abc123" class="btn btn-primary">
  Yes! Add to Order ($19.99)
</a>

{
  "showIf": {
    "minCartValue": 5000
  }
}

{
  "showIf": {
    "productIds": ["prod_123", "prod_456"]
  }
}

{
  "showIf": {
    "excludeProductIds": ["warranty_123"]
  }
}

{
  "showIf": {
    "minCartValue": 2500,
    "productIds": ["prod_electronics"],
    "excludeProductIds": ["bundle_complete"]
  }
}

{
  "success": true,
  "orderId": "order_123",
  "paymentMethodToken": "pm_1ABC|cus_XYZ"
}

POST /api/checkout/get-payment-token
Content-Type: application/json

{
  "provider": "stripe",
  "transactionId": "pi_123"
}

// Session expired
{
  "error": "Session expired",
  "status": 400
}

// Invalid offer ID
{
  "error": "Offer not found in session",
  "status": 404
}

// Payment failed
{
  "error": "Payment failed: Card declined",
  "status": 402
}

// After successful checkout
const checkoutResult = await fetch('/api/checkout/complete', {
  method: 'POST',
  body: JSON.stringify({
    orderId: 'order_123',
    transactionId: 'pi_abc',
    provider: 'stripe',
    // ... other fields
  }),
});

const { paymentMethodToken, orderId } = await checkoutResult.json();

// Create upsell session
const sessionResult = await fetch('/api/upsell/create-session', {
  method: 'POST',
  body: JSON.stringify({
    orderId: `upsell_${orderId}`,
    originalOrderId: orderId,
    customerEmail: 'customer@example.com',
    paymentMethodToken,
    provider: 'stripe',
    offers: [
      {
        id: 'premium_upgrade',
        name: 'Premium Upgrade',
        price: 4999,
        originalPrice: 9999,
      },
    ],
    cartTotal: 9999,
    purchasedProductIds: ['prod_123'],
  }),
});

const session = await sessionResult.json();

if (session.skipUpsell) {
  // Redirect to success page
  window.location.href = '/success';
} else {
  // Redirect to upsell page
  window.location.href = session.upsellUrl;
}