@bigcommerce/checkout-sdk / CheckoutService
Responsible for completing the checkout process for the current customer.
This object can be used to collect all information that is required for checkout, such as shipping and billing information. It can also be used to retrieve the current checkout state and subscribe to its changes.
- applyCoupon
- applyGiftCertificate
- applyStoreCredit
- assignItemsToAddress
- clearError
- continueAsGuest
- createConsignments
- createCustomerAccount
- createCustomerAddress
- deinitializeCustomer
- deinitializePayment
- deinitializeShipping
- deleteConsignment
- deleteInstrument
- executePaymentMethodCheckout
- executeSpamCheck
- finalizeOrderIfNeeded
- getState
- handleExtensionCommand
- initializeCustomer
- initializePayment
- initializeShipping
- initializeSpamProtection
- loadBillingAddressFields
- loadBillingCountries
- loadCheckout
- loadExtensions
- loadInstruments
- loadOrder
- loadPaymentMethodByIds
- loadPaymentMethods
- loadPickupOptions
- loadShippingAddressFields
- loadShippingCountries
- loadShippingOptions
- notifyState
- removeCoupon
- removeGiftCertificate
- renderExtension
- selectConsignmentShippingOption
- selectShippingOption
- sendSignInEmail
- signInCustomer
- signOutCustomer
- submitOrder
- subscribe
- unassignItemsToAddress
- updateBillingAddress
- updateCheckout
- updateConsignment
- updateShippingAddress
- updateSubscriptions
• new CheckoutService()
▸ applyCoupon(code
, options?
): Promise
<CheckoutSelectors
>
Applies a coupon code to the current checkout.
Once the coupon code gets applied, the quote for the current checkout will be adjusted accordingly. The same coupon code cannot be applied more than once.
await service.applyCoupon('COUPON');
Name | Type | Description |
---|---|---|
code |
string |
The coupon code to apply to the current checkout. |
options? |
RequestOptions <Object > |
Options for applying the coupon code. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ applyGiftCertificate(code
, options?
): Promise
<CheckoutSelectors
>
Applies a gift certificate to the current checkout.
Once the gift certificate gets applied, the quote for the current checkout will be adjusted accordingly.
await service.applyGiftCertificate('GIFT_CERTIFICATE');
Name | Type | Description |
---|---|---|
code |
string |
The gift certificate to apply to the current checkout. |
options? |
RequestOptions <Object > |
Options for applying the gift certificate. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ applyStoreCredit(useStoreCredit
, options?
): Promise
<CheckoutSelectors
>
Applies or removes customer's store credit code to the current checkout.
Once the store credit gets applied, the outstanding balance will be adjusted accordingly.
const state = await service.applyStoreCredit(true);
console.log(state.data.getCheckout().outstandingBalance);
Name | Type | Description |
---|---|---|
useStoreCredit |
boolean |
- |
options? |
RequestOptions <Object > |
Options for applying store credit. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ assignItemsToAddress(consignment
, options?
): Promise
<CheckoutSelectors
>
Convenience method that assigns items to be shipped to a specific address.
Note: this method finds an existing consignment that matches the provided address and assigns the provided items. If no consignment matches the address, a new one will be created.
Name | Type | Description |
---|---|---|
consignment |
ConsignmentAssignmentRequestBody |
The consignment data that will be used. |
options? |
RequestOptions <Object > |
Options for the request |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ clearError(error
): Promise
<CheckoutSelectors
>
Clear errors that have been collected from previous calls.
const state = await service.clearError(error);
console.log(state.errors.getError());
Name | Type | Description |
---|---|---|
error |
Error |
Specific error object to clear |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ continueAsGuest(credentials
, options?
): Promise
<CheckoutSelectors
>
Continues to check out as a guest.
If your Checkout Settings allow it, your customers could continue the checkout as guests (without signing in). If you have enabled the checkout setting "Prompt existing accounts to sign in", this information is exposed as part of the Customer object.
Once they provide their email address, it will be stored as part of their billing address.
Name | Type | Description |
---|---|---|
credentials |
GuestCredentials |
The guest credentials to use, with optional subscriptions. |
options? |
RequestOptions <Object > |
Options for continuing as a guest. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ createConsignments(consignments
, options?
): Promise
<CheckoutSelectors
>
Creates consignments given a list.
Note: this is used when items need to be shipped to multiple addresses,
for single shipping address, use CheckoutService#updateShippingAddress
.
When consignments are created, an updated list of shipping options will
become available for each consignment, unless no options are available.
If the update is successful, you can call
CheckoutStoreSelector#getConsignments
to retrieve the updated list of
consignments.'
Beware that if a consignment includes all line items from another consignment, that consignment will be deleted as a valid consignment must include at least one valid line item.
You can submit an address that is partially complete. The address does not get validated until you submit the order.
const state = await service.createConsignments(consignments);
console.log(state.data.getConsignments());
Name | Type | Description |
---|---|---|
consignments |
ConsignmentsRequestBody |
The list of consignments to be created. |
options? |
RequestOptions <Object > |
Options for updating the shipping address. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ createCustomerAccount(customerAccount
, options?
): Promise
<CheckoutSelectors
>
Creates a customer account.
remarks
checkoutService.createCustomerAccount({
email: 'foo@bar.com',
firstName: 'Foo',
lastName: 'Bar',
password: 'password',
acceptsMarketingEmails: true,
customFields: [],
});
Please note that createCustomerAccount
is currently in an early stage
of development. Therefore the API is unstable and not ready for public
consumption.
alpha
Name | Type | Description |
---|---|---|
customerAccount |
CustomerAccountRequestBody |
The customer account data. |
options? |
RequestOptions <Object > |
Options for creating customer account. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ createCustomerAddress(customerAddress
, options?
): Promise
<CheckoutSelectors
>
Creates a customer account address.
remarks
checkoutService.createCustomerAddress({
firstName: 'Foo',
lastName: 'Bar',
address1: '55 Market St',
stateOrProvinceCode: 'CA',
countryCode: 'US',
postalCode: '90110',
customFields: [],
});
Please note that createCustomerAccountAddress
is currently in an early stage
of development. Therefore the API is unstable and not ready for public
consumption.
alpha
Name | Type | Description |
---|---|---|
customerAddress |
AddressRequestBody |
The customer account data. |
options? |
RequestOptions <Object > |
Options for creating customer account. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ deinitializeCustomer(options?
): Promise
<CheckoutSelectors
>
De-initializes the sign-in step of a checkout process.
It should be called once you no longer want to prompt customers to sign in. It can perform any necessary clean-up behind the scene, i.e.: remove DOM nodes or event handlers that are attached as a result of customer initialization.
await service.deinitializeCustomer({
methodId: 'amazonpay',
});
Name | Type | Description |
---|---|---|
options? |
CustomerRequestOptions |
Options for deinitializing the customer step of checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ deinitializePayment(options
): Promise
<CheckoutSelectors
>
De-initializes the payment step of a checkout process.
The method should be called once you no longer require a payment method to be initialized. It can perform any necessary clean-up behind the scene, i.e.: remove DOM nodes or event handlers that are attached as a result of payment initialization.
await service.deinitializePayment({
methodId: 'amazonpay',
});
Name | Type | Description |
---|---|---|
options |
PaymentRequestOptions |
Options for deinitializing the payment step of checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ deinitializeShipping(options?
): Promise
<CheckoutSelectors
>
De-initializes the shipping step of a checkout process.
It should be called once you no longer need to collect shipping details. It can perform any necessary clean-up behind the scene, i.e.: remove DOM nodes or event handlers that are attached as a result of shipping initialization.
await service.deinitializeShipping({
methodId: 'amazonpay',
});
Name | Type | Description |
---|---|---|
options? |
ShippingRequestOptions <Object > |
Options for deinitializing the shipping step of checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ deleteConsignment(consignmentId
, options?
): Promise
<CheckoutSelectors
>
Deletes a consignment
const state = await service.deleteConsignment('55c96cda6f04c');
console.log(state.data.getConsignments());
Name | Type | Description |
---|---|---|
consignmentId |
string |
The ID of the consignment to be deleted |
options? |
RequestOptions <Object > |
Options for the consignment delete request |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ deleteInstrument(instrumentId
): Promise
<CheckoutSelectors
>
Deletes a payment instrument by an id.
Once an instrument gets removed, it can no longer be retrieved using
CheckoutStoreSelector#getInstruments
.
const state = service.deleteInstrument('123');
console.log(state.data.getInstruments());
Name | Type | Description |
---|---|---|
instrumentId |
string |
The identifier of the payment instrument to delete. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ executePaymentMethodCheckout(options?
): Promise
<CheckoutSelectors
>
Executes custom checkout of the priority payment method.
Some payment methods, such as Bolt, can use their own checkout with autofilled customers data, to make checkout passing process easier and faster for customers with Bolt account.
await service.executePaymentMethodCheckout({
methodId: 'bolt',
fallback: () => {},
});
Name | Type | Description |
---|---|---|
options? |
ExecutePaymentMethodCheckoutOptions |
Options for executing payment method checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ executeSpamCheck(): Promise
<CheckoutSelectors
>
Verifies whether the current checkout is created by a human.
Note: this method will do the initialization, therefore you do not
need to call CheckoutService#initializeSpamProtection
before calling this method.
With spam protection enabled, the customer has to be verified as
a human. The order creation will fail if spam protection
is enabled but verification fails. You should call this method before
submitOrder
method is called (i.e.: when the shopper
first gets to the payment step).
Note: You need to enable Google ReCAPTCHA bot protection in your Checkout Settings.
await service.executeSpamCheck();
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ finalizeOrderIfNeeded(options?
): Promise
<CheckoutSelectors
>
Finalizes the submission process for an order.
This method is only required for certain hosted payment methods that require a customer to enter their credit card details on their website. You need to call this method once the customer has redirected back to checkout in order to complete the checkout process.
If the method is called before order finalization is required or for a payment method that does not require order finalization, an error will be thrown. Conversely, if the method is called successfully, you should immediately redirect the customer to the order confirmation page.
try {
await service.finalizeOrderIfNeeded();
window.location.assign('/order-confirmation');
} catch (error) {
if (error.type !== 'order_finalization_not_required') {
throw error;
}
}
throws
OrderFinalizationNotRequiredError
error if order finalization
is not required for the current order at the time of execution.
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for finalizing the current order. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ getState(): CheckoutSelectors
Returns a snapshot of the current checkout state.
The method returns a new instance every time there is a change in the checkout state. You can query the state by calling any of its getter methods.
const state = service.getState();
console.log(state.data.getOrder());
console.log(state.errors.getSubmitOrderError());
console.log(state.statuses.isSubmittingOrder());
The current customer's checkout state
▸ handleExtensionCommand<T
>(extensionId
, command
, handler
): () => void
Manages the command handler for an extension.
alpha
Name | Type |
---|---|
T |
extends keyof ExtensionCommandMap |
Name | Type | Description |
---|---|---|
extensionId |
string |
The ID of the extension sending the command. |
command |
T |
The command to be handled. |
handler |
(command : ExtensionCommandMap [T ]) => void |
The handler function for the extension command. |
fn
A function that, when called, will deregister the command handler.
▸ (): void
Manages the command handler for an extension.
alpha
void
A function that, when called, will deregister the command handler.
▸ initializeCustomer(options?
): Promise
<CheckoutSelectors
>
Initializes the sign-in step of a checkout process.
Some payment methods, such as Amazon Pay, have their own sign-in flow. In order to support them, this method must be called.
await service.initializeCustomer({
methodId: 'amazonpay',
amazonpay: {
container: 'signInButton',
},
});
Name | Type | Description |
---|---|---|
options? |
CustomerInitializeOptions |
Options for initializing the customer step of checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ initializePayment(options
): Promise
<CheckoutSelectors
>
Initializes the payment step of a checkout process.
Before a payment method can accept payment details, it must first be initialized. Some payment methods require you to provide additional initialization options. For example, you can provide an element ID for Amazon Pay if you want users to be able to select a different payment method by clicking on the element.
await service.initializePayment({
methodId: 'amazonpay',
amazonpay: {
editButtonId: 'edit-button',
},
});
Name | Type | Description |
---|---|---|
options |
PaymentInitializeOptions |
Options for initializing the payment step of checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ initializeShipping(options?
): Promise
<CheckoutSelectors
>
Initializes the shipping step of a checkout process.
Some payment methods, such as Amazon Pay, can provide shipping information to be used for checkout. In order to support them, this method must be called.
await service.initializeShipping({
methodId: 'amazonpay',
amazonpay: {
editAddressButtonId: 'changeAddressButton',
},
});
Name | Type | Description |
---|---|---|
options? |
ShippingInitializeOptions <Object > |
Options for initializing the shipping step of checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ initializeSpamProtection(options
): Promise
<CheckoutSelectors
>
Initializes the spam protection for order creation.
Note: Use CheckoutService#executeSpamCheck
instead.
You do not need to call this method before calling
CheckoutService#executeSpamCheck
.
With spam protection enabled, the customer has to be verified as a human. The order creation will fail if spam protection is enabled but verification fails.
await service.initializeSpamProtection();
deprecated
- Use CheckoutService#executeSpamCheck instead.
Name | Type | Description |
---|---|---|
options |
SpamProtectionOptions |
Options for initializing spam protection. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadBillingAddressFields(options?
): Promise
<CheckoutSelectors
>
Loads a set of form fields that should be presented to customers in order to capture their billing address.
Once the method has been executed successfully, you can call
CheckoutStoreSelector#getBillingAddressFields
to retrieve the set of
form fields.
const state = service.loadBillingAddressFields();
console.log(state.data.getBillingAddressFields('US'));
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for loading the billing address form fields. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadBillingCountries(options?
): Promise
<CheckoutSelectors
>
Loads a list of countries available for billing.
Once you make a successful request, you will be able to retrieve the list
of countries by calling CheckoutStoreSelector#getBillingCountries
.
const state = await service.loadBillingCountries();
console.log(state.data.getBillingCountries());
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for loading the available billing countries. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadCheckout(id?
, options?
): Promise
<CheckoutSelectors
>
Loads the current checkout.
This method can only be called if there is an active checkout. Also, it
can only retrieve data that belongs to the current customer. When it is
successfully executed, you can retrieve the data by calling
CheckoutStoreSelector#getCheckout
.
const state = await service.loadCheckout('0cfd6c06-57c3-4e29-8d7a-de55cc8a9052');
console.log(state.data.getCheckout());
Name | Type | Description |
---|---|---|
id? |
string |
The identifier of the checkout to load, or the default checkout if not provided. |
options? |
RequestOptions <CheckoutParams > |
Options for loading the current checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadExtensions(options?
): Promise
<CheckoutSelectors
>
Loads a list of extensions available for checkout.
const state = await service.loadExtensions();
console.log(state.data.getExtensions());
alpha
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for loading the extensions that are available to the current customer. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadInstruments(): Promise
<CheckoutSelectors
>
Loads a list of payment instruments associated with a customer.
Once the method has been called successfully, you can retrieve the list
of payment instruments by calling CheckoutStoreSelector#getInstruments
.
If the customer does not have any payment instruments on record, i.e.:
credit card, you will get an empty list instead.
const state = service.loadInstruments();
console.log(state.data.getInstruments());
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadOrder(orderId
, options?
): Promise
<CheckoutSelectors
>
Loads an order by an id.
The method can only retrieve an order if the order belongs to the current
customer. If it is successfully executed, the data can be retrieved by
calling CheckoutStoreSelector#getOrder
.
const state = await service.loadOrder(123);
console.log(state.data.getOrder());
Name | Type | Description |
---|---|---|
orderId |
number |
The identifier of the order to load. |
options? |
RequestOptions <Object > |
Options for loading the order. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadPaymentMethodByIds(methodIds
, options?
): Promise
<CheckoutSelectors
>
Loads a list of payment methods for given ids.
Once the method is executed successfully, you can call
CheckoutStoreSelector#getPaymentMethods
to retrieve the list of payment
methods.
const state = service.loadPaymentMethodsById(['applepay']);
console.log(state.data.getPaymentMethodOrThrow('applepay'));
Name | Type | Description |
---|---|---|
methodIds |
string [] |
The identifier for the payment methods to load. |
options? |
RequestOptions <Object > |
Options for loading the payment methods that are available to the current customer. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadPaymentMethods(options?
): Promise
<CheckoutSelectors
>
Loads a list of payment methods available for checkout.
If a customer enters their payment details before navigating to the checkout page (i.e.: using PayPal checkout button on the cart page), only one payment method will be available for the customer - the selected payment method. Otherwise, by default, all payment methods configured by the merchant will be available for the customer.
Once the method is executed successfully, you can call
CheckoutStoreSelector#getPaymentMethods
to retrieve the list of payment
methods.
const state = service.loadPaymentMethods();
console.log(state.data.getPaymentMethods());
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for loading the payment methods that are available to the current customer. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadPickupOptions(query
): Promise
<CheckoutSelectors
>
Loads a list of pickup options for a given criteria.
const consignmentId = '1';
const searchArea = {
radius: {
value: 1.4,
unit: 'KM'
},
coordinates: {
latitude: 1.4,
longitude: 0
},
};
const state = await service.loadPickupOptions({ consignmentId, searchArea });
console.log(state.data.getPickupOptions(consignmentId, searchArea));
alpha
Name | Type | Description |
---|---|---|
query |
PickupOptionRequestBody |
Options for loading the available shipping countries. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadShippingAddressFields(options?
): Promise
<CheckoutSelectors
>
Loads a set of form fields that should be presented to customers in order to capture their shipping address.
Once the method has been executed successfully, you can call
CheckoutStoreSelector#getShippingAddressFields
to retrieve the set of
form fields.
const state = service.loadShippingAddressFields();
console.log(state.data.getShippingAddressFields('US'));
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for loading the shipping address form fields. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadShippingCountries(options?
): Promise
<CheckoutSelectors
>
Loads a list of countries available for shipping.
The list is determined based on the shipping zones configured by a
merchant. Once you make a successful call, you will be able to retrieve
the list of available shipping countries by calling
CheckoutStoreSelector#getShippingCountries
.
const state = await service.loadShippingCountries();
console.log(state.data.getShippingCountries());
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for loading the available shipping countries. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ loadShippingOptions(options?
): Promise
<CheckoutSelectors
>
Loads a list of shipping options available for checkout.
Available shipping options can only be determined once a customer
provides their shipping address. If the method is executed successfully,
CheckoutStoreSelector#getShippingOptions
can be called to retrieve the
list of shipping options.
const state = await service.loadShippingOptions();
console.log(state.data.getShippingOptions());
Name | Type | Description |
---|---|---|
options? |
RequestOptions <Object > |
Options for loading the available shipping options. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ notifyState(): void
Notifies all subscribers with the current state.
When this method gets called, the subscribers get called regardless if they have any filters applied.
void
▸ removeCoupon(code
, options?
): Promise
<CheckoutSelectors
>
Removes a coupon code from the current checkout.
Once the coupon code gets removed, the quote for the current checkout will be adjusted accordingly.
await service.removeCoupon('COUPON');
Name | Type | Description |
---|---|---|
code |
string |
The coupon code to remove from the current checkout. |
options? |
RequestOptions <Object > |
Options for removing the coupon code. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ removeGiftCertificate(code
, options?
): Promise
<CheckoutSelectors
>
Removes a gift certificate from an order.
Once the gift certificate gets removed, the quote for the current checkout will be adjusted accordingly.
await service.removeGiftCertificate('GIFT_CERTIFICATE');
Name | Type | Description |
---|---|---|
code |
string |
The gift certificate to remove from the current checkout. |
options? |
RequestOptions <Object > |
Options for removing the gift certificate. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ renderExtension(container
, region
): Promise
<CheckoutSelectors
>
Renders an extension for a checkout extension region. Currently, only one extension is allowed per region.
alpha
Name | Type | Description |
---|---|---|
container |
string |
The ID of a container which the extension should be inserted. |
region |
ExtensionRegion |
The name of an area where the extension should be presented. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ selectConsignmentShippingOption(consignmentId
, shippingOptionId
, options?
): Promise
<CheckoutSelectors
>
Selects a shipping option for a given consignment.
Note: this is used when items need to be shipped to multiple addresses,
for single shipping address, use CheckoutService#updateShippingAddress
.
If a shipping option has an additional cost, the quote for the current order will be adjusted once the option is selected.
const state = await service.selectConsignmentShippingOption(consignmentId, optionId);
console.log(state.data.getConsignments());
Name | Type | Description |
---|---|---|
consignmentId |
string |
The identified of the consignment to be updated. |
shippingOptionId |
string |
The identifier of the shipping option to select. |
options? |
ShippingRequestOptions <Object > |
Options for selecting the shipping option. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ selectShippingOption(shippingOptionId
, options?
): Promise
<CheckoutSelectors
>
Selects a shipping option for the current address.
If a shipping option has an additional cost, the quote for the current order will be adjusted once the option is selected.
const state = await service.selectShippingOption('address-id', 'shipping-option-id');
console.log(state.data.getSelectedShippingOption());
Name | Type | Description |
---|---|---|
shippingOptionId |
string |
The identifier of the shipping option to select. |
options? |
ShippingRequestOptions <Object > |
Options for selecting the shipping option. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ sendSignInEmail(signInEmailRequest
, options?
): Promise
<CheckoutSelectors
>
Sends a email that contains a single-use sign-in link. When a valid links is clicked, signs in the customer without requiring any password, redirecting them to the account page if no redirectUrl is provided.
checkoutService.sendSignInEmail({ email: 'foo@bar.com', redirectUrl: 'checkout' });
Name | Type | Description |
---|---|---|
signInEmailRequest |
SignInEmailRequestBody |
The sign-in email request values. |
options? |
RequestOptions <Object > |
Options for the send email request. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ signInCustomer(credentials
, options?
): Promise
<CheckoutSelectors
>
Signs into a customer's registered account.
Once the customer is signed in successfully, the checkout state will be
populated with information associated with the customer, such as their
saved addresses. You can call CheckoutStoreSelector#getCustomer
to
retrieve the data.
const state = await service.signInCustomer({
email: 'foo@bar.com',
password: 'password123',
});
console.log(state.data.getCustomer());
Name | Type | Description |
---|---|---|
credentials |
CustomerCredentials |
The credentials to be used for signing in the customer. |
options? |
CustomerRequestOptions |
Options for signing in the customer. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ signOutCustomer(options?
): Promise
<CheckoutSelectors
>
Signs out the current customer if they are previously signed in.
Once the customer is successfully signed out, the checkout state will be reset automatically.
const state = await service.signOutCustomer();
// The returned object should not contain information about the previously signed-in customer.
console.log(state.data.getCustomer());
When a store has "Allow customers to access their cart across multiple devices" enabled, signing out will remove the cart/checkout data from the current session. An error with type="checkout_not_available" will be thrown.
try {
await service.signOutCustomer();
} catch (error) {
if (error.type === 'checkout_not_available') {
window.top.location.assign('/');
}
}
Name | Type | Description |
---|---|---|
options? |
CustomerRequestOptions |
Options for signing out the customer. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ submitOrder(payload
, options?
): Promise
<CheckoutSelectors
>
Submits an order, thereby completing a checkout process.
Before you can submit an order, you must initialize the payment method
chosen by the customer by calling CheckoutService#initializePayment
.
await service.initializePayment({ methodId: 'braintree' });
await service.submitOrder({
payment: {
methodId: 'braintree',
paymentData: {
ccExpiry: { month: 10, year: 20 },
ccName: 'BigCommerce',
ccNumber: '4111111111111111',
ccCvv: 123,
},
},
});
You are not required to include paymentData
if the order does not
require additional payment details. For example, the customer has already
entered their payment details on the cart page using one of the hosted
payment methods, such as PayPal. Or the customer has applied a gift
certificate that exceeds the grand total amount.
If the order is submitted successfully, you can retrieve the newly
created order by calling CheckoutStoreSelector#getOrder
.
const state = await service.submitOrder(payload);
console.log(state.data.getOrder());
Name | Type | Description |
---|---|---|
payload |
OrderRequestBody |
The request payload to submit for the current order. |
options? |
RequestOptions <Object > |
Options for submitting the current order. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ subscribe(subscriber
, ...filters
): () => void
Subscribes to any changes to the current state.
The method registers a callback function and executes it every time there is a change in the checkout state.
service.subscribe(state => {
console.log(state.data.getCart());
});
The method can be configured to notify subscribers only regarding relevant changes, by providing a filter function.
const filter = state => state.data.getCart();
// Only trigger the subscriber when the cart changes.
service.subscribe(state => {
console.log(state.data.getCart())
}, filter);
Name | Type | Description |
---|---|---|
subscriber |
(state : CheckoutSelectors ) => void |
The function to subscribe to state changes. |
...filters |
(state : CheckoutSelectors ) => any [] |
One or more functions to filter out irrelevant state changes. If more than one function is provided, the subscriber will only be triggered if all conditions are met. |
fn
A function, if called, will unsubscribe the subscriber.
▸ (): void
Subscribes to any changes to the current state.
The method registers a callback function and executes it every time there is a change in the checkout state.
service.subscribe(state => {
console.log(state.data.getCart());
});
The method can be configured to notify subscribers only regarding relevant changes, by providing a filter function.
const filter = state => state.data.getCart();
// Only trigger the subscriber when the cart changes.
service.subscribe(state => {
console.log(state.data.getCart())
}, filter);
void
A function, if called, will unsubscribe the subscriber.
▸ unassignItemsToAddress(consignment
, options?
): Promise
<CheckoutSelectors
>
Convenience method that unassigns items from a specific shipping address.
Note: this method finds an existing consignment that matches the provided address and unassigns the specified items. If the consignment ends up with no line items after the unassignment, it will be deleted.
Name | Type | Description |
---|---|---|
consignment |
ConsignmentAssignmentRequestBody |
The consignment data that will be used. |
options? |
RequestOptions <Object > |
Options for the request |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ updateBillingAddress(address
, options?
): Promise
<CheckoutSelectors
>
Updates the billing address for the current checkout.
A customer must provide their billing address before they can proceed to pay for their order.
You can submit an address that is partially complete. The address does not get validated until you submit the order.
const state = await service.updateBillingAddress(address);
console.log(state.data.getBillingAddress());
Name | Type | Description |
---|---|---|
address |
Partial <BillingAddressRequestBody > |
The address to be used for billing. |
options? |
RequestOptions <Object > |
Options for updating the billing address. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ updateCheckout(payload
, options?
): Promise
<CheckoutSelectors
>
Updates specific properties of the current checkout.
const state = await service.updateCheckout(checkout);
console.log(state.data.getCheckout());
Name | Type | Description |
---|---|---|
payload |
CheckoutRequestBody |
The checkout properties to be updated. |
options? |
RequestOptions <Object > |
Options for loading the current checkout. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ updateConsignment(consignment
, options?
): Promise
<CheckoutSelectors
>
Updates a specific consignment.
Note: this is used when items need to be shipped to multiple addresses,
for single shipping address, use CheckoutService#selectShippingOption
.
When a shipping address for a consignment is updated, an updated list of
shipping options will become available for the consignment, unless no
options are available. If the update is successful, you can call
CheckoutStoreSelector#getConsignments
to retrieve updated list of
consignments.
Beware that if the updated consignment includes all line items from another consignment, that consignment will be deleted as a valid consignment must include at least one valid line item.
If the shipping address changes and the selected shipping option becomes unavailable for the updated address, the shipping option will be deselected.
You can submit an address that is partially complete. The address does not get validated until you submit the order.
const state = await service.updateConsignment(consignment);
console.log(state.data.getConsignments());
Name | Type | Description |
---|---|---|
consignment |
ConsignmentUpdateRequestBody |
The consignment data that will be used. |
options? |
RequestOptions <Object > |
Options for updating the shipping address. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ updateShippingAddress(address
, options?
): Promise
<CheckoutSelectors
>
Updates the shipping address for the current checkout.
When a customer updates their shipping address for an order, they will
see an updated list of shipping options and the cost for each option,
unless no options are available. If the update is successful, you can
call CheckoutStoreSelector#getShippingAddress
to retrieve the address.
If the shipping address changes and the selected shipping option becomes unavailable for the updated address, the shipping option will be deselected.
You can submit an address that is partially complete. The address does not get validated until you submit the order.
const state = await service.updateShippingAddress(address);
console.log(state.data.getShippingAddress());
Name | Type | Description |
---|---|---|
address |
Partial <AddressRequestBody > |
The address to be used for shipping. |
options? |
ShippingRequestOptions <CheckoutParams > |
Options for updating the shipping address. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.
▸ updateSubscriptions(subscriptions
, options?
): Promise
<CheckoutSelectors
>
Updates the subscriptions associated to an email.
Name | Type | Description |
---|---|---|
subscriptions |
Subscriptions |
The email and associated subscriptions to update. |
options? |
RequestOptions <Object > |
Options for continuing as a guest. |
Promise
<CheckoutSelectors
>
A promise that resolves to the current state.