Medusa Plugin: LookTwice (medusa-plugin-looktwice)

Official LookTwice integration plugin for Medusa v2.

Add production-grade EU VAT validation (VIES), checkout email screening, IBAN validation, and CPSC product safety recall screening to your Medusa store.

Features

• EU VAT Validation with Outage Resilience: Live VIES validation that distinguishes invalid VAT numbers from temporary registry outages (503 / MS_UNAVAILABLE), preventing checkout abandonment.
• Audit-Grade Consultation IDs: Stores official VIES request identifiers (request_identifier) for tax audits.
• Disposable Email Screening: Detects temporary and burner email domains at customer registration.
• CPSC Recall Catalog Screening: Automated matching of product titles, brands, models, and UPCs against 9,500+ official CPSC recalls and safety warnings.
• Zero-Cost Error Semantics: Upstream network failures release reserved credits and cost 0.

Installation

pnpm add medusa-plugin-looktwice looktwice-api
# or
npm install medusa-plugin-looktwice looktwice-api

Configuration

In your medusa-config.js or medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils";

export default defineConfig({
  projectConfig: {
    // ...
  },
  modules: [
    {
      resolve: "medusa-plugin-looktwice",
      options: {
        apiKey: process.env.LOOKTWICE_API_KEY,
        // Optional settings:
        allowUncheckedVatOnViesOutage: true, // Default: true (doesn't block checkout on VIES downtime)
        blockDisposableEmails: false,        // Default: false
      },
    },
  ],
});

Usage Examples

1. Validating EU VAT Numbers at Checkout

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
import { LookTwiceService } from "medusa-plugin-looktwice";

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const looktwice: LookTwiceService = req.scope.resolve("looktwiceService");
  const { country_code, vat_number } = req.body as { country_code: string; vat_number: string };

  const result = await looktwice.validateVat({
    country_code,
    vat_number,
  });

  if (result.valid) {
    // Apply B2B tax exemption and record request_identifier for audit
    return res.json({
      exempt: true,
      company_name: result.name,
      company_address: result.address,
      request_identifier: result.request_identifier,
    });
  }

  if (result.isOutageFallback) {
    // VIES is currently down; allow order but flag for background re-validation
    return res.json({
      exempt: false,
      flagged_for_review: true,
      reason: "VIES service temporarily unavailable",
    });
  }

  return res.status(400).json({
    message: "Invalid VAT number provided",
  });
}

2. Screening Products Against CPSC Recalls

import { LookTwiceService } from "medusa-plugin-looktwice";

export async function screenProduct(looktwice: LookTwiceService, product: { product_name: string; brand?: string; upc?: string }) {
  const match = await looktwice.screenProductRecall({
    product_name: product.product_name,
    brand: product.brand,
    upc: product.upc,
  });

  if (match.match_level === "exact" || match.match_level === "likely") {
    console.warn(`[RECALL ALERT] Product matches recall ${match.candidates[0].recall_number}: ${match.candidates[0].title}`);
    // Take safety action: unpublish product or flag inventory
  }
}

License

MIT © LookTwice