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
yarn add "@boldcommerce/checkout-frontend-library"
yarn add "@boldcommerce/checkout-frontend-library"@1.0.0
(replace "1.0.0" with the version number that you want)
npm install "@boldcommerce/checkout-frontend-library"
npm install "@boldcommerce/checkout-frontend-library"@1.0.0
(replace "1.0.0" with the version number that you want)
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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. |
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
▸ 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.
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.
▸ getAddresses(): IAddressType
Get the latest shipping and billing address from the Checkout Frontend Library local state management.
const addresses: IAddressType = await getAddresses();
▸ getApplicationState(): IApplicationState
Get the latest application state from the Checkout Frontend Library local state management.
const app: IApplicationState = await getApplicationState();
▸ getBillingAddress(): IAddress
Get the latest billing address from the Checkout Frontend Library local state management.
const billing: IAddress = await getBillingAddress();
▸ getCurrency(): ICurrency
Gets the order currency details from the Checkout Frontend Library local state management.
const currency: ICurrency = await getCurrency();
▸ getCustomer(): ICustomer
Gets the customer details from the Checkout Frontend Library local state management.
const customer: ICustomer = await getCustomer();
▸ 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();
▸ 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();
▸ 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();
▸ getOrderInitialData(): IOrderInitialData
Gets the initial data on the order from the Checkout Frontend Library local state management.
const initData: IOrderInitialData = await getOrderInitialData();
▸ getOrderMetaData(): IOrderMetaData
Gets the order metadata from the Checkout Frontend Library local state management.
const initData: IOrderMetaData = await getOrderMetaData();
▸ 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();
▸ getShipping(): IShipping
Gets the shipping lines details from the Checkout Frontend Library local state management.
const shippingLines: IShipping = await getShipping();
▸ getShippingAddress(): IAddress
Gets the shipping address information from the Checkout Frontend Library local state management.
const shipping: IAddress = await getShippingAddress();
▸ getTaxes(): Array<ITax>
Gets all the applied taxes from the Checkout Frontend Library local state management.
const taxes: Array<ITax> = await getTaxes();