JavaScript API reference

window.addEventListener('abconvert:ready', function (event) {
  const ABConvert = event.detail;
  console.log(ABConvert.getAssignments());
});

window.addEventListener('abconvert:assignment-ready', function (event) {
  const assignment = event.detail;
  console.log(assignment.experimentId, assignment.testGroup.index);
});

interface ABConvertAPI {
  onReady(callback: (api: ABConvertAPI) => void): void;
  getAssignments(): Assignment[];
  getAssignment(experimentId: string): Assignment | null;
  getPriceByVariantId?(variantId: string, options?: PriceOptions): Price | null;
  getPriceByProductId?(productId: string, options?: PriceOptions): Price | null;
  formatPrice(amount: number, currency?: string): string;
  getShippingRates?(options?: ShippingOptions): ShippingRate[] | null;
  getFreeShippingThreshold?(options?: ShippingOptions): FreeShippingThreshold | null;
  getOffers?(): Offer[];
  track(name: string, payload?: { value?: unknown }): void;
  getVisitorId(): string;
  getCountry(): string;
  forceTestGroup(experimentId: string, index: number): void;
  clearForcedTestGroup(experimentId: string): void;
}

interface Window {
  ABConvert?: ABConvertAPI;
  ABConvertQueue?: Array<(api: ABConvertAPI) => void>;
}

interface Assignment {
  experimentId: string;
  experimentName: string;
  type: 'price' | 'shipping' | 'theme' | 'template' | 'url_redirect' | 'checkout' | 'offer' | 'visual_editor' | 'combined' | 'personalization';
  status: 'active' | 'preview';
  testGroup: TestGroup;
  reason: 'random_split' | 'force_assign_group' | 'preview_override' | 'url_force_assign';
}

interface TestGroup {
  index: number;
  name: string;
  control: boolean;
  split: number;
}

interface Price {
  experimentId: string;
  testGroup: TestGroup;
  amount: number;
  compareAtAmount: number | null;
  currency: string;
  country: string;
  productId: string;
  variantId: string;
}

interface PriceOptions {
  country?: string;
  aggregate?: 'min' | 'max' | 'first';
}

interface ShippingRate {
  experimentId: string;
  testGroup: TestGroup;
  zone: string;
  name: string;
  amount: number;
  currency: string;
  condition: { type: 'price' | 'weight'; minimum: number | null; maximum: number | null; unit: string | null } | null;
}

interface FreeShippingThreshold {
  experimentId: string;
  testGroup: TestGroup;
  zone: string;
  amount: number;
  currency: string;
}

interface ShippingOptions {
  zone?: string;
}

interface Offer {
  experimentId: string;
  testGroup: TestGroup;
  title: string;
  discounts: Discount[];
}

type Discount =
  | { type: 'product_discount';   value: DiscountValue; scope?: DiscountScope; condition?: DiscountCondition }
  | { type: 'order_discount';     value: DiscountValue; condition?: DiscountCondition }
  | { type: 'shipping_discount';  value: DiscountValue; scope?: ShippingDiscountScope; condition?: DiscountCondition }
  | { type: 'volume_discount';    tiers: VolumeTier[]; scope?: DiscountScope; condition?: DiscountCondition }
  | { type: 'threshold_discount'; tiers: ThresholdTier[]; condition?: DiscountCondition };

type DiscountValue =
  | { unit: 'percentage'; value: number; maxDiscountAmount?: Money }   // percent off, capped at maxDiscountAmount
  | { unit: 'fixed'; amount: Money };

type DiscountScope =                                            // omitted = all products
  | { type: 'all_products' }
  | { type: 'specific_products'; productIds: string[] }
  | { type: 'specific_collections'; collectionIds: string[] };

type ShippingDiscountScope =                                    // omitted = all rates
  | { type: 'all_rates' }
  | { type: 'specific_rates'; rateNames: string[] };

type DiscountCondition =
  | { type: 'order_price'; minimum: Money }
  | { type: 'quantity'; minimum: number };

type VolumeTier = { threshold: number; value: DiscountValue };      // threshold: item count
type ThresholdTier = { threshold: Money; value: DiscountValue };    // threshold: order subtotal
type Money = { amount: number; currency: string };