Available Extensibility Interfaces for the Cart and Checkout blocks

The Cart and Checkout blocks are still in early access (via the feature plugin). It’s expected that some existing WooCommerce Extensions, that integrate with the current checkout flow in WooCommerce core, will not work with the Cart and Checkout blocks.

We keep a list of the supported extensions; outside the extensions on this list, it’s up to third-party developers to add support for the new checkout flow offered via the Cart and Checkout blocks. 

With that in mind, this post has been written to offer third-party developers a tour through the available extensibility interfaces they can use to extend the Cart and Checkout blocks functionality for integrating their products.

A look at Our Main Architecture

From a merchant perspective, the Cart and Checkout blocks are parent blocks, with a collection of inner blocks: core and user-defined blocks. The parent blocks handle the framework part: initializing state, fetching data, sharing data between inner blocks, and processing orders. The inner blocks are responsible for rendering a section of the Cart and Checkout block, and communicating changes that happen at their level up to the corresponding parent block. 

Interacting with the Cart block’s inner blocks in the editor

Despite the flexibility of the blocks, the architecture of the parent blocks is not decoupled, and it won’t be possible to take a core inner block and replace it with a third-party block. Furthermore, to ensure an optimal checkout experience, we lock these core blocks. Therefore, a merchant can’t just delete or move a section because it could jeopardize the checkout experience (and the higher conversion rates we are seeing with the current structure).

For data, the Cart and Checkout blocks rely on the WooCommerce Store API to interact with the WooCommerce store. This data is fetched from the server and displayed in the blocks. The data is updated as a result of shopper interactions with the blocks.

Extensibility 

During our efforts to help merchants to customize checkout flows, we were able to identify, build, and validate extensibility interfaces. This section documents the available extensibility interfaces:

Extensibility on the Front-End Side

Adding Custom Content to the Cart and Checkout Blocks

Checkout – Blocks Registry

When it comes to customizing the content of the Cart and Checkout blocks, adding custom inner blocks is the main and recommended way. You can create custom blocks that can be inserted automatically or optionally, moved or locked to a place, can be edited, and have attributes and settings, just as the core inner blocks.

Image of the Checkout Block
The Checkout block has several areas in which inner blocks can be registered and added. Once registered, blocks can be inserted by merchants.

For information about creating and configuring an inner block see our documentation on GitHub:

Checkout – Blocks Registry


Slot and Fill

Another tool for adding your custom content in specific places in the Cart and Checkout blocks is Slot and Fill. It gives you the possibility to render your own HTML in pre-defined places in the Cart and Checkout blocks. Your component will get access to contextual data and will get re-rendered when needed.

Available Slots
ExperimentalOrderMeta
ExperimentalOrderShippingPackages
ExperimentalDiscountsMeta
Please note that the list might change as we are continuously working on graduating or removing experimental features
ExperimentalOrderMeta Slot Example

This Slot renders below the Checkout summary section and above the “Proceed to Checkout” button in the Cart.

Example of a Fill using the ExperimentalOrderMeta Slot in the Cart block
ExperimentalOrderShippingPackages Slot Example

This slot renders inside the shipping step of Checkout and inside the shipping options in Cart.

Example of a Fill using the ExperimentalOrderShippingPackages Slot in the Cart block
ExperimentalDiscountsMeta Slot Example

This slot renders below the Coupon code input.

Example of a Fill using the ExperimentalDiscountsMeta Slot in the Cart block

Read more about Slot and Fill on our GitHub documentation files:


Modifying existing Cart and Checkout Block Fields

Checkout JS filters

We have implemented a Filter registry that allows callbacks to be registered to manipulate certain values in the Cart and Checkout blocks. This is similar to the traditional filter system in WordPress, where you register a callback with a specific filter and return a modified value.

We offer a variety of filters to extend the way certain strings are displayed:

Available Filters
Cart Line Items
Order Summary Items
Totals footer item
Coupons
Snackbar notices
Examples

Changing the wording of the Totals label in the Cart and Checkout blocks using the Totals footer item filter:

BeforeAfter

Changing the name of a coupon using the Coupons Filter filter:

BeforeAfter

Changing the format of the item’s single price with a custom filter:

BeforeAfter

For a full overview, head to our GitHub documentation:


Exposing Your Data in the Store API

ExtendRestApi

When you are extending the Cart and Checkout blocks you might need to access some custom, business-related logic. If you would rather not create your own endpoints you can append your data to the WooCommerce Store API using ExtendRestApi. 

ExtendRestApi offers the possibility to add contextual custom data to the wc/store/cart and wc/store/cart/items endpoints. The data, which will live under the extensions key, is namespaced to your plugin and protected from other plugins causing it to malfunction. The data is available on all Frontend filters and Slot and Fill for you to consume.

For information about handling GET and POST requests, see our GitHub documentation:


Payment Gateways

Extensibility on the Payment gateways side has been one of our most important focuses, and we have been writing about it in the past. 

The Payment Method API

We offer an extensive Payment Method API for you to integrate a payment gateway or an express payment gateway like WooCommerce Pay, Stripe, PayPal, Square.

This document covers the Payment Method API

Filtering Payment Methods

Separate from the Payment API, you can also filter out payment methods. For the cases where some payment gateways don’t fit your product type (for example subscriptions, bookings, etc.) or you want to add special conditions to certain payment gateways we offer two APIs:

Extensibility on the Server Side (Hooks)

There are also some PHP action and filter hooks provided for extending various aspects of checkout behaviour on the server. Keep in mind that it’s generally preferable to use extension interfaces like the IntegrationRegistry instead of filters and actions as they provide a more stable way to integrate. However, these filters and actions still allow for some more flexibility in complex integrations.

Actions
woocommerce_add_to_cart
woocommerce_applied_coupon
woocommerce_blocks_cart_enqueue_data
woocommerce_blocks_checkout_enqueue_data
woocommerce_blocks_checkout_order_processed (deprecated)
woocommerce_blocks_checkout_update_order_from_request (deprecated)
woocommerce_blocks_checkout_update_order_meta (deprecated)
woocommerce_blocks_enqueue_cart_block_scripts_after
woocommerce_blocks_enqueue_cart_block_scripts_before
woocommerce_blocks_enqueue_checkout_block_scripts_after
woocommerce_blocks_enqueue_checkout_block_scripts_before
woocommerce_blocks_loaded
woocommerce_blocks_{$this->registry_identifier}_registration
woocommerce_check_cart_items
woocommerce_created_customer
woocommerce_register_post
woocommerce_rest_checkout_process_payment_with_context

woocommerce_store_api_checkout_order_processed
woocommerce_store_api_checkout_update_order_from_request
woocommerce_store_api_checkout_update_order_meta
wooocommerce_store_api_validate_add_to_cart
wooocommerce_store_api_validate_cart_item

Please note that the list might change as we are continuously working on graduating or removing experimental features
Filters
__experimental_woocommerce_blocks_add_data_attributes_to_block
__experimental_woocommerce_blocks_add_data_attributes_to_namespace
__experimental_woocommerce_blocks_payment_gateway_features_list
wc_stripe_allow_prepaid_card (deprecated)
wc_stripe_display_save_payment_method_checkbox (deprecated)
wc_stripe_payment_request_button_locale (deprecated)
woocommerce_add_cart_item
woocommerce_add_cart_item_data
woocommerce_add_to_cart_sold_individually_quantity
woocommerce_add_to_cart_validation
woocommerce_adjust_non_base_location_prices
woocommerce_apply_individual_use_coupon
woocommerce_apply_with_individual_use_coupon
woocommerce_blocks_product_grid_is_cacheable
woocommerce_blocks_product_grid_item_html
woocommerce_blocks_register_script_dependencies
woocommerce_cart_contents_changed
woocommerce_ga_disable_tracking
woocommerce_get_item_data
woocommerce_new_customer_data
woocommerce_registration_errors
woocommerce_shared_settings
woocommerce_shipping_package_name
woocommerce_store_api_disable_nonce_check
woocommerce_store_api_product_quantity_limit
woocommerce_variation_option_name
Please note that the list might change as we are continuously working on graduating or removing experimental features

For more details, please head to our GitHub documentation:  


We are here for you

We aren’t done with building extension interfaces, and we invite you to peek into the WooCommerce Blocks Roadmap for some insight into our plans for the blocks. We encourage you to start experimenting and trying out integrating your extensions. Our engineers will be available for technical guidance on any questions that might arise, so feel free to create issues in the Woo Blocks repository if you are having difficulty integrating your extension with the available Woo Blocks integration points.


4 responses to “Available Extensibility Interfaces for the Cart and Checkout blocks”

  1. Incorrect link for Extensibility on the server (backend) of the store. Please fix!

    1. Thank you so much @yourkoolpal for pointing this out. The link is now fixed.

  2. it’s up to third-party developers to add support for the new checkout flow offered via the Cart and Checkout blocks.

    and

    Despite the flexibility of the blocks, the architecture of the parent blocks is not decoupled and it won’t be possible to take a core inner block and replace it with a third-party block.

    Seem at odds? How do we ensure compatibility when it’s not yet possible to make the required changes? For example, I need to be able to remove the quantity buttons in certain places to fix compatibility with 2 of my plugins.

    I do see that it’s now possible to tweak the subtotal and price at the line item level… cool! Is there a functioning example of that? And can it be done conditionally based on the line item? Previously have been able to do things with $cart_item data array… what’s the new equivalent?

    1. Hi @kathydarling9,
      Thank you so much for reaching out. This type of feedback about missing extensibility interfaces helps us prioritize what to work on next. It also gives us a feel for where we might want to focus on first for providing tutorials and examples.

      How do we ensure compatibility when it’s not yet possible to make the required changes?

      We’re not done yet 🙂 If the existing interfaces don’t provide what you need for enhancing your extension so it’s compatible with WooCommerce blocks, definitely reach out to us (like you’re doing now)! This post is intended to be a window into what is available now, anticipating that there are a number of extensions that will have what they need. We definitely know there’s more to do.

      For example, I need to be able to remove the quantity buttons in certain places to fix compatibility with 2 of my plugins.

      Taking the quantity example, this is something we wanted to avoid acting on until we heard some use cases in different plugins that made sense for how we’re going to implement it, and is something that’s on our immediate pipeline. We can take a look at some use cases we are trying to cover for now 1, 2

      I do see that it’s now possible to tweak the subtotal and price at the line item level… cool! Is there a functioning example of that?

      You should use the Order Summary Items filter. We have an example for changing the format of the item’s single price in the same doc file. If this isn’t sufficient, let us know and we’ll look at adding this to our list of things to evaluate and support in future iterations.

      And can it be done conditionally based on the line item?

      Yes, the callback function you will use for changing the values receives an arg parameter that holds the cartItem value.

      [code lang=text]
      const yourFunction = ( value, extensions, args ) => {

      };
      [/code]

Leave a Reply

Your email address will not be published. Required fields are marked *