Integrate Checkout in your Storefront Theme

The checkout pages are not considered part of the theme itself. However, when you build your theme, you must complete some additional tasks to ensure that the checkout process works properly.

There are three main parts to the integration process:

• Configure the cart preview
• Configure the "add to cart" behavior
• Configure the product configuration tool

The classic and Plaza base themes provided with the toolkit both integrate all of these features as a reference.

Cart preview

The cart preview consists of a cart icon that appears in your theme header and a preview dialog that appears when a product is added to the cart. provides a cart preview component that you can use in your theme.

Usage

In the header-footer folders, open the logged-in.html template. You can add the cart icon and preview dialog with the following tag:

    {{CART-DROPDOWN-COMPONENT}}

The cart icon appears after you add the tag.

Style cart preview components

To preview the cart in the toolkit, you need a logged-in header. See Create the header and footer.

Hover over the cart to see the default state of the cart. You can style the cart preview through CSS. You cannot change the HTML structure of the cart; however, you can create a custom cart component.

The styles for the cart preview are in the /header-footer/css/header-components/cart.scss file.

To test elements in your cart, click any Add To Cart button or trigger the following function on the window object:

    window.AD_addToCart("123123")

The AD_addToCart function uses mocks, so you can use any random IDs when you call the function.

Create custom cart preview components

Although we provide a default cart on the storefront through a header component, you can use events to create custom cart experiences.

Use the JavaScript addEventListener() method with the following events.

• Update cart preview document.addEventListener('universalnav:update:cart');
• Hide cart preview document.addEventListener('universalnav:hide:cart');
• Add item to cart preview document.addEventListener('universalnav:add:cart');

Add to cart

Theme developers can use a JavaScript window function to support "add to cart" operations. The function requires the plan IDs of the product and add-on editions. It automatically manages the cart preview and user redirection.

Prerequisites

The checkout flow supports either Buy Now or Add to Cart buttons. The information in this section is only relevant if your marketplace uses the Add to Cart button.

To enable the Add to Cart button

1. Go to *Manage > Marketplace > Settings >• Billing Settings | Billing Functionality.
2. In the Product Configurator section, select Add to Cart.
3. At the bottom of the page, click Save Settings.

Usage

Add the following function to your JavaScript code:

    window.AD_addToCart(EditionPlanId, [AddonsPlanId, AddonsPlanId])

You can retrieve the pricing plan ID with the Data viewer. On a product page, navigate to the following data:

    application > editions > items > 0 > plans > 0 > uuid

When activated, the callToActions list can include an Add To Cart action. You must catch the ADD_TO_CART actionType and trigger the AD_addToCart function on click.

Product configurator

The product configurator refers to the part of the checkout process in which a customer selects the edition of a product they want to buy, and chooses any available add-ons. Theme developers can customize the configurator to suit their needs.

Product configuration customization consists of three parts:

• Create the user interface for the edition and add-on listings.
• Manage the states of the selected items.
• Manage how to add items to the cart.

You can view the product configuration page directly in the Storefront Toolkit. Use the following URL pattern:

    /locale/apps/appId/appName/configure

For example:

    /en-US/apps/577/g-suite/configure

Build the user interface

You build the edition and add-on listing user interface with the same lists that appear on the product page: the application > editions and application > addonsProducts page objects.

When you have your lists, you can manage the selected states. The selected editions and add-ons are available under the application > configurator object. It is important to set them as selected when the page loads. There are many scenarios where they might be selected by default, for example when a customer clicks an edition directly on the product page and goes to the configuration page to select add-ons.

The new checkout flow only accepts pricing plan IDs as items to add to carts. As you build the UI, you must maintain a reference to those IDs. You can find them under the edition object (plans > 0 > uuid).

There are two ways to add items to the cart:

• through a Buy button, which sends customers to the cart
• through an Add to Cart action, which keeps customers on the storefront (see Add to cart)

Create the Buy button

Under application > callToAction, the urlCreator object contains the necessary parts to construct the URL for your selected items. For example:

• "base": "https://example.com/api/internal/storefront/v1/cta?productId=577&type=BUY"
• "actionType": "BUY"
• "editionParam": "eppid"
• "addonParam": "appid"

You must use JavaScript to construct the URL for the selected items. A product with one edition and two add-ons selected would resemble the following example:

    https://example.com/api/internal/storefront/v1/cta?productId=577&type=BUY&eppid=123123-123123&appid=1233-123&appid=876-4569