Agentic Checkout Specification

POST /checkout_sessions

interface CreateSessionRequest {
  cart_items: Array<{
    product_id: string;
    variant_id?: string;
    quantity: number;
  }>;
  buyer_context?: {
    shipping_address?: Address;
    email?: string;
  };
  currency: string;
}

interface CreateSessionResponse {
  checkout_session_id: string;
  state: 'not_ready_for_payment' | 'ready_for_payment';
  cart: { items: LineItem[] };
  totals: Totals;
  fulfillment_options: FulfillmentOption[];
  expires_at: string;
}

POST /checkout_sessions/{id}/complete

interface CompleteCheckoutRequest {
  payment_data: {
    token: string;      // Shared Payment Token
    provider: 'stripe';
    billing_address?: Address;
  };
}

interface CompleteCheckoutResponse {
  checkout_session_id: string;
  state: 'completed';
  order: {
    order_id: string;
    order_number: string;
    permalink_url: string;
    status: 'confirmed';
  };
}

interface Totals {
  items_base_amount: number;
  items_discount: number;
  subtotal: number;
  discount: number;
  fulfillment: number;
  tax: number;
  fee: number;
  total: number;
}

interface Address {
  line1: string;
  line2?: string;
  city: string;
  state?: string;
  postal_code: string;
  country: string;
}

import crypto from 'crypto';
 
function verifySignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const message = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('base64');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}