Skip to content

bold-commerce/checkout-frontend-library

Repository files navigation

Checkout Frontend Library

Description

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

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