CheckoutAPI reference

CheckoutAPI is the global object the checkout platform mounts on window.CheckoutAPI, on the checkout page and on the thank-you page. Its methods are grouped into namespaces such as order, store and address, and let an extension read the order and the choices the buyer has made, listen for those values changing, and drive part of the checkout UI. The methods listed here are the checkout CheckoutAPI methods open to apps, following the platform's public capability list. Every type named in a method signature is defined in Types at the end of this page.

Quick start

CheckoutAPI splits its methods into 15 namespaces, and every call has the same shape: CheckoutAPI.<namespace>.<method>(). The example below prints an overview of the checkout page — the current step, the order, the totals and the line items — and to do that it reaches into three namespaces: step, store and summary. Get it running and you know how to use the whole page: when you need a piece of data, find the namespace that owns it and look up the method name in its table.

const MOUNT_INTERVAL_MS = 100;
const MOUNT_MAX_ATTEMPTS = 50; // 100ms * 50 ≈ 5 seconds

// CheckoutAPI is attached to window only after the checkout page has finished
// loading, so poll for it instead of reading window.CheckoutAPI directly.
function mount(cb, attempt = 0) {
  if (window.CheckoutAPI) {
    cb(window.CheckoutAPI);
    return;
  }
  if (attempt >= MOUNT_MAX_ATTEMPTS) {
    console.warn('CheckoutAPI did not mount within the expected time');
    return;
  }
  window.setTimeout(() => mount(cb, attempt + 1), MOUNT_INTERVAL_MS);
}

// Kept in a variable so it can be taken off again with
// api.store.removePricesChangeCb(onPricesChange).
const onPricesChange = (prices) => console.log('total is now', prices.totalPrice);

mount((api) => {
  const order = api.store.getOrderInfo();
  const prices = api.store.getPrices();
  const products = api.summary.getProductList();

  console.log('step:', api.step.getStep());
  console.log('order:', order.orderNo, order.status, order.currencyCode);
  console.log('subtotal / total:', prices.subtotalPrice, prices.totalPrice);
  console.log('lines:', products.length, products.map((p) => p.productTitle + ' x' + p.quantity));

  api.store.onPricesChange(onPricesChange);
});

A method's name prefix tells you what kind of call it is:

Name pattern	What it does
get* / is* / has*	Reads a value synchronously and returns it immediately.
on* / remove*	on* registers a callback, remove* takes it off again. Use them as a pair and pass the same function reference to both.
register* / unregister*	Registers a rewriter. The platform consumes what the callback returns, so returning the wrong thing breaks the whole page. Use these only when you mean to change platform behaviour.
dispatch*	Triggers one UI refresh.
Returns a Promise	Sends a request or runs a validation, so the result arrives later.

Read this before your first call

• CheckoutAPI is not on window yet when your script starts. The platform attaches it only after the checkout page has finished loading, so poll for it the way the example above does rather than reading window.CheckoutAPI straight away. A worked example is in Scenario 3: API calls and event listening.
• Pair every on* with its remove*. A callback registered with on* stays registered until the page is unloaded. Keep it in a variable and pass the same function reference to the matching remove* method once you no longer need it — a callback written inline as an arrow function can never be removed.
• register* methods are providers, not listeners. A method whose name starts with register hands the checkout page a callback whose return value the platform consumes. registerUiShippingLinesChange, for example, decides which shipping lines the page renders: return undefined from it and the page reads undefined.length and crashes to an error screen. Register these only when you actually intend to change platform behaviour, and always return a value of the type in the signature. To watch a value without changing it, use the matching on* method instead.

address

The address namespace exposes the two address forms, shipping and billing: their values, the schema the UI renders them from, validation, and the addresses the buyer has saved. It also provides the country list and the address templates that decide which fields a given country collects.

Shipping address

Method	Purpose	Parameters	Returns
getShippingAddress	Get the values of the shipping address form	—	AddressValues
getShippingAddressSchema	Get the schema of the shipping address form; the UI renders the fields from this list	—	ExtendSchema[]
onShippingSchemaChange	Register a callback for the shipping address schema changing; re-render the form when it fires	cb: AddressChangeCb	void
removeShippingSchemaChangeCb	Remove a shipping address schema change callback	cb: AddressChangeCb	void
onShippingAddressChange	Register a callback for the shipping address values changing	cb: AddressValuesChangeCb	void
removeShippingAddressChangeCb	Remove a shipping address value change callback	cb: AddressValuesChangeCb	void
onShippingAddressChangeByInput	Register a callback for the shipping address values changing, fired only when the buyer edits the form and not when code changes the values	cb: AddressValuesChangeCb	void
removeShippingAddressChangeByInput	Remove a buyer-edit shipping address callback	cb: AddressValuesChangeCb	void
validateShippingAddress	Validate the shipping address; pass ids to validate only those fields	ids?: string[] options?: ValidateOptions	Promise<ValidateResult[]>
isSaveAddress	Whether the "save to address book" checkbox is ticked	—	boolean
setIsSaveAddress	Set the "save to address book" checkbox	isSave: boolean	void
clearShippingAddress	Clear the shipping address	—	void
updateShippingAddress	Update the shipping address	address: Partial<ShippingAddress>	void
getEmailSchema	Get the schema of the email field	config: ContactSchemaConfig	AddressItemEmailSchema | null
getPhoneSchema	Get the schema of the phone field	config: ContactSchemaConfig	AddressItemGeneralPhoneSchema | AddressItemStringSchema | null
getEmailOrPhoneSchema	Get the schema of the combined email-or-phone field	—	AddressItemStringSchema | null
validateContact	Validate the contact field	options?: ValidateOptions	Promise<ValidateResult | undefined>
getContactSchema	Get the schema of the contact field, combining getEmailSchema, getPhoneSchema and getEmailOrPhoneSchema	—	AddressItemPhoneSchema | AddressItemStringSchema | AddressItemEmailSchema
registerShippingAddressSchemaSort	Register a sort callback for the shipping address form, used to reorder its fields	cb: SortSchemaCb	void
registerShippingAddressSchemaChangeVisibility	Register a visibility callback for the optional shipping address fields, used to hide them	cb: SchemaItemVisibilityCb	void
registerShippingAddressSchemaChangeLabel	Register a rewrite callback for the shipping address field labels	cb: SchemaChangeLabelCb	void
dispatchShippingAddressSchemaChange	Manually notify the UI to re-render the shipping address form	—	void
expandShippingAddress	Expand the shipping address form; reason records what triggered the expansion	reason?: AddressExpandReason	void
formatPhone	Format a phone number using the country of the current shipping address	value: string	string
getCollapsibleShippingAddressSchema	Get the shipping address schema in its collapsed form: the autocomplete fields stay hidden until it expands, address acts as the autocomplete entry, and a manual-entry link is appended	—	ExtendSchema[]
getShippingAddressFocusIdPrefix	Get the prefix of the focus ids used by the shipping address fields, so you can build the full id of an input	—	string
getSubmitShippingAddress	Get the shipping address in the shape submitted to the platform, which is nested rather than flat and fills in some defaults	—	ShippingAddress
isFieldShow	Check whether a field is shown under the current address template	key: keyof AddressValues	boolean
isShippingAddressExpanded	Check whether the shipping address form is currently expanded	—	boolean
registerShippingAddressSchemaChangeDisable	Register a disable callback for the shipping address fields, which can lock down fields that already have a value	cb: SchemaChangeDisableCB	void
registerShippingAddressSchemaChangeValidateRule	Register extra validation rules for the shipping address form, applied on top of the built-in ones	cb: SchemaChangeValidateRuleCB	void

Billing address

Method	Purpose	Parameters	Returns
getBillingAddress	Get the billing address	—	AddressValues | ShippingAddress | undefined
getBillingAddressSchema	Get the schema of the billing address form; the UI renders the fields from this list	—	AddressItemSchema[]
onBillingSchemaChange	Register a callback for the billing address schema changing; re-render the form when it fires	cb: BillingAddressChangeCb	void
removeBillingSchemaChangeCb	Remove a billing address schema change callback	cb: BillingAddressChangeCb	void
validateBillingAddress	Validate the billing address	—	Promise<ValidateResult[]>
onBillingAddressValuesChange	Register a callback for the billing address values changing	cb: BillingAddressValuesChangeCb	void
removeBillingAddressValuesChange	Remove a billing address value change callback	cb: BillingAddressValuesChangeCb	void
isUseShippingAsBillingAddress	Whether the billing address reuses the shipping address, in which case the billing form is collapsed and the buyer does not fill it in	—	boolean
setIsUseShippingAsBillingAddress	Set whether the billing address reuses the shipping address	isUse: boolean	void
onUseShippingAsBillingAddressChange	Register a callback for the reuse-shipping-as-billing state changing	cb: UseShippingAsBillingAddressCb	void
removeUseShippingAsBillingAddressChange	Remove a reuse-shipping-as-billing callback	cb: UseShippingAsBillingAddressCb	void
registerBillingAddressSchemaChangeLabel	Register a rewrite callback for the billing address field labels	cb: SchemaChangeLabelCb	void
setBillingAddress	Set the values of the billing address form	address: AddressValues	void
registerBillingAddressSchemaSort	Register a sort callback for the billing address form, used to reorder the billing fields of non-gift-card products	cb: SortSchemaCb	void
dispatchBillingAddressSchemaChange	Manually notify listeners that the billing address form structure has changed	—	void

Address book

Method	Purpose	Parameters	Returns
onChangeAddressBook	Register a callback for the address book changing; call getAddressBookList again when it fires	cb: AddressBookChangeCbs	void
removeAddressBookChangeCb	Remove an address book change callback	cb: AddressBookChangeCbs	void
getAddressBookList	Get the buyer's saved addresses	—	IAddressBookItem[]
applyAddress	Fill the shipping address from a saved address	id: string setBilling?: boolean	void

Address utilities

Method	Purpose	Parameters	Returns
getAddressTemplate	Get the address template for a country, province and preset; the template decides which fields that country collects	params: GetAddressTemplateParams	AddressTemplate
getAllCountries	Get every country the platform supports	—	AddressCountry[]
getAvailableCountries	Get the countries the store has made available	—	AddressCountry[]
getDefaultAddressValues	Get an empty set of address values, usable as the initial value of a form	—	AddressValues
getSchemaManager	Create a schema manager for an address form, which builds and validates each field from the current values and the address template	context: AddressSchemaManagerContext config: SchemaManagerConfig	AddressSchemaManager
hasCountry	Check whether a country code is in the store's available country list	countryCode: string	boolean
isMiddleEastCountry	Check whether a country is one of the Middle East countries that need special address handling	countryCode: string	boolean
isMultiLevelCountry	Check whether a country uses multi-level administrative divisions	countryCode: string	boolean

base

The base namespace holds the plumbing of the checkout page: loading and pending state, phone number formatting, localized messages, and whether each native module is currently on screen.

Loading and pending state

Method	Purpose	Parameters	Returns
getLoadingStatus	Get the global loading state	—	LoadingStatus
onLoadingStatusChange	Register a callback for the loading state changing	cb: OnLoadingStatusChangeCallback	void
removeLoadingStatusChangeCb	Remove a loading state callback	cb: OnLoadingStatusChangeCallback	void
setLoadingStatus	Update the loading state	status: Partial<LoadingStatus>	void
getPending	Get the pending state of each module	—	Pending
onPendingChange	Register a callback for the pending state changing	pending: OnSubmitPendingChangeCallback	void
removePendingChangeCb	Remove a pending state callback	cb: OnSubmitPendingChangeCallback	void
resetAllPending	Reset every pending flag	—	void
setPricePending	Set the pending flag for price calculation	pending: boolean	void
setPickupLocationPending	Set the pending flag for the pickup location list	pending: boolean	void
getPickupLocationPending	Get the pending flag for the pickup location list	—	boolean
setShippingLinesPending	Set the pending flag for the shipping line list	pending: boolean	void
getShippingLinesPending	Get the pending flag for the shipping line list	—	boolean
setPaymentPending	Set the pending flag for loading the payment script	pending: boolean	void

Phone number formatting

Method	Purpose	Parameters	Returns
getPhoneAreaList	Get the list of phone country codes	—	Country[]
getDefaultPhoneKey	Get the default phone country code, resolved from the buyer's IP first and from the browser language as a fallback	—	string
getPhoneArea	Resolve the country or region a phone number belongs to	phone: string phoneKey?: string	Country | undefined
formatPhone	Format a phone number for a country	phone: string countryCode: string	string
isValidPhone	Check whether a phone number is valid for a country	phone: string countryCode?: string	boolean
initPhone	Initialize the phone number and its country code: the country code is resolved from the number already on the order, then the number is reformatted to the standard form of that country	phone: string _phoneAreaCode: string isPhoneRequired: boolean	InitPhoneResult | null

Localization

Method	Purpose	Parameters	Returns
getLocale	Get the current language, for example en	—	string
formatMessage	Look up a message for the current language by key, falling back to defaultMessage when the key is missing; context fills the placeholders in the message	id: string defaultMessage?: string context?: Record<string, string | number>	string
formatPrice	Format an amount into a display string with its currency symbol	price: number | string symbolStr?: string	string
isRtlLocale	Whether the current language is written right to left, such as Arabic	—	boolean
registerLocaleMap	Register your extension's own messages, grouped by language	locales: LocaleMap	void
getFullLocale	Get the full locale tag, for example en-US	—	Locale

Usage

Register your own messages per language, then read them back with formatMessage. Nested keys are flattened with a dot, so audit2: { deep: … } is read as 'audit2.deep'; context fills the {placeholder} slots in the message.

CheckoutAPI.base.registerLocaleMap({
  'en-US': { 'audit.greet': 'Hi {name}', audit2: { deep: 'deep {name}' } },
  'zh-CN': { 'audit.greet': '你好 {name}', audit2: { deep: '深层 {name}' } },
});

CheckoutAPI.base.getLocale();      // 'en'
CheckoutAPI.base.getFullLocale();  // 'en-US'

CheckoutAPI.base.formatMessage('audit.greet', '', { name: 'Audit' });  // 'Hi Audit'
CheckoutAPI.base.formatMessage('audit2.deep', '', { name: 'Audit' });  // 'deep Audit'

// Without defaultMessage a missing key comes back as the key itself
CheckoutAPI.base.formatMessage('probe.not_exist');                    // 'probe.not_exist'
CheckoutAPI.base.formatMessage('probe.not_exist', 'FALLBACK TEXT');   // 'FALLBACK TEXT'

CheckoutAPI.base.formatPrice(10);        // '$10.00'
CheckoutAPI.base.formatPrice('10.5');    // '$10.50'
CheckoutAPI.base.formatPrice(10, '€');   // '€10.00'

The buyer's language decides which map is used: getLocale() returns the short form and getFullLocale() the full tag that keys the map. A key with no entry for the current language falls back to the defaultMessage argument, or to the key itself when you pass no fallback.

Module visibility

Method	Purpose	Parameters	Returns
getSpecialInstructionVisible	Whether the order note input is shown	—	boolean
getBillingVisible	Whether the billing address is shown	—	boolean
getVirtualBillingVisible	Whether the billing address for virtual products is shown	—	boolean
getBillingSelectorVisible	Whether the "use the shipping address as the billing address" selector is shown	—	boolean
getPickupAddressVisible	Whether the pickup location list is shown	—	boolean
getPickupInformationVisible	Whether the pickup information module is shown	—	boolean
getAddressCardVisible	Whether the filled-in information card is shown	—	boolean
getDeliveryMethodVisible	Whether the delivery method module is shown	—	boolean
getExpressCheckoutVisible	Whether express checkout is shown	—	boolean
getDeliveryVisible	Whether the shipping line list is shown	—	boolean
getMobileCouponVisible	Whether the discount code input is shown on mobile	—	boolean
getSummaryCouponVisible	Whether the discount code input is shown on desktop	—	boolean
getAddressBookVisible	Whether the address book is shown	—	boolean
getShippingAddressVisible	Whether the shipping address is shown	—	boolean
getContactInformationVisible	Whether the contact information module is shown	—	boolean
setIsExpandedManually	Record that the buyer expanded the filled-in information card by hand	val: boolean	void
getIsExpandedManually	Whether the buyer expanded the filled-in information card by hand	—	boolean
getVisibleConfig	Get the visibility state of every module at once	—	VisibleConfig
onVisibleConfigChange	Register a callback for module visibility changing	cb: VisibleConfigChangeCb	void
removeVisibleConfigChangeCb	Remove a module visibility callback	cb: VisibleConfigChangeCb	void
getShowDetails	The card-collapse configuration provided by the platform	—	ShowDetails
getGiftCardBillingVisible	Check whether the billing form of a gift card order is shown	—	boolean

config

The config namespace is read-only store and page configuration: theme, market, feature flags, and which of the two checkout pages is currently open.

Method	Purpose	Parameters	Returns
getFeatureConfig	Get the checkout feature flags	—	CheckoutFeatures
getThemeConfig	Get the checkout theme configuration	—	CheckoutThemeConfig
getAppConfig	Get the checkout app configuration	—	CheckoutAppConfig
getMarketConfig	Get the market configuration	—	MarketInfo
getShopConfig	Get the store configuration	—	ShopConfig
getRootUrl	Get the API root URL	—	string
getPolicyTitles	Get the titles of the policy links in the page footer	—	string[]
isThankyouPage	Whether the current page is the thank-you page	—	boolean
isCheckoutPage	Whether the current page is the checkout page	—	boolean
getCSettings	Get the page-level checkout settings	—	CSettings
isMobileLayout	Whether the mobile layout is in use, which happens when the window is narrower than 768px	—	boolean
onThemeConfigChange	Register a callback for the theme configuration changing	cb: ThemeConfigChangeCb	void
removeThemeConfigChange	Remove a theme configuration callback	cb: ThemeConfigChangeCb	void
updateThemeConfig	Update the theme configuration	config: Partial<CheckoutThemeConfig>	void

coupon

The coupon namespace covers the savings a buyer can apply: coupons they hold, discount codes they type in, and gift cards. It reads what is currently applied, applies and removes codes and gift cards, and lets you rewrite how the gift card and discount code tags render.

Coupons

Method	Purpose	Parameters	Returns
applyCoupon	Apply a coupon	code: string	Promise<any>
cancelCoupon	Remove a coupon that has been applied	code: string	Promise<any>
getAvailableCouponData	Get the coupons that can be used on this order	—	CouponData
getSelectedDiscountCoupon	Get the coupon currently applied	—	DiscountApplication | undefined
getUnavailableCouponData	Get the coupons that cannot be used on this order	—	CouponData
isShowDiscountCoupon	Check whether the coupon entry is shown	—	boolean
onAvailableCouponDataChange	Register a callback for the available coupon list changing	cb: CouponListChangeCb	void
onCouponChange	Register a callback for the applied coupon changing	cb: CouponChangeCb	void
onUnavailableCouponDataChange	Register a callback for the unavailable coupon list changing	cb: CouponListChangeCb	void
removeAvailableCouponDataChangeCb	Remove an available coupon list callback	cb: CouponListChangeCb	void
removeCouponChangeCb	Remove an applied coupon callback	cb: CouponChangeCb	void
removeUnavailableCouponDataChangeCb	Remove an unavailable coupon list callback	cb: CouponListChangeCb	void
requestCouponList	Fetch the coupon list for the given availability status	status: CouponAvailStatus	Promise<void>

Gift cards and discount codes

Method	Purpose	Parameters	Returns
registerGiftCardTagChange	Register a rewrite callback for one discount code or gift card tag, used to customize how that tag renders	id: string cb: GiftCardTagChange	void
getGiftCardTags	Get the discount code and gift card tags	—	GiftCardTagItem[]
onDiscountChange	Register a callback for the tag list changing	cb: GiftCardTagsChangeCb	void
removeDiscountChangeCb	Remove a tag list callback	cb: GiftCardTagsChangeCb	void
getGiftCards	Get the gift cards applied to this order	—	GiftCard[]
getDiscountCodes	Get the discount codes applied to this order	—	DiscountApplication[]
getDiscountApplications	Get every discount applied to this order, both codes and automatic promotions	—	DiscountApplication[]
applyGiftCardOrDiscountCode	Apply a discount code or gift card; position records which input it came from and is used for tracking only	code: string position?: 'coupon-pc' | 'coupon-mobile'	Promise<any>
cancelGiftCardOrDiscountCode	Remove an applied discount code or gift card	parasm: CancelCouponParams	Promise<any>
applyDiscount	Apply one or more discount codes	codes: string[]	Promise<PriceResult | undefined>
cancelDiscountCode	Remove one or more discount codes that have been applied	codes: string[]	Promise<PriceResult | undefined>
isCurrentStepShowDiscountCode	Check whether the discount code and gift card inputs are shown on the current step, per the store's settings	step?: CheckoutStep	boolean
registerGiftCardTagsFilter	Register a filter callback for the gift card and discount code tags, deciding which tags render	cb: GiftCardTagsFilter	void

exception

The exception namespace covers business errors raised during checkout: checking a response for an error code, reading and clearing the stored error, watching submit failures, and the state of the removed-items dialog.

Method	Purpose	Parameters	Returns
checkException	Check a response for a business error code: when one is present the error is stored and the method returns false, otherwise it returns true. The stored error can then drive a dialog or another message	exception?: ExceptNotification	boolean
onExceptionChange	Register a callback for the stored business error changing, fired both when one is stored and when it is cleared	cb: ExceptionChangeCbs	void
removeExceptionChangeCb	Remove a business error callback	cb: ExceptionChangeCbs	void
unsetException	Clear the stored business error	—	void
getSubmitErrorInfo	Get the current submit error	—	SubmitError | undefined
setSubmitErrorInfo	Set the submit error code. The platform already sets it when the order is submitted, so this is mostly used to clear it	code: IExceptionCode | ''	void
onSubmitErrorChange	Register a callback for the submit error changing	cb: SubmitErrorChangeCbs	void
removeSubmitErrorChangeCb	Remove a submit error callback	cb: SubmitErrorChangeCbs	void
getExceptionInfo	Get the stored business error	—	ExceptionInfo
getException	Get the business error currently stored	—	IException | undefined
handleExceptionOk	Run the handler behind the confirm button of the business error dialog	—	Promise<boolean>

extension

The extension namespace is about extensions themselves: registering one, reading what is registered at a point, watching extensions finish loading, checking and watching which native modules are hidden, and building the real name of a dynamic extension point.

Method	Purpose	Parameters	Returns
generateRealDynamicPoint	Turn a dynamic extension point template containing {id} into the real extension point name	point: ExtensionPoint id?: string	string
getExtensionComponents	Return the extension component of the point, which carries more than getExtensionContent; an id means the point is dynamic	point: ExtensionPoint id?: string	ExtensionComponent[]
getExtensionContent	Return the extension string of the point, empty when there is none; an id means the point is dynamic	point: ExtensionPoint id?: string	string
getExtensionList	Get the list of extensions	—	Extension[]
getPlaceholderContent	Return the placeholder content of the point, which the UI layer inserts with innerHTML	point: ExtensionPoint	string
isHideExtensionTarget	Whether an extension target is hidden; the UI layer reads it to decide whether to hide that native module	target: ExtensionTarget	boolean
onAllExtensionLoaded	Register a callback for all extensions having finished loading	cb: AllExtensionLoadedCb	void
onExtensionLoad	Register a callback that runs when the extension of a point has finished loading	cb: ExtensionLoadCb	void
onHideExtensionTarget	Register a callback for the result of isHideExtensionTarget changing	cb: HideExtensionTargetCb	void
registerExtension	Register an extension; extension developers call this function to complete the registration	params: RenderParams	Promise<void>
removeAllExtensionLoadedCb	Remove a callback registered for all extensions having finished loading	cb: AllExtensionLoadedCb	void
removeHideExtensionTarget	Remove the callback	cb: HideExtensionTargetCb	void

order

The order namespace covers what the buyer picks on the way to placing an order: delivery method, shipping line, shipping protection, tip, order note, and the submit step, together with the price refresh that follows every change.

Delivery method

Method	Purpose	Parameters	Returns
getDeliveryMethodList	Get the delivery methods this checkout offers, such as shipping and in-store pickup	—	DeliveryMethodItem[]
getSelectedDeliveryMethod	Get the delivery method the buyer has selected	—	DeliveryMethodItem
updateDeliveryMethod	Switch the selected delivery method and return the recalculated prices	type: CheckoutBusinessType	Promise<PriceResult | undefined>
onDeliveryMethodChange	Register a callback for the selected delivery method changing	cb: DeliveryMethodChangeCb	void
removeDeliveryMethodChangeCb	Remove a delivery method change callback	cb: DeliveryMethodChangeCb	void
onDeliveryMethodListChange	Register a callback for the delivery method list changing	cb: DeliveryListChangeCb	void
removeDeliveryMethodListChange	Remove a delivery method list callback	cb: DeliveryListChangeCb	void
unregisterDeliveryMethodListChange	Unregister the delivery method list rewrite callback	cb: DeliveryMethodListChangeCb	void
registerDeliveryMethodListChange	Register a rewrite callback for the delivery method list, used to customize each entry, for example by hiding its icon or inserting content; the callback must return the full list	cb: DeliveryMethodListChangeCb	void

Line items

Method	Purpose	Parameters	Returns
addLineItems	Add line items to the current order; the prices are recalculated automatically	params: AddLineItemsInput	Promise<LineMutationResult>
removeLineItems	Remove line items from the current order; the prices are recalculated automatically	params: RemoveLineItemsInput	Promise<LineMutationResult>

Submit and validation

Method	Purpose	Parameters	Returns
couldSubmit	Whether the current step can be submitted, for driving the disabled state of a custom submit button	—	boolean
onSubmitChange	Register a callback for the submittable state changing	cb: SubmitChangeCb	void
removeSubmitChangeCb	Remove a submittable state callback	cb: SubmitChangeCb	void
preSaveAddress	Pre-save the address currently entered in the form to the order	—	Promise<void>
submitInformationAndNavigate	Submit the information step and navigate to the next one, running form validation and extension validation first; used only by the two-step and three-step layouts	—	Promise<ValidateResult[] | undefined>
registerBuyerJourneyIntercept	Register a checkout interception rule: returning block from the callback stops the buyer and opens a dialog, returning allow lets the submission through	cb: BuyerJourneyInterceptCb	void
addBeforeSubmitCb	Add a validation callback that runs before the address is submitted; the platform's own two cover email and address	cb: BeforeSubmitCb	void
removeBeforeSubmitCb	Remove a validation callback that runs before the address is submitted	cb: BeforeSubmitCb	void
submitAddressAndShippingLines	Submit the address together with the selected shipping line	—	Promise<Res<SubmitSuccessData>>
submitShippingLinesAndNavigate	Submit the shipping line and move to the next step; only the three-step layout uses this	—	Promise<ValidateResult[] | undefined>
submitValidate	The general pre-submit validation: it picks the checks that apply to the current layout and step, and moves focus to the first input that fails	—	Promise<ValidateResult[]>
unregisterBuyerJourneyIntercept	Unregister a checkout interception rule	cb: BuyerJourneyInterceptCb	void

Tipping

Method	Purpose	Parameters	Returns
getTippingOptions	Get the preset tip options offered on this checkout	—	TippingOption[]
onTippingChange	Register a callback for the tip changing	cb: TippingChangeCb	void
removeTippingChangeCb	Remove a tip change callback	cb: TippingChangeCb	void
handleTipping	Submit a tip, where type tells a preset option (select) from a buyer-entered amount (input)	value: number type: 'select' | 'input'	Promise<any>
getTippingInfo	Get the tipping state: whether tipping is supported and shown, the currency symbol, the tip received so far, and the product subtotal after discounts, free-shipping coupons excluded	—	TippingInfo

Shipping lines

Method	Purpose	Parameters	Returns
getShippingLines	Get the shipping lines available for the current address	—	FormatShippingLineType[]
getSelectedShippingLine	Get the shipping line the buyer has selected, or null when none is selected	—	FormatShippingLineType | null
updateSelectedShippingLine	Switch the selected shipping line	shippingLine: ShippingLineType	Promise<void>
shouldCalculateShippingLine	Whether shipping lines should be requested at this point; in the three-step layout it returns false on the information step	—	boolean
onShippingChange	Register a callback for the selected shipping line changing	cb: ShippingChangeCb	void
removeShippingChangeCb	Remove a shipping line change callback	cb: ShippingChangeCb	void
isShippingMethodAutoSelect	Whether the store is configured to auto-select a shipping line	—	boolean
isSupportShippingLinesCollapse	Whether the shipping line list can be collapsed, which only the single-page and two-step layouts support	—	boolean
getShippingPromptMessage	Get the prompt currently shown on the shipping line list, or null when there is none	—	PromptMessage | null
onShippingPromptMessageChange	Register a callback for the shipping line prompt changing	cb: ShippingPromptMessageChangeCb	void
removeShippingPromptMessageChange	Remove a shipping line prompt callback	cb: ShippingPromptMessageChangeCb	void
dispatchShippingChange	Manually notify listeners that the shipping line changed	—	void
getShippingLinesErrorInfo	Get the error information of the shipping line list	—	ShippingLinesErrorInfo
getUiShippingLines	Get the shipping lines the page finally renders, which an extension may have rewritten	—	FormatShippingLineType[]
unregisterUiShippingLinesChange	Unregister the shipping line list rewrite callback	cb: UiShippingLinesChangeCb	void
registerUiShippingLinesChange	Register a rewrite callback for the shipping line list, deciding which lines the page finally renders; the callback must return the full list	cb: UiShippingLinesChangeCb	void

Shipping protection

Method	Purpose	Parameters	Returns
getChargeQuotes	Get the shipping protection offers	—	ChargeQuote[]
onShippingProtectionChange	Register a callback for the shipping protection selection changing	cb: ShippingProtectionChangeCb	void
removeShippingProtectionChangeCb	Remove a shipping protection callback	cb: ShippingProtectionChangeCb	void
switchShippingProtection	Select or clear one shipping protection offer	quoteId: string selected: boolean	Promise<SwitchShippingProtectionResult>

Order note

Method	Purpose	Parameters	Returns
getSpecialInstructionNote	Get the order note the buyer has entered	—	string
updateSpecialInstructionNote	Write the order note, and persist it to the order when saveToBackend is true	note: string saveToBackend?: boolean	Promise<any>
onChangeSpecialInstruction	Register a callback for the order note changing	cb: (info: string) => void	void
removeSpecialInstructionChangeCb	Remove an order note change callback	cb: (info: string) => void	void
expendSpecialInstruction	Expand the order note input	—	void
isInstructionCollapse	Whether the order note input is currently collapsed	—	boolean
onInstructionCollapseChange	Register a callback for the order note input collapsing or expanding	cb: IsSpecialInstructionCollapseChange	void
removeInstructionCollapseChange	Remove an order note collapse callback	cb: IsSpecialInstructionCollapseChange	void

Filled-in information card

Method	Purpose	Parameters	Returns
getCollapseInfo	Get the contents of the filled-in information card: contact, shipping address, delivery method, shipping line, and whether the new-address button is shown	—	CollapseInfo
onCollapseInfoChange	Register a callback for the filled-in information card changing	cb: CollapseInfoChangeCb	void
removeCollapseInfoChangeCb	Remove a filled-in information card callback	cb: CollapseInfoChangeCb	void

Order data and price refresh

Method	Purpose	Parameters	Returns
updateDataByPriceApi	Call the price API again and refresh the prices held by the checkout	params?: UpdateDataByPriceApiParams	Promise<PriceResult | undefined>
updateDataByOrderAndPriceApi	Call the order and price APIs in parallel and refresh both, typically to recover after an error	params?: UpdateDataByPriceApiParams	Promise<UpdateDataByOrderAndPriceApiResult>
updateDataByOrderApi	Call the order API again and refresh the order data	—	Promise<OrderResult | undefined>
calculatePrice	Calculate prices from the given parameters and return the result without writing it back to the checkout data	params?: UpdateDataByPriceApiParams	Promise<PriceResult | undefined>

payment

The payment namespace covers the payment methods on offer: which ones the buyer can choose from, which one is selected, submitting the payment, and the callbacks that run when a payment is attempted, fails, or completes.

Method	Purpose	Parameters	Returns
paymentPay	Start the payment after the buyer submits	—	Promise<void>
getPaymentLines	Get every payment method in the list	—	PaymentUpdateParams['paymentLines']
getSelectedPaymentLine	Get the payment method the buyer has selected	—	PaymentLine | null | undefined
onAfterPay	Register a callback that runs after payment completes	cb: AfterPayCb	void
onPayAttempt	Register a callback for a payment attempt; it fires before form validation, so a failed validation that never reaches the gateway still counts as an attempt	cb: PayAttemptCb	void
onPayFailed	Register a handler for a failed payment; several can be registered, they run in order, and the first one that returns a value decides the outcome	handler: PayFailedHandler	void
removePayAttemptCb	Remove a payment attempt callback	cb: PayAttemptCb	void

pickup

The pickup namespace covers in-store pickup: the pickup locations, the one the buyer selected, the pickup information form, and pickup validation.

Method	Purpose	Parameters	Returns
getPickupLocations	Get the pickup locations	—	PickupLocation[]
getPickupLocationValidateResult	Get the validation result for the pickup location	—	ValidateResult | undefined
onPickupLocationValidateResultChange	Register a callback for the pickup location validation result changing	cb: ValidatePickupResultChangeCb	void
removePickupLocationValidateResultChange	Remove a pickup location validation callback	cb: ValidatePickupResultChangeCb	void
validatePickupLocation	Validate that a pickup location has been chosen	—	Promise<ValidateResult | undefined>
getSelectedPickupLocation	Get the pickup location the buyer has selected	—	PickupLocation | undefined
updatePickupLocation	Switch the selected pickup location and return the recalculated prices	location: PickupLocation	Promise<PriceResult | undefined>
onPickupLocationsChange	Register a callback for the pickup location list changing	cb: PickupLocationsChangeCb	void
removePickupLocationsChangeCb	Remove a pickup location list callback	cb: PickupLocationsChangeCb	void
onSelectedPickupLocationChange	Register a callback for the selected pickup location changing	cb: SelectedPickupLocationChangeCb	void
removeSelectedPickupLocationChangeCb	Remove a selected pickup location callback	cb: SelectedPickupLocationChangeCb	void
onPickupInformationChange	Register a callback for the pickup information changing	cb: PickupInformationChangeCb	void
removePickupInformationChangeCb	Remove a pickup information callback	cb: PickupInformationChangeCb	void
getPickupInformationSchema	Get the schema of the pickup information form	—	AddressItemSchema[]
validatePickupInfo	Validate the pickup information form	—	Promise<ValidateResult[]>

step

The step namespace covers the steps of a checkout: reading the current step, moving between steps, the breadcrumb configuration, and leaving checkout for another page of the store.

Method	Purpose	Parameters	Returns
getStep	Get the step the buyer is on	—	CheckoutStep
isInformationStep	Whether the buyer is on the information step	—	boolean
isShippingStep	Whether the buyer is on the shipping step, which only exists as the second page of the three-step layout	—	boolean
isPaymentStep	Whether the buyer is on the payment step, the last page of the three-step and two-step layouts	—	boolean
stepNavToInformation	Navigate to the information step	type?: EventType	Promise<void>
stepNavToShipping	Navigate to the shipping step	type?: EventType	Promise<void>
stepNavToPayment	Navigate to the payment step	—	Promise<void>
stepNavToNext	Navigate to the next step, whatever the layout and checkout mode	—	Promise<void>
stepNavToPrevious	Navigate back to the previous step	—	void
hasShippingMethodStep	Whether this order has a shipping step, which needs pickup to be unselected and the products to be physical	—	boolean
getNavigateLinks	Get the configuration of the step breadcrumb	—	NavigateLink[]
onNavigateLinksChange	Register a callback for the step breadcrumb changing	cb: NavigateLinksChangeCb	void
removeNavigateLinksChange	Remove a step breadcrumb callback	cb: NavigateLinksChangeCb	void
onStepChange	Register a callback for the step changing	cb: StepChangeCb	void
removeStepChangeCb	Remove a step change callback	cb: StepChangeCb	void
navigateClick	Navigate to a step the way clicking the breadcrumb does	id: CheckoutStep	Promise<void>
couldNavTo	Whether the breadcrumb can jump to a step. The breadcrumb only goes backwards; moving forward means submitting the current step	id: CheckoutStep	boolean
stepNavTo	Navigate to a given step	id: CheckoutStep location?: EventType	Promise<any>
navToReferrerPage	Navigate back to the page the buyer came from before checkout	—	void
goToOrderInfoPage	Navigate to the order details page	—	void
goToHomePage	Navigate to the store home page	—	void
disableJump	Block step navigation, optionally only for the given ways of navigating	way?: JumpWay[]	Promise<void>
getReturnBtnText	Get the text of the return button; an empty string means the button is not shown	—	string
goToThankyouPage	Redirect to the thank-you page	—	void
isDisableJump	Check whether step navigation is currently blocked	—	boolean
locationHref	Navigate to a given URL	url: string	void
stepNavToWithoutSubmit	Move to the given step without submitting the current step's data	id: CheckoutStep	void

store

The store namespace is where the order data lives. The order itself, its prices, its business type and the checkout layout are all read from here, and this is where you listen for a refresh.

Method	Purpose	Parameters	Returns
onPricesChange	Register a callback for the prices changing; when it fires the discounted line prices may still be the old values, so read line item data again a moment later	cb: PricesChangeCb	void
removePricesChangeCb	Remove a price change callback	cb: PricesChangeCb	void
getOrderStatus	Get the status of the order	—	OrderStatus
onOrderChange	Register a callback for the order data being refreshed, fired whenever the order and price APIs write new data. The callback carries no data — read it with the matching get methods	cb: OnStoreDataChangeCb	void
removeOrderChangeCb	Remove an order refresh callback	cb: OnStoreDataChangeCb	void
getPrices	Get the prices of the order	—	CheckoutPrices
getOrderInfo	Get the basic order information	—	OrderInfo
getOrderConfig	Get the order attributes, such as the checkout layout and the order business type	—	OrderConfig
getBusinessType	Get the business type of the order	—	CheckoutBusinessType
getCheckoutSettings	Get the checkout settings of the store	—	CheckoutSettings
getInstructionType	Get the collapse mode configured for the order note input	—	InstructionType
getCustomerAuthority	Get who is allowed to place the order; login means only signed-in buyers can	—	CustomerAuthority
setBusinessType	Set the business type of the order, which the pickup layout uses	type: CheckoutBusinessType	void
onBusinessTypeChange	Register a callback for the order business type changing	cb: CheckoutBusinessTypeChangeCb	void
removeBusinessTypeChangeCb	Remove an order business type callback	cb: CheckoutBusinessTypeChangeCb	void
getPageType	Get the checkout layout, which does not change while the page is open	—	CheckoutPageType
isThreeStepPage	Whether this is the three-step checkout layout	—	boolean
isTwoStepPage	Whether this is the two-step checkout layout	—	boolean
isOneStepPage	Whether this is the single-page checkout layout	—	boolean
getContactType	Get how the store collects contact details	—	ContactType
getAddressSettings	Get the address form settings	—	CheckoutAddressSettings
isPageTypeSupportFirstStepCollapse	Whether this layout can collapse the address into a card on the first step, which only the single-page and two-step layouts support	—	boolean
isStandardTemplate	Whether this is the shipped-goods checkout template	—	boolean
isVirtualTemplate	Whether this is the virtual-goods checkout template, used when every product in the order is virtual	—	boolean
isStandardBusiness	Whether the order business type is shipping	—	boolean
isVirtualBusiness	Whether the order business type is virtual goods	—	boolean
isPickupTemplate	Whether this is the pickup checkout template, which it becomes as soon as the merchant has pickup locations. Whether the buyer actually picks up is isSelectedPickup	—	boolean
isSelectedPickup	Whether this order is a pickup order, true only when this is the pickup template and the buyer selected pickup	—	boolean
isDirectPayment	Whether the order was created from the merchant admin, in which case the buyer lands straight on the payment step	—	boolean
isShippingInInformationStep	Whether shipping lines are shown on the first step. The single-page and two-step layouts show them on the information step, which decides whether shipping has to be calculated there	—	boolean
isCartOrder	Whether the order was placed from the cart	—	boolean
isBuyNowOrder	Whether the order was placed with buy-now on a product page	—	boolean
getReferInfo	Get where the order came from	—	ReferInfo
getTaxLines	Get the tax breakdown	—	TaxLines
isGiftCardOrder	Check whether this is a gift card order	—	boolean
isOrderIdEmpty	Check whether the order id is empty	—	boolean
onPageTypeChange	Register a callback for the checkout layout changing	cb: PageTypeChangeCb	void
removePageTypeChange	Remove a checkout layout callback	cb: PageTypeChangeCb	void
setOrderId	Set the order id	id: string	void
setPageType	Set the checkout layout	type: CheckoutPageType	void

summary

The summary namespace covers the order summary column: the line items, the price breakdown, and the text shown for the shipping cost.

Method	Purpose	Parameters	Returns
getProductList	Get the line items, including the custom properties field	—	ProductItem[]
onProductListChange	Register a callback for the line item list changing	cb: ProductListChangeCb	void
removeProductListChangeCb	Remove a line item list callback	cb: ProductListChangeCb	void
getPriceList	Get the grouped price breakdown computed by the platform	—	PriceGroupDetail[]
onPriceListChange	Register a callback for the price breakdown changing	cb: PriceListChangeCb	void
removePriceListChangeCb	Remove a price breakdown callback	cb: PriceListChangeCb	void
getShippingPriceDisplay	Get the text shown for the shipping cost	—	string
onShippingPriceDisplayChange	Register a callback for the shipping cost text changing	cb: ShippingPriceDisplayChangeCb	void
removeShippingPriceDisplayChange	Remove a shipping cost text callback	cb: ShippingPriceDisplayChangeCb	void
registerUiProductListChange	Register a rewrite callback for the line item list, deciding which lines the page finally renders; the callback must return the full list	cb: UiProductListChangeCb	void
getGiftCardPrice	Get the gift card line of the price breakdown	—	PriceGroupDetail | undefined
dispatchPriceListChange	Manually notify the UI to re-render the price breakdown	—	void
dispatchProductListChange	Manually trigger a refresh of the line item list in the UI	—	void
getUiProductList	Get the line items the order summary finally renders, which an extension may have rewritten	—	UIProduct[]
unregisterUiProductListChange	Unregister the line item list rewrite callback	cb: UiProductListChangeCb	void

track

The track namespace reports analytics events. It has a general-purpose track method plus one method per checkout milestone (entering checkout, filling the address, picking a shipping line, starting a payment and so on), and it can also read the order payload used for reporting and attach extra fields to a given event.

Method	Purpose	Parameters	Returns
track	Report a tracking event	event: string data?: Record<string, any>	void
getAssemblyOrder	Get the order payload used for analytics reporting	—	CheckoutOrder
registerTrackExtraInfo	Attach extra fields to one analytics event, which are then included every time that event is reported	eventName: string data: Record<string, unknown>	void
trackAddPaymentInfo	Report the add payment info event	extra?: Record<string, any>	void
trackAddShippingMethod	Report the add shipping method event	—	void
trackAddressFill	Report an address autofill event	data: TrackAddressFillParams	void
trackAddressFormExpand	Report the address form expand event	reason: AddressExpandReason	void
trackAioBeforePay	Report the event fired before an aggregated payment starts	—	void
trackBeforePay	Report the event fired before a payment starts	extra?: Record<string, any>	void
trackCompleteOrderClick	Report a click on the place order button	—	void
trackCompleteOrderError	Report a failed order submission	data: string	void
trackContinueToPayment	Report the continue to payment event	—	void
trackCouponChangeTab	Report a tab switch in the coupon panel	status: string	void
trackEnterCheckout	Report entering the checkout page	—	void
trackGiftCard	Report a gift card event	type: TrackGiftCardProps info: Record<string, string | number>	void
trackInitialAddressFill	Report the first address fill	—	void
trackInitiateCheckout	Report the initiate checkout event	—	void
trackLogout	Report a sign-out	—	void
trackPaymentRedirect	Report a payment redirect, taking the load time of the redirect page	loadTime: number	void
trackShippingAddressSubmitErrors	Report a shipping address submission failure	code: string	void
trackShippingMethodsCardExpose	Report that the shipping method card was shown	—	void
trackShippingMethodsRender	Report that the shipping methods rendered	—	void
trackShippingMethodsRequest	Report a shipping methods fetch	triggerSource: ShippingMethodsFetchTriggerSource	void
trackSubmitAddress	Report an address submission	options?: TrackSubmitAddressParams	void
trackTipping	Report a tipping event	type: TrackTippingType data: TrackTippingData	void

user

The user namespace covers who the buyer is and how to reach them: sign-in state, account details, the email and phone entered at checkout, and the marketing subscription.

Customer account

Method	Purpose	Parameters	Returns
isLogin	Whether the buyer is signed in	—	boolean
getIPAddress	Get the buyer's IP address information	—	CheckoutIpAddress
doLogin	Redirect to the sign-in page; the parameters passed in are appended to the return URL	returnUrlSearchParams?: Record<string, string>	void
doRegister	Redirect to the sign-up page	—	void
doLogout	Sign the buyer out	—	Promise<void>
getUserInfo	Get the account information of the signed-in buyer	—	UserInfo
getCustomerInfo	Get the customer information that is submitted with the order	—	CheckoutCustomerInfo
updateCustomerInfo	Update the customer information that is submitted with the order	data: Partial<CheckoutCustomerInfo>	void
onUserInfoChange	Register a callback for the account information changing	cb: UserInfoChangeCb	void
removeUserInfoChangeCb	Remove an account information callback	cb: UserInfoChangeCb	void

Contact details

Method	Purpose	Parameters	Returns
getEmail	Get the contact email the buyer entered	—	string
getPhone	Get the contact phone number the buyer entered	—	string
getPhoneAreaCode	Get the phone country code the buyer entered	—	string
getEmailOrPhone	When the store collects either an email or a phone number, get whichever the buyer entered	—	string
getContactInformation	Get the contact details: email, phone, phone country code, and the combined email-or-phone field	—	ContactInformation
onContactInformationChange	Register a callback for the contact details changing	cb: ContactInformationChangeCb	void
removeContactInformationChangeCb	Remove a contact details callback	cb: ContactInformationChangeCb	void
setNewsletter	Set the marketing email subscription checkbox	val: NewsLetterStatus	void
getNewsletter	Get the marketing email subscription checkbox	—	NewsLetterStatus

utils

The utils namespace provides the checkout page's own dialog and drawer, plus three lodash functions passed straight through.

Method	Purpose	Parameters	Returns
debounce	lodash debounce, passed through unchanged	—	unknown
get	lodash get, passed through unchanged	—	unknown
throttle	lodash throttle, passed through unchanged	—	unknown
createDialog	Create a dialog, a modal confirmation box	content: DialogContent options?: DialogOptions	IDialog
createDrawer	Create a drawer, a panel that slides in from the edge of the screen	content: DrawerContent options?: DrawerOptions	IDrawer

Usage

Both take the content and the button labels as their first argument, and an optional second argument for options such as hiding a button or setting the size. createDialog returns { show, hide }; createDrawer returns { show, hide, onClose, destroy, getId }. show() resolves to true when the buyer confirms.

const dialog = CheckoutAPI.utils.createDialog({
  content: '<div>Ship to this address?</div>',
  footer: '<div>Delivery takes 3 to 5 days.</div>',
  trueBtn: 'OK',
  falseBtn: 'Cancel',
});
const confirmed = await dialog.show();  // true after the buyer clicks OK

const drawer = CheckoutAPI.utils.createDrawer({
  content: '<div style="height:200px">Ship to this address?</div>',
  footer: '<div>Delivery takes 3 to 5 days.</div>',
});
drawer.onClose((type) => {
  // type is 'true_btn' when the buyer confirms
});
await drawer.show();

A drawer without trueBtn and falseBtn uses the default Yes and No labels. The dialog node stays in the DOM after it closes, hidden rather than removed, so create it once and reuse it rather than creating one per click.

utils.eventBus

The utils.eventBus object is an in-page event bus for passing messages between extensions on the same checkout page. Prefix every event name with your extension id, as {extension-id}:{event}, so it cannot collide with another extension's.

Method	Purpose	Parameters	Returns
emit	Emit an event	name: string ...rest: any[]	void
on	Listen for an event	name: string cb: Function	void
once	Listen for an event once	name: string cb: Function	void
off	Stop listening for an event	name: string cb: Function	void

Types

The types named in the method tables above. CountryCode comes from the libphonenumber-js package and is not redefined here.

AdditionalPrice

Field	Type	Description
name?	string	Name of the add-on charge
price?	string	Amount of the add-on charge

AdditionalProperty

Field	Type	Description
id	string	Field name, also the key used in extraInfo
name	string	Label shown for the field
inputType	1 | 2 | 3 | 4	Input type, which maps to the input control rendered on screen
enable	1	Whether the field is enabled
showType	'all' | 'and' | 'or'	Display condition: all always shows, and shows when every rule matches, or shows when any rule matches
showRules	Array<{ field: string; rules: string[]; }>	Display rules
require	0 | 1	Whether the buyer must fill this in, 1 for yes
description	string	Description of this field
validates	Array<{ type: 'regex'; regexp: ''; }>	The validation rules that apply
enums?	Array<{ name: string; value: string; }>	Options of a dropdown field

AdditionValues

Field	Type	Description
[key: string]	{ name: string; val: string; }	Any other key, keyed by name

AddLineItemsInput

Field	Type	Description
lineItems	AddProductInput[]	The line items of the order
mutationSource	MutationSource	A tag of your own naming what made this change

AddProductInput

Field	Type	Description
variantId	string	Id of the variant
quantity	number	Quantity
properties?	ProductProperties	Custom properties to put on the new line, as a JSON string

AddressBookChangeCbs

export type AddressBookChangeCbs = () => void;

AddressBookItem

Field	Type	Description
address	string | null	Street address
address1	string | null	First line of the street address
area	string | null	Area or district
city	string | null	City
company	string | null	Company name
country	string | null	Country or region name
countryCode	string | null	Country or region code
createdAt	string | null	When this record was created
email	string | null	Email address
firstName	string | null	First name
gender	string | null	Gender recorded on the address
id	string | null	Unique id of this item
isDefault	boolean	Whether this is the default address
lastName	string | null	Last name
phone	string | null	Phone number
phoneAreaCode	string | null	International dialling code of the phone number
province	string | null	Province or state name
provinceCode	string | null	Province or state code
zip	string | null	Postal code

AddressChangeByInputCb

export type AddressChangeByInputCb = (
  changeValue: Partial<AddressValues>,
  fullAddress: AddressValues,
  config: ChangeValuesConfig,
) => void;

AddressChangeCb

export type AddressChangeCb = () => void;

AddressCountry

Field	Type	Description
isoCode2	string	Two-letter country code
name	string	Country name
provinces	AddressCountryProvince[]	Provinces or states of this country
depth	number	Number of address levels this country or region has
code	string	Two-letter country or region code
preset	string
format?	AddressFormat	Address format template

AddressCountryProvince

Field	Type	Description
cnName	string	Chinese name
code	string	Province or state code
name	string	Province or state name
oldCode	string
provinceId	string	Id of the province or state
preset?	string
format?	AddressFormat	Format rules of this field

AddressExpandReason

Value	Description
'manual_click'	The buyer clicked to expand the form
'empty_fallback_click'	The buyer clicked an empty collapsed form
'auto_fill'	The form expanded because it was auto-filled
'submit_validate'	The form expanded so a validation error could be shown
'browser_fill'	The browser filled the form in

AddressFormat

Field	Type	Description
fields	AddressFormatField[]	The fields this template contains
[k: string]	any	Any other key, keyed by name

AddressFormatField

Field	Type	Description
id	string	Unique id of this item
label?	string	Label shown above the field
show?	0 | 1	Whether this item is shown
row?	number	Row this field sits in within the form grid
description?	string	Description of this field
[k: string]	any	Any other key, keyed by name

AddressItemActionSchema

Field	Type	Description
id	string	Unique id of this item
show	true	Whether this item is shown
type	FieldType.Action	Field type, always the action type
text	string	Text of the action
row	number	Row this field sits in within the form grid
col	number	Column this field sits in within the form grid
style?	Record<string, string | number>	Inline styles put on the element
className?	string	CSS class put on the element
onClick()	void	Called when the buyer clicks this row

AddressItemCheckoutSchema

Field	Type	Description
id	string	Unique id of this item
type	FieldType.Checkbox	Field type, always the checkbox type
desc	string	Label shown next to the checkbox
show	true	Whether this item is shown
value	boolean	Whether the checkbox is ticked
row	number	Row this field sits in within the form grid
col	number	Column this field sits in within the form grid
changeValue(isCheck)	void	Ticks or unticks the checkbox

AddressItemEmailSchema

Field	Type	Description
type	FieldType.Email	Field type, always email

AddressItemGeneralPhoneSchema

Schema of the phone field. It also carries every field of BaseAddressItemSchema and ValueInterface; only its own members are listed below.

Field	Type	Description
type	FieldType.Phone	Field type, always the phone type
phoneInfo	PhoneInfo	Dialling code and formatting rules of the phone field
maxLength?	number	Largest number of characters accepted
changePhone(value, format?, config?)	void	Writes a new phone number into the field
changePhoneAreaCode(value)	void	Writes a new dialling code into the field

AddressItemPhoneSchema

Alias of AddressItemGeneralPhoneSchema.

export type AddressItemPhoneSchema = AddressItemGeneralPhoneSchema;

AddressItemSchema

Schema of one address form field: select, phone, string or email.

export type AddressItemSchema =
  | AddressItemSelectSchema
  | AddressItemPhoneSchema
  | AddressItemStringSchema
  | AddressItemEmailSchema;

AddressItemSelectSchema

Field	Type	Description
type	FieldType.Enum	Field type, always the select type
selectType	SelectType	Whether the option list is fixed or fetched, as a SelectType value
options	OptionValue[]	The options in the dropdown

AddressItemStringSchema

Field	Type	Description
type	FieldType.String	Field type, always string
readOnly?	boolean	Read-only, the buyer cannot change it
format?	Array<[regexp: string, params: string[]]> | string[]	Formatting rules for the value, for example a Brazilian tax number is reformatted on blur

AddressItemTitleSchema

Field	Type	Description
id	string	Unique id of this item
show	true	Whether this item is shown
type	FieldType.Title	Field type, always the title type
title	string	Title text
row	number	Row this field sits in within the form grid
col	number	Column this field sits in within the form grid

AddressManagerConfig

Field	Type	Description
useAllCountry	boolean	Whether every country or region is offered, not just the shippable ones

AddressSchemaManager

Schema manager for one address form: it reads and changes the values, hands out the per-field schemas, and validates them.

class AddressSchemaManager {
  getFieldType(key: keyof AddressValues);
  updateContext(context: AddressSchemaManagerContext, config?: AddressManagerConfig);
  onUpdateContext(cb: UpdateContextCb);
  registerSchemaChange(field: keyof AddressValues, cb: AddSchemaChangeCbs);
  onAddressChangeByInput(cb: AddressChangeByInputCb);
  removeAddressChangeByInput(cb: AddressChangeByInputCb);
  onAddressChange(cb: AddressValuesChangeCb);
  removeAddressChange(cb: AddressValuesChangeCb);
  onFieldsChange(cb: FieldsChangeCb);
  getAddressValues();
  changeValues(values: Partial<AddressValues>, config?: ChangeValuesConfig);
  onValuesChange(cb: AddressValuesChangeCb);
  removeValuesChangeCb(cb: AddressValuesChangeCb);
  dispatchAddressValuesChange(changeVal: Partial<AddressValues>, options?: AddressValuesChangeOptions);
  validateFields(fieldIds?: Array<keyof AddressValues>, config?: { updateUi?: boolean; onlyValidateExistValue?: boolean }): Promise<ValidateResult[]>;
  onValidateResultChange(cb: ValidateResultChangeCb);
  removeValidateResultChange(cb: ValidateResultChangeCb);
  getCountries();
  hasCountry(countryCode: string);
  getProvinces();
  isValidProvinceCode(code: string);
  getAllSchema(): Array<AddressItemSchema>;
  getCustomLabelById(id: string);
  getCountryCodeSchema(): AddressItemSelectSchema | null;
  getProvinceSchema(config?: { emptyHide: boolean }): AddressItemSelectSchema | AddressItemStringSchema | null;
  getCitySchema(): AddressItemSelectSchema | AddressItemStringSchema | null;
  getAreaSchema(): AddressItemSelectSchema | AddressItemStringSchema | null;
  getAddressSchema(config?: { ignoreSettings?: boolean }): AddressItemSelectSchema | AddressItemStringSchema | null;
  getAddress1Schema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
  getZipSchema(config?: { noUseSetting: boolean }): AddressItemStringSchema | null;
  getFirstNameSchema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
  getLastNameSchema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
  getCompanySchema(config?: { ignoreSettings?: boolean }): AddressItemStringSchema | null;
  getCustomizedFields(): Array<AddressItemStringSchema | AddressItemPhoneSchema | AddressItemEmailSchema | AddressItemSelectSchema>;
  getPhoneSchema(config: ContactSchemaConfig): AddressItemGeneralPhoneSchema | AddressItemStringSchema | null;
  getEmailSchema(config: ContactSchemaConfig): AddressItemEmailSchema | null;
  getEmailOrPhoneSchema(): AddressItemStringSchema | null;
  getIdNumberSchema(): AddressItemStringSchema | null;
  getCpfSchema(): AddressItemStringSchema | null;
  formatPhone(value: string);
  changePhone(value: string, format?: boolean, config?: ChangeValueConfig);
  changePhoneAreaCode(code: string, setEmailOrPhone?: boolean);
  changeEmailOrPhone(values: Partial<AddressValues>, config?: ChangeValueConfig);
}

The manager keeps state of its own, so it is listed as source code rather than as a table. Get an instance from CheckoutAPI.address instead of constructing one yourself.

AddressSchemaManagerContext

Field	Type	Description
addressValues	AddressValues	Current values of the address form
addressTemplate	AddressTemplate	Address template of the current country or region

AddressTemplate

Field	Type	Description
fields	AddressTemplateField[]	The address fields this template collects
stringify	string
preset	string
addressLevel	number	Number of address levels

AddressTemplateField

Field	Type	Description
id	string	Unique id of this item
col	number	Column this field sits in within the form grid
row	number	Row this field sits in within the form grid
show	0 | 1	Whether this item is shown
format?	Array<[regexp: string, params: string[]]> | string[]	Format rules the value has to match
length?	number | { min?: number; max?: number }	Allowed length of the value
required	0 | 1	Whether the buyer must fill this in
type	FieldType	Type of this item
label?	string	Label shown above the field
tips?	string	Hint text shown under the field
validate?	AddressTemplateFieldValidate[]	The validation rules for this field

AddressTemplateFieldValidate

Field	Type	Description
id	string	Unique id of this item
message	string	Message shown when the check fails
regexp	string	Regular expression the value has to match

AddressValues

Field	Type	Description
id?	string	Address id
firstName	string	First name
lastName	string	Last name
countryCode	string	Country code
country	string	Country name
provinceCode	string	Province or state code
province	string	Province or state name
area	string	District or county
city	string	City
address	string	Street address
address1	string	Second address line, such as an apartment or suite number
shortAddress?	string	Short address
zip	string	Postal code
cpf?	string	Tax number
taxText?	string	Label of the tax number field
idNumber?	string	National ID number
idNumberText?	string	Label of the national ID field
company	string	Company name
latitude?	string	Latitude
longitude?	string	Longitude
source?	string	Where the current address values came from
tags?	string
gender?	string	Gender
phone	string	Phone number
emailOrPhone	string	Value of the combined email-or-phone field
email	string	Email
phoneAreaCode	string	Phone area code
[key: string]	string | undefined	Any other key, keyed by name
originId?	string	Id of the address this value came from

AddressValuesChangeCb

export type CommonAddressValuesChangeCb = (
  changeValue: Partial<AddressValues>,
  fullAddress: AddressValues,
  options?: AddressValuesChangeOptions,
) => void;

AddressValuesChangeOptions

Field	Type	Description
apiAutoFilled?	boolean	Whether the value was filled in by a request rather than by the buyer
changeByInput?	boolean	Whether the change came from the buyer typing

AddSchemaChangeCbs

type AddSchemaChangeCbs = (item: AddressItemSchema) => AddressItemSchema;

AfterPayCb

export type AfterPayCb = (res: AfterPayParams) => void;

AfterPayParams

What the payment attempt produced: the PayResponse plus a loadTime when the payment call went through, an Error when it threw, or undefined when there is nothing to report.

export type AfterPayParams =
  | (PayResponse & {
      loadTime: number;
    })
  | Error
  | undefined;

AllExtensionLoadedCb

export type AllExtensionLoadedCb = () => void;

AlreadyPaymentLines

An array of the payments already taken on this order. The fields below are those of one entry.

Field	Type	Description
creditCardNumber	string	Card number used for this payment
extraInfo	{ name: string; channel: string; method: string; lastCharacters: string; realPaidTotal: string; }	Extra details of the payment
paidTotal	string	Amount taken by this payment

AppliedGiftCard

Field	Type	Description
id	string	Unique id of this item
lastCharacters	string	Last few characters of the gift card code
amountUsed	string	Amount taken off by the gift card
realAmountCurrency	string	Currency the gift card is denominated in
realSymbol	string	Currency symbol of the gift card's own currency
realAmountUsed	string	Amount used, in the gift card's own currency

BannerConfig

Field	Type	Description
checkoutPcImage	string	Banner image used on desktop
checkoutMobileImage	string	Banner image used on mobile
checkoutImageHeight	'normal' | 'large' | 'small'	Height preset of the banner image
checkoutAlignment	'top' | 'center' | 'bottom'	Vertical alignment of the banner
checkoutIsFullWidth	boolean	Whether the banner spans the full page width
checkoutShowBottomMargin	boolean	Whether a bottom margin is left under the banner

BaseAddressItemSchema

Field	Type	Description
id	string	Unique id of this item
row	number	Row this field sits in within the form grid
col	number	Column this field sits in within the form grid
show	boolean	Whether this item is shown
label	string	Label shown above the field
eventBus	EventBus	The event bus of this field
description?	string	Description of this field
max?	number	Largest value accepted
min?	number	Smallest value accepted
tips?	string	Hint text shown under the field
autocomplete?	string	Value put on the input's autocomplete attribute
required	boolean	Whether the buyer must fill this in
readonly?	boolean	Read-only, the buyer cannot change it
htmlAttr?	Record<string, string | number>	Extra HTML attributes put on the input
fieldType?	'standard' | 'custom'	Whether this is a standard address field or one the merchant added
focusId?	string	Id of the input to move focus to
nameId?	string	Value put on the input's name attribute
placeType?	PlaceType	Which place types the address autocomplete looks for
validateFn(updateUi?)	Promise<ValidateResult | undefined>	Validates the field's current value
validateByValue?	(val: string) => ValidateResult | undefined	Validates a value you pass in, without touching the field
validateResult?	ValidateResult	Result of the last validation
onValidateResultChange(cb)	void	Registers a callback for when the validation result changes
removeValidateResultChange(cb)	void	Takes a validation-result callback off again

BasePriceDetail

Field	Type	Description
key?	string	Identifier of this breakdown row
dataRobot?	string
title?	string	Title of this row
titleLangId?	string	Translation key of the title
subTitle?	string	Secondary title of this row
subTitleLangId?	string	Translation key of the secondary title
originPrice?	string	Price before the discount
price?	string	Amount of this row
originalValue?	string	Unformatted value of this row
value?	string	Value of this item
desc?	string	Extra description shown with this row
descLangId?	string	Translation key of the description
icon?	string	Icon shown with this row
isShow?	boolean	Whether this row is shown
tooltip?	string	Tooltip text of this row

BaseResponse

Field	Type	Description
ok	boolean	Whether the request succeeded
config	ReqConfig	Configuration carried with this request or order

BeforeSubmitCb

export type BeforeSubmitCb = (params: BeforeSubmitCbParams) => Promise<boolean>;

BeforeSubmitCbParams

Field	Type	Description
pageType	CheckoutPageType	Checkout layout, as a CheckoutPageType value
step	CheckoutStep	Checkout step this applies to

BillingAddress

Field	Type	Description
id?	string	Unique id of this item
firstName	string	First name
lastName	string	Last name
email	string	Email address
emailOrPhone	string	Whichever of email and phone the buyer filled in
phone	string	Phone number
phoneAreaCode	string	International dialling code of the phone number
countryCode	string	Country or region code
country	string	Country or region name
provinceCode	string	Province or state code
province	string	Province or state name
area	string	Area or district
city	string	City
address	string	Street address
address1	string	First line of the street address
zip	string	Postal code
company	string	Company name

BillingAddressChangeCb

export type BillingAddressChangeCb = () => void;

BillingAddressValuesChangeCb

export type BillingAddressValuesChangeCb = (values: Partial<AddressValues>) => void;

BuyerJourneyInterceptCb

export type BuyerJourneyInterceptCb = () => BuyerJourneyInterceptCbReturn;

BuyerJourneyInterceptCbReturn

Field	Type	Description
behavior	'block' | 'allow'	Whether to block the buyer or let them go on
pointId	string	Id of the extension point the interception came from
hideTrueBtn?	boolean	Hide the confirm button of the dialog
hideFalseBtn?	boolean	Hide the cancel button of the dialog

CancelCouponParams

export type CancelCouponParams =
  | {
      code: string;
      discountCodeType: DiscountCodeType.DISCOUNT_CODE;
    }
  | {
      id: string;
      discountCodeType: DiscountCodeType.GIFT_CARD;
    };

CardInfo

Field	Type	Description
cardFirstName	string	First name of the cardholder
cardLastName	string	Last name of the cardholder
cardDate	string	Expiry date on the card
cardCode	string	Security code on the card
cardNumber	string	Card number
instalmentsPlans	string	Instalment plan chosen on the card

Cards

Field	Type	Description
supportCards	Array<PlayCardCards>	Card types this payment method accepts

ChangedLineItem

Field	Type	Description
id	string	Unique id of this item
productId	string	Id of the product
variantId	string	Id of the variant
quantity	number	Quantity
originalQuantity	number	Quantity before the change
image	{ src: string; }	Image of the product
productTitle	string	Title of the product
options	Array<{ name: string; value: string }>	The options available on this item
properties	string	Custom properties carried on this line
reason	| 'line_item_sold_out' | 'line_item_shortage' | 'line_item_off_line' | 'line_item_not_exist' | 'line_item_mismatch_wholesale_conditions'	Why this line changed

ChangeValueConfig

Field	Type	Description
format?	boolean	Whether the value is reformatted as it is written
changeByInput?	boolean	Whether the change came from the buyer typing

ChangeValuesConfig

Field	Type	Description
ignoreValidate?	boolean	Whether to skip validation for this change
dispatchUpdate?	boolean	Whether to trigger a UI refresh after the change
changeByInput?	boolean	Whether the change came from the buyer typing
changeByUserInput?	boolean	The buyer typed the value
apiAutoFilled?	boolean	Filled in by address autocomplete, so the UI highlights the field
onlyValidateExistValue?	boolean	Whether to validate only the fields that already have a value

ChargeQuote

Field	Type	Description
quoteId	string	Quote id
feeTitle	string	Fee title
fee	string	Fee amount
feeValue	string	Fee as a formatted string
currency	string	Currency code
selected	boolean	Whether it is selected
available	boolean	Whether it can be selected
providerIcon	string	Provider icon
providerName	string	Provider name
title	string	Title
description	string	Description
tooltip	string	Tooltip text
lineItems	Array<{ lineItemId: string; quantity: number; fee: string }>	The line items this quote covers

CheckoutAddressSettings

Field	Type	Description
name	NameSetting	Settings for the name field
nameRequirement	NmeRequirementSetting	Whether the name field is required
contactDetails	ContactDetailsSetting	Settings for the contact details field
phone	SimplesSetting	Settings for the phone field
email	SimplesSetting	Settings for the email field
company	SimplesSetting	Settings for the company field
address	SimplesSetting	Settings for the address field
address1	SimplesSetting	Settings for the second address line field

CheckoutAppConfig

Field	Type	Description
namespace	string	Namespace of the app
routes	{ root: string; }	Base paths of the app's routes
currencySymbol	string	Currency symbol
localeRtl	boolean	Whether the current locale is right-to-left
locale	string	Current locale
favicon?	string	Site favicon
siteKey	string | null	Site key of the CAPTCHA provider
cdnDomain	string	CDN domain
imageDomain	string	Image domain
currencySymbolPos	string	Whether the currency symbol goes before or after the amount
moneyFormat	string	Money format
paymentSettings	{ paypalExpressEnabled: boolean; }	Payment settings
market	MarketInfo	Market information

CheckoutBusinessType

Checkout type: standard products, virtual products, or in-store pickup.

Member	Value	Description
STANDARD	0	Ordinary physical products
VIRTUAL_PRODUCT	1	Virtual products, which need no shipping
PICKUP	2	In-store pickup

CheckoutBusinessTypeChangeCb

export type CheckoutBusinessTypeChangeCb = (type: CheckoutBusinessType) => void;

CheckoutCustomerInfo

Field	Type	Description
email	string	Email
phone	string	Phone number
emailOrPhone	string	Value of the combined email-or-phone field
firstName	string	First name
lastName	string	Last name
newsletter	0 | 1	Whether the buyer subscribed to marketing emails: 1 yes, 0 no
note	null | string	Buyer note
saveAddress	0 | 1	Whether the address is saved to the address book: 1 yes, 0 no

CheckoutFeatures

Feature switches of the checkout page: the key is the feature name, the value says whether it is on.

export type CheckoutFeatures = Record<string, boolean>;

checkoutFontfamily

Field	Type	Description
family	string	Font family name
fallbackFamilies	string	Fallback font families
style	string	Font style
weight	string	Font weight
fontFace	string	The @font-face rule for this font

CheckoutIpAddress

Field	Type	Description
countryCode	string	Country code
provinceName	string	Province or state name
countryName	string	Country name
city	string	City
ip	string	IP address

CheckoutMenuPolicyLink

Field	Type	Description
id	number	Unique id of this item
title	string	Only the three built-in policies have a value here
type	string	Menu type: policy for the three built-in policies, web for a menu the merchant added
url	string	Built-in policies use a fixed value: refund_policy, privacy_policy or service_policy. A merchant-added menu holds the URL they entered; an empty string renders text with no link

CheckoutOrder

Field	Type	Description
failCode	string | null	Failure code, empty when nothing failed
id	string	Order id
orderNo	string	Order number
status	string	Order status
checkoutStatus	string	Checkout status
financialStatus	string	Payment status
fulfillmentStatus	string	Fulfillment status
postSaleStatus?	string | null	Post-sale status
emailStatus?	string	Status of the order confirmation email
note?	string | null	Order note
customerNote	string	Buyer note
appliedGiftCards	Array<AppliedGiftCard>	Gift cards applied to this order
alreadyPaymentLines	AlreadyPaymentLines	Payments already made
cancelReason	string | null	Cancellation reason
currencyCode	string	Currency code
currencySymbol	string	Currency symbol
discountApplications	Array<DiscountApplication>	Discounts applied to the order
lineItems	Array<LineItem>	Order line items
shippingAddress	ShippingAddress	Shipping address
billingAddress	BillingAddress	Billing address
pickupLocation?	PickupLocation	Pickup location
subTotal	string	Subtotal of the products
shippingTotal?	string	Shipping total
taxTotal?	string	Tax total
discountTotal?	string	Discount total
totalTipReceived	string	Tip total
discountShippingPrice	string	Amount taken off the shipping cost
total	string	Order total
giftCardPrice	string	Amount covered by gift cards
paymentDue	string	Amount the buyer actually pays
paidTotal	string	Amount already paid
prices	CheckoutPrices	Price breakdown
lineItemDiscountTotal	string	Line item discount total
codeDiscountTotal	string	Discount code total
shippingLine	ShippingLineType | null	The shipping option currently selected
config	{ checkoutBusinessType: number; checkoutTemplateType: number; pageType: 'single' | 'three_step' | 'two_step'; marketSetting: { marketId?: string; }; productTaxIncluded?: boolean; }	Configuration carried with this request or order
customer	Customer	Buyer information
referInfo	ReferInfo	Referrer information
paymentLine?	PaymentLine	The payment method currently selected
paymentLines	Array<PaymentLine>	The payment methods that can be selected
discountSubTotal?	string	Subtotal after the product discounts
shippingTaxTotal?	string	Shipping tax total
allTaxTotal?	string	Total of all taxes
paymentDiscountTotal?	string	Payment-method discount
prePaymentAmount?	string	paymentDue without the payment-method discount, used to decide whether the payment list needs a refresh
additionalPrices?	AdditionalPrice[]	Additional charges
checkoutPriceList	PriceGroupDetail[]	Grouped price breakdown
taxLines	TaxLines	Tax breakdown
checkoutId?	string	Checkout id
checkoutUrl?	string	Checkout page URL
createTime?	string	Creation time
identifierExtra?	string
installmentFee?	string	Installment fee
orderKey?	string
orderStatusUrl?	string	Order status page URL
orderToken?	string	Token identifying the checkout session
orderType?	number	Order type
refund?	string	Refund amount
shippingAddressEditable?	boolean	Whether the shipping address can still be edited
shippingTaxType?	number	How tax on shipping is worked out
taxType?	number	How tax on the order is worked out
updatedTime?	string	Update time
yetPayment?	string

CheckoutPageType

Checkout layout: single page, two steps or three steps.

Member	Value	Description
SINGLE	'single'	Single-page checkout
THREE_STEP	'three_step'	Three-step checkout
TWO_STEP	'two_step'	Two-step checkout

CheckoutPrices

Every price field below is a string holding a decimal amount in the primary unit, for example "10.99" for 10.99 USD — not the smallest unit (not "1099" cents). Use a library such as Decimal.js for arithmetic to avoid JavaScript floating-point errors.

Field	Type	Description
subtotalPrice	string	Subtotal of the products
shippingPrice	string	Shipping cost
taxPrice	string	Tax
discountCodePrice	string	Amount taken off by discount codes
discountPrice	string	Total discount
totalPrice	string	Order total
discountLineItemPrice	string	Amount taken off the line items
totalTipReceived	string	Tip total
discountShippingPrice	string	Amount taken off the shipping cost
giftCardPrice	string	Amount covered by gift cards
paymentDue	string	Amount the buyer actually pays
paidTotal	string	Amount already paid
discountSubTotal?	string	Subtotal after the product discounts
shippingTaxTotal?	string	Shipping tax total
allTaxTotal?	string	Total of all taxes
paymentDiscountTotal?	string	Payment-method discount
prePaymentAmount?	string	paymentDue without the payment-method discount, used to decide whether the payment list needs a refresh
additionalPrices?	AdditionalPrice[]	Additional charges
chargeQuotes?	ChargeQuote[]	Shipping protection

CheckoutSettings

Field	Type	Description
customerAuthority	'all' | 'login'	Who can check out: all for everyone, login for signed-in buyers only
discountShowV2	string[]
reductionShow	{ single: string[]; twoStep: string[]; threeStep: string[]; }	Which discount rows are shown, per checkout layout
orderTimeout	number	Order timeout
shippingCpf	ShippingCpf	CPF field settings used for shipping
zipCheckV2	string
zipCheckConfigV2	Record<CountryCode, number>	Postal code check setting per country or region
zipFormatCheck	SwitchSetting	Whether the postal code format is validated
doorplateFormatCheck	SwitchSetting	Whether the house number format is checked
forcedZipCheck	CountryCode[]	Countries where the postal code check is enforced
instruction	string	How the order instructions box is shown, as an InstructionType value
autoComplete	SwitchSetting	Whether address autocomplete is on
autoCompleteCollapseMode?	SwitchSetting	Whether the address form collapses after autocomplete fills it
identificationInfo	{ default: IdentificationConfig; }	Identity document settings, keyed by country or region
shippingMethodDisplayStyle	'auto_select' | 'manual_select'	How a shipping option is picked: auto_select or manual_select
additionalProperties	AdditionalProperty[]	Extra fields the merchant added

CheckoutStep

Checkout step: contact information, shipping method or payment method.

Value	Description
'contact_information'	The step where the buyer fills in contact details and the address
'shipping_method'	The step where the buyer picks a shipping method
'payment_method'	The step where the buyer picks a payment method

CheckoutThemeConfig

Theme configuration of the checkout page, the fields of ThemeStyleConfig, LogoConfig, MenuPolicyConfig, BannerConfig, PluginConfig and InteractionConfig merged into one object.

Field	Type	Description
checkoutRecommendImageLink	'' | { url: string; type: string }	Link of the promotion banner
checkoutRecommendImage	string	Image of the promotion banner
checkoutPaymentBackgroundImage	string	Payment area background image
checkoutPaymentBackgroundColor	string	Payment area background color; the image wins when both are set
checkoutInputBackgroundColor	string	Input background color
checkoutOrderBackgroundImage	string	Order summary background image
checkoutOrderBackgroundColor	string	Order summary background color; the image wins when both are set
checkoutHeadingFontfamily	checkoutFontfamily	Font of the headings
checkoutBodyFontfamily	checkoutFontfamily	Font of the body text
checkoutButtonFontfamily	checkoutFontfamily	Font of the buttons
checkoutButtonBackgroundColor	string	Button background color, also the text color of the footer return link
checkoutButtonText	string	Text colour of the buttons
checkoutErrorColor	string	Text color of error messages
checkoutFocusColor	string	Colour of the focus ring on inputs
checkoutBorderRadius	string	Corner radius used across the page
checkoutBorderColor	string	Form area on the left
checkoutTextMainColor	string	Primary text colour of the page
checkoutTextSubColor	string	Secondary text colour of the page
checkoutEmptyBgColor	string	Background colour of empty areas
checkoutBlockBorderColor	string	Inside the cards on the left, including inputs and shipping line cards
checkoutBlockTextMainColor	string	Primary text colour inside cards
checkoutBlockTextSubColor	string	Secondary text colour inside cards
checkoutSummaryBorderColor	string	Order summary area on the right
checkoutSummaryTextMainColor	string	Primary text colour of the order summary
checkoutSummaryTextSubColor	string	Secondary text colour of the order summary
checkoutSummaryBlockBorderColor	string	Inside the cards on the right
checkoutSummaryBlockTextMainColor	string	Primary text colour of cards in the order summary
checkoutSummaryBlockTextSubColor	string	Secondary text colour of cards in the order summary
checkoutLogoImage	string	Logo image of the checkout page
checkoutLogoSize	'large' | 'medium' | 'small'	Size preset of the logo
checkoutLogoPosition	string	Where the logo sits
checkoutMenuPolicyLink1?	'' | CheckoutMenuPolicyLink	Link target of the first policy menu item
checkoutMenuPolicyLink2?	'' | CheckoutMenuPolicyLink	Link target of the second policy menu item
checkoutMenuPolicyLink3?	'' | CheckoutMenuPolicyLink	Link target of the third policy menu item
checkoutMenuPolicyText1?	string	Label of the first policy menu item
checkoutMenuPolicyText2?	string	Label of the second policy menu item
checkoutMenuPolicyText3?	string	Label of the third policy menu item
checkoutMenuAlignment	string	Alignment of the policy menu
blocks	Array<{ type: string; settings: { checkoutMenuPolicyText: string; checkoutMenuPolicyLink: CheckoutMenuPolicyLink; }; key: string; }>	The current data format; the six fields above are the older one. When both are present, blocks wins
checkoutPcImage	string	Banner image used on desktop
checkoutMobileImage	string	Banner image used on mobile
checkoutImageHeight	'normal' | 'large' | 'small'	Height preset of the banner image
checkoutAlignment	'top' | 'center' | 'bottom'	Vertical alignment of the banner
checkoutIsFullWidth	boolean	Whether the banner spans the full page width
checkoutShowBottomMargin	boolean	Whether a bottom margin is left under the banner
plugins	{ appserval: { servalBg1Color: string; servalBg2Color: string; servalDiscountColor: string; servalHeadingColor: string; showNewCustomerExclusiveTag: boolean; exclusiveForNewUsers: false; }; }	Configuration of the checkout plugins
checkoutPaymentIconShow	boolean	Whether payment method icons are shown
checkoutMobileOrderSummaryCollapse	boolean	Whether the order summary starts collapsed on mobile
checkoutMobileDiscountBoxLocation	'orderSummaryAndPaymentMethod' | 'orderSummary' | 'paymentMethod'	Where the discount code box sits on mobile

CloseType

Value	Description
'close_icon'	The buyer clicked the close icon
'true_btn'	The buyer clicked the confirm button
'false_btn'	The buyer clicked the cancel button
'hide_fn'	Your code called hide()

CollapseInfo

Field	Type	Description
contact	string	Contact shown in the collapsed summary
delivery	string	Delivery method shown in the collapsed summary
addressInfo	string	Address shown in the collapsed summary
addressInfoTitle	string	Title of the collapsed address line
showNewBtn	boolean	Whether the new shipping address button is shown

CollapseInfoChangeCb

export type CollapseInfoChangeCb = () => void;

CommonAddressValuesChangeCb

export type CommonAddressValuesChangeCb = (
  changeValue: Partial<AddressValues>,
  fullAddress: AddressValues,
  options?: AddressValuesChangeOptions,
) => void;

ContactDetailsSetting

Value	Description
'single'	One contact field is collected
'multiple'	More than one contact field is collected

ContactInformation

Field	Type	Description
email	string	Email
phone	string	Phone number
emailOrPhone	string	Value of the combined email-or-phone field
phoneAreaCode	string	Phone area code

ContactInformationChangeCb

export type ContactInformationChangeCb = (contactInformation: Partial<ContactInformation>) => void;

ContactSchemaConfig

Field	Type	Description
type	'address' | 'contact'	Type of this item
showWhenOptional?	boolean	Whether the field is still shown when it is optional

ContactType

How contact details are collected: email only, phone only, or either one.

Member	Value	Description
ONLY_EMAIL	'only_email'	Only an email address is collected
ONLY_PHONE	'only_phone'	Only a phone number is collected
EMAIL_OR_PHONE	'email_or_phone'	Either an email address or a phone number is accepted

Country

Field	Type	Description
cnName	string	Chinese name
name	string	Country name
flag	string	Flag
phoneCode	string	Phone country code
phoneKey	string	Key of the dialling code for this country or region
isoCode2	string	Two-letter country code

CouponAvailStatus

Member	Value	Description
AVAILABLE	'available'	The coupon can be used on this order
UNAVAILABLE	'unavailable'	The coupon cannot be used on this order

CouponChangeCb

export type CouponChangeCb = () => void;

CouponData

Field	Type	Description
page	number	Page number
limit	number	Page size
data	CouponItem[]	The coupons on this page
total	number	Total count

CouponItem

Field	Type	Description
id	string	Unique id of this item
code	string	Coupon code
title	string	Name of the coupon
discountText	string	Text describing what the coupon takes off
prerequisiteText	string	What the buyer has to do to use the coupon
createdAt	string	When this record was created
expiredAt	string	When the coupon expires
isFirstOrder	boolean	Whether the coupon is for first orders only

CouponListChangeCb

export type CouponListChangeCb = (data: CouponData) => void;

CSettings

Field	Type	Description
locale	string	Current locale
localeRtl	boolean	Whether the current locale is right-to-left
cdnDomain	string	CDN domain
customer	{ customerId: string; customerEmail: string; customerPhone: string; }	Buyer information
imageDomain	string	Image domain
paymentSettings	{ paypalExpressEnabled: true; expressCheckoutConfig: { expressAccountInfos: {}; expressChannels: string[]; expressThemeConfigs: {}; }; }	Payment settings
saServerUrl	string	Endpoint analytics events are sent to
saWebUrl	string	URL the analytics script is loaded from
currencyCode	string	Currency code
currencySymbol	string	Currency symbol
currencySymbolPos	string	Whether the currency symbol goes before or after the amount
theme	{ themeVersionId: string; merchantThemeName: string; updatedAt: string; }	Theme information
meta	{ page: { templateName: string; templateType: number; }; }	Page metadata of the checkout front end
moneyFormat	string	Money format
slug	string
clientSentryDsn	string	Sentry DSN the front end reports errors to
environment	string	Environment the front end is running in
region	string	Region code
storePlan	string	Store plan
storeTrial	boolean	Whether the store is on trial
passwordEnabled	boolean	Whether the store is password protected
namespace	string	Namespace of the checkout front end
siteKey	null	Site key of the CAPTCHA provider
routes	{ root: string; }	Base paths of the app's routes
market	{ marketId: string; }	Market information
shop	{ customerId: string; finance: string; financeSymbol: string; cdnDomain: string; shopName: string; themeId: string; shopId: string; shopEnv: string; defaultImg: string; templateName: string; templateType: string; favicon: string; formLang: {}; contactEmail: string; serviceEmail: string; timeZone: string; }	Store information

Customer

Field	Type	Description
id	string	Id of the customer record
firstName	string	First name
lastName	string	Last name
email	string	Email address
phone	string | null	Phone number
name	string	Full name of the customer
orderCount	number	Number of orders this customer has placed
customerId	string	Id of the customer
createAt	string	When the customer record was created
registeredAt	string	When the buyer registered
registered	string	Whether the buyer has a store account
subscribed	boolean	Whether the buyer is subscribed to marketing email

CustomerAuthority

Who can check out: all for everyone, login for signed-in buyers only.

Value	Description
'all'	Anyone can check out
'login'	Only signed-in buyers can check out

DayConfigOfPickupTime

Field	Type	Description
day?	number	1-7
state?	number	0 closed, 1 open
start?	string	Start of the time window
end?	string	End of the time window

DeliveryListChangeCb

export type DeliveryListChangeCb = () => void;

DeliveryMethodChangeCb

export type DeliveryMethodChangeCb = (id: DeliveryMethodItem) => void;

DeliveryMethodItem

Field	Type	Description
iconType	string	Which icon to use for this delivery method
checkoutBusinessType	CheckoutBusinessType	The checkout type this delivery method belongs to
text	string	Display text

DeliveryMethodListChangeCb

export type DeliveryMethodListChangeCb = (items: DeliveryMethodItem[]) => DeliveryMethodItem[];

DialogContent

Field	Type	Description
content	string	Body content of the dialog or drawer
footer?	string	Footer content of the dialog or drawer
trueBtn?	string	Label of the confirm button
falseBtn?	string	Label of the cancel button

DialogOptions

Field	Type	Description
hideTrueBtn?	boolean	Hide the confirm button
hideFalseBtn?	boolean	Hide the cancel button
closeThroughResolve?	boolean	Resolve instead of reject when the close icon is clicked; defaults to false
maskBlur?	boolean	Blur the page behind the mask; defaults to false
style?	{ width?: number; height?: number; maxHeight?: number; maxWidth?: number; backgroundColor?: string; }	Inline styles put on the element

DiscountApplication

Field	Type	Description
type	string	Discount type
code	string	Discount code
status	string	Discount status
message	string	Message
discountId	string	Discount id
discountAmount	string	Discount on this product, e.g. "2.00"
discountMessage	string	Message shown with this discount
entitledProductList	Array<{ productId: string; variantId: string; price: string; quantity: number; compareAtPrice: string; inventoryTracking: boolean; inventoryQuantity: number; spu: string; }>	Products this discount applies to
valueType	string	Whether the discount is a fixed amount or a percentage
targetType	string	What the discount applies to, such as products or shipping
targetSelection	string	Which items the discount picks out
title	string	Discount title
value	string	e.g. "20"
discountType	string	Kind of discount
allocationMethod	string	How the discount is spread across the line items
isFreeGift	boolean	Whether this is a free-gift discount
totalDiscountAmount	string	Total discount of this promotion, e.g. "2"
subType	string	Finer-grained kind of discount
icon	string	URL
labelText	string	Label text
labelFontColor	string	Label text colour
labelBackgroundColor	string	Label background colour

DiscountCodeType

Member	Value	Description
DISCOUNT_CODE	'discountCode'	The code is a discount code
GIFT_CARD	'giftCard'	The code is a gift card

DiscountTypeEnum

Member	Value	Description
AUTOMATIC	'automatic'	Automatic discount, applied without a code
DISCOUNT_REBATE	'discount_rebate'	Spend-and-save discount
DISCOUNT_CODE	'discount_code'	Discount code the buyer types in
DISCOUNT_COUPON	'discount_coupon'	Coupon held by the buyer
GIFT_CARD	'gift_card'	Gift card

DrawerContent

Field	Type	Description
content	string	Body content of the dialog or drawer
footer?	string	Footer content of the dialog or drawer
trueBtn?	string	Label of the confirm button
falseBtn?	string	Label of the cancel button

DrawerOptions

Field	Type	Description
hideTrueBtn?	boolean	Hide the confirm button
hideFalseBtn?	boolean	Hide the cancel button
maskBlur?	boolean	Blur the page behind the mask; defaults to false
style?	{ width?: number; height?: number; maxHeight?: number; maxWidth?: number; backgroundColor?: string; }	Inline styles put on the element

DynamicExtensionPoint

enum DynamicExtensionPoint {
  // One member per dynamic extension point template, listed in full on the extension points page
  PRODUCT_RENDER_AFTER = 'Checkout::Product-{id}::RenderAfter',
  SHIPPING_LINE_RENDER_AFTER = 'Checkout::ShippingLine-{id}::RenderAfter',
  // ...
}

EventBus

A small publish-subscribe bus. Each address field carries one on its eventBus property.

Field	Type	Description
eventMap	Map<string, Set<Function>>	Callbacks registered per event name
onceCbMap	Map<Function, Function>	Wrappers of the one-shot callbacks, keyed by the original function
emit(name, ...rest)	—	Fires an event to every callback listening on that name
on(name, cb)	—	Registers a callback on an event name
once(name, cb)	—	Registers a callback that fires only the first time
off(name, cb)	—	Removes one callback from an event name

EventType

Value	Description
'change'	A value on the page changed
'return'	The buyer went back
'navigate'	The page navigated somewhere else

ExceptionChangeCbs

export type ExceptionChangeCbs = (tags?: IException) => void;

ExceptionInfo

Field	Type	Description
code	string	Error code
message?	string	Error message
title?	string	Title
content?	string	Body text
footer?	string	Footer text
backStep?	string	The step the buyer is sent back to
invalidLineItems?	Array<InvalidLineItem>	Line items that are no longer valid
changedLineItems?	Array<ChangedLineItem>	Line items that changed

ExceptNotification

Field	Type	Description
code	string	Error code of the exception
message?	string	Error message of the exception
nextAction?	NextAction	What the page should do next
invalidLineItems?	Array<InvalidLineItem>	Line items that are no longer valid
kickLineItems?	Array<KickLineItem>	Line items removed from the order
thirdPartyErrorDetails?	Record<string, unknown>[]	Raw error details returned by a third party

ExtendSchema

Schema of one item in the address form: an ordinary field, a checkbox, a title or an action.

export type ExtendSchema =
  | AddressItemSchema
  | AddressItemCheckoutSchema
  | AddressItemTitleSchema
  | AddressItemActionSchema;

Extension

Field	Type	Description
components	ExtensionComponent[]	The extension's components
name	string	Extension name
name_en	string	English extension name
desc	string	Extension description
desc_en	string	English extension description
deleteTargets	string[]	Native modules this extension hides
placeholder	Record<string, string>	Placeholder text, keyed by field id

ExtensionComponent

Field	Type	Description
extensionId	string	Extension id
content	string	The HTML that gets rendered
point	string	The extension point it renders at

ExtensionList

Field	Type	Description
extensionId	string	Id of the extension
resourceUrl	string	URL the extension's script is loaded from
fields?	string	Fields the extension declares
name?	string	Name of the extension
name_en?	string	English name
desc?	string	Description of the extension
desc_en?	string	English description

ExtensionLoadCb

export type ExtensionLoadCb = (point: ExtensionPoint) => void;

ExtensionPoint

export type ExtensionPoint = StaticExtensionPoint | DynamicExtensionPoint;

ExtensionTarget

enum ExtensionTarget {
  // One member per native module that can be hidden, listed in full in the checkout extension reference
  shippingList = 'shippingList',
  couponDrawer = 'couponDrawer',
  // ...
}

FailPriceResult

Field	Type	Description
data	null	Payload of the result
message	string	Error message
state	string	State of the result, success when it worked

FieldFnValidate

Field	Type	Description
id	string	Id of this validation rule
message	string	Message shown when the check fails
validate(value)	boolean	Returns whether the value passes

FieldRegExpValidate

Field	Type	Description
id	string	Unique id of this item
message	string	Message shown when the check fails
regexp	string	Regular expression the value has to match

FieldsChangeCb

export type FieldsChangeCb = (fields?: Array<keyof AddressValues>) => void;

FieldType

Member	Value	Description
String	0	Plain text field
Number	1	Numeric field
Enum	2	Field with a fixed set of options
Bool	3	True / false field
Phone	101	Phone number field
Email	102	Email field
Checkbox	103	Checkbox
Title	104	Title row, not an input
Action	105	Action row such as a link or a button, not an input

FieldValidate

export type FieldValidate = FieldRegExpValidate | FieldFnValidate;

FormatShippingLineType

Field	Type	Description
formatDiscountShippingPrice	string	Discounted shipping cost with the currency symbol
formatShippingPrice	string	Shipping cost with the currency symbol
isFree	boolean	Whether shipping is free

GetAddressTemplateParams

Field	Type	Description
countryCode	string	Country or region code
provinceCode	string	Province or state code

GiftCard

Field	Type	Description
type	DiscountCodeType	Code type
code	string	Gift card code
id	string	Gift card id
title	string	Gift card title
lastCharacters?	string	Last characters of the card number
amountUsed?	string	Amount used
realAmountCurrency?	string	Currency the gift card is denominated in
realSymbol?	string	Currency symbol of the gift card's own currency
realAmountUsed?	string	Amount used, in the gift card's own currency

GiftCardTagChange

export type GiftCardTagChange = (item: GiftCardTagItem) => GiftCardTagItem;

GiftCardTagItem

Field	Type	Description
disable?	boolean	Whether it is disabled
hideIcon?	boolean	Whether the icon is hidden

GiftCardTagsChangeCb

export type GiftCardTagsChangeCb = (tags: GiftCardTagItem[]) => void;

GiftCardTagsFilter

export type GiftCardTagsFilter = (tags: GiftCardTagItem[]) => GiftCardTagItem[];

HideExtensionTargetCb

export type HideExtensionTargetCb = () => void;

HttpCompleteResponse

Field	Type	Description
status	number	HTTP status code
statusText	string	HTTP status text
headers	Record<string, string>	Request or response headers
data	Payload	Body of the response

HttpFailResponse

Field	Type	Description
ok	false	Whether the request succeeded

HttpSuccessResponse

Field	Type	Description
ok	true	Whether the request succeeded

IAddressBookItem

Field	Type	Description
showEmail	boolean	Whether the email is shown
showPhone	boolean	Whether the phone number is shown

IdentificationConfig

Field	Type	Description
countries?	Record<string, string[]> | null	Countries or regions this configuration covers
isFilled	boolean	Whether the buyer has filled the field in
formatCheck	boolean	Whether the value format is checked
rules	Array<{ countryCode: string; provinceCode?: string; name: string; regexp: string; exampleVal: string; }>	The rules that apply, one entry per country or region

IDialog

Field	Type	Description
show()	Promise<boolean>	Whether this item is shown
hide()	void	Closes the dialog or drawer

IDrawer

Field	Type	Description
show()	Promise<boolean>	Whether this item is shown
hide()	void	Closes the dialog or drawer
onClose(cb)	void	Registers a callback for when the drawer closes
destroy()	void	Closes the drawer and releases it

IException

Field	Type	Description
code	string	Error code
message?	string	Error message
invalidLineItems?	Array<InvalidLineItem>	Line items that are no longer valid
changedLineItems?	Array<ChangedLineItem>	Line items that changed
kickLineItems?	Array<KickLineItem | (Omit<KickLineItem, 'properties'> & { properties: Record<string, string> })>	Line items removed from the order
nextAction?	NextAction	What the page should do next
thirdPartyErrorDetails?	ThirdPartyErrorDetails	Error details returned by a third party

IExceptionCode

Value	Description
'30002'	Platform error code 30002
'30003'	Platform error code 30003
'30005'	Platform error code 30005
'line_items_variant_not_exist'	A variant in the order no longer exists
'price_shipline_changed'	The shipping price changed
'price_tax_changed'	The tax changed
'price_shipping_tax_changed'	The tax on shipping changed
'checkout_address_invalid'	The address on the order is not valid
'shipping_not_available'	No shipping method is available for this address
'payment_method_invalid'	The chosen payment method cannot be used
'80009'	Platform error code 80009
'discount_code_expired'	The discount code has expired
'discount_code_times_limit'	The discount code has been used too many times
'shipping_line_changed'	The shipping method changed
'shipping_line_changed_refresh'	The shipping method changed and the page needs refreshing
'gift_card_disabled'	The gift card is disabled
'gift_card_no_funds'	The gift card has no balance left
'total_price_changed'	The order total changed
'pickup_changed'	The pickup location changed
'pay_cod_limit'	The order is over the cash-on-delivery limit
'pay_ip_limit'	Payment was blocked by an IP restriction
'price_shipline_changed_true'	The shipping price changed and the new value is already applied
'system_busy'	The platform is busy, try again

InitPhoneResult

A name this documentation gives the type so it can be referenced; in the source it is an inline type.

Field	Type	Description
phoneAreaCode	string	International dialling code of the phone number
phone	string	Phone number

InstructionType

How the order instructions box is shown: unfolded, folded or hidden.

Member	Value	Description
UNFOLD	'unfold'	The order instructions box starts expanded
FOLD	'fold'	The order instructions box starts collapsed
HIDDEN	'hidden'	The order instructions box is not shown

InteractionConfig

Field	Type	Description
checkoutPaymentIconShow	boolean	Whether payment method icons are shown
checkoutMobileOrderSummaryCollapse	boolean	Whether the order summary starts collapsed on mobile
checkoutMobileDiscountBoxLocation	'orderSummaryAndPaymentMethod' | 'orderSummary' | 'paymentMethod'	Where the discount code box sits on mobile

InvalidLineItem

Field	Type	Description
productTitle	string	Title of the product
image	{ src: string; }	Image of the product
options	Array<{ name: string; value: string | number; }>	The options available on this item

isShowCountries

Field	Type	Description
[key: string]	{ countryCodes?: string; countries?: { [key: string]: string[] }; isFilled: boolean; title: string; formatCheck?: boolean; }	Any other key, keyed by name

IsSpecialInstructionCollapseChange

export type IsSpecialInstructionCollapseChange = (isCollapse: boolean) => void;

JumpWay

Value	Description
'a'	Follow an <a> link
'window.open'	Open in a new window with window.open
'history'	Push a history entry, no page reload
'hash'	Change only the URL hash
'location'	Assign to location, which reloads the page

KickLineItem

Field	Type	Description
id	string	Unique id of this item
productId	string	Id of the product
variantId	string	Id of the variant
quantity	number	Quantity left after the adjustment
originalQuantity	number	Quantity before the adjustment
url	string	Product image URL
name	string	Product name without localization; use productTitle instead
options	Array<{ name: string; value: any }>	The options available on this item
productTitle?	string	Product name, localized
properties	string	Custom properties carried on this line

LineItem

Field	Type	Description
id	string	Line item id
productTitle	string	Product title
productId	string	Product id
productHandle	string	Product handle
variantId	string	Variant id
variantTitle	string	Variant title
quantity	number	Quantity
fulfillmentStatus	string	Fulfillment status
note	string	Note
image	{ path: string; src: string; }	Product image
compareAtPrice	string	Compare-at price
price	string	Unit price
linePrice	string	Price of this line
total	string	Total of this line
sku	string	SKU
weight	string	Weight
weightUnit	string	Weight unit
taxable	boolean	Whether it is taxable
requiresShipping	boolean	Whether it needs shipping
options	Array<{ name: string; value: string }>	Variant options
vendor	string	Vendor
productUrl	string	Product page URL
properties	string	Custom properties
discountApplications	Array<DiscountApplication>	Discounts applied to this line
finalPrice?	string	Unit price after every discount, e.g. "9.00"
finalLinePrice?	string	Unit price after every discount x quantity, e.g. "18.00"
discountTotal?	string	Total discount on this line, the sum of discountApplications, e.g. "2.00"
isFreeGift?	boolean	Whether it is a free gift
type?	string	Type of this item

LineMutationErrorCode

Value	Description
'bundled_product_requires_real_item'	A bundled product was added without the real product it belongs to
'checkout_token_missing'	The checkout token was not found on the page
'checkout_token_invalid'	The checkout token is not valid

LineMutationResult

Field	Type	Description
state	'success' | string	State of the result, success when it worked
data?	LineMutationResultData	Payload of the result
code?	LineMutationErrorCode | string	Error code when the change failed
message?	string	Error message

LineMutationResultData

Field	Type	Description
orderId	string	Id of the order
lineItems	LineItem[]	The line items of the order
priceDirty	boolean	True when the prices are stale and need recalculating
lineItemsVersion	number	Version number of the line items, bumped on every change
shippingReselectRequired?	boolean	True only when the order flipped between needing shipping and not needing it
paymentReselectRequired?	boolean	Whether the buyer has to pick a payment method again

LoadingStatus

Field	Type	Description
globalLoading	boolean	Whether the whole page is loading

Locale

The language tags the checkout page supports.

Value	Description
'ar-SA'	Arabic (Saudi Arabia)
'de-DE'	German (Germany)
'en-US'	English (United States)
'es-ES'	Spanish (Spain)
'fr-FR'	French (France)
'id-ID'	Indonesian (Indonesia)
'it-IT'	Italian (Italy)
'ja-JP'	Japanese (Japan)
'ko-KR'	Korean (South Korea)
'nl-NL'	Dutch (Netherlands)
'pl-PL'	Polish (Poland)
'pt-PT'	Portuguese (Portugal)
'ru-RU'	Russian (Russia)
'th-TH'	Thai (Thailand)
'zh-CN'	Simplified Chinese (mainland China)
'zh-TW'	Traditional Chinese (Taiwan)

LocaleMap

Field	Type	Description
'en-US'	Record<string, string>	One entry per locale; the value is the text for that language
[k in Locale]	Record<string, string>	One entry per locale; the value is the text for that language

LogoConfig

Field	Type	Description
checkoutLogoImage	string	Logo image of the checkout page
checkoutLogoSize	'large' | 'medium' | 'small'	Size preset of the logo
checkoutLogoPosition	string	Where the logo sits

MarketInfo

Field	Type	Description
marketId	string	Market id
marketPriceSetting	MarketPriceSetting	Price settings for this market

MarketPriceSetting

Field	Type	Description
local_currency_enabled	boolean	Whether prices are shown in the local currency
custom_rate_enabled	boolean	Whether a custom exchange rate is used
custom_rate	number	Manual rate, primary market currency -> market base currency
rate	number	Automatic rate, primary market currency -> market base or local currency
back_rate	number	Reverse automatic rate, market base or local currency -> primary market currency
actual_rate	number	The rate actually applied, primary market currency -> market base or local currency
base_to_local	number	Market base currency -> local currency
local_to_base	number	Local currency -> market base currency
adjust	number	Price adjustment
price_round_enabled	true	Whether converted prices are rounded

MenuPolicyConfig

Field	Type	Description
checkoutMenuPolicyLink1?	'' | CheckoutMenuPolicyLink	Link target of the first policy menu item
checkoutMenuPolicyLink2?	'' | CheckoutMenuPolicyLink	Link target of the second policy menu item
checkoutMenuPolicyLink3?	'' | CheckoutMenuPolicyLink	Link target of the third policy menu item
checkoutMenuPolicyText1?	string	Label of the first policy menu item
checkoutMenuPolicyText2?	string	Label of the second policy menu item
checkoutMenuPolicyText3?	string	Label of the third policy menu item
checkoutMenuAlignment	string	Alignment of the policy menu
blocks	Array<{ type: string; settings: { checkoutMenuPolicyText: string; checkoutMenuPolicyLink: CheckoutMenuPolicyLink; }; key: string; }>	The current data format; the six fields above are the older one. When both are present, blocks wins

MutationSource

export type MutationSource = string;

NameSetting

Value	Description
'separate'	First name and last name are two fields
'normal'	The name is one single field

NavigateLink

Field	Type	Description
id	CheckoutStep	The checkout step this link points to
title	'information' | 'shipping' | 'payment'	Used for analytics
text	string	Link text

NavigateLinksChangeCb

export type NavigateLinksChangeCb = () => void;

NewsLetterStatus

Marketing email subscription status: not subscribed, or subscribed.

Member	Value	Description
NO_SUBSCRIPTION	0	Not subscribed to marketing email
SUBSCRIBED	1	Subscribed to marketing email

NextAction

Field	Type	Description
redirectToUrl	{ url: string; }	The URL to send the buyer to
type	'redirect_to_url'	Type of this item

NmeRequirementSetting

Value	Description
'both'	Both first name and last name are required
'last_name'	Only the last name is required

OnCloseCb

export type OnCloseCb = (type: CloseType) => void;

OnLoadingStatusChangeCallback

export type OnLoadingStatusChangeCallback = (status: LoadingStatus) => void;

OnPayFailedPayload

Field	Type	Description
sysCodeGroup	string | null
paymentKey	string	Key identifying the payment method

OnPayFailedResult

Field	Type	Description
handled	boolean	Whether your callback has already handled the failure

OnStoreDataChangeCb

export type OnStoreDataChangeCb = () => void;

OnSubmitPendingChangeCallback

export type OnSubmitPendingChangeCallback = (val: Pending, change: Partial<Pending>) => void;

OptionValue

Field	Type	Description
name	string	Name of the option
code	C	Code of this item
alternateNames?	string[]	Other names this option is also known by

OrderConfig

The configuration carried on the order, taken from the config field of CheckoutOrder.

Field	Type	Description
checkoutBusinessType	number	Checkout type of this order, as a CheckoutBusinessType value
checkoutTemplateType	number	Template the checkout page renders with
pageType	'single' | 'three_step' | 'two_step'	Checkout layout, as a CheckoutPageType value
marketSetting	{ marketId?: string; }	Market this order belongs to
productTaxIncluded?	boolean	Whether product prices already include tax

OrderInfo

Field	Type	Description
currencyCode	string	Checkout currency, for example USD
currencySymbol	string	Currency symbol, for example $
alreadyPaymentLines	AlreadyPaymentLines	Payments already made
failCode	string | null	Failure code, empty when nothing failed
id	string	Order id
status	OrderStatus	Order status
checkoutStatus	string	Checkout status
financialStatus	string	Payment status
orderNo	string	Order number
cancelReason	string | null	Cancellation reason
orderType?	number	Order type: 1 = gift card order, 0 = any other order (physical, digital and so on)
exceptionError?	string	The next two fields only ever appear on the thank-you page
exceptionErrorMessage?	string	Error message
additionalPrices?	AdditionalPrice[]	Additional charges

OrderResult

Field	Type	Description
data?	OrderResultData	Payload of the response
state	string	State of the result, success when it worked
errors	string[]	Error messages

OrderResultData

Field	Type	Description
exceptNotification	ExceptNotification	The exception the platform is reporting
addressSettings	CheckoutAddressSettings	Address form settings of the store
checkoutSettings	CheckoutSettings	Checkout settings of the store
customerInfo	CheckoutCustomerInfo	Contact details the buyer entered
ipAddress	CheckoutIpAddress	IP address the order was placed from
order	CheckoutOrder	The order itself
paymentSettings	PaymentSettings	Payment settings of the store
showDetails	ShowDetails	Which blocks of the page are shown
step	CheckoutStep	Checkout step this applies to

OrderStatus

Order status.

Value	Description
'opened'	The order exists but has not been placed yet
'placed'	The order has been placed
'cancelled'	The order was cancelled
'finished'	The order is complete

PageTypeChangeCb

export type PageTypeChangeCb = (type: CheckoutPageType) => void;

PayAttemptCb

export type PayAttemptCb = () => void;

PayFailedHandler

export type PayFailedHandler = (payload: OnPayFailedPayload) => Promise<OnPayFailedResult>;

PaymentIconResource

Field	Type	Description
paymentKey	string	Key identifying the payment method
icon	string	Icon shown with this row

PaymentLine

Field	Type	Description
failCode?	string | null	Failure code, empty when nothing failed
available	boolean | string	Whether this payment method is available
createdAt	string	Creation time
desc	string	Description
id	string	Payment method id
name	string	Payment method name
paymentChannel	string	Payment channel
paymentMethod	string	Payment method
publicKey	any
status	string	Status
storeId	string	Store id
tips	string	Tip text
updatedAt	string	Update time
supportTip?	boolean	Whether it supports tipping
paypalClassicMode?	boolean	Whether the classic PayPal flow is used
channel	string	Payment channel
method	string	Payment method
fePay?	boolean	Whether the payment is completed in the front end
failReason?	string	Failure reason
paymentKey?	string	Key identifying the payment method
discounts?	Record<string, unknown>[]	Discounts tied to this payment method

PaymentLinesSource

Value	Description
'destroy'	The previous payment line was torn down
'verificationError'	Payment verification failed
'api'	The payment lines came back from a request

PaymentResources

Field	Type	Description
[key: string]	Cards	Any other key, keyed by name

PaymentSettings

Field	Type	Description
supportChannels	string[]	Payment channels the store has turned on
paymentResources	PaymentResources	Static resources the payment methods need
paymentIconResources?	PaymentIconResource[]	Icons of the available payment methods
paypalExpressEnabled	string	Whether PayPal Express is turned on

PaymentUpdateParams

Field	Type	Description
paymentLine	PaymentLine	The payment method currently selected
paymentLines	Array<PaymentLine>	The payment methods that can be selected
paymentButton	boolean	Whether the payment button is shown
paymentReady	boolean	Whether the payment method is ready to be submitted
cardInfo	Partial<CardInfo>	Card information
source?	PaymentLinesSource	What triggered this payment update, as a PaymentLinesSource value
paymentFeatures?	{ useCustomPaymentButton: boolean; useBillingAddress: boolean; }	Which payment features this method needs

PayResponse

export type PayResponse = (
  | {
      data: {
        exceptNotification: ExceptNotification;
        result?:
          | {
              redirectType: 'newwindow' | 'redirect' | 'iframe';
              redirectUrl: string;
            }
          | {
              redirectType: 'form';
              form: string;
            };
      };
      state: 'success';
    }
  | {
      data: null;
      state: 'pay_failed';
    }
) & {
  errors: string[];
  message: string;
};

Pending

Field	Type	Description
price	boolean	Price API call in flight
shippingLines	boolean	Shipping line list loading
payment	boolean	Payment script loading, not the payment method list
pickupLocation	boolean	Pickup location list loading

PhoneInfo

Field	Type	Description
phone	string	Phone number
phoneAreaCode	string	International dialling code of the phone number

PickupInformationChangeCb

export type PickupInformationChangeCb = (pickupInformation?: string) => void;

PickupLocation

Field	Type	Description
deliveryMethod?	number	1 shipping, 2 local delivery, 3 in-store pickup
businessTimeType?	number	1 one schedule for every day, 2 a schedule per day; defaults to 1 when absent
id?	string	Pickup location id
name?	string	Pickup location name
desc?	string	Pickup location description
shippingPrice?	string	Fee for this pickup location
supportCod?	number	0 not supported, 1 supported
locationId?	string	Id of the linked location
country?	string	Country name
countryCode?	string	Country code
province?	string	Province or state name
provinceCode?	string	Province or state code
city?	string	City
address?	string	Street address
address1?	string	Second address line, such as an apartment or suite number
company?	string	Company name
zip?	string	Postal code
timeZone?	string	Time zone
timeDaySetting?	DayConfigOfPickupTime[]	Pickup time slots per day
timeRemark?	string	Note about the pickup times
businessStart?	string	Opening time of the pickup location
businessEnd?	string	Closing time of the pickup location
timeLag?	string	Estimated wait before the order can be picked up, in hours
estimatedTimeEnd?	string	Estimated pickup time, for display
estimatedTimeUnit?	string	Unit of the estimated pickup time, either h or d
pickupAt?	string	Pickup time the buyer chose
lastSelected?	boolean	Whether this was the pickup location selected last time
formattedPickAt?	string	Pickup time in the location's own time zone, formatted as YYYY-MM-DD HH:mm:ss

PickupLocationsChangeCb

export type PickupLocationsChangeCb = (locations?: PickupLocation[]) => void;

PlaceType

export type PlaceType =
  | {
      types: Array<string>;
      stringify?: string;
    }
  | Array<string>;

PlayCardCards

Field	Type	Description
cardName	string	Display name of the card type
cardType	string	Card type, such as Visa or Mastercard
countryCnName?	string	Chinese name of the country or region
countryCode?	string	Country or region code
countryEnName?	string	English name of the country or region
icon	string	Icon shown with this row
name?	string	Name of this item
pmId?	string

PluginConfig

Field	Type	Description
plugins	{ appserval: { servalBg1Color: string; servalBg2Color: string; servalDiscountColor: string; servalHeadingColor: string; showNewCustomerExclusiveTag: boolean; exclusiveForNewUsers: false; }; }	Configuration of the checkout plugins

PriceDetail

One row of the price breakdown: every field of BasePriceDetail, plus an id and an optional list of sub-rows.

Field	Type	Description
key?	string	Identifier of this breakdown row
dataRobot?	string
title?	string	Title of this row
titleLangId?	string	Translation key of the title
subTitle?	string	Secondary title of this row
subTitleLangId?	string	Translation key of the secondary title
originPrice?	string	Price before the discount
price?	string	Amount of this row
originalValue?	string	Unformatted value of this row
value?	string	Value of this item
desc?	string	Extra description shown with this row
descLangId?	string	Translation key of the description
icon?	string	Icon shown with this row
isShow?	boolean	Whether this row is shown
tooltip?	string	Tooltip text of this row
subList?	SubPriceDetail[]	Sub-rows under this row
id	string	Unique id of this item

PriceGroupDetail

Field	Type	Description
key	PriceGroupDetailKey	Group key
list?	PriceDetail[]	Price entries in this group
desc?	string	Description
descLangId?	string	Translation key of the description

PriceGroupDetailKey

Value	Description
'tax_total'	Total tax
'shipping_tax_total'	Tax on shipping
'sub_total'	Subtotal of the products
'shipping_total'	Total shipping
'discount_coupon_total'	Total coupon discount
'discount_flash_sale_total'	Total flash-sale discount
'discount_applications'	The individual discounts applied
'total_tip_received'	Total tip
'gift_card'	Gift card
'payment_discount_total'	Total payment-method discount
'additional_price'	Shipping insurance
'charge_quotes'	Add-on fees quoted for this order

PriceListChangeCb

export type PriceListChangeCb = (newPriceList: PriceGroupDetail[]) => void;

PriceParams

Field	Type	Description
reductions?	Array<{ code: string }>	Discount codes to apply, given by code
discountApplications?	Array<{ code: string; discountId: string; _delete: 1; }>	The individual discounts applied
calculateShippingLine	boolean	Whether shipping should be recalculated
totalTipReceived	string	Total tip on the order
appliedGiftCards?	Record<string, { id: string; _delete: 1 }>	Gift cards applied to this order
type?	DiscountTypeEnum	Kind of discount being applied, as a DiscountTypeEnum value
step?	string	Checkout step this applies to
paymentLine?	PaymentLine | null	The payment method chosen on the order
config	{ checkoutBusinessType: CheckoutBusinessType; }	Configuration carried with this request or order

PriceResult

export type PriceResult = SuccessPriceResult | FailPriceResult;

PriceResultData

Field	Type	Description
exceptNotification	ExceptNotification	The exception the platform is reporting
discountApplications	CheckoutOrder['discountApplications']	The individual discounts applied
lineItems	CheckoutOrder['lineItems']	The line items of the order
prices	CheckoutPrices	The price breakdown of the order
shippingInfo	{ requiresShipping: boolean; shippingLine: ShippingLineType; shippingLines: Array<ShippingLineType>; }	Shipping method and whether shipping is needed
appliedGiftCards	Array<AppliedGiftCard>	Gift cards applied to this order
alreadyPaymentLines	AlreadyPaymentLines	Payments already taken on this order
pickupLocations	PickupLocation[]	The pickup locations available
pickupLocation	PickupLocation	The pickup location chosen on the order
checkoutPriceList?	PriceGroupDetail[]	Grouped price breakdown
taxLines?	TaxLines	The taxes worked out for this order

PricesChangeCb

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

ProductItem

Derived from LineItem: the same fields, except properties is a key-value object (Record<string, string>) instead of a string.

Field	Type	Description
id	string	Unique id of this item
productTitle	string	Title of the product
productId	string	Id of the product
productHandle	string	URL handle of the product
variantId	string	Id of the variant
variantTitle	string	Title of the variant
quantity	number	Quantity
fulfillmentStatus	string	Fulfillment status of this line
note	string	Note attached to this line
image	{ path: string; src: string; }	Image of the product
compareAtPrice	string	Compare-at price of the variant
price	string	Amount of this row
linePrice	string	Unit price times quantity for this line
total	string	Total of this line
sku	string	SKU of the variant
weight	string	Weight of the product
weightUnit	string	Unit the weight is measured in
taxable	boolean	Whether this line is taxable
requiresShipping	boolean	Whether this line needs shipping
options	Array<{ name: string; value: string }>	The options available on this item
vendor	string	Vendor of the product
productUrl	string	Storefront path of the product
discountApplications	Array<DiscountApplication>	The individual discounts applied
finalPrice?	string	Unit price after every discount, e.g. "9.00"
finalLinePrice?	string	Unit price after every discount x quantity, e.g. "18.00"
discountTotal?	string	Total discount on this line, the sum of discountApplications, e.g. "2.00"
isFreeGift?	boolean	Whether this line is a free gift
type?	string	Type tag of the line item
properties	Record<string, string>	Custom properties carried on this line

ProductListChangeCb

export type ProductListChangeCb = (newProductList: ProductItem[]) => void;

ProductProperties

Field	Type	Description
_shoplazza_bundled_product?	boolean	Bundled product, which cannot be fulfilled as an order of its own
_shoplazza_exclude_calculation?	boolean	Left out of every calculation and only added back into the final total
[key: string]	any	Any other key, keyed by name

PromptMessage

Field	Type	Description
type	string	Prompt type
dataRobot	string
errorMessage?	string	Error message
locales	string[]	Locales this message has text for

ReferInfo

Field	Type	Description
clientId	string	Client id of the app
country	string	Country
domain	string	Domain
fbc	string
fbp	string
ip	string	IP address
source	'buy_now' | 'back' | 'cart'	Where the buyer came into checkout from: buy_now, back or cart
userAgent	string	Browser user agent
payMethod?	string	Payment method
note?	string	Note

RemoveLineItemsInput

Field	Type	Description
lineItemIds	string[]	Ids of the line items to act on
mutationSource	MutationSource	A tag of your own naming what made this change

RenderParams

Field	Type	Description
id	string	Unique id of this item
extensionPoint	ExtensionPoint	Name of the extension point the content renders at
component	Promise<string> | string	HTML the extension renders, or a promise resolving to it

ReqConfig

Field	Type	Description
url	string	Request URL
method?	RequestInit['method']	HTTP method
headers?	Record<string, string>	Request or response headers
params?	Record<string, any> | URLSearchParams	Query parameters of the request
data?	Record<string, any> | string	Payload of the result
timeout?	number	Request timeout in milliseconds
withCredentials?	boolean	Whether cookies are sent with the request
responseType?	'json'	Format the response is parsed as
xsrfCookieName?	string	Name of the cookie the XSRF token is read from
xsrfHeaderName?	string	Name of the header the XSRF token is sent in

Res

export type Res<Shape = Record<string, any>, ErrorPayload = Record<string, any> & { state: string | '' }> =
  | HttpSuccessResponse<Shape>
  | HttpFailResponse<ErrorPayload>;

SaleTaxLine

Field	Type	Description
key?	string	Identifier of this tax line
price?	string	Amount of this row

SchemaChangeDisableCB

export type SchemaChangeDisableCB = () => Record<string, boolean>;

SchemaChangeLabelCb

export type SchemaChangeLabelCb = () => Record<string, string>;

SchemaChangeValidateRule

Field	Type	Description
[k: string]	SchemaChangeValidateRuleValue	Any other key, keyed by name

SchemaChangeValidateRuleCB

export type SchemaChangeValidateRuleCB = () => SchemaChangeValidateRule;

SchemaChangeValidateRuleValue

Field	Type	Description
required	true	Whether the buyer must fill this in
validates	FieldValidate[]	The validation rules that apply

SchemaItemVisibilityCb

export type SchemaItemVisibilityCb = () => Record<string, boolean>;

SchemaManagerConfig

Field	Type	Description
focusIdPrefix	string	Prefix put in front of every generated focus id

SchemaManagerConfigFn

Field	Type	Description
getAddressVisible()	boolean	Returns whether the address form is currently visible
getCustomLabels?	() => Record<string, string>	Returns the labels the merchant customised, keyed by field id
getCustomValidateRules?	() => SchemaChangeValidateRule	Returns the extra validation rules to apply
getAddressExpanded?	() => boolean	Whether the address form is currently expanded; treated as expanded when not provided
expandAddress?	(reason: 'manual_click' | 'empty_fallback_click' | 'auto_fill') => void	Expand the address form

SelectedPickupLocationChangeCb

export type SelectedPickupLocationChangeCb = (location?: PickupLocation) => void;

SelectType

Value	Description
'static'	The option list is fixed
'dynamic'	The option list is fetched as the buyer types

ShippingAddress

Field	Type	Description
phoneCountryCode?	string	Country code the phone number belongs to
id?	string	Address id
firstName	string	First name
lastName	string	Last name
email	string	Email
phone	string	Phone number
countryCode	string	Country code
country	string	Country name
provinceCode	string	Province or state code
province	string	Province or state name
area	string	District or county
city	string	City
address	string	Street address
address1	string	Second address line, such as an apartment or suite number
zip	string	Postal code
extraInfo	{ cpf?: string; taxText?: string; idNumber?: string; idNumberText?: string; addition?: AdditionValues; shortAddress?: string; }	Extra address fields such as tax and ID numbers
company	string	Company name
emailOrPhone	string	Value of the combined email-or-phone field
phoneAreaCode	string	Phone area code
latitude?	string	Latitude
longitude?	string	Longitude

ShippingChangeCb

export type ShippingChangeCb = () => void;

ShippingCpf

Field	Type	Description
isShow	boolean	Whether this row is shown
configInfo	{ configBr: { length: string; type: string; }; configDefault: { length: string; type: string; }; }	Per-country configuration of the CPF field
countries	any[]	Countries or regions this configuration covers
isShowCountries	isShowCountries	Countries or regions the CPF field is shown in

ShippingLinesErrorInfo

Field	Type	Description
message?	string	Error message

ShippingLineType

Field	Type	Description
createdAt?	string	Creation time
desc?	string	Description
id	string | number	Shipping option id
name?	string	Shipping option name
rateAdditionalAmount?	string	Charge for each additional unit
rateAdditionalRange?	string	Size of one additional billing unit
rateAdditionalUnit?	string	Unit the additional charge is measured in
rateAmount?	string	Base shipping charge
rateFirstRange?	string	Size of the first billing unit
rateFirstUnit?	string	Unit the first charge is measured in
rateType?	string	How the shipping rate is worked out
ruleRangeInfinite?	number	Whether the billing range has no upper bound
ruleRangeMax?	string	Upper bound of the billing range
ruleRangeMin?	string	Lower bound of the billing range
ruleRangeUnit?	string	Unit the billing range is measured in
ruleType?	string	What the billing range is measured on, such as weight or price
shippingId?	string	Id of the shipping method
shippingPrice?	number | string	Shipping cost
storeId?	number	Store id
supportCod?	number	Whether cash on delivery is supported
selected?	boolean	Whether it is selected
discountShippingPrice	number | string	Shipping cost after discount

ShippingMethodsFetchTriggerSource

Value	Description
'init'	First load of the page
'address_change'	The shipping address changed
'shipping_method_switch'	The buyer switched shipping method
'tipping_change'	The tip changed
'charge_quote_change'	An add-on fee changed
'billing_address_change'	The billing address changed
'step_change'	The buyer moved to another step
'delivery_method_change'	The buyer switched between delivery and pickup
'pickup_location_change'	The buyer picked another pickup location
'coupon_apply'	A coupon or discount code was applied
'coupon_cancel'	A coupon or discount code was removed
'gift_card_remove'	A gift card was removed
'payment_change'	The buyer picked another payment method
'payment_cancel'	The buyer cancelled the payment
'submit_retry'	The buyer submitted the order again
'exception_recovery'	The page recovered from an exception
'other'	Any other trigger

ShippingPriceDisplayChangeCb

export type ShippingPriceDisplayChangeCb = () => void;

ShippingPromptMessageChangeCb

export type ShippingPromptMessageChangeCb = () => void;

ShippingProtectionChangeCb

export type ShippingProtectionChangeCb = () => void;

ShopConfig

Field	Type	Description
contactEmail	string	Contact email
defaultImg	string	Placeholder image used when a product has none
shopName	string	Store name
shopId	string	Store id
favicon	string	Site favicon
finance	string	Currency code of the store
customerId	string	Id of the customer
financeSymbol	string	Currency symbol of the store
serviceEmail	string	Customer service email
cdnDomain	string	CDN domain
[key: string]	any	Any other key, keyed by name

ShowDetails

Field	Type	Description
isAddressAvailable?	boolean	Whether the address is usable

SimplesSetting

Value	Description
'hidden'	The field is not shown
'optional'	The field is shown and optional
'required'	The field is shown and must be filled in

SortSchemaCb

export type SortSchemaCb = (items: SortSchemaItem[]) => SortSchemaItem[];

SortSchemaItem

Field	Type	Description
id	string	Unique id of this item
row	number	Row this field sits in within the form grid

StaticExtensionPoint

enum StaticExtensionPoint {
  // One member per static extension point, listed in full on the extension points page
  PAGE_BEFORE = 'Checkout::RenderBefore',
  MAIN_AFTER = 'Checkout::Main::RenderAfter',
  // ...
}

StepChangeCb

export type StepChangeCb = () => void;

SubmitChangeCb

export type SubmitChangeCb = () => void;

SubmitError

Field	Type	Description
code	string	Error code
message	string	Error message

SubmitErrorChangeCbs

export type SubmitErrorChangeCbs = (tags: { code: string; message: string }) => void;

SubmitSuccessData

Field	Type	Description
data?	{ exceptNotification: ExceptNotification; result: Record<string, any>; }	Payload of the result
state	string	State of the result, success when it worked
errors	string[]	Error messages

SubPriceDetail

One sub-row under a price breakdown row: the key, price, value, title, titleLangId and tooltip fields of BasePriceDetail.

Field	Type	Description
key?	string	Identifier of this breakdown row
title?	string	Title of this row
titleLangId?	string	Translation key of the title
price?	string	Amount of this row
value?	string	Value of this item
tooltip?	string	Tooltip text of this row

SuccessPriceResult

Field	Type	Description
data	PriceResultData	Payload of the result
message	string	Message text
state	'success'	State of the result, success when it worked

Suggestion

Field	Type	Description
text	string	Text shown on this row
id	string	Unique id of this item
prefix?	string	Part of the suggestion before the matched text
suffix?	string	Part of the suggestion after the matched text

SuggestionChangeCb

export type SuggestionChangeCb = (sugs: Suggestion[], status?: SuggestionSearchStatus) => void;

SuggestionSchema

Field	Type	Description
suggestions?	Array<Suggestion>	Suggestion list
onSuggestionsChange?(cb)	void	Registers a callback for when the suggestion list changes
removeSuggestionChangeCb?(cb)	void	Takes a suggestion-change callback off again
onSelectSuggestion?(item)	void	Called when the buyer picks one suggestion
prefixIcon?	string	Icon shown in front of the input, given as an Icon type name

SuggestionSearchStatus

Value	Description
'idle'	No search is running
'empty'	The search finished with no results

SwitchSetting

Value	Description
'disabled'	Off
'enabled'	On

SwitchShippingProtectionResult

Field	Type	Description
success	boolean	Whether the call worked
message	string	Message text
data	any	Payload of the result

TaxLines

Field	Type	Description
salesTaxLines?	SaleTaxLine[]	Sales tax breakdown

ThemeConfigChangeCb

export type ThemeConfigChangeCb = () => void;

ThemeStyleConfig

Field	Type	Description
checkoutRecommendImageLink	'' | { url: string; type: string }	Link of the promotion banner
checkoutRecommendImage	string	Image of the promotion banner
checkoutPaymentBackgroundImage	string	Payment area background image
checkoutPaymentBackgroundColor	string	Payment area background color; the image wins when both are set
checkoutInputBackgroundColor	string	Input background color
checkoutOrderBackgroundImage	string	Order summary background image
checkoutOrderBackgroundColor	string	Order summary background color; the image wins when both are set
checkoutHeadingFontfamily	checkoutFontfamily	Font of the headings
checkoutBodyFontfamily	checkoutFontfamily	Font of the body text
checkoutButtonFontfamily	checkoutFontfamily	Font of the buttons
checkoutButtonBackgroundColor	string	Button background color, also the text color of the footer return link
checkoutButtonText	string	Text colour of the buttons
checkoutErrorColor	string	Text color of error messages
checkoutFocusColor	string	Colour of the focus ring on inputs
checkoutBorderRadius	string	Corner radius used across the page
checkoutBorderColor	string	Form area on the left
checkoutTextMainColor	string	Primary text colour of the page
checkoutTextSubColor	string	Secondary text colour of the page
checkoutEmptyBgColor	string	Background colour of empty areas
checkoutBlockBorderColor	string	Inside the cards on the left, including inputs and shipping line cards
checkoutBlockTextMainColor	string	Primary text colour inside cards
checkoutBlockTextSubColor	string	Secondary text colour inside cards
checkoutSummaryBorderColor	string	Order summary area on the right
checkoutSummaryTextMainColor	string	Primary text colour of the order summary
checkoutSummaryTextSubColor	string	Secondary text colour of the order summary
checkoutSummaryBlockBorderColor	string	Inside the cards on the right
checkoutSummaryBlockTextMainColor	string	Primary text colour of cards in the order summary
checkoutSummaryBlockTextSubColor	string	Secondary text colour of cards in the order summary

ThirdPartyErrorDetails

export type ThirdPartyErrorDetails = Record<string, unknown>[];

TippingChangeCb

export type TippingChangeCb = () => void;

TippingInfo

Field	Type	Description
productTotalPrice	number	Product total
isShowTipping	boolean	Whether the tipping block is shown
isSupportTipping	boolean	Whether tipping is supported
currencySymbol	string	Currency symbol
totalTipReceived	string	Tip total

TippingOption

Field	Type	Description
percent	number | 'none' | 'custom'	Percentage; none is no tip, custom is the amount the buyer types in
value	number	Amount
formatValue	string	Amount with the currency symbol

TipSchema

Field	Type	Description
tip?	string	Tip amount
tipChangeEvent?	string

TrackAddressFillParams

A name this documentation gives the type so it can be referenced; in the source it is an inline type.

Field	Type	Description
data	Partial<AddressBookItem>	Payload of the result
fillType	number

TrackGiftCardProps

Value	Description
'checkout_coupon_apply_begin'	The buyer started applying a gift card
'checkout_coupon_close_begin'	The buyer started closing the gift card box
'checkout_coupon_fail'	Applying the gift card failed

TrackSubmitAddressParams

A name this documentation gives the type so it can be referenced; in the source it is an inline type.

Field	Type	Description
skipSetShippingAddress?	boolean	Whether the shipping address step is skipped

TrackTippingData

Field	Type	Description
total?	string	Tip amount reported with the event
rate?	number	Tip rate the buyer picked
keyword?	string

TrackTippingType

Value	Description
'checkout_tipping_add_tip'	The buyer added a tip
'checkout_tipping_select'	The buyer picked a tip amount
'checkout_tipping_visible'	The tipping module came into view
'checkout_tipping_focus'	The buyer focused the tip input

UIProduct

Field	Type	Description
id	string	Unique id of this item
variantId	string	Variant id
productTitle	string	Product title
properties	ProductItem['properties']	Custom properties
discountApplications	ProductItem['discountApplications']	Discounts applied to this line
options	ProductItem['options']	Variant options
isFreeGift	boolean	Whether it is a free gift
quantity	ProductItem['quantity']	Quantity
linePrice	ProductItem['linePrice']	Price of this line
discountTotal?	ProductItem['discountTotal']	Total discount on this line
finalLinePrice?	ProductItem['finalLinePrice']	Price of this line after discount
compareAtPrice	ProductItem['compareAtPrice']	Compare-at price
price	ProductItem['price']	Unit price
coverUrl	string	Cover image URL

UiProductListChangeCb

export type UiProductListChangeCb = (product: UIProduct[]) => UIProduct[];

UiShippingLinesChangeCb

export type UiShippingLinesChangeCb = (lines: FormatShippingLineType[]) => FormatShippingLineType[];

UpdateContextCb

type UpdateContextCb = (context: AddressSchemaManagerContext) => void;

UpdateDataByOrderAndPriceApiResult

A name this documentation gives the type so it can be referenced; in the source it is an inline type.

Field	Type	Description
price?	PriceResult	Amount of this row
order?	OrderResult	The order itself

UpdateDataByPriceApiParams

The fields of PriceParams, all optional here: pass only the ones you want to change.

Field	Type	Description
reductions?	Array<{ code: string }>	Discount codes to apply, given by code
discountApplications?	Array<{ code: string; discountId: string; _delete: 1; }>	The individual discounts applied
calculateShippingLine?	boolean	Whether shipping should be recalculated
totalTipReceived?	string	Total tip on the order
appliedGiftCards?	Record<string, { id: string; _delete: 1 }>	Gift cards applied to this order
type?	DiscountTypeEnum	Type of this item
step?	string	Checkout step this applies to
paymentLine?	PaymentLine | null	The payment method chosen on the order
config?	{ checkoutBusinessType: CheckoutBusinessType; }	Configuration carried with this request or order

UserInfo

Buyer information: every field of Customer is optional here.

Field	Type	Description
id?	string	Unique id of this item
firstName?	string	First name
lastName?	string	Last name
email?	string	Email address
phone?	string | null	Phone number
name?	string	Name of this item
orderCount?	number	Number of orders this customer has placed
customerId?	string	Id of the customer
createAt?	string	When the customer record was created
registeredAt?	string	When the buyer registered
registered?	string	Whether the buyer has a store account
subscribed?	boolean	Whether the buyer is subscribed to marketing email

UserInfoChangeCb

export type UserInfoChangeCb = (d: UserInfo) => void;

UseShippingAsBillingAddressCb

export type UseShippingAsBillingAddressCb = (val: boolean) => void;

ValidateOptions

Field	Type	Description
updateUi?	boolean	Whether the validation result is shown on screen

ValidatePickupResultChangeCb

export type ValidatePickupResultChangeCb = (result: ValidateResult | undefined) => void;

ValidateResult

Field	Type	Description
fieldId	string	Field id
focusId	string	Id of the input to move focus to
id	string	Unique id of this item
message	string	Validation message

ValidateResultChangeCb

export type ValidateResultChangeCb = (fieldId: string, result: ValidateResult | undefined) => void;

ValueInterface

Field	Type	Description
value	string	Value of this item
onBlur?	(val: string) => void	Called when the input loses focus
changeValues	(values: Partial<AddressValues>, config?: ChangeValueConfig) => void	Writes new values into the address form
onValuesChange(cb)	void	Registers a callback for when the field values change
removeValuesChangeCb(cb)	void	Takes a value-change callback off again

VisibleConfig

Field	Type	Description
billing	boolean	Whether the billing address block is shown
virtualProductBilling	boolean	Whether the billing address block for virtual products is shown
billingSelector	boolean	Whether the billing address selector is shown
addressCard	boolean	Whether the address card is shown
deliveryMethod	boolean	Whether the delivery method block is shown
specialInstruction	boolean	Whether the order instructions block is shown
pickupInformation	boolean	Whether the pickup information block is shown
pickupAddress	boolean	Whether the pickup address is shown
expressCheckout	boolean	Whether the express checkout block is shown
delivery	boolean	Whether the delivery block is shown
mobileCoupon	boolean	Whether the mobile coupon block is shown
summaryCoupon	boolean	Whether the coupon block in the order summary is shown
addressBook	boolean	Whether the address book is shown
shippingAddress	boolean	Whether the shipping address block is shown
contactInformation	boolean	Whether the contact information block is shown

VisibleConfigChangeCb

export type VisibleConfigChangeCb = (visibleConfig: VisibleConfig) => void;