Requirements

[gabesullice]

It'd be great to have a clearly defined set of requirements for a decoupled cart API.

Like:

• It should be possible to add an item to a user's cart.
  • Constraints:
  • There can be >1 cart
  • The user might not yet have a cart
• It should be possible to fetch all items in all carts
• It should be possible to fetch all items in a particular cart
• It should be possible to remove an item from a cart
• It should be possible to remove all items from a cart
• It should be possible to remove an item from all carts
• It should be possible to remove an item from all carts
• It should be possible to get a list of all carts
• it should be possible to change the quantity of an item in a cart

Are all of these requirements? Can some of them be removed? Did I miss constraints?

What's the data model? What entity types are involved? A user entity. A cart entity (with bundles?), an order item entity?

How do those entities relate to one another? Via entity reference fields? Something else?

From there, I'd love to work out a spec for a cart API. Rather than starting from the implementation, that would help me know how I could best help you.

A spec would make it more clear to me what public JSON:API PHP APIs are needed than reverse engineering an experimental implementation.

I'm sure that what is easiest to get working today is not a 1:1 match to what would be easiest with an explicitly designed API.

[mglaman]

Thanks for writing this up. I will work to clarify and extend as needed.

[mglaman]

Here is step 1 to define the data model and workflow. I am working backwards to get to a user story like statement

Cart / Order Data model

A cart is an order which is in a draft state and has the cart boolean marked as true. The latter option is part of our CartProvider and CartManager APIs. Cart can be considered as a module that provides access control and management to non-elevated users.

An order has the following entity references:

• The user entity it belongs to.
• The profile entity that serves as the billing profile for the order.
• The order items that belong to the order, an order can have one to multiple order items.
• The store the order is for.
• The order type (bundle), which maintains information on how we handle checkout, workflow, and more.

An order item represents something that has been purchased and belongs to one order. The order item's bundle defines what purchasable entity type_ it references. An order item may not reference any purchasable entities. The default purchasable entity available is there Product Variation entity. Although any entity implementing PurchasableEntityInterface is allowed. We rely heavily upon the PurchasableEntityInterface class for order item relationships to products.

NOTE we do not have any kind of validation ensuring that the order item type references a class implementing this class. Only in Drupal's form validation. I should open an issue for this.

Add to cart flow and processes

This is an outline of the add to cart flow, and understanding how a purchasable entity becomes attached to a cart as an order item.

Notes:

• Purchasable entities define what order items they will produce.
• Order items define what order types they belong to.
• We allow hooking into the order type resolution to override default configuration mapping.

1. Determine the proper store based on the purchased entity. We take the stores the purchasable entity belongs to and verify it can be purchased from the current store. If it cannot be purchased from this store, this is an unprocessable request.
2. We then create an order item from the purchasable entity, using the order item's storage method ::createFromPurchasableEntity. This created an order item with the bundle requested by the purchasable entity. The unit price is set from the purchasable entity's price.
3. The order item's price is resolved to allow for price calculation, overriding the default base price from the purchasable entity.
4. The order type is resolved by the order item type.
5. The CartProvider is used to check if a cart exists for the resolved order type and current store.
6. If a cart does not exist, one is created of the resolved type for the current store.
7. The order item is then added to the cart using the CartManager
8. The CartManager handles combining existing order items to update their quantity, if requested, versus creating duplicate order items. It also fires an event to allow users to react to an add to cart event.

We do not just directly call Order::addItem or Order::get('order_items)::appendItem()

Relevant PHP interfaces we use for interacting with carts.

• CartManagerInterface: https://git.drupalcode.org/project/commerce/blob/8.x-2.x/modules/cart/src/CartManagerInterface.php
• CartProviderInterface.php: https://git.drupalcode.org/project/commerce/blob/8.x-2.x/modules/cart/src/CartProviderInterface.php

[mglaman]

Here is a go at writing down some constraints for the operations

Constraints

• It should be possible to get a list of all carts
  • Constraints:
    • A user may have more than one cart, if any of the following scenarios occur:
    • The user has carts between multiple stores (to be determined if query access should filter based on the current store, https://www.drupal.org/project/commerce_cart_api/issues/3041154)
    • The user has purchased products which require different order types (ie: physical order and a digital order)

NOTE while this is out of the box behavior, generally a site should be configured to prevent multiple carts. Such as re-assigning an order if the store changes, or ignoring if changing stores is not expected behavior. However multiple carts can be a requirement, such as B2B scenarios.

• It should be possible to add an item to a user's cart.

  • Constraints:
  • There can be >1 cart
  • A user may not have a cart created, and one should be generated.
  • The client should not have to initiative a cart prior to the operation.

• It should be possible to remove an item from a cart

  • If removing the last item,it should not delete the order, only the order items and purge references. This should be handled by the CartManager service from the PHP based API.

• It should be possible to remove all items from a cart

  • Removing all items should not delete the order, only the order items and purge references. This should be handled by the CartManager service from the PHP based API.

• It should be possible to change the quantity of an item in a cart

  • Update the quantity field. Generic PATCH request, allows updating of custom fields as well.

• It should be possible to update the quantities of all items in a cart

  • In many cases, such as B2B a bulk update of quantities is possible. It seems that this would be solved by JSON:API operations. https://github.com/json-api/json-api/issues/795
  • Out of the box, nothing in Drupal Commerce "headed" forms support this.

Non requirements, documented for clarity:

• It should be possible to fetch all items in all carts
  • This should be an automatic include on orders, ideally we'd want to treat order items as "embedded" entities / objects.
• It should be possible to fetch all items in a particular cart
  • This should be an automatic include on orders, ideally we'd want to treat order items as "embedded" entities / objects.
• It should be possible to remove an item from all carts
  • Full multi-cart is possible, but purging a purchasable entity across all carts is not an assumed piece of functionality.