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();