The new Store API is something we’ve been building alongside the Cart and Checkout Blocks for the past two years. It not only powers the new Block based Cart and Checkout experience, but also the various product Blocks as well.
As part of WooCommerce Blocks 7.2 (and the upcoming WooCommerce 6.4 release) this API can now be considered stable. It has been finalised, versioned, and can now be utilised by developers more easily!
What is the Store API exactly?
Making sure that Store API is agnostic to the view part was a critical step. Along the way, we also tried to make it environment agnostic.
Nadir Seghir, Cart & Checkout Engineer
The WooCommerce Store API provides public REST API endpoints for the development of customer-facing cart, checkout, and product functionality.
Since it follows many of the patterns used in the WordPress REST API, it should be familiar to developers who have worked with APIs before.
Whilst the Store API is heavily utilised by the Cart and Checkout Blocks, it is built in such a way that it works independently so it can be consumed by anyone.
What blocks are using the Store API?
The Store API is already being used throughout WooCommerce Blocks.
All Products Block
Gets products from the Store API to display via the wc/store/v1/products endpoint. The product filter blocks also use Store API to limit which products are shown.
Cart Block
Updates cart items, calculates totals, and shows available shipping options/shipping calculator. Also has a coupon form. Gets data via wc/store/v1/cart.
Checkout Block
Updates customer session data, calculates shipping, and creates orders/processes payments via the wc/store/v1/checkout endpoint.
How does the Store API compare to the WC REST API?
The main difference between the Store API and WC REST API is that the Store API allows unauthenticated access to store data, for example, products. This makes it suitable for a variety of use-cases, including custom frontends.
This is an unauthenticated API. It does not require API keys or authentication tokens for access.
Another difference is that the Store API has support for Cart data. This allows for cart operations such as adding items to the cart, updating quantities, applying coupons, and submitting orders. Only the current customer’s cart can be accessed.
Data returned from the Store API is always reflective of the current user (cookie-based), whereas the WC REST API allows more extensive access to any data, should you have the correct access rights.
API Versioning
Now that a v1 of the API has been released (under the namespace wc/store/v1), this API can be considered stable.
The Store API establishes a contract between itself and API consumers via the use of Schema. This contract should not be broken unless absolutely necessary.
As our guiding principles explain, no breaking changes are permitted, only changes which are backwards compatible. Some examples of allowed changes include:
- Adding new properties to schema
- Adding new routes, endpoints, methods
- Adding optional request parameters
- Re-ordering response fields
If ever the need arises for a non-backwards compatible change, we’d release a new version (wc/store/v2) leaving the v1 route intact and unaltered.
Examples
Here is a basic example showing how to query products using cURL and return the results in JSON format:
curl "https://example-store.com/wp-json/wc/store/v1/products"Here is another example, querying a single product by it’s ID and sending the results to jq for formatting:
curl "https://store.local/wp-json/wc/store/v1/products/35" | jq '.'
Using Insomnia API client
To demonstrate what is possible using the Store API, we can actually go through the entire purchase flow using just an API client–not even visiting the store!
First, I can get a list of products from /wc/store/v1/products. This returns products in JSON format and shows product IDs and pricing information:
We can then pick which product we’d like to add to the cart, and go ahead and add it via the /wc/store/v1/cart/add-item route. This will either add the item to the cart, returning the new updated cart object, or return an error response if something went wrong.
With the item now in the cart, we can attempt to purchase it using the /wc/store/v1/checkout endpoint. This requires a billing and shipping address, and a chosen payment method. The payload we send looks something like this:
{
"billing_address": {
"first_name": "Steve",
"last_name": "Stevenson",
"email": "test@test.com",
"address_1": "41 Some Street",
"city": "Townford",
"postcode": "CB25 6FG",
"country": "GB"
},
"shipping_address": {
"first_name": "Steve",
"last_name": "Stevenson",
"address_1": "41 Some Street",
"city": "Townford",
"postcode": "CB25 6FG",
"country": "GB"
},
"payment_method": "bacs"
}We also need a special header (Nonce) to confirm the user actually wants to checkout. This header is returned via other requests so can be stored in your client.
Once we send our payload and Nonce header, we’ll get either an error or success response back from the API, and we’re done! We can now see the successfully placed order in WooCommerce admin!
With this success, we can now see the successfully placed order in WooCommerce admin!
Further Reading
If you’d like to learn more about the Store API and how you can use it in extensions or custom code, check out the following resources:
For feedback, reporting issues, or submitting feature requests, you can do so here on GitHub.
Leave a Reply