Checkout UI Extension 提供了用于获取信息的 API。

本页按结账页面中的常见信息类型整理 CheckoutAPI 能力，包括订单、商品、价格、用户和地址等。使用这些 API 时，建议先确认 extension 所在页面和生命周期，再决定是直接读取当前值，还是注册对应的变更回调来响应页面状态变化。涉及回调注册的接口，通常需要在组件卸载或不再使用时移除回调，避免重复监听。

订单相关

interface OrderInfo {
  // 结账货币，例如 USD
  currencyCode: string;
  // 结账货币符号，$
  currencySymbol: string;
  // 已支付行项目列表
  alreadyPaymentLines: AlreadyPaymentLines;

  failCode: string;
  id: string;
  status: OrderStatus;
  checkoutStatus: string;
  financialStatus: string;
  orderNo: string;
  cancelReason: string;
  // 以下两个字段仅在"感谢"页面上可用
  exceptionError?: string;
  exceptionErrorMessage?: string;
  additionalPrices?: AdditionalPrice[];
}

CheckoutAPI.store.getOrderInfo(): OrderInfo;

type OrderStatus = 'opened' | 'placed' | 'cancelled' | 'finished';

/**
* 获取订单状态
*/
CheckoutAPI.store.getOrderStatus(): OrderStatus;

interface ReferInfo {
  clientId: string;
  country: string;
  domain: string;
  fbc: string;
  fbp: string;
  ip: string;
  source: 'buy_now' | 'back' | 'cart';
  userAgent: string;
  payMethod: string;
  note: string;
}

/**
* 获取订单的来源信息
*/
CheckoutAPI.store.getReferInfo(): ReferInfo;

商品信息

interface UIProduct {
  id: string;
  variantId: string;
  productTitle: string;
  properties: ProductItem['properties'];
  discountApplications: ProductItem['discountApplications'];
  options: ProductItem['options'];
  isFreeGift: boolean;
  quantity: ProductItem['quantity'];
  linePrice: ProductItem['linePrice'];
  discountTotal?: ProductItem['discountTotal'];
  finalLinePrice?: ProductItem['finalLinePrice'];
  compareAtPrice: ProductItem['compareAtPrice'];
  price: ProductItem['price'];
  coverUrl: string;
}

/**
获取商品列表，该列表为包含 properties 字段的行项目列表
*/
CheckoutAPI.summary.getProductList(): UIProduct[];

价格相关

interface CheckoutPrices {
  subtotalPrice: string;
  shippingPrice: string;
  taxPrice: string;
  discountCodePrice: string;
  discountPrice: string;
  totalPrice: string;
  discountLineItemPrice: string;
  totalTipReceived: string;
  discountShippingPrice: string;
  giftCardPrice: string;
  paymentDue: string; // 应付金额
  paidTotal: string;
  discountSubTotal?: string;
  shippingTaxTotal?: string;
  allTaxTotal?: string;
  paymentDiscountTotal?: string; // 支付折扣
  prePaymentAmount?: string; 
  additionalPrices?: AdditionalPrice[];
}

/**
* 获取订单的价格信息
*/
CheckoutAPI.store.getPrices(): CheckoutPrices;

type PricesChangeCb = (prices: CheckoutPrices) => void;

/**
* 添加/移除价格变更回调
*/
CheckoutAPI.store.onPricesChange(cb: PricesChangeCb): void;
CheckoutAPI.store.removePricesChangeCb(cb: PricesChangeCb): void;

用户相关

/**
* 检查用户是否已登录
*/
CheckoutAPI.user.isLogin(): boolean;

/**
* 跳转至登录页面
* @param returnUrlSearchParams 可在返回 URL 中附加额外的搜索参数
*/
CheckoutAPI.user.doLogin(returnUrlSearchParams?: Record<string, string>): void;

/**
* 跳转至注册页面
*/
CheckoutAPI.user.doRegister(): void;

/**
* 退出登录
*/
CheckoutAPI.user.doLogout(): Promise<void>;

/**
* 获取已登录用户的信息
*/
CheckoutAPI.user.getUserInfo(): UserInfo;

地址相关

interface AddressValues {
  id?: string;
  firstName: string;
  lastName: string;
  countryCode: string;
  country: string;
  provinceCode: string;
  province: string;
  area: string;
  city: string;
  address: string;
  address1: string;
  // 邮政编码
  zip: string;
  // 税号
  cpf?: string;
  // 税号名称
  taxText?: string;
  // 身份证号
  idNumber?: string;
  // 身份证号名称
  idNumberText?: string;
  company: string;
  latitude?: string;
  longitude?: string;
  source?: string;
  tags?: string;
  gender?: string;

  phone: string;
  emailOrPhone: string;
  email: string;
  phoneAreaCode: string;
  [key: string]: string | undefined;
  originId?: string;
}

/**
* 获取收货地址值对象
*/
CheckoutAPI.address.getShippingAddress(): AddressValues;

/**
* 注册收货地址值变更的回调函数
* @param cb
*/
CheckoutAPI.address.onShippingAddressChange(cb: AddressValuesChangeCb): void;

/**
* 移除收货地址值变更的回调函数。
* 注册与移除需成对使用，代码须自成体系。
* @param cb
*/
CheckoutAPI.address.removeShippingAddressChangeCb(cb: AddressValuesChangeCb): void;

步骤相关

Checkout API 还提供了与页面步骤相关的方法：

type CheckoutStep = 'contact_information' | 'shipping_method' | 'payment_method';

/**
* 获取当前步骤
*/
CheckoutAPI.step.getStep(): CheckoutStep;

/**
* 跳转至信息页面
* @param type
*/
CheckoutAPI.step.stepNavToInformation(): Promise<void>;

/**
* 跳转至配送页面
* @param type
*/
CheckoutAPI.step.stepNavToShipping(): Promise<void>;

/**
* 跳转至支付页面
*/
CheckoutAPI.step.stepNavToPayment(): Promise<void>;

type StepChangeCb = () => void;

/**
* 步骤变更回调
* @param cb
*/
CheckoutAPI.step.onStepChange(cb: StepChangeCb): void;

/**
* 移除步骤变更回调
* @param cb
*/
CheckoutAPI.step.removeStepChangeCb(cb: StepChangeCb): void;

/**
* 用于设置 location.href
*/
CheckoutAPI.step.locationHref(url: string): void;

/**
* 跳转至首页
*/
CheckoutAPI.step.goToHomePage(): void;