# CheckoutAPI reference

> Reference for CheckoutAPI, the object a Shoplazza checkout extension uses to read the order, listen for the buyer's choices changing, and drive the checkout UI.

`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](#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.

```javascript
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. |

:::caution 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](/docs/app/extensions/checkout/extension-recipes#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 | — | <code>AddressValues</code> |
| `getShippingAddressSchema` | Get the schema of the shipping address form; the UI renders the fields from this list | — | <code>ExtendSchema[]</code> |
| `onShippingSchemaChange` | Register a callback for the shipping address schema changing; re-render the form when it fires | <code>cb: AddressChangeCb</code> | `void` |
| `removeShippingSchemaChangeCb` | Remove a shipping address schema change callback | <code>cb: AddressChangeCb</code> | `void` |
| `onShippingAddressChange` | Register a callback for the shipping address values changing | <code>cb: AddressValuesChangeCb</code> | `void` |
| `removeShippingAddressChangeCb` | Remove a shipping address value change callback | <code>cb: AddressValuesChangeCb</code> | `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 | <code>cb: AddressValuesChangeCb</code> | `void` |
| `removeShippingAddressChangeByInput` | Remove a buyer-edit shipping address callback | <code>cb: AddressValuesChangeCb</code> | `void` |
| `validateShippingAddress` | Validate the shipping address; pass ids to validate only those fields | `ids?: string[]`<code>options?: ValidateOptions</code> | <code>Promise&lt;ValidateResult[]&gt;</code> |
| `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 | <code>address: Partial&lt;ShippingAddress&gt;</code> | `void` |
| `getEmailSchema` | Get the schema of the email field | <code>config: ContactSchemaConfig</code> | <code>AddressItemEmailSchema &#124; null</code> |
| `getPhoneSchema` | Get the schema of the phone field | <code>config: ContactSchemaConfig</code> | <code>AddressItemGeneralPhoneSchema &#124; AddressItemStringSchema &#124; null</code> |
| `getEmailOrPhoneSchema` | Get the schema of the combined email-or-phone field | — | <code>AddressItemStringSchema &#124; null</code> |
| `validateContact` | Validate the contact field | <code>options?: ValidateOptions</code> | <code>Promise&lt;ValidateResult &#124; undefined&gt;</code> |
| `getContactSchema` | Get the schema of the contact field, combining getEmailSchema, getPhoneSchema and getEmailOrPhoneSchema | — | <code>AddressItemPhoneSchema &#124; AddressItemStringSchema &#124; AddressItemEmailSchema</code> |
| `registerShippingAddressSchemaSort` | Register a sort callback for the shipping address form, used to reorder its fields | <code>cb: SortSchemaCb</code> | `void` |
| `registerShippingAddressSchemaChangeVisibility` | Register a visibility callback for the optional shipping address fields, used to hide them | <code>cb: SchemaItemVisibilityCb</code> | `void` |
| `registerShippingAddressSchemaChangeLabel` | Register a rewrite callback for the shipping address field labels | <code>cb: SchemaChangeLabelCb</code> | `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 | <code>reason?: AddressExpandReason</code> | `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 | — | <code>ExtendSchema[]</code> |
| `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 | — | <code>ShippingAddress</code> |
| `isFieldShow` | Check whether a field is shown under the current address template | <code>key: keyof AddressValues</code> | `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 | <code>cb: SchemaChangeDisableCB</code> | `void` |
| `registerShippingAddressSchemaChangeValidateRule` | Register extra validation rules for the shipping address form, applied on top of the built-in ones | <code>cb: SchemaChangeValidateRuleCB</code> | `void` |

### Billing address

| Method | Purpose | Parameters | Returns |
|---|---|---|---|
| `getBillingAddress` | Get the billing address | — | <code>AddressValues &#124; ShippingAddress &#124; undefined</code> |
| `getBillingAddressSchema` | Get the schema of the billing address form; the UI renders the fields from this list | — | <code>AddressItemSchema[]</code> |
| `onBillingSchemaChange` | Register a callback for the billing address schema changing; re-render the form when it fires | <code>cb: BillingAddressChangeCb</code> | `void` |
| `removeBillingSchemaChangeCb` | Remove a billing address schema change callback | <code>cb: BillingAddressChangeCb</code> | `void` |
| `validateBillingAddress` | Validate the billing address | — | <code>Promise&lt;ValidateResult[]&gt;</code> |
| `onBillingAddressValuesChange` | Register a callback for the billing address values changing | <code>cb: BillingAddressValuesChangeCb</code> | `void` |
| `removeBillingAddressValuesChange` | Remove a billing address value change callback | <code>cb: BillingAddressValuesChangeCb</code> | `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 | <code>cb: UseShippingAsBillingAddressCb</code> | `void` |
| `removeUseShippingAsBillingAddressChange` | Remove a reuse-shipping-as-billing callback | <code>cb: UseShippingAsBillingAddressCb</code> | `void` |
| `registerBillingAddressSchemaChangeLabel` | Register a rewrite callback for the billing address field labels | <code>cb: SchemaChangeLabelCb</code> | `void` |
| `setBillingAddress` | Set the values of the billing address form | <code>address: AddressValues</code> | `void` |
| `registerBillingAddressSchemaSort` | Register a sort callback for the billing address form, used to reorder the billing fields of non-gift-card products | <code>cb: SortSchemaCb</code> | `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 | <code>cb: AddressBookChangeCbs</code> | `void` |
| `removeAddressBookChangeCb` | Remove an address book change callback | <code>cb: AddressBookChangeCbs</code> | `void` |
| `getAddressBookList` | Get the buyer's saved addresses | — | <code>IAddressBookItem[]</code> |
| `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 | <code>params: GetAddressTemplateParams</code> | <code>AddressTemplate</code> |
| `getAllCountries` | Get every country the platform supports | — | <code>AddressCountry[]</code> |
| `getAvailableCountries` | Get the countries the store has made available | — | <code>AddressCountry[]</code> |
| `getDefaultAddressValues` | Get an empty set of address values, usable as the initial value of a form | — | <code>AddressValues</code> |
| `getSchemaManager` | Create a schema manager for an address form, which builds and validates each field from the current values and the address template | <code>context: AddressSchemaManagerContext</code><code>config: SchemaManagerConfig</code> | <code>AddressSchemaManager</code> |
| `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 | — | <code>LoadingStatus</code> |
| `onLoadingStatusChange` | Register a callback for the loading state changing | <code>cb: OnLoadingStatusChangeCallback</code> | `void` |
| `removeLoadingStatusChangeCb` | Remove a loading state callback | <code>cb: OnLoadingStatusChangeCallback</code> | `void` |
| `setLoadingStatus` | Update the loading state | <code>status: Partial&lt;LoadingStatus&gt;</code> | `void` |
| `getPending` | Get the pending state of each module | — | <code>Pending</code> |
| `onPendingChange` | Register a callback for the pending state changing | <code>pending: OnSubmitPendingChangeCallback</code> | `void` |
| `removePendingChangeCb` | Remove a pending state callback | <code>cb: OnSubmitPendingChangeCallback</code> | `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 | — | <code>Country[]</code> |
| `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` | <code>Country &#124; undefined</code> |
| `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` | <code>InitPhoneResult &#124; null</code> |

### 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 | <code>locales: LocaleMap</code> | `void` |
| `getFullLocale` | Get the full locale tag, for example en-US | — | <code>Locale</code> |

**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.

```javascript
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 | — | <code>VisibleConfig</code> |
| `onVisibleConfigChange` | Register a callback for module visibility changing | <code>cb: VisibleConfigChangeCb</code> | `void` |
| `removeVisibleConfigChangeCb` | Remove a module visibility callback | <code>cb: VisibleConfigChangeCb</code> | `void` |
| `getShowDetails` | The card-collapse configuration provided by the platform | — | <code>ShowDetails</code> |
| `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 | — | <code>CheckoutFeatures</code> |
| `getThemeConfig` | Get the checkout theme configuration | — | <code>CheckoutThemeConfig</code> |
| `getAppConfig` | Get the checkout app configuration | — | <code>CheckoutAppConfig</code> |
| `getMarketConfig` | Get the market configuration | — | <code>MarketInfo</code> |
| `getShopConfig` | Get the store configuration | — | <code>ShopConfig</code> |
| `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 | — | <code>CSettings</code> |
| `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 | <code>cb: ThemeConfigChangeCb</code> | `void` |
| `removeThemeConfigChange` | Remove a theme configuration callback | <code>cb: ThemeConfigChangeCb</code> | `void` |
| `updateThemeConfig` | Update the theme configuration | <code>config: Partial&lt;CheckoutThemeConfig&gt;</code> | `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 | — | <code>CouponData</code> |
| `getSelectedDiscountCoupon` | Get the coupon currently applied | — | <code>DiscountApplication &#124; undefined</code> |
| `getUnavailableCouponData` | Get the coupons that cannot be used on this order | — | <code>CouponData</code> |
| `isShowDiscountCoupon` | Check whether the coupon entry is shown | — | `boolean` |
| `onAvailableCouponDataChange` | Register a callback for the available coupon list changing | <code>cb: CouponListChangeCb</code> | `void` |
| `onCouponChange` | Register a callback for the applied coupon changing | <code>cb: CouponChangeCb</code> | `void` |
| `onUnavailableCouponDataChange` | Register a callback for the unavailable coupon list changing | <code>cb: CouponListChangeCb</code> | `void` |
| `removeAvailableCouponDataChangeCb` | Remove an available coupon list callback | <code>cb: CouponListChangeCb</code> | `void` |
| `removeCouponChangeCb` | Remove an applied coupon callback | <code>cb: CouponChangeCb</code> | `void` |
| `removeUnavailableCouponDataChangeCb` | Remove an unavailable coupon list callback | <code>cb: CouponListChangeCb</code> | `void` |
| `requestCouponList` | Fetch the coupon list for the given availability status | <code>status: CouponAvailStatus</code> | `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`<code>cb: GiftCardTagChange</code> | `void` |
| `getGiftCardTags` | Get the discount code and gift card tags | — | <code>GiftCardTagItem[]</code> |
| `onDiscountChange` | Register a callback for the tag list changing | <code>cb: GiftCardTagsChangeCb</code> | `void` |
| `removeDiscountChangeCb` | Remove a tag list callback | <code>cb: GiftCardTagsChangeCb</code> | `void` |
| `getGiftCards` | Get the gift cards applied to this order | — | <code>GiftCard[]</code> |
| `getDiscountCodes` | Get the discount codes applied to this order | — | <code>DiscountApplication[]</code> |
| `getDiscountApplications` | Get every discount applied to this order, both codes and automatic promotions | — | <code>DiscountApplication[]</code> |
| `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 | <code>parasm: CancelCouponParams</code> | `Promise<any>` |
| `applyDiscount` | Apply one or more discount codes | `codes: string[]` | <code>Promise&lt;PriceResult &#124; undefined&gt;</code> |
| `cancelDiscountCode` | Remove one or more discount codes that have been applied | `codes: string[]` | <code>Promise&lt;PriceResult &#124; undefined&gt;</code> |
| `isCurrentStepShowDiscountCode` | Check whether the discount code and gift card inputs are shown on the current step, per the store's settings | <code>step?: CheckoutStep</code> | `boolean` |
| `registerGiftCardTagsFilter` | Register a filter callback for the gift card and discount code tags, deciding which tags render | <code>cb: GiftCardTagsFilter</code> | `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 | <code>exception?: ExceptNotification</code> | `boolean` |
| `onExceptionChange` | Register a callback for the stored business error changing, fired both when one is stored and when it is cleared | <code>cb: ExceptionChangeCbs</code> | `void` |
| `removeExceptionChangeCb` | Remove a business error callback | <code>cb: ExceptionChangeCbs</code> | `void` |
| `unsetException` | Clear the stored business error | — | `void` |
| `getSubmitErrorInfo` | Get the current submit error | — | <code>SubmitError &#124; undefined</code> |
| `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>code: IExceptionCode &#124; ''</code> | `void` |
| `onSubmitErrorChange` | Register a callback for the submit error changing | <code>cb: SubmitErrorChangeCbs</code> | `void` |
| `removeSubmitErrorChangeCb` | Remove a submit error callback | <code>cb: SubmitErrorChangeCbs</code> | `void` |
| `getExceptionInfo` | Get the stored business error | — | <code>ExceptionInfo</code> |
| `getException` | Get the business error currently stored | — | <code>IException &#124; undefined</code> |
| `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 | <code>point: ExtensionPoint</code>`id?: string` | `string` |
| `getExtensionComponents` | Return the extension component of the point, which carries more than getExtensionContent; an id means the point is dynamic | <code>point: ExtensionPoint</code>`id?: string` | <code>ExtensionComponent[]</code> |
| `getExtensionContent` | Return the extension string of the point, empty when there is none; an id means the point is dynamic | <code>point: ExtensionPoint</code>`id?: string` | `string` |
| `getExtensionList` | Get the list of extensions | — | <code>Extension[]</code> |
| `getPlaceholderContent` | Return the placeholder content of the point, which the UI layer inserts with innerHTML | <code>point: ExtensionPoint</code> | `string` |
| `isHideExtensionTarget` | Whether an extension target is hidden; the UI layer reads it to decide whether to hide that native module | <code>target: ExtensionTarget</code> | `boolean` |
| `onAllExtensionLoaded` | Register a callback for all extensions having finished loading | <code>cb: AllExtensionLoadedCb</code> | `void` |
| `onExtensionLoad` | Register a callback that runs when the extension of a point has finished loading | <code>cb: ExtensionLoadCb</code> | `void` |
| `onHideExtensionTarget` | Register a callback for the result of isHideExtensionTarget changing | <code>cb: HideExtensionTargetCb</code> | `void` |
| `registerExtension` | Register an extension; extension developers call this function to complete the registration | <code>params: RenderParams</code> | `Promise<void>` |
| `removeAllExtensionLoadedCb` | Remove a callback registered for all extensions having finished loading | <code>cb: AllExtensionLoadedCb</code> | `void` |
| `removeHideExtensionTarget` | Remove the callback | <code>cb: HideExtensionTargetCb</code> | `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 | — | <code>DeliveryMethodItem[]</code> |
| `getSelectedDeliveryMethod` | Get the delivery method the buyer has selected | — | <code>DeliveryMethodItem</code> |
| `updateDeliveryMethod` | Switch the selected delivery method and return the recalculated prices | <code>type: CheckoutBusinessType</code> | <code>Promise&lt;PriceResult &#124; undefined&gt;</code> |
| `onDeliveryMethodChange` | Register a callback for the selected delivery method changing | <code>cb: DeliveryMethodChangeCb</code> | `void` |
| `removeDeliveryMethodChangeCb` | Remove a delivery method change callback | <code>cb: DeliveryMethodChangeCb</code> | `void` |
| `onDeliveryMethodListChange` | Register a callback for the delivery method list changing | <code>cb: DeliveryListChangeCb</code> | `void` |
| `removeDeliveryMethodListChange` | Remove a delivery method list callback | <code>cb: DeliveryListChangeCb</code> | `void` |
| `unregisterDeliveryMethodListChange` | Unregister the delivery method list rewrite callback | <code>cb: DeliveryMethodListChangeCb</code> | `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 | <code>cb: DeliveryMethodListChangeCb</code> | `void` |

### Line items

| Method | Purpose | Parameters | Returns |
|---|---|---|---|
| `addLineItems` | Add line items to the current order; the prices are recalculated automatically | <code>params: AddLineItemsInput</code> | <code>Promise&lt;LineMutationResult&gt;</code> |
| `removeLineItems` | Remove line items from the current order; the prices are recalculated automatically | <code>params: RemoveLineItemsInput</code> | <code>Promise&lt;LineMutationResult&gt;</code> |

### 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 | <code>cb: SubmitChangeCb</code> | `void` |
| `removeSubmitChangeCb` | Remove a submittable state callback | <code>cb: SubmitChangeCb</code> | `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 | — | <code>Promise&lt;ValidateResult[] &#124; undefined&gt;</code> |
| `registerBuyerJourneyIntercept` | Register a checkout interception rule: returning block from the callback stops the buyer and opens a dialog, returning allow lets the submission through | <code>cb: BuyerJourneyInterceptCb</code> | `void` |
| `addBeforeSubmitCb` | Add a validation callback that runs before the address is submitted; the platform's own two cover email and address | <code>cb: BeforeSubmitCb</code> | `void` |
| `removeBeforeSubmitCb` | Remove a validation callback that runs before the address is submitted | <code>cb: BeforeSubmitCb</code> | `void` |
| `submitAddressAndShippingLines` | Submit the address together with the selected shipping line | — | <code>Promise&lt;Res&lt;SubmitSuccessData&gt;&gt;</code> |
| `submitShippingLinesAndNavigate` | Submit the shipping line and move to the next step; only the three-step layout uses this | — | <code>Promise&lt;ValidateResult[] &#124; undefined&gt;</code> |
| `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 | — | <code>Promise&lt;ValidateResult[]&gt;</code> |
| `unregisterBuyerJourneyIntercept` | Unregister a checkout interception rule | <code>cb: BuyerJourneyInterceptCb</code> | `void` |

### Tipping

| Method | Purpose | Parameters | Returns |
|---|---|---|---|
| `getTippingOptions` | Get the preset tip options offered on this checkout | — | <code>TippingOption[]</code> |
| `onTippingChange` | Register a callback for the tip changing | <code>cb: TippingChangeCb</code> | `void` |
| `removeTippingChangeCb` | Remove a tip change callback | <code>cb: TippingChangeCb</code> | `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 | — | <code>TippingInfo</code> |

### Shipping lines

| Method | Purpose | Parameters | Returns |
|---|---|---|---|
| `getShippingLines` | Get the shipping lines available for the current address | — | <code>FormatShippingLineType[]</code> |
| `getSelectedShippingLine` | Get the shipping line the buyer has selected, or null when none is selected | — | <code>FormatShippingLineType &#124; null</code> |
| `updateSelectedShippingLine` | Switch the selected shipping line | <code>shippingLine: ShippingLineType</code> | `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 | <code>cb: ShippingChangeCb</code> | `void` |
| `removeShippingChangeCb` | Remove a shipping line change callback | <code>cb: ShippingChangeCb</code> | `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 | — | <code>PromptMessage &#124; null</code> |
| `onShippingPromptMessageChange` | Register a callback for the shipping line prompt changing | <code>cb: ShippingPromptMessageChangeCb</code> | `void` |
| `removeShippingPromptMessageChange` | Remove a shipping line prompt callback | <code>cb: ShippingPromptMessageChangeCb</code> | `void` |
| `dispatchShippingChange` | Manually notify listeners that the shipping line changed | — | `void` |
| `getShippingLinesErrorInfo` | Get the error information of the shipping line list | — | <code>ShippingLinesErrorInfo</code> |
| `getUiShippingLines` | Get the shipping lines the page finally renders, which an extension may have rewritten | — | <code>FormatShippingLineType[]</code> |
| `unregisterUiShippingLinesChange` | Unregister the shipping line list rewrite callback | <code>cb: UiShippingLinesChangeCb</code> | `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 | <code>cb: UiShippingLinesChangeCb</code> | `void` |

### Shipping protection

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

### 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 | <code>cb: IsSpecialInstructionCollapseChange</code> | `void` |
| `removeInstructionCollapseChange` | Remove an order note collapse callback | <code>cb: IsSpecialInstructionCollapseChange</code> | `void` |

### Custom fields

| Method | Purpose | Parameters | Returns |
|---|---|---|---|
| `getOrderCustomFields` | Get the custom business fields saved on the current order. It reads the order data the page already holds and returns straight away without sending a request; an order with no fields returns an empty object | — | `Record<string, string>` |
| `updateOrderCustomFields` | Set or delete the custom business fields on the current order. It only works while the order is still editable: on the thank-you page, on a cancelled order, and before the order exists it fails without sending a request | <code>params: UpdateOrderCustomFieldsInput</code> | <code>Promise&lt;UpdateCustomFieldsResult&gt;</code> |

### 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 | — | <code>CollapseInfo</code> |
| `onCollapseInfoChange` | Register a callback for the filled-in information card changing | <code>cb: CollapseInfoChangeCb</code> | `void` |
| `removeCollapseInfoChangeCb` | Remove a filled-in information card callback | <code>cb: CollapseInfoChangeCb</code> | `void` |

### Order data and price refresh

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

## 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 | — | <code>PaymentUpdateParams['paymentLines']</code> |
| `getSelectedPaymentLine` | Get the payment method the buyer has selected | — | <code>PaymentLine &#124; null &#124; undefined</code> |
| `onAfterPay` | Register a callback that runs after payment completes | <code>cb: AfterPayCb</code> | `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 | <code>cb: PayAttemptCb</code> | `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 | <code>handler: PayFailedHandler</code> | `void` |
| `removePayAttemptCb` | Remove a payment attempt callback | <code>cb: PayAttemptCb</code> | `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 | — | <code>PickupLocation[]</code> |
| `getPickupLocationValidateResult` | Get the validation result for the pickup location | — | <code>ValidateResult &#124; undefined</code> |
| `onPickupLocationValidateResultChange` | Register a callback for the pickup location validation result changing | <code>cb: ValidatePickupResultChangeCb</code> | `void` |
| `removePickupLocationValidateResultChange` | Remove a pickup location validation callback | <code>cb: ValidatePickupResultChangeCb</code> | `void` |
| `validatePickupLocation` | Validate that a pickup location has been chosen | — | <code>Promise&lt;ValidateResult &#124; undefined&gt;</code> |
| `getSelectedPickupLocation` | Get the pickup location the buyer has selected | — | <code>PickupLocation &#124; undefined</code> |
| `updatePickupLocation` | Switch the selected pickup location and return the recalculated prices | <code>location: PickupLocation</code> | <code>Promise&lt;PriceResult &#124; undefined&gt;</code> |
| `onPickupLocationsChange` | Register a callback for the pickup location list changing | <code>cb: PickupLocationsChangeCb</code> | `void` |
| `removePickupLocationsChangeCb` | Remove a pickup location list callback | <code>cb: PickupLocationsChangeCb</code> | `void` |
| `onSelectedPickupLocationChange` | Register a callback for the selected pickup location changing | <code>cb: SelectedPickupLocationChangeCb</code> | `void` |
| `removeSelectedPickupLocationChangeCb` | Remove a selected pickup location callback | <code>cb: SelectedPickupLocationChangeCb</code> | `void` |
| `onPickupInformationChange` | Register a callback for the pickup information changing | <code>cb: PickupInformationChangeCb</code> | `void` |
| `removePickupInformationChangeCb` | Remove a pickup information callback | <code>cb: PickupInformationChangeCb</code> | `void` |
| `getPickupInformationSchema` | Get the schema of the pickup information form | — | <code>AddressItemSchema[]</code> |
| `validatePickupInfo` | Validate the pickup information form | — | <code>Promise&lt;ValidateResult[]&gt;</code> |

## 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 | — | <code>CheckoutStep</code> |
| `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 | <code>type?: EventType</code> | `Promise<void>` |
| `stepNavToShipping` | Navigate to the shipping step | <code>type?: EventType</code> | `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 | — | <code>NavigateLink[]</code> |
| `onNavigateLinksChange` | Register a callback for the step breadcrumb changing | <code>cb: NavigateLinksChangeCb</code> | `void` |
| `removeNavigateLinksChange` | Remove a step breadcrumb callback | <code>cb: NavigateLinksChangeCb</code> | `void` |
| `onStepChange` | Register a callback for the step changing | <code>cb: StepChangeCb</code> | `void` |
| `removeStepChangeCb` | Remove a step change callback | <code>cb: StepChangeCb</code> | `void` |
| `navigateClick` | Navigate to a step the way clicking the breadcrumb does | <code>id: CheckoutStep</code> | `Promise<void>` |
| `couldNavTo` | Whether the breadcrumb can jump to a step. The breadcrumb only goes backwards; moving forward means submitting the current step | <code>id: CheckoutStep</code> | `boolean` |
| `stepNavTo` | Navigate to a given step | <code>id: CheckoutStep</code><code>location?: EventType</code> | `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 | <code>way?: JumpWay[]</code> | `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 | <code>id: CheckoutStep</code> | `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 | <code>cb: PricesChangeCb</code> | `void` |
| `removePricesChangeCb` | Remove a price change callback | <code>cb: PricesChangeCb</code> | `void` |
| `getOrderStatus` | Get the status of the order | — | <code>OrderStatus</code> |
| `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 | <code>cb: OnStoreDataChangeCb</code> | `void` |
| `removeOrderChangeCb` | Remove an order refresh callback | <code>cb: OnStoreDataChangeCb</code> | `void` |
| `getPrices` | Get the prices of the order | — | <code>CheckoutPrices</code> |
| `getOrderInfo` | Get the basic order information | — | <code>OrderInfo</code> |
| `getOrderConfig` | Get the order attributes, such as the checkout layout and the order business type | — | <code>OrderConfig</code> |
| `getBusinessType` | Get the business type of the order | — | <code>CheckoutBusinessType</code> |
| `getCheckoutSettings` | Get the checkout settings of the store | — | <code>CheckoutSettings</code> |
| `getInstructionType` | Get the collapse mode configured for the order note input | — | <code>InstructionType</code> |
| `getCustomerAuthority` | Get who is allowed to place the order; login means only signed-in buyers can | — | <code>CustomerAuthority</code> |
| `setBusinessType` | Set the business type of the order, which the pickup layout uses | <code>type: CheckoutBusinessType</code> | `void` |
| `onBusinessTypeChange` | Register a callback for the order business type changing | <code>cb: CheckoutBusinessTypeChangeCb</code> | `void` |
| `removeBusinessTypeChangeCb` | Remove an order business type callback | <code>cb: CheckoutBusinessTypeChangeCb</code> | `void` |
| `getPageType` | Get the checkout layout, which does not change while the page is open | — | <code>CheckoutPageType</code> |
| `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 | — | <code>ContactType</code> |
| `getAddressSettings` | Get the address form settings | — | <code>CheckoutAddressSettings</code> |
| `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 | — | <code>ReferInfo</code> |
| `getTaxLines` | Get the tax breakdown | — | <code>TaxLines</code> |
| `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 | <code>cb: PageTypeChangeCb</code> | `void` |
| `removePageTypeChange` | Remove a checkout layout callback | <code>cb: PageTypeChangeCb</code> | `void` |
| `setOrderId` | Set the order id | `id: string` | `void` |
| `setPageType` | Set the checkout layout | <code>type: CheckoutPageType</code> | `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 | — | <code>ProductItem[]</code> |
| `onProductListChange` | Register a callback for the line item list changing | <code>cb: ProductListChangeCb</code> | `void` |
| `removeProductListChangeCb` | Remove a line item list callback | <code>cb: ProductListChangeCb</code> | `void` |
| `getPriceList` | Get the grouped price breakdown computed by the platform | — | <code>PriceGroupDetail[]</code> |
| `onPriceListChange` | Register a callback for the price breakdown changing | <code>cb: PriceListChangeCb</code> | `void` |
| `removePriceListChangeCb` | Remove a price breakdown callback | <code>cb: PriceListChangeCb</code> | `void` |
| `getShippingPriceDisplay` | Get the text shown for the shipping cost | — | `string` |
| `onShippingPriceDisplayChange` | Register a callback for the shipping cost text changing | <code>cb: ShippingPriceDisplayChangeCb</code> | `void` |
| `removeShippingPriceDisplayChange` | Remove a shipping cost text callback | <code>cb: ShippingPriceDisplayChangeCb</code> | `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 | <code>cb: UiProductListChangeCb</code> | `void` |
| `getGiftCardPrice` | Get the gift card line of the price breakdown | — | <code>PriceGroupDetail &#124; undefined</code> |
| `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 | — | <code>UIProduct[]</code> |
| `unregisterUiProductListChange` | Unregister the line item list rewrite callback | <code>cb: UiProductListChangeCb</code> | `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 | — | <code>CheckoutOrder</code> |
| `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 | <code>data: TrackAddressFillParams</code> | `void` |
| `trackAddressFormExpand` | Report the address form expand event | <code>reason: AddressExpandReason</code> | `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 | <code>type: TrackGiftCardProps</code>`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 | <code>triggerSource: ShippingMethodsFetchTriggerSource</code> | `void` |
| `trackSubmitAddress` | Report an address submission | <code>options?: TrackSubmitAddressParams</code> | `void` |
| `trackTipping` | Report a tipping event | <code>type: TrackTippingType</code><code>data: TrackTippingData</code> | `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 | — | <code>CheckoutIpAddress</code> |
| `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 | — | <code>UserInfo</code> |
| `getCustomerInfo` | Get the customer information that is submitted with the order | — | <code>CheckoutCustomerInfo</code> |
| `updateCustomerInfo` | Update the customer information that is submitted with the order | <code>data: Partial&lt;CheckoutCustomerInfo&gt;</code> | `void` |
| `onUserInfoChange` | Register a callback for the account information changing | <code>cb: UserInfoChangeCb</code> | `void` |
| `removeUserInfoChangeCb` | Remove an account information callback | <code>cb: UserInfoChangeCb</code> | `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 | — | <code>ContactInformation</code> |
| `onContactInformationChange` | Register a callback for the contact details changing | <code>cb: ContactInformationChangeCb</code> | `void` |
| `removeContactInformationChangeCb` | Remove a contact details callback | <code>cb: ContactInformationChangeCb</code> | `void` |
| `setNewsletter` | Set the marketing email subscription checkbox | <code>val: NewsLetterStatus</code> | `void` |
| `getNewsletter` | Get the marketing email subscription checkbox | — | <code>NewsLetterStatus</code> |

## 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 | <code>content: DialogContent</code><code>options?: DialogOptions</code> | <code>IDialog</code> |
| `createDrawer` | Create a drawer, a panel that slides in from the edge of the screen | <code>content: DrawerContent</code><code>options?: DrawerOptions</code> | <code>IDrawer</code> |

**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.

```javascript
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 {#type-additionalprice}

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

### AdditionalProperty {#type-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 {#type-additionvalues}

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

### AddLineItemsInput {#type-addlineitemsinput}

| Field | Type | Description |
|---|---|---|
| `lineItems` | <code>AddProductInput[]</code> | The line items of the order |
| `mutationSource` | <code>MutationSource</code> | A tag of your own naming what made this change |

### AddProductInput {#type-addproductinput}

| Field | Type | Description |
|---|---|---|
| `variantId` | `string` | Id of the variant |
| `quantity` | `number` | Quantity |
| `properties?` | <code>ProductProperties</code> | Custom properties to put on the new line, as a JSON string |

### AddressBookChangeCbs {#type-addressbookchangecbs}

```typescript
export type AddressBookChangeCbs = () => void;
```

### AddressBookItem {#type-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 {#type-addresschangebyinputcb}

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

### AddressChangeCb {#type-addresschangecb}

```typescript
export type AddressChangeCb = () => void;
```

### AddressCountry {#type-addresscountry}

| Field | Type | Description |
|---|---|---|
| `isoCode2` | `string` | Two-letter country code |
| `name` | `string` | Country name |
| `provinces` | <code>AddressCountryProvince[]</code> | 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?` | <code>AddressFormat</code> | Address format template |

### AddressCountryProvince {#type-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?` | <code>AddressFormat</code> | Format rules of this field |

### AddressExpandReason {#type-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 {#type-addressformat}

| Field | Type | Description |
|---|---|---|
| `fields` | <code>AddressFormatField[]</code> | The fields this template contains |
| `[k: string]` | `any` | Any other key, keyed by name |

### AddressFormatField {#type-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 {#type-addressitemactionschema}

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Unique id of this item |
| `show` | `true` | Whether this item is shown |
| `type` | <code>FieldType.Action</code> | 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 {#type-addressitemcheckoutschema}

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Unique id of this item |
| `type` | <code>FieldType.Checkbox</code> | 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 {#type-addressitememailschema}

| Field | Type | Description |
|---|---|---|
| `type` | <code>FieldType.Email</code> | Field type, always email |

### AddressItemGeneralPhoneSchema {#type-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` | <code>FieldType.Phone</code> | Field type, always the phone type |
| `phoneInfo` | <code>PhoneInfo</code> | 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 {#type-addressitemphoneschema}

Alias of `AddressItemGeneralPhoneSchema`.

```typescript
export type AddressItemPhoneSchema = AddressItemGeneralPhoneSchema;
```

### AddressItemSchema {#type-addressitemschema}

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

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

### AddressItemSelectSchema {#type-addressitemselectschema}

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

### AddressItemStringSchema {#type-addressitemstringschema}

| Field | Type | Description |
|---|---|---|
| `type` | <code>FieldType.String</code> | 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 {#type-addressitemtitleschema}

| Field | Type | Description |
|---|---|---|
| `id` | `string` | Unique id of this item |
| `show` | `true` | Whether this item is shown |
| `type` | <code>FieldType.Title</code> | 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 {#type-addressmanagerconfig}

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

### AddressSchemaManager {#type-addressschemamanager}

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

```typescript
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 {#type-addressschemamanagercontext}

| Field | Type | Description |
|---|---|---|
| `addressValues` | <code>AddressValues</code> | Current values of the address form |
| `addressTemplate` | <code>AddressTemplate</code> | Address template of the current country or region |

### AddressTemplate {#type-addresstemplate}

| Field | Type | Description |
|---|---|---|
| `fields` | <code>AddressTemplateField[]</code> | The address fields this template collects |
| `stringify` | `string` |  |
| `preset` | `string` |  |
| `addressLevel` | `number` | Number of address levels |

### AddressTemplateField {#type-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` | <code>FieldType</code> | Type of this item |
| `label?` | `string` | Label shown above the field |
| `tips?` | `string` | Hint text shown under the field |
| `validate?` | <code>AddressTemplateFieldValidate[]</code> | The validation rules for this field |

### AddressTemplateFieldValidate {#type-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 {#type-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 {#type-addressvalueschangecb}

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

### AddressValuesChangeOptions {#type-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}

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

### AfterPayCb {#type-afterpaycb}

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

### AfterPayParams {#type-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.

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

### AllExtensionLoadedCb {#type-allextensionloadedcb}

```typescript
export type AllExtensionLoadedCb = () => void;
```

### AlreadyPaymentLines {#type-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 {#type-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 {#type-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 {#type-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` | <code>EventBus</code> | 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?` | <code>PlaceType</code> | Which place types the address autocomplete looks for |
| `validateFn(updateUi?)` | <code>Promise&lt;ValidateResult &#124; undefined&gt;</code> | Validates the field's current value |
| `validateByValue?` | <code>(val: string) =&gt; ValidateResult &#124; undefined</code> | Validates a value you pass in, without touching the field |
| `validateResult?` | <code>ValidateResult</code> | 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 {#type-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 {#type-baseresponse}

| Field | Type | Description |
|---|---|---|
| `ok` | `boolean` | Whether the request succeeded |
| `config` | <code>ReqConfig</code> | Configuration carried with this request or order |

### BeforeSubmitCb {#type-beforesubmitcb}

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

### BeforeSubmitCbParams {#type-beforesubmitcbparams}

| Field | Type | Description |
|---|---|---|
| `pageType` | <code>CheckoutPageType</code> | Checkout layout, as a `CheckoutPageType` value |
| `step` | <code>CheckoutStep</code> | Checkout step this applies to |

### BillingAddress {#type-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 {#type-billingaddresschangecb}

```typescript
export type BillingAddressChangeCb = () => void;
```

### BillingAddressValuesChangeCb {#type-billingaddressvalueschangecb}

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

### BuyerJourneyInterceptCb {#type-buyerjourneyinterceptcb}

```typescript
export type BuyerJourneyInterceptCb = () => BuyerJourneyInterceptCbReturn;
```

### BuyerJourneyInterceptCbReturn {#type-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 {#type-cancelcouponparams}

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

### CardInfo {#type-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 {#type-cards}

| Field | Type | Description |
|---|---|---|
| `supportCards` | <code>Array&lt;PlayCardCards&gt;</code> | Card types this payment method accepts |

### ChangedLineItem {#type-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 {#type-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 {#type-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 {#type-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 {#type-checkoutaddresssettings}

| Field | Type | Description |
|---|---|---|
| `name` | <code>NameSetting</code> | Settings for the name field |
| `nameRequirement` | <code>NmeRequirementSetting</code> | Whether the name field is required |
| `contactDetails` | <code>ContactDetailsSetting</code> | Settings for the contact details field |
| `phone` | <code>SimplesSetting</code> | Settings for the phone field |
| `email` | <code>SimplesSetting</code> | Settings for the email field |
| `company` | <code>SimplesSetting</code> | Settings for the company field |
| `address` | <code>SimplesSetting</code> | Settings for the address field |
| `address1` | <code>SimplesSetting</code> | Settings for the second address line field |

### CheckoutAppConfig {#type-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` | <code>MarketInfo</code> | Market information |

### CheckoutBusinessType {#type-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 {#type-checkoutbusinesstypechangecb}

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

### CheckoutCustomerInfo {#type-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 {#type-checkoutfeatures}

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

```typescript
export type CheckoutFeatures = Record<string, boolean>;
```

### checkoutFontfamily {#type-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 {#type-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 {#type-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 {#type-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` | <code>Array&lt;AppliedGiftCard&gt;</code> | Gift cards applied to this order |
| `alreadyPaymentLines` | <code>AlreadyPaymentLines</code> | Payments already made |
| `cancelReason` | `string \| null` | Cancellation reason |
| `currencyCode` | `string` | Currency code |
| `currencySymbol` | `string` | Currency symbol |
| `discountApplications` | <code>Array&lt;DiscountApplication&gt;</code> | Discounts applied to the order |
| `lineItems` | <code>Array&lt;LineItem&gt;</code> | Order line items |
| `shippingAddress` | <code>ShippingAddress</code> | Shipping address |
| `billingAddress` | <code>BillingAddress</code> | Billing address |
| `pickupLocation?` | <code>PickupLocation</code> | 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` | <code>CheckoutPrices</code> | Price breakdown |
| `lineItemDiscountTotal` | `string` | Line item discount total |
| `codeDiscountTotal` | `string` | Discount code total |
| `shippingLine` | <code>ShippingLineType &#124; null</code> | 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` | <code>Customer</code> | Buyer information |
| `referInfo` | <code>ReferInfo</code> | Referrer information |
| `paymentLine?` | <code>PaymentLine</code> | The payment method currently selected |
| `paymentLines` | <code>Array&lt;PaymentLine&gt;</code> | 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?` | <code>AdditionalPrice[]</code> | Additional charges |
| `checkoutPriceList` | <code>PriceGroupDetail[]</code> | Grouped price breakdown |
| `taxLines` | <code>TaxLines</code> | 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` |  |
| `customFields?` | `Record<string, string>` | Custom business fields of the order |

### CheckoutPageType {#type-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 {#type-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?` | <code>AdditionalPrice[]</code> | Additional charges |
| `chargeQuotes?` | <code>ChargeQuote[]</code> | Shipping protection |

### CheckoutSettings {#type-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` | <code>ShippingCpf</code> | CPF field settings used for shipping |
| `zipCheckV2` | `string` |  |
| `zipCheckConfigV2` | `Record<CountryCode, number>` | Postal code check setting per country or region |
| `zipFormatCheck` | <code>SwitchSetting</code> | Whether the postal code format is validated |
| `doorplateFormatCheck` | <code>SwitchSetting</code> | 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` | <code>SwitchSetting</code> | Whether address autocomplete is on |
| `autoCompleteCollapseMode?` | <code>SwitchSetting</code> | Whether the address form collapses after autocomplete fills it |
| `identificationInfo` | <code>&#123; default: IdentificationConfig; &#125;</code> | 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` | <code>AdditionalProperty[]</code> | Extra fields the merchant added |

### CheckoutStep {#type-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 {#type-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` | <code>checkoutFontfamily</code> | Font of the headings |
| `checkoutBodyFontfamily` | <code>checkoutFontfamily</code> | Font of the body text |
| `checkoutButtonFontfamily` | <code>checkoutFontfamily</code> | 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?` | <code>'' &#124; CheckoutMenuPolicyLink</code> | Link target of the first policy menu item |
| `checkoutMenuPolicyLink2?` | <code>'' &#124; CheckoutMenuPolicyLink</code> | Link target of the second policy menu item |
| `checkoutMenuPolicyLink3?` | <code>'' &#124; CheckoutMenuPolicyLink</code> | 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` | <code>Array&lt;&#123; type: string; settings: &#123; checkoutMenuPolicyText: string; checkoutMenuPolicyLink: CheckoutMenuPolicyLink; &#125;; key: string; &#125;&gt;</code> | 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 {#type-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 {#type-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 {#type-collapseinfochangecb}

```typescript
export type CollapseInfoChangeCb = () => void;
```

### CommonAddressValuesChangeCb {#type-commonaddressvalueschangecb}

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

### ContactDetailsSetting {#type-contactdetailssetting}

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

### ContactInformation {#type-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 {#type-contactinformationchangecb}

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

### ContactSchemaConfig {#type-contactschemaconfig}

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

### ContactType {#type-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 {#type-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 {#type-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 {#type-couponchangecb}

```typescript
export type CouponChangeCb = () => void;
```

### CouponData {#type-coupondata}

| Field | Type | Description |
|---|---|---|
| `page` | `number` | Page number |
| `limit` | `number` | Page size |
| `data` | <code>CouponItem[]</code> | The coupons on this page |
| `total` | `number` | Total count |

### CouponItem {#type-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 {#type-couponlistchangecb}

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

### CSettings {#type-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 {#type-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 {#type-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 {#type-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 {#type-deliverylistchangecb}

```typescript
export type DeliveryListChangeCb = () => void;
```

### DeliveryMethodChangeCb {#type-deliverymethodchangecb}

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

### DeliveryMethodItem {#type-deliverymethoditem}

| Field | Type | Description |
|---|---|---|
| `iconType` | `string` | Which icon to use for this delivery method |
| `checkoutBusinessType` | <code>CheckoutBusinessType</code> | The checkout type this delivery method belongs to |
| `text` | `string` | Display text |

### DeliveryMethodListChangeCb {#type-deliverymethodlistchangecb}

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

### DialogContent {#type-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 {#type-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 {#type-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 {#type-discountcodetype}

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

### DiscountTypeEnum {#type-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 {#type-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 {#type-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 {#type-dynamicextensionpoint}

```typescript
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 {#type-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 {#type-eventtype}

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

### ExceptionChangeCbs {#type-exceptionchangecbs}

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

### ExceptionInfo {#type-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?` | <code>Array&lt;InvalidLineItem&gt;</code> | Line items that are no longer valid |
| `changedLineItems?` | <code>Array&lt;ChangedLineItem&gt;</code> | Line items that changed |

### ExceptNotification {#type-exceptnotification}

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

### ExtendSchema {#type-extendschema}

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

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

### Extension {#type-extension}

| Field | Type | Description |
|---|---|---|
| `components` | <code>ExtensionComponent[]</code> | 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 {#type-extensioncomponent}

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

### ExtensionList {#type-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 {#type-extensionloadcb}

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

### ExtensionPoint {#type-extensionpoint}

```typescript
export type ExtensionPoint = StaticExtensionPoint | DynamicExtensionPoint;
```

### ExtensionTarget {#type-extensiontarget}

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

### FailPriceResult {#type-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 {#type-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 {#type-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 {#type-fieldschangecb}

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

### FieldType {#type-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 {#type-fieldvalidate}

```typescript
export type FieldValidate = FieldRegExpValidate | FieldFnValidate;
```

### FormatShippingLineType {#type-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 {#type-getaddresstemplateparams}

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

### GiftCard {#type-giftcard}

| Field | Type | Description |
|---|---|---|
| `type` | <code>DiscountCodeType</code> | 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 {#type-giftcardtagchange}

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

### GiftCardTagItem {#type-giftcardtagitem}

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

### GiftCardTagsChangeCb {#type-giftcardtagschangecb}

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

### GiftCardTagsFilter {#type-giftcardtagsfilter}

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

### HideExtensionTargetCb {#type-hideextensiontargetcb}

```typescript
export type HideExtensionTargetCb = () => void;
```

### HttpCompleteResponse {#type-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 {#type-httpfailresponse}

| Field | Type | Description |
|---|---|---|
| `ok` | `false` | Whether the request succeeded |

### HttpSuccessResponse {#type-httpsuccessresponse}

| Field | Type | Description |
|---|---|---|
| `ok` | `true` | Whether the request succeeded |

### IAddressBookItem {#type-iaddressbookitem}

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

### IdentificationConfig {#type-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 {#type-idialog}

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

### IDrawer {#type-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 {#type-iexception}

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

### IExceptionCode {#type-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 {#type-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 {#type-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 {#type-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 {#type-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 {#type-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 {#type-isspecialinstructioncollapsechange}

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

### JumpWay {#type-jumpway}

| Value | Description |
|---|---|
| `'a'` | Follow an `&lt;a&gt;` 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 {#type-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 {#type-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` | <code>Array&lt;DiscountApplication&gt;</code> | 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 {#type-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 {#type-linemutationresult}

| Field | Type | Description |
|---|---|---|
| `state` | `'success' \| string` | State of the result, `success` when it worked |
| `data?` | <code>LineMutationResultData</code> | Payload of the result |
| `code?` | <code>LineMutationErrorCode &#124; string</code> | Error code when the change failed |
| `message?` | `string` | Error message |

### LineMutationResultData {#type-linemutationresultdata}

| Field | Type | Description |
|---|---|---|
| `orderId` | `string` | Id of the order |
| `lineItems` | <code>LineItem[]</code> | 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 {#type-loadingstatus}

| Field | Type | Description |
|---|---|---|
| `globalLoading` | `boolean` | Whether the whole page is loading |

### Locale {#type-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 {#type-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 {#type-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 {#type-marketinfo}

| Field | Type | Description |
|---|---|---|
| `marketId` | `string` | Market id |
| `marketPriceSetting` | <code>MarketPriceSetting</code> | Price settings for this market |

### MarketPriceSetting {#type-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 -&gt; market base currency |
| `rate` | `number` | Automatic rate, primary market currency -&gt; market base or local currency |
| `back_rate` | `number` | Reverse automatic rate, market base or local currency -&gt; primary market currency |
| `actual_rate` | `number` | The rate actually applied, primary market currency -&gt; market base or local currency |
| `base_to_local` | `number` | Market base currency -&gt; local currency |
| `local_to_base` | `number` | Local currency -&gt; market base currency |
| `adjust` | `number` | Price adjustment |
| `price_round_enabled` | `true` | Whether converted prices are rounded |

### MenuPolicyConfig {#type-menupolicyconfig}

| Field | Type | Description |
|---|---|---|
| `checkoutMenuPolicyLink1?` | <code>'' &#124; CheckoutMenuPolicyLink</code> | Link target of the first policy menu item |
| `checkoutMenuPolicyLink2?` | <code>'' &#124; CheckoutMenuPolicyLink</code> | Link target of the second policy menu item |
| `checkoutMenuPolicyLink3?` | <code>'' &#124; CheckoutMenuPolicyLink</code> | 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` | <code>Array&lt;&#123; type: string; settings: &#123; checkoutMenuPolicyText: string; checkoutMenuPolicyLink: CheckoutMenuPolicyLink; &#125;; key: string; &#125;&gt;</code> | The current data format; the six fields above are the older one. When both are present, blocks wins |

### MutationSource {#type-mutationsource}

```typescript
export type MutationSource = string;
```

### NameSetting {#type-namesetting}

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

### NavigateLink {#type-navigatelink}

| Field | Type | Description |
|---|---|---|
| `id` | <code>CheckoutStep</code> | The checkout step this link points to |
| `title` | `'information' \| 'shipping' \| 'payment'` | Used for analytics |
| `text` | `string` | Link text |

### NavigateLinksChangeCb {#type-navigatelinkschangecb}

```typescript
export type NavigateLinksChangeCb = () => void;
```

### NewsLetterStatus {#type-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 {#type-nextaction}

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

### NmeRequirementSetting {#type-nmerequirementsetting}

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

### OnCloseCb {#type-onclosecb}

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

### OnLoadingStatusChangeCallback {#type-onloadingstatuschangecallback}

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

### OnPayFailedPayload {#type-onpayfailedpayload}

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

### OnPayFailedResult {#type-onpayfailedresult}

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

### OnStoreDataChangeCb {#type-onstoredatachangecb}

```typescript
export type OnStoreDataChangeCb = () => void;
```

### OnSubmitPendingChangeCallback {#type-onsubmitpendingchangecallback}

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

### OptionValue {#type-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 {#type-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 {#type-orderinfo}

| Field | Type | Description |
|---|---|---|
| `currencyCode` | `string` | Checkout currency, for example USD |
| `currencySymbol` | `string` | Currency symbol, for example $ |
| `alreadyPaymentLines` | <code>AlreadyPaymentLines</code> | Payments already made |
| `failCode` | `string \| null` | Failure code, empty when nothing failed |
| `id` | `string` | Order id |
| `status` | <code>OrderStatus</code> | 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?` | <code>AdditionalPrice[]</code> | Additional charges |
| `customFields?` | `Record<string, string>` | Custom business fields of the order |

### OrderResult {#type-orderresult}

| Field | Type | Description |
|---|---|---|
| `data?` | <code>OrderResultData</code> | Payload of the response |
| `state` | `string` | State of the result, `success` when it worked |
| `errors` | `string[]` | Error messages |

### OrderResultData {#type-orderresultdata}

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

### OrderStatus {#type-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 {#type-pagetypechangecb}

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

### PayAttemptCb {#type-payattemptcb}

```typescript
export type PayAttemptCb = () => void;
```

### PayFailedHandler {#type-payfailedhandler}

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

### PaymentIconResource {#type-paymenticonresource}

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

### PaymentLine {#type-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 {#type-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 {#type-paymentresources}

| Field | Type | Description |
|---|---|---|
| `[key: string]` | <code>Cards</code> | Any other key, keyed by name |

### PaymentSettings {#type-paymentsettings}

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

### PaymentUpdateParams {#type-paymentupdateparams}

| Field | Type | Description |
|---|---|---|
| `paymentLine` | <code>PaymentLine</code> | The payment method currently selected |
| `paymentLines` | <code>Array&lt;PaymentLine&gt;</code> | 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` | <code>Partial&lt;CardInfo&gt;</code> | Card information |
| `source?` | <code>PaymentLinesSource</code> | What triggered this payment update, as a `PaymentLinesSource` value |
| `paymentFeatures?` | `{ useCustomPaymentButton: boolean; useBillingAddress: boolean; }` | Which payment features this method needs |

### PayResponse {#type-payresponse}

```typescript
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 {#type-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 {#type-phoneinfo}

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

### PickupInformationChangeCb {#type-pickupinformationchangecb}

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

### PickupLocation {#type-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?` | <code>DayConfigOfPickupTime[]</code> | 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 {#type-pickuplocationschangecb}

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

### PlaceType {#type-placetype}

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

### PlayCardCards {#type-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 {#type-pluginconfig}

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

### PriceDetail {#type-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?` | <code>SubPriceDetail[]</code> | Sub-rows under this row |
| `id` | `string` | Unique id of this item |

### PriceGroupDetail {#type-pricegroupdetail}

| Field | Type | Description |
|---|---|---|
| `key` | <code>PriceGroupDetailKey</code> | Group key |
| `list?` | <code>PriceDetail[]</code> | Price entries in this group |
| `desc?` | `string` | Description |
| `descLangId?` | `string` | Translation key of the description |

### PriceGroupDetailKey {#type-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 {#type-pricelistchangecb}

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

### PriceParams {#type-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?` | <code>DiscountTypeEnum</code> | Kind of discount being applied, as a `DiscountTypeEnum` value |
| `step?` | `string` | Checkout step this applies to |
| `paymentLine?` | <code>PaymentLine &#124; null</code> | The payment method chosen on the order |
| `config` | <code>&#123; checkoutBusinessType: CheckoutBusinessType; &#125;</code> | Configuration carried with this request or order |

### PriceResult {#type-priceresult}

```typescript
export type PriceResult = SuccessPriceResult | FailPriceResult;
```

### PriceResultData {#type-priceresultdata}

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

### PricesChangeCb {#type-priceschangecb}

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

### ProductItem {#type-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` | <code>Array&lt;DiscountApplication&gt;</code> | 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 {#type-productlistchangecb}

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

### ProductProperties {#type-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 {#type-promptmessage}

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

### ReferInfo {#type-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 {#type-removelineitemsinput}

| Field | Type | Description |
|---|---|---|
| `lineItemIds` | `string[]` | Ids of the line items to act on |
| `mutationSource` | <code>MutationSource</code> | A tag of your own naming what made this change |

### RenderParams {#type-renderparams}

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

### ReqConfig {#type-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 {#type-res}

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

### SaleTaxLine {#type-saletaxline}

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

### SchemaChangeDisableCB {#type-schemachangedisablecb}

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

### SchemaChangeLabelCb {#type-schemachangelabelcb}

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

### SchemaChangeValidateRule {#type-schemachangevalidaterule}

| Field | Type | Description |
|---|---|---|
| `[k: string]` | <code>SchemaChangeValidateRuleValue</code> | Any other key, keyed by name |

### SchemaChangeValidateRuleCB {#type-schemachangevalidaterulecb}

```typescript
export type SchemaChangeValidateRuleCB = () => SchemaChangeValidateRule;
```

### SchemaChangeValidateRuleValue {#type-schemachangevalidaterulevalue}

| Field | Type | Description |
|---|---|---|
| `required` | `true` | Whether the buyer must fill this in |
| `validates` | <code>FieldValidate[]</code> | The validation rules that apply |

### SchemaItemVisibilityCb {#type-schemaitemvisibilitycb}

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

### SchemaManagerConfig {#type-schemamanagerconfig}

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

### SchemaManagerConfigFn {#type-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?` | <code>() =&gt; SchemaChangeValidateRule</code> | 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 {#type-selectedpickuplocationchangecb}

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

### SelectType {#type-selecttype}

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

### ShippingAddress {#type-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` | <code>&#123; cpf?: string; taxText?: string; idNumber?: string; idNumberText?: string; addition?: AdditionValues; shortAddress?: string; &#125;</code> | 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 {#type-shippingchangecb}

```typescript
export type ShippingChangeCb = () => void;
```

### ShippingCpf {#type-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` | <code>isShowCountries</code> | Countries or regions the CPF field is shown in |

### ShippingLinesErrorInfo {#type-shippinglineserrorinfo}

| Field | Type | Description |
|---|---|---|
| `message?` | `string` | Error message |

### ShippingLineType {#type-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 {#type-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 {#type-shippingpricedisplaychangecb}

```typescript
export type ShippingPriceDisplayChangeCb = () => void;
```

### ShippingPromptMessageChangeCb {#type-shippingpromptmessagechangecb}

```typescript
export type ShippingPromptMessageChangeCb = () => void;
```

### ShippingProtectionChangeCb {#type-shippingprotectionchangecb}

```typescript
export type ShippingProtectionChangeCb = () => void;
```

### ShopConfig {#type-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 {#type-showdetails}

| Field | Type | Description |
|---|---|---|
| `isAddressAvailable?` | `boolean` | Whether the address is usable |

### SimplesSetting {#type-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 {#type-sortschemacb}

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

### SortSchemaItem {#type-sortschemaitem}

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

### StaticExtensionPoint {#type-staticextensionpoint}

```typescript
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 {#type-stepchangecb}

```typescript
export type StepChangeCb = () => void;
```

### SubmitChangeCb {#type-submitchangecb}

```typescript
export type SubmitChangeCb = () => void;
```

### SubmitError {#type-submiterror}

| Field | Type | Description |
|---|---|---|
| `code` | `string` | Error code |
| `message` | `string` | Error message |

### SubmitErrorChangeCbs {#type-submiterrorchangecbs}

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

### SubmitSuccessData {#type-submitsuccessdata}

| Field | Type | Description |
|---|---|---|
| `data?` | <code>&#123; exceptNotification: ExceptNotification; result: Record&lt;string, any&gt;; &#125;</code> | Payload of the result |
| `state` | `string` | State of the result, `success` when it worked |
| `errors` | `string[]` | Error messages |

### SubPriceDetail {#type-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 {#type-successpriceresult}

| Field | Type | Description |
|---|---|---|
| `data` | <code>PriceResultData</code> | Payload of the result |
| `message` | `string` | Message text |
| `state` | `'success'` | State of the result, `success` when it worked |

### Suggestion {#type-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 {#type-suggestionchangecb}

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

### SuggestionSchema {#type-suggestionschema}

| Field | Type | Description |
|---|---|---|
| `suggestions?` | <code>Array&lt;Suggestion&gt;</code> | 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 {#type-suggestionsearchstatus}

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

### SwitchSetting {#type-switchsetting}

| Value | Description |
|---|---|
| `'disabled'` | Off |
| `'enabled'` | On |

### SwitchShippingProtectionResult {#type-switchshippingprotectionresult}

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

### TaxLines {#type-taxlines}

| Field | Type | Description |
|---|---|---|
| `salesTaxLines?` | <code>SaleTaxLine[]</code> | Sales tax breakdown |

### ThemeConfigChangeCb {#type-themeconfigchangecb}

```typescript
export type ThemeConfigChangeCb = () => void;
```

### ThemeStyleConfig {#type-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` | <code>checkoutFontfamily</code> | Font of the headings |
| `checkoutBodyFontfamily` | <code>checkoutFontfamily</code> | Font of the body text |
| `checkoutButtonFontfamily` | <code>checkoutFontfamily</code> | 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 {#type-thirdpartyerrordetails}

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

### TippingChangeCb {#type-tippingchangecb}

```typescript
export type TippingChangeCb = () => void;
```

### TippingInfo {#type-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 {#type-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 {#type-tipschema}

| Field | Type | Description |
|---|---|---|
| `tip?` | `string` | Tip amount |
| `tipChangeEvent?` | `string` |  |

### TrackAddressFillParams {#type-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` | <code>Partial&lt;AddressBookItem&gt;</code> | Payload of the result |
| `fillType` | `number` |  |

### TrackGiftCardProps {#type-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 {#type-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 {#type-tracktippingdata}

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

### TrackTippingType {#type-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 {#type-uiproduct}

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

### UiProductListChangeCb {#type-uiproductlistchangecb}

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

### UiShippingLinesChangeCb {#type-uishippinglineschangecb}

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

### UpdateContextCb {#type-updatecontextcb}

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

### UpdateCustomFieldsResult {#type-updatecustomfieldsresult}

| Field | Type | Description |
|---|---|---|
| `state` | `'success' \| string` | State of the result, `success` when it worked; the method never throws, so read this instead of catching |
| `message?` | `string` | Error message when the change failed, for example both parameters being empty, the order not being editable, or the fields exceeding the total length limit |

### UpdateDataByOrderAndPriceApiResult {#type-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?` | <code>PriceResult</code> | Amount of this row |
| `order?` | <code>OrderResult</code> | The order itself |

### UpdateDataByPriceApiParams {#type-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?` | <code>DiscountTypeEnum</code> | Type of this item |
| `step?` | `string` | Checkout step this applies to |
| `paymentLine?` | <code>PaymentLine &#124; null</code> | The payment method chosen on the order |
| `config?` | <code>&#123; checkoutBusinessType: CheckoutBusinessType; &#125;</code> | Configuration carried with this request or order |

### UpdateOrderCustomFieldsInput {#type-updateordercustomfieldsinput}

| Field | Type | Description |
|---|---|---|
| `customFields?` | `Record<string, string>` | Fields to set, merged into the fields already on the order so the ones not mentioned are left alone; a key that is already there is overwritten. A key may be neither empty nor `*`. Values are strings only: pass objects and arrays through `JSON.stringify` yourself |
| `deleteCustomFields?` | `string[]` | Keys to delete; `['*']` deletes every field |

### UserInfo {#type-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 {#type-userinfochangecb}

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

### UseShippingAsBillingAddressCb {#type-useshippingasbillingaddresscb}

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

### ValidateOptions {#type-validateoptions}

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

### ValidatePickupResultChangeCb {#type-validatepickupresultchangecb}

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

### ValidateResult {#type-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 {#type-validateresultchangecb}

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

### ValueInterface {#type-valueinterface}

| Field | Type | Description |
|---|---|---|
| `value` | `string` | Value of this item |
| `onBlur?` | `(val: string) => void` | Called when the input loses focus |
| `changeValues` | <code>(values: Partial&lt;AddressValues&gt;, config?: ChangeValueConfig) =&gt; void</code> | 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 {#type-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 {#type-visibleconfigchangecb}

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