Skip to main content

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.

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 cartStore StoreDescriptor in any module referencing it. Assuming @woocommerce/block-data is registered as an external pointing to wc.wcBlocksData you can import the StoreDescriptor via:

const { cartStore } = 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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
dispatch( setIsCartDataStale( isCartDataStale ) );

updatingCustomerData​

This action returns an action object to indicate if the customer data (billing and/or shipping address) 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( cartStore );
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( cartStore );
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.
    • overwriteDirtyCustomerData boolean: Whether to overwrite the customer data in the client with the data returned from the server, even if it is dirty (i.e. it hasn't been pushed to the server yet).

Example​

const { dispatch } = useDispatch( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
const shippingRates = store.getShippingRates();

getNeedsShipping​

Queries whether the cart needs shipping.

Returns​

  • boolean: True if the cart needs shipping.

Example​

const store = select( cartStore );
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( cartStore );
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( cartStore );
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 (billing and/or shipping address) 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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
const isCartDataStale = store.isCartDataStale();

getCouponBeingApplied​

Returns the coupon code being applied.

Returns​

  • string: The coupon code being applied.

Example​

const store = select( cartStore );
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( cartStore );
const isRemovingCoupon = store.isRemovingCoupon();

getCouponBeingRemoved​

Returns the coupon code being removed.

Returns​

  • string: The coupon code being removed.

Example​

const store = select( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
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( cartStore );
const isCustomerDataUpdating = store.isCustomerDataUpdating();

isAddressFieldsForShippingRatesUpdating​

Queries whether shipping address fields impacting the shipping rates are being updated. By default, Store API considers the following shipping fields as essential for shipping rate calculations: state, country, postcode, and city.

Returns​

  • boolean: True if shipping address fields impacting the shipping rates are being updated.

Example​

const store = select( cartStore );
const isAddressFieldsForShippingRatesUpdating = store.isAddressFieldsForShippingRatesUpdating();

hasPendingItemsOperations​

Queries whether there are any pending cart operations (add, quantity update, or delete items).

Returns​

  • boolean: True if there are pending cart operations (adding products, updating quantities, or deleting items).

Example​

const store = select( cartStore );
const hasPendingItemsOperations = store.hasPendingItemsOperations();

isShippingRateBeingSelected​

Queries whether a shipping rate is being selected.

Returns​

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

Example​

const store = select( cartStore );
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( cartStore );
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( cartStore );
const itemsPendingDelete = store.getItemsPendingDelete();

Use of your personal data

We and our partners process your personal data (such as browsing data, IP Addresses, cookie information, and other unique identifiers) based on your consent and/or our legitimate interest to optimize our website, marketing activities, and your user experience.