@bigcommerce/checkout-sdk › CheckoutService

Class: 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.

Hierarchy

CheckoutService

Index

Methods

applyCoupon
applyGiftCertificate
applyStoreCredit
assignItemsToAddress
clearError
continueAsGuest
createConsignments
createCustomerAccount
createCustomerAddress
deinitializeCustomer
deinitializePayment
deinitializeShipping
deleteConsignment
deleteInstrument
executePaymentMethodCheckout
executeSpamCheck
finalizeOrderIfNeeded
getState
initializeCustomer
initializePayment
initializeShipping
initializeSpamProtection
loadBillingAddressFields
loadBillingCountries
loadCheckout
loadInstruments
loadOrder
loadPaymentMethods
loadShippingAddressFields
loadShippingCountries
loadShippingOptions
notifyState
removeCoupon
removeGiftCertificate
selectConsignmentShippingOption
selectShippingOption
sendSignInEmail
signInCustomer
signOutCustomer
submitOrder
subscribe
unassignItemsToAddress
updateBillingAddress
updateCheckout
updateConsignment
updateShippingAddress
updateSubscriptions

Methods

applyCoupon

▸ applyCoupon(code: string, options?: RequestOptions): 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');

Parameters:

Name	Type	Description
`code`	string	The coupon code to apply to the current checkout.
`options?`	RequestOptions	Options for applying the coupon code.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

applyGiftCertificate

▸ applyGiftCertificate(code: string, options?: RequestOptions): 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');

Parameters:

Name	Type	Description
`code`	string	The gift certificate to apply to the current checkout.
`options?`	RequestOptions	Options for applying the gift certificate.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

applyStoreCredit

▸ applyStoreCredit(useStoreCredit: boolean, options?: RequestOptions): 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);

Parameters:

Name	Type	Description
`useStoreCredit`	boolean	-
`options?`	RequestOptions	Options for applying store credit.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

assignItemsToAddress

▸ assignItemsToAddress(consignment: ConsignmentAssignmentRequestBody, options?: RequestOptions): 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.

Parameters:

Name	Type	Description
`consignment`	ConsignmentAssignmentRequestBody	The consignment data that will be used.
`options?`	RequestOptions	Options for the request

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

clearError

▸ clearError(error: Error): Promise‹CheckoutSelectors›

Clear errors that have been collected from previous calls.

const state = await service.clearError(error);

console.log(state.errors.getError());

Parameters:

Name	Type	Description
`error`	Error	Specific error object to clear

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

continueAsGuest

▸ continueAsGuest(credentials: GuestCredentials, options?: RequestOptions): 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.

Parameters:

Name	Type	Description
`credentials`	GuestCredentials	The guest credentials to use, with optional subscriptions.
`options?`	RequestOptions	Options for continuing as a guest.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

createConsignments

▸ createConsignments(consignments: ConsignmentsRequestBody, options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`consignments`	ConsignmentsRequestBody	The list of consignments to be created.
`options?`	RequestOptions	Options for updating the shipping address.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

createCustomerAccount

▸ createCustomerAccount(customerAccount: CustomerAccountRequestBody, options?: RequestOptions): 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

Parameters:

Name	Type	Description
`customerAccount`	CustomerAccountRequestBody	The customer account data.
`options?`	RequestOptions	Options for creating customer account.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

createCustomerAddress

▸ createCustomerAddress(customerAddress: CustomerAddressRequestBody, options?: RequestOptions): 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

Parameters:

Name	Type	Description
`customerAddress`	CustomerAddressRequestBody	The customer account data.
`options?`	RequestOptions	Options for creating customer account.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

deinitializeCustomer

▸ deinitializeCustomer(options?: CustomerRequestOptions): 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: 'amazon',
});

Parameters:

Name	Type	Description
`options?`	CustomerRequestOptions	Options for deinitializing the customer step of checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

deinitializePayment

▸ deinitializePayment(options: PaymentRequestOptions): 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: 'amazon',
});

Parameters:

Name	Type	Description
`options`	PaymentRequestOptions	Options for deinitializing the payment step of checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

deinitializeShipping

▸ deinitializeShipping(options?: ShippingRequestOptions): 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: 'amazon',
});

Parameters:

Name	Type	Description
`options?`	ShippingRequestOptions	Options for deinitializing the shipping step of checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

deleteConsignment

▸ deleteConsignment(consignmentId: string, options?: RequestOptions): Promise‹CheckoutSelectors›

Deletes a consignment

const state = await service.deleteConsignment('55c96cda6f04c');

console.log(state.data.getConsignments());

Parameters:

Name	Type	Description
`consignmentId`	string	The ID of the consignment to be deleted
`options?`	RequestOptions	Options for the consignment delete request

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

deleteInstrument

▸ deleteInstrument(instrumentId: string): 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());

Parameters:

Name	Type	Description
`instrumentId`	string	The identifier of the payment instrument to delete.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

executePaymentMethodCheckout

▸ executePaymentMethodCheckout(options?: ExecutePaymentMethodCheckoutOptions): 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: () => {},
});

Parameters:

Name	Type	Description
`options?`	ExecutePaymentMethodCheckoutOptions	Options for executing payment method checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

executeSpamCheck

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

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

finalizeOrderIfNeeded

▸ finalizeOrderIfNeeded(options?: RequestOptions): 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.

Parameters:

Name	Type	Description
`options?`	RequestOptions	Options for finalizing the current order.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

getState

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

Returns: CheckoutSelectors

The current customer's checkout state

initializeCustomer

▸ initializeCustomer(options?: CustomerInitializeOptions): Promise‹CheckoutSelectors›

Initializes the sign-in step of a checkout process.

Some payment methods, such as Amazon, have their own sign-in flow. In order to support them, this method must be called.

await service.initializeCustomer({
    methodId: 'amazon',
    amazon: {
        container: 'signInButton',
    },
});

Parameters:

Name	Type	Description
`options?`	CustomerInitializeOptions	Options for initializing the customer step of checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

initializePayment

▸ initializePayment(options: PaymentInitializeOptions): 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, Amazon requires a container ID in order to initialize their payment widget.

await service.initializePayment({
    methodId: 'amazon',
    amazon: {
        container: 'walletWidget',
    },
});

Parameters:

Name	Type	Description
`options`	PaymentInitializeOptions	Options for initializing the payment step of checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

initializeShipping

▸ initializeShipping(options?: ShippingInitializeOptions): Promise‹CheckoutSelectors›

Initializes the shipping step of a checkout process.

Some payment methods, such as Amazon, can provide shipping information to be used for checkout. In order to support them, this method must be called.

await service.initializeShipping({
    methodId: 'amazon',
    amazon: {
        container: 'addressBook',
    },
});

Parameters:

Name	Type	Description
`options?`	ShippingInitializeOptions	Options for initializing the shipping step of checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

initializeSpamProtection

▸ initializeSpamProtection(options: SpamProtectionOptions): 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.

Parameters:

Name	Type	Description
`options`	SpamProtectionOptions	Options for initializing spam protection.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadBillingAddressFields

▸ loadBillingAddressFields(options?: RequestOptions): 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'));

Parameters:

Name	Type	Description
`options?`	RequestOptions	Options for loading the billing address form fields.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadBillingCountries

▸ loadBillingCountries(options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`options?`	RequestOptions	Options for loading the available billing countries.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadCheckout

▸ loadCheckout(id?: undefined | string, options?: RequestOptions‹CheckoutParams›): 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());

Parameters:

Name	Type	Description
`id?`	undefined \| string	The identifier of the checkout to load, or the default checkout if not provided.
`options?`	RequestOptions‹CheckoutParams›	Options for loading the current checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadInstruments

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

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadOrder

▸ loadOrder(orderId: number, options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`orderId`	number	The identifier of the order to load.
`options?`	RequestOptions	Options for loading the order.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadPaymentMethods

▸ loadPaymentMethods(options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`options?`	RequestOptions	Options for loading the payment methods that are available to the current customer.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadShippingAddressFields

▸ loadShippingAddressFields(options?: RequestOptions): 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'));

Parameters:

Name	Type	Description
`options?`	RequestOptions	Options for loading the shipping address form fields.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadShippingCountries

▸ loadShippingCountries(options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`options?`	RequestOptions	Options for loading the available shipping countries.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

loadShippingOptions

▸ loadShippingOptions(options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`options?`	RequestOptions	Options for loading the available shipping options.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

notifyState

▸ 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.

Returns: void

removeCoupon

▸ removeCoupon(code: string, options?: RequestOptions): 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');

Parameters:

Name	Type	Description
`code`	string	The coupon code to remove from the current checkout.
`options?`	RequestOptions	Options for removing the coupon code.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

removeGiftCertificate

▸ removeGiftCertificate(code: string, options?: RequestOptions): 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');

Parameters:

Name	Type	Description
`code`	string	The gift certificate to remove from the current checkout.
`options?`	RequestOptions	Options for removing the gift certificate.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

selectConsignmentShippingOption

▸ selectConsignmentShippingOption(consignmentId: string, shippingOptionId: string, options?: ShippingRequestOptions): 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());

Parameters:

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	Options for selecting the shipping option.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

selectShippingOption

▸ selectShippingOption(shippingOptionId: string, options?: ShippingRequestOptions): 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());

Parameters:

Name	Type	Description
`shippingOptionId`	string	The identifier of the shipping option to select.
`options?`	ShippingRequestOptions	Options for selecting the shipping option.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

sendSignInEmail

▸ sendSignInEmail(signInEmailRequest: SignInEmailRequestBody, options?: RequestOptions): 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' });

Parameters:

Name	Type	Description
`signInEmailRequest`	SignInEmailRequestBody	The sign-in email request values.
`options?`	RequestOptions	Options for the send email request.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

signInCustomer

▸ signInCustomer(credentials: CustomerCredentials, options?: CustomerRequestOptions): 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());

Parameters:

Name	Type	Description
`credentials`	CustomerCredentials	The credentials to be used for signing in the customer.
`options?`	CustomerRequestOptions	Options for signing in the customer.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

signOutCustomer

▸ signOutCustomer(options?: CustomerRequestOptions): 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('/');
  }
}

Parameters:

Name	Type	Description
`options?`	CustomerRequestOptions	Options for signing out the customer.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

submitOrder

▸ submitOrder(payload: OrderRequestBody, options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`payload`	OrderRequestBody	The request payload to submit for the current order.
`options?`	RequestOptions	Options for submitting the current order.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

subscribe

▸ subscribe(subscriber: function, ...filters: Array‹function›): function

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

Parameters:

▪ subscriber: function

The function to subscribe to state changes.

▸ (state: CheckoutSelectors): void

Parameters:

Name	Type
`state`	CheckoutSelectors

▪... filters: Array‹function›

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.

Returns: function

A function, if called, will unsubscribe the subscriber.

▸ (): void

unassignItemsToAddress

▸ unassignItemsToAddress(consignment: ConsignmentAssignmentRequestBody, options?: RequestOptions): 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.

Parameters:

Name	Type	Description
`consignment`	ConsignmentAssignmentRequestBody	The consignment data that will be used.
`options?`	RequestOptions	Options for the request

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

updateBillingAddress

▸ updateBillingAddress(address: Partial‹BillingAddressRequestBody›, options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`address`	Partial‹BillingAddressRequestBody›	The address to be used for billing.
`options?`	RequestOptions	Options for updating the billing address.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

updateCheckout

▸ updateCheckout(payload: CheckoutRequestBody, options?: RequestOptions): Promise‹CheckoutSelectors›

Updates specific properties of the current checkout.

const state = await service.updateCheckout(checkout);

console.log(state.data.getCheckout());

Parameters:

Name	Type	Description
`payload`	CheckoutRequestBody	The checkout properties to be updated.
`options?`	RequestOptions	Options for loading the current checkout.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

updateConsignment

▸ updateConsignment(consignment: ConsignmentUpdateRequestBody, options?: RequestOptions): 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());

Parameters:

Name	Type	Description
`consignment`	ConsignmentUpdateRequestBody	The consignment data that will be used.
`options?`	RequestOptions	Options for updating the shipping address.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

updateShippingAddress

▸ updateShippingAddress(address: Partial‹AddressRequestBody›, options?: ShippingRequestOptions‹CheckoutParams›): 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());

Parameters:

Name	Type	Description
`address`	Partial‹AddressRequestBody›	The address to be used for shipping.
`options?`	ShippingRequestOptions‹CheckoutParams›	Options for updating the shipping address.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

updateSubscriptions

▸ updateSubscriptions(subscriptions: Subscriptions, options?: RequestOptions): Promise‹CheckoutSelectors›

Updates the subscriptions associated to an email.

Parameters:

Name	Type	Description
`subscriptions`	Subscriptions	The email and associated subscriptions to update.
`options?`	RequestOptions	Options for continuing as a guest.

Returns: Promise‹CheckoutSelectors›

A promise that resolves to the current state.

Files

checkoutservice.md

Latest commit

History

checkoutservice.md

File metadata and controls

Class: CheckoutService

Hierarchy

Index

Methods

Methods

applyCoupon

applyGiftCertificate

applyStoreCredit

assignItemsToAddress

clearError

continueAsGuest

createConsignments

createCustomerAccount

createCustomerAddress

deinitializeCustomer

deinitializePayment

deinitializeShipping

deleteConsignment

deleteInstrument

executePaymentMethodCheckout

executeSpamCheck

finalizeOrderIfNeeded

getState

initializeCustomer

initializePayment

initializeShipping

initializeSpamProtection

loadBillingAddressFields

loadBillingCountries

loadCheckout

loadInstruments

loadOrder

loadPaymentMethods

loadShippingAddressFields

loadShippingCountries

loadShippingOptions

notifyState

removeCoupon

removeGiftCertificate

selectConsignmentShippingOption

selectShippingOption

sendSignInEmail

signInCustomer

signOutCustomer

submitOrder

subscribe

unassignItemsToAddress

updateBillingAddress

updateCheckout

updateConsignment

updateShippingAddress

updateSubscriptions