@boldcommerce/checkout-frontend-library

Checkout Frontend Library

Description

The Checkout Frontend Library is a Bold Javascript library, which contains reusable methods to help accomplish the following:

• Call Bold's Headless Checkout APIs
• Control request retry
• Communicate to the PIGI API
• Get useful types and constants to avoid defining interfaces

Installation

Install with Yarn

yarn add "@boldcommerce/checkout-frontend-library"

Install a specific version

yarn add "@boldcommerce/checkout-frontend-library"@1.0.0

(replace "1.0.0" with the version number that you want)

Install with NPM

npm install "@boldcommerce/checkout-frontend-library"

Install a specific version

npm install "@boldcommerce/checkout-frontend-library"@1.0.0

(replace "1.0.0" with the version number that you want)

Methods Reference

Initialize

---

Initialize library

▸ initialize(initData, shopIdentifier, environment): Promise <IApiReturnObject>

Initialize the library with order data and environment variables. The library needs to be initialized with required data before using any other functionality.

 const response: IApiReturnObject = await initialize(initData, shopIdentifier, environment);

Parameters

Parameter	Type	Description
initData	IInitializeOrderResponse	The order data obtain from Initialize Order endpoint.
shopIdentifier	string	The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.
environment	IEnvironment	Defined the bold API environment.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Address

---

Set Shipping Address

▸ setShippingAddress(shippingAddress, numOfRetries?): Promise <IApiReturnObject>

Set the shipping address on the order. If a shipping address already exists, the existing address is overwritten.

 const response: IApiReturnObject = await setShippingAddress(_shipping, API_RETRY);

Parameters

Parameter	Type	Description
shippingAddress	IAddress	The shipping address details.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Update Shipping Address

▸ updateShippingAddress(shippingAddress, numOfRetries?): Promise <IApiReturnObject>

Updates the shipping address on the order.

 const response: IApiReturnObject = await updateShippingAddress(_shipping, API_RETRY);

Parameters

Parameter	Type	Description
shippingAddress	IAddress	The shipping address details.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Delete Shipping Address

▸ deleteShippingAddress(numOfRetries?): Promise <IApiReturnObject>

Deletes the shipping address from the order.

 const response: IApiReturnObject = await deleteShippingAddress(API_RETRY);

Parameters

Parameter	Type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Set Billing Address

▸ setBillingAddress(billingAddress, numOfRetries?): Promise <IApiReturnObject>

Set the billing address on the order. If a billing address already exists, the existing address is overwritten.

 const response: IApiReturnObject = await setBillingAddress(_billing, API_RETRY);

Parameters:

Parameter	Type	Description
billingAddress	IAddress	The billing address details.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Update Billing Address

▸ updateBillingAddress(billingAddress, numOfRetries?): Promise <IApiReturnObject>

Updates the billing address on the order.

 const response: IApiReturnObject = await updateBillingAddress(_billing, API_RETRY);

Parameters

Parameter	Type	Description
billingAddress	IAddress	The billing address details.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Delete Billing Address

▸ deleteBillingAddress(numOfRetries?): Promise <IApiReturnObject>

Deletes the billing address from the order.

 const response: IApiReturnObject = await deleteBillingAddress(API_RETRY);

Parameters

Parameter	Type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Customer

---

Add Guest customer

▸ addGuestCustomer(firstName, lastName, email, acceptsMarketing?, numOfRetries?): Promise <IApiReturnObject>

Adds the guest customer details to the order. This method returns an error if a customer already exists on the order.

 const response: IApiReturnObject = await addGuestCustomer(first_name, last_name, email_address, accepts_marketing, API_RETRY);

Parameters

Parameter	Type	Description
firstName	string	The customer's first name.
lastName	string	The customer's last name.
email	string	The customer's email address.
acceptsMarketing?	boolean	If the customer would like to receive any sort of marketing emails. The default value is false.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Delete customer

▸ deleteCustomer(numOfRetries?): Promise <IApiReturnObject>

Deletes the customer from the order.

 const response: IApiReturnObject = await deleteCustomer(API_RETRY);

Parameters

Parameter	Type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Update customer

▸ updateCustomer(firstName, lastName, email, acceptsMarketing, numOfRetries?): Promise <IApiReturnObject>

Updates the customer on the order.

 const response: IApiReturnObject = await updateCustomer(first_name, last_name, email_address, accepts_marketing, API_RETRY);

Parameters

Parameter	Type	Description
firstName	string	The customer's first name.
lastName	string	The customer's last name.
email	string	The customer's email address.
acceptsMarketing	boolean	If the customer would like to receive any sort of marketing emails.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Validate customer email address

▸ validateEmail(email, numOfRetries?): Promise <IApiReturnObject>

Validates the customer email address.

 const response: IApiReturnObject = await validateEmail(email_address, API_RETRY);

Parameters

Parameter	Type	Description
email	string	The customer's email address.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Discounts

---

Add Discount Code

▸ addDiscount(code,numOfRetries?): Promise <IApiReturnObject>

Adds discount code to the order.

 const response: IApiReturnObject = await addDiscount(code, API_RETRY);

Parameters

Parameter	type	Description
code	string	The discount code.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Delete Discount Code

▸ deleteDiscount(code,numOfRetries?): Promise <IApiReturnObject>

Deletes a discount code from the order.

 const response: IApiReturnObject = await deleteDiscount(code, API_RETRY);

Parameters

Parameter	type	Description
code	string	The discount code.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Validate Discount Code

▸ validateDiscount(code,numOfRetries?): Promise <IApiReturnObject>

Validates the given discount code against the current order state. This method does not add discount code to the order.

 const response: IApiReturnObject = await validateDiscount(code, API_RETRY);

Parameters

Parameter	type	Description
code	string	The discount code.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Items

---

Update Line Item Quantity

▸ updateLineItemQuantity(lineItemKey, quantity ,numOfRetries?): Promise <IApiReturnObject>

Updates the quantity of a line item on the order.

 const response: IApiReturnObject = await updateLineItemQuantity(lineItemKey, quantity, API_RETRY);

Parameters

Parameter	type	Description
lineItemKey	string	The unique key to identify the line item.
quantity	number	The updated quantity.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Shipping Lines

---

Change Shipping Line

▸ changeShippingLine(index ,numOfRetries?): Promise <IApiReturnObject>

Adds or updates the shipping line on the order.

 const response: IApiReturnObject = await changeShippingLine(index, API_RETRY);

Parameters

Parameter	type	Description
index	string	The index of a shipping line, selected from available shipping lines. The available shipping lines can be retrieved from the get shipping line method.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Get Shipping Lines

▸ getShippingLines(numOfRetries?): Promise <IApiReturnObject>

Get all the available shipping lines.

 const response: IApiReturnObject = await getShippingLines(API_RETRY);

Parameters

Parameter	type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Taxes

---

Set Taxes

▸ setTaxes(numOfRetries?): Promise <IApiReturnObject>

Calculates and applies taxes to the order. Taxes are not automatically recalculated, so you must call this method after you make any changes to the shipping address.

 const response: IApiReturnObject = await setTaxes(API_RETRY);

Parameters

Parameter	type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Order

---

Check Inventory

▸ checkInventory(stage,numOfRetries?): Promise <IApiReturnObject>

Performs an inventory check on the items of the order.

 const response: IApiReturnObject = await checkInventory(stage, API_RETRY);

Parameters

Parameter	type	Description
stage	IInventoryStage	A enum of initial or final. For most use cases, the value should be initial to indicate that the order has not been processed.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Process Order

▸ processOrder(numOfRetries?): Promise <IApiReturnObject>

Processes the order.

 const response: IApiReturnObject = await processOrder(API_RETRY);

Parameters

Parameter	type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Get Application State

▸ getRefreshedApplicationState(numOfRetries?): Promise <IApiReturnObject>

Gets a refreshed copy of the application state.

 const response: IApiReturnObject = await getRefreshedApplicationState(API_RETRY);

Parameters

Parameter	type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Payment

---

Add Payment

▸ addPayment(payment,numOfRetries?): Promise <IApiReturnObject>

Adds a new payment to the order.

 const response: IApiReturnObject = await addPayment(payment, API_RETRY);

Parameters

Parameter	type	Description
payment	IAddPaymentRequest	The payment details. gateway_public_id and token fields are mandatory for adding a new payment.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Delete Payment

▸ deletePayment(payment,numOfRetries?): Promise <IApiReturnObject>

Removes the payment by token.

 const response: IApiReturnObject = await deletePayment(payment, API_RETRY);

Parameters

Parameter	type	Description
payment	IAddPaymentRequest	The payment details. gateway_public_id and token fields are mandatory for adding a new payment.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Update Payment

▸ updatePayment(payment,numOfRetries?): Promise <IApiReturnObject>

Updates the value of the payment. Only the amount of payment can be changed.

 const response: IApiReturnObject = await updatePayment(payment, API_RETRY);

Parameters

Parameter	type	Description
payment	IAddPaymentRequest	The payment details. gateway_public_id and token fields are mandatory for adding a new payment.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

List Payments

▸ getPaymentList(numOfRetries?): Promise <IApiReturnObject>

Lists the payments that have been applied to the order.

 const response: IApiReturnObject = await getPaymentList(API_RETRY);

Parameters

Parameter	type	Description
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

Remove Gift Card

▸ deleteGiftCardPayment(id,numOfRetries?): Promise <IApiReturnObject>

Removes a gift card payment by id.

 const response: IApiReturnObject = await getPaymentList(API_RETRY);

Parameters

Parameter	type	Description
id	string	The ID of the gift card payment.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

Payment Iframe

---

Get Payment Iframe

▸ getPaymentIframeUrl(): Promise <IApiReturnObject>

Retrieve the Payment Isolation Gateway Interface (PIGI) url.

 const response: IApiReturnObject = await getPaymentIframeUrl();

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

---

CSS Styling for PIGI

▸ cssStylingPaymentIframe(body,numOfRetries?): Promise <IApiReturnObject>

Styles the Payment Isolation Gateway Interface (PIGI) using CSS and media queries.

 const response: IApiReturnObject = await cssStylingPaymentIframe(body, API_RETRY);

Parameters

Parameter	type	Description
body	ICssStylingPaymentIframeRequest	The css and media rules that need to be applied to PIGI Iframe.
numOfRetries?	number	The number of times to retry the API in case of a 408, 429, 503, 504, or 544 error. The default is 0.

Returns

Promise<IApiReturnObject>

A promise that resolves the API response.

PIGI Actions

---

Set PIGI Listener

▸ setPigiListener(iFrameId, callback): void

Sets the callback function that will receive all action responses from PIGI. The callback function is executed when the parent receives any response from PIGI. You can also implement PIGI event driven responses in the callback function.

const handlePigiMessage = (e) => {
    const {responseType, payload} = e.data as IPigiResponseData;
    // Implement all action responses by responseType
}

setPigiListener(IframeId, handlePigiMessage);

Parameters

Parameter	type	Description
iFrameId	string	The unique identifier for the PIGI Iframe.
callback	EventListenerOrEventListenerObject	The callback function to call when PIGI responses are received.

---

Add Payment Action

▸ sendAddPaymentAction(): IApiReturnObject
▸ sendAddPaymentActionAsync(): Promise <IPigiResponseType>

The Add payment PIGI action requests that PIGI adds the payment token to the order after customer enters the payment information.

 const response: IApiReturnObject = sendAddPaymentAction();
 const responseAsync: IPigiResponseType = await sendAddPaymentActionAsync();

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

Clear PIGI Error Action

▸ sendClearErrorMessageAction(): IApiReturnObject
▸ sendClearErrorMessageActionAsync(): Promise <IPigiResponseType>

The Clear PIGI error action removes all errors from the PIGI user interface.

 const response: IApiReturnObject = sendClearErrorMessageAction();
 const responseAsync: IPigiResponseType = await sendClearErrorMessageActionAsync();

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

Display Error Message

▸ sendDisplayErrorMessageAction(message, subType): IApiReturnObject
▸ sendDisplayErrorMessageActionAsync(message, subType): Promise <IPigiResponseType>

The Display error message action displays an error message in the PIGI user interface.

 const response: IApiReturnObject = sendDisplayErrorMessageAction(message, subType);
 const responseAsync: IPigiResponseType = await sendDisplayErrorMessageActionAsync(message, subType);

Parameters

Parameter	type	Description
message	string	The error message to display in PIGI.
subType	string	The type of error, corresponds to payment gateway name.

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

Handle SCA Action

▸ sendHandleScaAction(clientSecretToken?): IApiReturnObject
▸ sendHandleScaActionAsync(clientSecretToken?): Promise <IPigiResponseType>

The Handle SCA action requests that PIGI handles SCA/3DS.

 const response: IApiReturnObject = sendHandleScaAction(clientSecretToken);
 const responseAsync: IApiReturnObject = await sendHandleScaAction(clientSecretToken);

Parameters

Parameter	type	Description
clientSecretToken?	string	The secret token from payment gateway.

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

Refresh Order Action

▸ sendRefreshOrderAction(): IApiReturnObject
▸ sendRefreshOrderActionAsync(): Promise <IPigiResponseType>

The Refresh Order action updates the order state in PIGI.

 const response: IApiReturnObject = sendRefreshOrderAction();
 const responseAsync: IPigiResponseType = await sendRefreshOrderActionAsync();

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

Select Payment Action

▸ sendSelectPaymentMethodAction(payload): IApiReturnObject
▸ sendSelectPaymentMethodActionAsync(payload): Promise <IPigiResponseType>

The Select Payment Method action selects the customer's choice of payment.

 const response: IApiReturnObject = sendSelectPaymentMethodAction(payload);
 const responseAsync: IPigiResponseType = await sendSelectPaymentMethodActionAsync(payload);

Parameters

Parameter	type	Description
payload	{index?: number, gatewayName?: string}	Provide an object with either the index or gatewayName. If both are used, PIGI uses index.

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

Update Language Action

▸ sendUpdateLanguageAction(languageCode): IApiReturnObject
▸ sendUpdateLanguageActionAsync(languageCode): Promise <IPigiResponseType>

The Update Language action changes the display language of PIGI.

 const response: IApiReturnObject = sendUpdateLanguageAction(languageCode);
 const responseAsync: IPigiResponseType = await sendUpdateLanguageActionAsync(languageCode);

Parameters

Parameter	type	Description
languageCode	string	The updated language code in ISO 639-1.

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

Update Media Match Action

▸ sendUpdateMediaMatchAction(conditionText, matches): IApiReturnObject
▸ sendUpdateMediaMatchActionAsync(conditionText, matches): Promise <IPigiResponseType>

The Update Media Match action changes the CSS styling of PIGI.

 const response: IApiReturnObject = sendUpdateMediaMatchAction(conditionText, matches);
 const responseAsync: IPigiResponseType = await sendUpdateMediaMatchActionAsync(conditionText, matches);

Parameters

Parameter	type	Description
conditionText	string	The media rule condition.
matches	boolean	Whether or not the condition was met.

Returns

IApiReturnObject | Promise<IPigiResponseType>

An API response or promise that resolve the PIGI response.

---

State

The Bold Checkout Frontend Library keeps a local copy of the most up-to-date application state, which is updated after every API call. Use the methods in this section to retrieve certain information about your order. To see the latest order status, you can also call the Get Application State endpoint.

---

Get Addresses

▸ getAddresses(): IAddressType

Get the latest shipping and billing address from the Checkout Frontend Library local state management.

 const addresses: IAddressType = await getAddresses();

---

Get Application State

▸ getApplicationState(): IApplicationState

Get the latest application state from the Checkout Frontend Library local state management.

 const app: IApplicationState = await getApplicationState();

---

Get Billing Address

▸ getBillingAddress(): IAddress

Get the latest billing address from the Checkout Frontend Library local state management.

 const billing: IAddress = await getBillingAddress();

---

Get Currency details

▸ getCurrency(): ICurrency

Gets the order currency details from the Checkout Frontend Library local state management.

 const currency: ICurrency = await getCurrency();

---

Get Customer details

▸ getCustomer(): ICustomer

Gets the customer details from the Checkout Frontend Library local state management.

 const customer: ICustomer = await getCustomer();

---

Get Discount List

▸ getDiscounts(): Array<IDiscount>

Gets all the discounts applied to the order from the Checkout Frontend Library local state management.

 const discounts: Array<IDiscount> = await getDiscounts();

---

Get Fees Information

▸ getFees(): Array<IFees>

Gets all the fees applied to the order from the Checkout Frontend Library local state management.

 const fees: Array<IFees> = await getFees();

---

Get Line Items

▸ getLineItems(): Array<ILineItem>

Gets all the line items in the cart from the Checkout Frontend Library local state management.

 const ILineItems: Array<ILineItem> = await getLineItems();

---

Get initial Order Data

▸ getOrderInitialData(): IOrderInitialData

Gets the initial data on the order from the Checkout Frontend Library local state management.

 const initData: IOrderInitialData = await getOrderInitialData();

---

Get Order Metadata

▸ getOrderMetaData(): IOrderMetaData

Gets the order metadata from the Checkout Frontend Library local state management.

 const initData: IOrderMetaData = await getOrderMetaData();

---

Get Payment Details

▸ getPayments(): Array<IPayment>

Gets all the payment details applied to the order from the Checkout Frontend Library local state management.

 const payments: Array<IPayment> = await getPayments();

---

Get Shipping Lines Details

▸ getShipping(): IShipping

Gets the shipping lines details from the Checkout Frontend Library local state management.

 const shippingLines: IShipping = await getShipping();

---

Get Shipping Address

▸ getShippingAddress(): IAddress

Gets the shipping address information from the Checkout Frontend Library local state management.

 const shipping: IAddress = await getShippingAddress();

---

Get Taxes

▸ getTaxes(): Array<ITax>

Gets all the applied taxes from the Checkout Frontend Library local state management.

 const taxes: Array<ITax> = await getTaxes();