cart.md

📣 Announcement: New documentation location

The documentation for WooCommerce Blocks has moved to the WooCommerce monorepo.

Please refer to the documentation in the new location as the files in this repository will no longer be updated and the repository will be archived.

---

Cart Store (wc/store/cart)

💡 What's the difference between the Cart Store and the Checkout Store?

The Cart Store (wc/store/cart) manages and retrieves data about the shopping cart, including items, customer data, and interactions like coupons.

The Checkout Store (wc/store/checkout) manages and retrieves data related to the checkout process, customer IDs, order IDs, and checkout status.

Table of Contents

• Overview
• Usage
• Actions
  • setCartData
  • setErrorData
  • receiveCartContents
  • receiveApplyingCoupon
  • receiveRemovingCoupon
  • receiveCartItem
  • itemIsPendingQuantity
  • itemIsPendingDelete
  • setIsCartDataStale
  • updatingCustomerData
  • shippingRatesBeingSelected
  • applyExtensionCartUpdate
  • applyCoupon
  • removeCoupon
  • addItemToCart
  • removeItemFromCart
  • changeCartItemQuantity
  • selectShippingRate
  • setBillingAddress
  • setShippingAddress
  • updateCustomerData
• Selectors
  • getCartData
  • getCustomerData
  • getShippingRates
  • getNeedsShipping
  • getHasCalculatedShipping
  • getCartTotals
  • getCartMeta
  • getCartErrors
  • isApplyingCoupon
  • isCartDataStale
  • getCouponBeingApplied
  • isRemovingCoupon
  • getCouponBeingRemoved
  • getCartItem( cartItemKey )
  • isItemPendingQuantity( cartItemKey )
  • isItemPendingDelete( cartItemKey )
  • isCustomerDataUpdating
  • isShippingRateBeingSelected
  • getItemsPendingQuantityUpdate
  • getItemsPendingDelete

Overview

The Cart Store provides a collection of selectors and methods to manage and retrieve cart-related data for WooCommerce Blocks. It offers functionality ranging from fetching cart details to managing customer interactions, such as applying coupons or updating shipping information.

Usage

To utilize this store you will import the CART_STORE_KEY in any module referencing it. Assuming @woocommerce/block-data is registered as an external pointing to wc.wcBlocksData you can import the key via:

const { CART_STORE_KEY } = window.wc.wcBlocksData;

Actions

setCartData

This action is used to set the cart data in the store.

Parameters

• cartData object: The current cart data with the following keys:
  • coupons array: The coupon items in the cart.
  • shippingRates array: The cart shipping rates (see getShippingRates selector).
  • shippingAddress object: The shipping address (see getCustomerData selector).
  • billingAddress object: The billing address (see getCustomerData selector).
  • items array: The cart items.
  • itemsCount number: The total number of items in the cart
  • itemsWeight number: The total weight of items in the cart.
  • crossSells array: The cross sells items.
  • needsPayment boolean: If the cart needs payment.
  • needsShipping boolean: If the cart needs shipping.
  • hasCalculatedShipping boolean: If the cart has calculated shipping.
  • fees array: The cart fees.
  • totals object: The cart totals (see getCartTotals selector).
  • errors array: The cart errors (see getCartErrors selector).
  • paymentRequirements object: The payment requirements for the cart.
  • extensions object: The extensions data.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setCartData( newCartData ) );

setErrorData

This action is used to set the error data in the store.

Parameters

• errorData object: The error data that needs to be set in the store.
  • code string: The error code.
  • message string: The error message.
  • data object: Additional error data. This is an optional object with the following keys:
    • status number: The error status.
    • params string: The error params.
    • message string: The error message.
    • cart object: The cart data. This is an optional object with the following keys:
      • coupons array: The coupon items in the cart.
      • shippingRates array: The cart shipping rates (see getShippingRates selector).
      • shippingAddress object: The shipping address (see getCustomerData selector).
      • billingAddress object: The billing address (see getCustomerData selector).
      • items array: The cart items.
      • itemsCount number: The total number of items in the cart
      • itemsWeight number: The total weight of items in the cart.
      • crossSells array: The cross sells items.
      • needsPayment boolean: If the cart needs payment.
      • needsShipping boolean: If the cart needs shipping.
      • hasCalculatedShipping boolean: If the cart has calculated shipping.
      • fees array: The cart fees.
      • totals object: The cart totals (see getCartTotals selector).
      • errors array: The cart errors (see getCartErrors selector).
      • paymentRequirements object: The payment requirements for the cart.
      • extensions object: The extensions data.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setErrorData( newErrorData ) );

receiveCartContents

This action returns an action object used in updating the store with the provided cart. It omits the customer addresses so that only updates to cart items and totals are received.

Parameters

• cartContents object: A cart contents API response.
  • coupons array: The coupon items in the cart.
  • shippingRates array: The cart shipping rates (see getShippingRates selector).
  • shippingAddress object: The shipping address (see getCustomerData selector).
  • billingAddress object: The billing address (see getCustomerData selector).
  • items array: The cart items.
  • itemsCount number: The total number of items in the cart
  • itemsWeight number: The total weight of items in the cart.
  • crossSells array: The cross sells items.
  • needsPayment boolean: If the cart needs payment.
  • needsShipping boolean: If the cart needs shipping.
  • hasCalculatedShipping boolean: If the cart has calculated shipping.
  • fees array: The cart fees.
  • totals object: The cart totals (see getCartTotals selector).
  • errors array: The cart errors (see getCartErrors selector).
  • paymentRequirements object: The payment requirements for the cart.
  • extensions object: The extensions data.

Returns

• object: The action object with the following keys:
  • type string: The action type.
  • cartContents object: The cart contents with the following keys:
    • coupons array: The coupon items in the cart.
    • shippingRates array: The cart shipping rates (see getShippingRates selector).
    • items array: The cart items.
    • itemsCount number: The total number of items in the cart
    • itemsWeight number: The total weight of items in the cart.
    • crossSells array: The cross sells items.
    • needsPayment boolean: If the cart needs payment.
    • needsShipping boolean: If the cart needs shipping.
    • hasCalculatedShipping boolean: If the cart has calculated shipping.
    • fees array: The cart fees.
    • totals object: The cart totals (see getCartTotals selector).
    • errors array: The cart errors (see getCartErrors selector).
    • paymentRequirements object: The payment requirements for the cart.
    • extensions object: The extensions data.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveCartContents( newCartContents ) );

receiveApplyingCoupon

This action returns an action object used to track when a coupon is applying.

Parameters

• couponCode string: The code of the coupon being applied.

Returns

• object: The action object with following keys:
  • type string: The action type.
  • couponCode string: The code of the coupon being applied.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveApplyingCoupon( couponCode ) );

receiveRemovingCoupon

This action returns an action object used to track when a coupon is removing.

Parameters

• couponCode string: The code of the coupon being removed.

Returns

• object: The action object with the following keys:
  • type string: The action type.
  • couponCode string: The code of the coupon being removed.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveRemovingCoupon( couponCode ) );

receiveCartItem

This action is used to update a specific item in the cart.

Parameters

• cartResponseItem object: Cart response object with the following keys:
  • cartItem object: The cart item (see getCartItem selector).

Returns

• object: The action object with the following keys:
  • type string: The action type.
  • cartItem object: The cart item (see getCartItem selector).

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveCartItem( CartResponseItem ) );

itemIsPendingQuantity

This action returns an action object to indicate if the specified cart item quantity is being updated.

Parameters

• cartItemKey string: The key of the cart item.
• isPending boolean (default: true): Whether the cart item quantity is being updated.

Returns

• object: The action object with following keys:
  • type string: The action type.
  • cartItemKey string: The key of the cart item.
  • isPending boolean: Whether the cart item quantity is being updated.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( itemIsPendingQuantity( cartItemKey, isPending ) );

itemIsPendingDelete

This action returns an action object to indicate if the specified cart item is being deleted.

Parameters

• cartItemKey string: The key of the cart item.
• isPending boolean (default: true): Whether the cart item is being deleted.

Returns

• object: The action object with the following keys:
  • type string: The action type.
  • cartItemKey string: The key of the cart item.
  • isPending boolean: Whether the cart item is being deleted.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( itemIsPendingDelete( cartItemKey, isPending ) );

setIsCartDataStale

This action returns an action object to indicate if the cart data is stale.

Parameters

• isCartDataStale boolean (default: true): Flag to mark cart data as stale; true if lastCartUpdate timestamp is newer than the one in wcSettings.

Returns

• object: The action object with the following keys:
  • type string: The action type.
  • isCartDataStale boolean: Flag to mark cart data as stale; true if lastCartUpdate timestamp is newer than the one in wcSettings.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setIsCartDataStale( isCartDataStale ) );

updatingCustomerData

This action returns an action object to indicate if the customer data is being updated.

Parameters

• isResolving boolean: Whether the customer data is being updated.

Returns

• object: The action object with the following keys:
  • type string: The action type.
  • isResolving boolean: Whether the customer data is being updated.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( updatingCustomerData( isResolving ) );

shippingRatesBeingSelected

This action returns an action object to indicate if the shipping rates are being selected.

Parameters

• isResolving boolean: True if shipping rate is being selected.

Returns

• object: The action object with the following keys:
  • type string: The action type.
  • isResolving boolean: True if shipping rate is being selected.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( shippingRatesBeingSelected( isResolving ) );

applyExtensionCartUpdate

This action is used to send POSTs request to the /cart/extensions endpoint with the data supplied by the extension.

Parameters

• args object: The arguments for the request with the following keys:
  • extensionId string: The extension ID.
  • data object: The data to send to the endpoint with the following keys:
    • key string: The key of the extension.
    • value string: The value of the extension.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( applyExtensionCartUpdate( args ) );

applyCoupon

This action is used to apply a coupon to the cart.

Parameters

• couponCode string: The code of the coupon to apply.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( applyCoupon( couponCode ) );

removeCoupon

This action is used to remove a coupon from the cart.

Parameters

• couponCode string: The code of the coupon to remove.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( removeCoupon( couponCode ) );

addItemToCart

This action is used to add an item to the cart.

Parameters

• productId number: Product ID to add to cart.
• quantity number (default: 1): The quantity of the product to add.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( addItemToCart( productId, quantity ) );

removeItemFromCart

This action is used to remove an item from the cart.

Parameters

• cartItemKey string: Cart item being updated.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( removeItemFromCart( cartItemKey ) );

changeCartItemQuantity

This action is used to change the quantity of an item in the cart.

Parameters

• cartItemKey string: Cart item being updated.
• quantity number: Quantity of the item.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( changeCartItemQuantity( cartItemKey, quantity ) );

selectShippingRate

This action is used to select a shipping rate for the cart.

Parameters

• rateId string: The ID of the shipping rate to select.
• packageId number | string (default: null): The key of the packages that will select within the shipping rate.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( selectShippingRate( rateId, packageId ) );

setBillingAddress

This action is used to set the billing address for the cart locally, as opposed to updateCustomerData which sends it to the server.

Parameters

• billingAddress object: Billing address that needs to be set. The keys are as following:
  • first_name string: The first name.
  • last_name string: The last name.
  • company string: The company name.
  • address_1 string: The address line 1.
  • address_2 string: The address line 2.
  • city string: The city name.
  • state string: The state name.
  • postcode string: The postcode.
  • country string: The country name.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setBillingAddress( billingAddress ) );

setShippingAddress

This action is used to set the shipping address for the cart locally, as opposed to updateCustomerData which sends it to the server.

Parameters

• shippingAddress object: Shipping address that needs to be set. The keys are as following:
  • first_name string: The first name.
  • last_name string: The last name.
  • company string: The company name.
  • address_1 string: The address line 1.
  • address_2 string: The address line 2.
  • city string: The city name.
  • state string: The state name.
  • postcode string: The postcode.
  • country string: The country name.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setShippingAddress( shippingAddress ) );

updateCustomerData

This action is used to updates the shipping and/or billing address for the customer and returns an updated cart.

Parameters

• customerData object: Customer billing and shipping address. The keys are as following:
  • shippingAddress object: The shipping address with the following keys:
    • first_name string: The first name.
    • last_name string: The last name.
    • company string: The company name.
    • address_1 string: The address line 1.
    • address_2 string: The address line 2.
    • city string: The city name.
    • state string: The state name.
    • postcode string: The postcode.
    • country string: The country name.
  • billingAddress object: The billing address (same keys as shipping address).
• editing: boolean (default: true): If the address is being edited, we don't update the customer data in the store from the response.

Example

const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( updateCustomerData( customerData, editing ) );

Selectors

getCartData

Returns the Cart data from the state.

Returns

• object: The current cart data with the following keys:
  • coupons array: The coupon items in the cart.
  • shippingRates array: The cart shipping rates (see getShippingRates selector).
  • shippingAddress object: The shipping address (see getCustomerData selector).
  • billingAddress object: The billing address.
  • items array: The cart items.
  • itemsCount number: The total number of items in the cart
  • itemsWeight number: The total weight of items in the cart.
  • crossSells array: The cross sells items.
  • needsPayment boolean: If the cart needs payment.
  • needsShipping boolean: If the cart needs shipping.
  • hasCalculatedShipping boolean: If the cart has calculated shipping.
  • fees array: The cart fees.
  • totals object: The cart totals (see getCartTotals selector).
  • errors array: The cart errors (see getCartErrors selector).
  • paymentRequirements object: The payment requirements for the cart.
  • extensions object: The extensions data.

Example

const store = select( CART_STORE_KEY );
const cartData = store.getCartData();

getCustomerData

Returns the shipping and billing address from the state.

Returns

• object: The current shipping and billing address with the following keys:
  • shippingAddress object: The shipping address with the following keys:
    • first_name string: The first name.
    • last_name string: The last name.
    • company string: The company name.
    • address_1 string: The address line 1.
    • address_2 string: The address line 2.
    • city string: The city name.
    • state string: The state name.
    • postcode string: The postcode.
    • country string: The country name.
  • billingAddress object: The billing address (same keys as shipping address).

Example

const store = select( CART_STORE_KEY );
const customerData = store.getCustomerData();

getShippingRates

Returns the shipping rates from the state.

Returns

• array: The shipping rates. They keys are as following:
  • id string: The shipping rate ID.
  • label string: The shipping rate label.
  • cost string: The shipping rate cost.
  • package_id number: The shipping rate package ID.
  • meta_data array: The shipping rate meta data. The keys are as following:
    • id number: The shipping rate meta data ID.
    • key string: The shipping rate meta data key.
    • value string: The shipping rate meta data value.
  • taxes array: The shipping rate taxes.

Example

const store = select( CART_STORE_KEY );
const shippingRates = store.getShippingRates();

getNeedsShipping

Queries whether the cart needs shipping.

Returns

• boolean: True if the cart needs shipping.

Example

const store = select( CART_STORE_KEY );
const needsShipping = store.getNeedsShipping();

getHasCalculatedShipping

Queries whether the cart shipping has been calculated.

Returns

• boolean: True if the shipping has been calculated.

Example

const store = select( CART_STORE_KEY );
const hasCalculatedShipping = store.getHasCalculatedShipping();

getCartTotals

Returns the cart totals from state.

Returns

• object: The current cart totals with the following keys:
  • total_items string: The sum total of items in the cart without discount, tax or shipping.
  • total_items_tax string: The total tax on all items before discount.
  • total_fees string: The total transaction fees.
  • total_fees_tax string: The tax on the total transaction fees.
  • total_discount string: The total discount applied to the cart.
  • total_discount_tax string: The tax applied to the total discount amount.
  • total_shipping string: The total shipping cost.
  • total_shipping_tax string: The tax applied to the total shipping cost.
  • total_tax string: The total tax applied to the cart.
  • total_price string: The total price of the cart including discount, tax or shipping.
  • tax_lines array of object: The tax lines: name, price, and rate.
  • currency_code string: The currency code for the cart.
  • currency_symbol string: The currency symbol for the cart.
  • currency_minor_unit integer: The currency minor unit for the cart.
  • currency_decimal_separator string: The currency decimal separator for the cart.
  • currency_thousand_separator string: The currency thousand separator for the cart.
  • currency_prefix string: The currency prefix for the cart.
  • currency_suffix string: The currency suffix for the cart.

Example

const store = select( CART_STORE_KEY );
const cartTotals = store.getCartTotals();

getCartMeta

Returns the cart meta from state.

Returns

• object: The current cart meta with the following keys:
  • updatingCustomerData boolean: If the customer data is being updated.
  • updatingSelectedRate boolean: If the selected rate is being updated.
  • isCartDataStale boolean: If the cart data is stale.
  • applyingCoupon string: The coupon code being applied.
  • removingCoupon string: The coupon code being removed.

Example

const store = select( CART_STORE_KEY );
const cartMeta = store.getCartMeta();

getCartErrors

Returns the cart errors from state if cart receives customer facing errors from the API.

Returns

• array: The cart errors with the following keys:
  • code string: The error code.
  • message string: The error message.
  • data object: API response data.

Example

const store = select( CART_STORE_KEY );
const cartErrors = store.getCartErrors();

isApplyingCoupon

Queries whether a coupon is being applied.

Returns

• boolean: True if a coupon is being applied.

Example

const store = select( CART_STORE_KEY );
const isApplyingCoupon = store.isApplyingCoupon();

isCartDataStale

Queries whether the cart data is stale.

Returns

• boolean: True if the cart data is stale.

Example

const store = select( CART_STORE_KEY );
const isCartDataStale = store.isCartDataStale();

getCouponBeingApplied

Returns the coupon code being applied.

Returns

• string: The coupon code being applied.

Example

const store = select( CART_STORE_KEY );
const couponBeingApplied = store.getCouponBeingApplied();

isRemovingCoupon

Queries whether a coupon is being removed.

Returns

• boolean: True if a coupon is being removed.

Example

const store = select( CART_STORE_KEY );
const isRemovingCoupon = store.isRemovingCoupon();

getCouponBeingRemoved

Returns the coupon code being removed.

Returns

• string: The coupon code being removed.

Example

const store = select( CART_STORE_KEY );
const couponBeingRemoved = store.getCouponBeingRemoved();

getCartItem( cartItemKey )

Returns a cart item from the state.

Parameters

• cartItemKey string: The cart item key.

Returns

• object: The cart item with the following keys:
  • key string: The cart item key.
  • id number: The cart item id.
  • catalog_visibility string: The catalog visibility.
  • quantity_limits object: The quantity limits.
  • name string: The cart item name.
  • summary string: The cart item summary.
  • short_description string: The cart item short description.
  • description string: The cart item description.
  • sku string: The cart item sku.
  • low_stock_remaining null or number: The low stock remaining.
  • backorders_allowed boolean indicating if backorders are allowed.
  • show_backorder_badge boolean indicating if the backorder badge should be shown.
  • sold_individually boolean indicating if the item is sold individually.
  • permalink string: The cart item permalink.
  • images array: The cart item images.
  • variation array: The cart item variation.
  • prices object: The cart item prices with the following keys:
    • currency_code string: The currency code.
    • currency_symbol string: The currency symbol.
    • currency_minor_unit number: The currency minor unit.
    • currency_decimal_separator string: The currency decimal separator.
    • currency_thousand_separator string: The currency thousand separator.
    • currency_prefix string: The currency prefix.
    • currency_suffix string: The currency suffix.
    • price string: The cart item price.
    • regular_price string: The cart item regular price.
    • sale_price string: The cart item sale price.
    • price_range string: The cart item price range.
  • totals object: The cart item totals with the following keys:
    • currency_code string: The currency code.
    • currency_symbol string: The currency symbol.
    • currency_minor_unit number: The currency minor unit.
    • currency_decimal_separator string: The currency decimal separator.
    • currency_thousand_separator string: The currency thousand separator.
    • currency_prefix string: The currency prefix.
    • currency_suffix string: The currency suffix.
    • line_subtotal string: The cart item line subtotal.
    • line_subtotal_tax string: The cart item line subtotal tax.
    • line_total string: The cart item line total.
    • line_total_tax string: The cart item line total tax.

Example

const store = select( CART_STORE_KEY );
const cartItem = store.getCartItem( cartItemKey );

isItemPendingQuantity( cartItemKey )

Queries whether a cart item is pending quantity.

Parameters

• cartItemKey string: The cart item key.

Returns

• boolean: True if the cart item is pending quantity.

Example

const store = select( CART_STORE_KEY );
const isItemPendingQuantity = store.isItemPendingQuantity( cartItemKey );

isItemPendingDelete( cartItemKey )

Queries whether a cart item is pending delete.

Parameters

• cartItemKey string: The cart item key.

Returns

• boolean: True if the cart item is pending delete.

Example

const store = select( CART_STORE_KEY );
const isItemPendingDelete = store.isItemPendingDelete( cartItemKey );

isCustomerDataUpdating

Queries whether the customer data is being updated.

Returns

• boolean: True if the customer data is being updated.

Example

const store = select( CART_STORE_KEY );
const isCustomerDataUpdating = store.isCustomerDataUpdating();

isShippingRateBeingSelected

Queries whether a shipping rate is being selected.

Returns

• boolean: True if a shipping rate is being selected.

Example

const store = select( CART_STORE_KEY );
const isShippingRateBeingSelected = store.isShippingRateBeingSelected();

getItemsPendingQuantityUpdate

Retrieves the item keys for items whose quantity is currently being updated.

Returns

• string[]: An array with the item keys for items whose quantity is currently being updated.

Example

const store = select( CART_STORE_KEY );
const itemsPendingQuantityUpdate = store.getItemsPendingQuantityUpdate();

getItemsPendingDelete

Retrieves the item keys for items that are currently being deleted.

Returns

• string[]: An array with the item keys for items that are currently being deleted.

Example

const store = select( CART_STORE_KEY );
const itemsPendingDelete = store.getItemsPendingDelete();

---

We're hiring! Come work with us!

🐞 Found a mistake, or have a suggestion? Leave feedback about this document here.