API Reference

https://your-domain.com/acp/v1

POST /checkout_sessions

interface CreateSessionRequest {
  cart_items: CartItem[];
  buyer_context?: BuyerContext;
  currency?: string;  // Default: "USD"
}
 
interface CartItem {
  product_id: string;
  quantity: number;
  variant_id?: string;
}
 
interface BuyerContext {
  shipping_address?: Address;
  billing_address?: Address;
  email?: string;
}

interface CheckoutSession {
  checkout_session_id: string;
  state: SessionState;
  cart: Cart;
  totals: Totals;
  shipping_options?: ShippingOption[];
  expires_at: string;  // ISO 8601
}

GET /checkout_sessions/{session_id}

PATCH /checkout_sessions/{session_id}

interface UpdateSessionRequest {
  buyer_context?: BuyerContext;
  selected_shipping_option?: string;
}

POST /checkout_sessions/{session_id}/complete

interface CompleteRequest {
  payment_data: PaymentData;
}
 
interface PaymentData {
  token: string;      // Shared Payment Token
  provider: string;   // "stripe"
}

interface CompletedSession extends CheckoutSession {
  state: "completed";
  order: Order;
}
 
interface Order {
  order_id: string;
  order_number: string;
  status: OrderStatus;
  estimated_delivery?: string;
  tracking_url?: string;
}

POST /checkout_sessions/{session_id}/cancel

type SessionState =
  | "not_ready_for_payment"
  | "ready_for_payment"
  | "completed"
  | "cancelled"
  | "expired";

type OrderStatus =
  | "pending"
  | "confirmed"
  | "processing"
  | "shipped"
  | "delivered"
  | "cancelled";

interface Address {
  name: string;
  line1: string;
  line2?: string;
  city: string;
  state: string;
  postal_code: string;
  country: string;  // ISO 3166-1 alpha-2
}

interface Totals {
  items_base_amount: number;
  discount?: number;
  subtotal: number;
  shipping?: number;
  tax: number;
  total: number;
}

interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
}