Introducing a New Order Status: checkout-draft

tl;dr

There is a new order status coming to WooCommerce. While no immediate action is necessary, developers should familiarize themselves with it now because they may need to update their code to support it.

Background

Over the past year, as part of the ongoing work to improve and expand support for Gutenberg Blocks in WooCommerce, there have been many enhancements that have landed in the feature-plugin version of WooCommerce Blocks. Two of those enhancements are new Blocks for both Cart and Checkout.

In WooCommerce Core, order creation and its peripheral business logic for processes like stock handling, are deeply coupled to the cart object, which makes client-side order creation a challenge. Therefore, to better support the functionality of the new Cart and Checkout Blocks, WooCommerce Blocks also introduced an experimental, public-facing REST API (the Store API). Unlike the WooCommerce Core REST API, this API does not require authentication and is meant for consumption by client-side code like the code that powers the various React components that comprise WooCommerce Blocks.

One of the endpoints available in the Store API handles order creation from the client side using the current cart details, but implementing it revealed a need for a way to identify orders that had been created but which had not yet been placed.

To that end, WooCommerce Blocks now includes a new status that orders may have: checkout-draft.

What are Checkout Drafts?

By default, when WooCommerce creates an order, the status the order receives is Pending. This status represents an order that is complete, which has been submitted, and which is pending payment. For the checkout process that WooCommerce Blocks provides, however, this status doesn’t truly reflect the current state of the order, which might be incomplete or which might not have been submitted yet.

The checkout-draft status provides a more accurate representation of what state these incomplete or un-submitted orders are in when they are created.

What does this mean for me as a developer?

This functionality is currently behind a flag in the feature-plugin version of WooCommerce Blocks. The new checkout-draft status will be only be visible for stores that:

  • have the WooCommerce Blocks feature-plugin active and
  • are using the Cart and Checkout blocks.

For these stores, Checkout Draft orders will show up for any query using wc_get_orders that doesn’t have an explicit status requested. Merchants who see these Checkout Drafts don’t need to take any action; there is a scheduled clean-up action that will automatically delete Checkout Drafts every 24 hours.

While there are currently only a small percentage of stores using the new Cart and Checkout Blocks via the feature-plugin, it’s important that developers be aware of this new status and start testing with it now. It will eventually become part of WooCommerce’s core functionality when the Cart and Checkout Blocks graduate from the feature-plugin to the version of WooCommerce Blocks that is bundled with WooCommerce Core. That inclusion is likely to increase adoption among merchants significantly, so it’s a good idea to get ahead of it.

As the timeline for including the Cart and Checkout Blocks with WooCommerce Core becomes more defined, we plan to publish a follow-up to this post with examples and recommendations to help developers update the code in any extensions that are affected by the new checkout-draft status.

In the meantime, don’t hesitate to reach out to us in the comments section below or in the #developers channel of our WooCommerce Community Slack.


4 responses to “Introducing a New Order Status: checkout-draft”

  1. I find the naming “checkout-draft” not very intuitive. Would call it more like “in-cart” or something more obvious.

    1. Allen Smith Avatar
      Allen Smith

      Howdy! I can see what you mean about the name for this status. One of the reasons we went with checkout-draft was to avoid creating confusion with the cart itself. The developer docs for the Cart and Checkout endpoints in the Store API provide more detail about how the cart is used to create a checkout-draft order and how the objects’ respective API responses differ.

      There is one thing that I neglected to clarify in the original post: since many of these new features are still considered experimental, certain aspects of them may change before they are merged into WooCommerce Core. One of the things that may end up changing is the name of the status.

      1. chizzel415 Avatar

        Hi Allen,

        I’m excited for these changes but I was wondering will it be possible to add a remove all button to the cart page. So if a customer decides they don’t want none of the items in the cart they can remove all with one click.

        1. Allen Smith Avatar
          Allen Smith

          Hi @chizzel415, 👋 This is something that is possible with the Store API. There is an endpoint that allows a developer to remove all items from the cart. There is a bit more documentation about it here: https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/StoreApi/docs/cart-items.md#delete-all-cart-items

Leave a Reply

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