Checkout API

The Checkout UI Extension provides an API for retrieving information.

Order-related

interface OrderInfo {
  // Checkout currency, e.g. USD
  currencyCode: string;
  // Checkout symbol, $
  currencySymbol: string;
  // List of already paid lines
  alreadyPaymentLines: AlreadyPaymentLines;

  failCode: string;
  id: string;
  status: OrderStatus;
  checkoutStatus: string;
  financialStatus: string;
  orderNo: string;
  cancelReason: string;
  // These two fields are only available on the "thank you" page
  exceptionError?: string;
  exceptionErrorMessage?: string;
  additionalPrices?: AdditionalPrice[];
}

CheckoutAPI.store.getOrderInfo(): OrderInfo;

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

/**
* Get the order status
*/
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;
}

/**
* Get the referral information of the order
*/
CheckoutAPI.store.getReferInfo(): ReferInfo;

Product Information


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;
}

/**
Get the product list, which is a list of line items that include the properties field
*/
CheckoutAPI.summary.getProductList(): UIProduct[];


Price-related

interface CheckoutPrices {
  subtotalPrice: string;
  shippingPrice: string;
  taxPrice: string;
  discountCodePrice: string;
  discountPrice: string;
  totalPrice: string;
  discountLineItemPrice: string;
  totalTipReceived: string;
  discountShippingPrice: string;
  giftCardPrice: string;
  paymentDue: string; // Amount due
  paidTotal: string;
  discountSubTotal?: string;
  shippingTaxTotal?: string;
  allTaxTotal?: string;
  paymentDiscountTotal?: string; // Payment discount
  prePaymentAmount?: string; 
  additionalPrices?: AdditionalPrice[];
}

/**
* Get the pricing information for the order
*/
CheckoutAPI.store.getPrices(): CheckoutPrices;

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

/**
* Add/remove price change callback
*/
CheckoutAPI.store.onPricesChange(cb: PricesChangeCb): void;
CheckoutAPI.store.removePricesChangeCb(cb: PricesChangeCb): void;

User-related

/**
* Check if the user is logged in
*/
CheckoutAPI.user.isLogin(): boolean;

/**
* Redirect to the login page
* @param returnUrlSearchParams Additional search parameters can be added to the return URL
*/
CheckoutAPI.user.doLogin(returnUrlSearchParams?: Record<string, string>): void;

/**
* Redirect to the registration page
*/
CheckoutAPI.user.doRegister(): void;

/**
* Log out
*/
CheckoutAPI.user.doLogout(): Promise<void>;

/**
* Get the logged-in user's information
*/
CheckoutAPI.user.getUserInfo(): UserInfo;

Address-related

interface AddressValues {
  id?: string;
  firstName: string;
  lastName: string;
  countryCode: string;
  country: string;
  provinceCode: string;
  province: string;
  area: string;
  city: string;
  address: string;
  address1: string;
  // Postal code
  zip: string;
  // Tax number
  cpf?: string;
  // Tax number name
  taxText?: string;
  // ID number
  idNumber?: string;
  // ID number name
  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;
}

/**
* Get the shipping address values object
*/
CheckoutAPI.address.getShippingAddress(): AddressValues;

/**
* Register callback for shipping address value changes
* @param cb
*/
CheckoutAPI.address.onShippingAddressChange(cb: AddressValuesChangeCb): void;

/**
* Remove the callback for shipping address value changes. 
* Registration and removal should match, the code should be self-contained.
* @param cb
*/
CheckoutAPI.address.removeShippingAddressChangeCb(cb: AddressValuesChangeCb): void;

Step-related

The Checkout API also provides methods related to page steps:

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

/**
* Get the current step
*/
CheckoutAPI.step.getStep(): CheckoutStep;

/**
* Navigate to the information page
* @param type
*/
CheckoutAPI.step.stepNavToInformation(): Promise<void>;

/**
* Navigate to the shipping page
* @param type
*/
CheckoutAPI.step.stepNavToShipping(): Promise<void>;

/**
* Navigate to the payment page
*/
CheckoutAPI.step.stepNavToPayment(): Promise<void>;

type StepChangeCb = () => void;

/**
* Callback for step change
* @param cb
*/
CheckoutAPI.step.onStepChange(cb: StepChangeCb): void;

/**
* Remove callback for step change
* @param cb
*/
CheckoutAPI.step.removeStepChangeCb(cb: StepChangeCb): void;

/**
* Use this for setting location.href
*/
CheckoutAPI.step.locationHref(url: string): void;

/**
* Navigate to the home page
*/
CheckoutAPI.step.goToHomePage(): void;