Introducing the Cart API

Introducing new endpoints aimed at simplifying development of the shopping experience. Cart is a usability enhancement which provides endpoints to interact with a given order. We consider it best practice to use Cart when implementing single-cart shopping experiences; however Cart can also be implemented for multi-cart shopping.

Before Cart, determining which Order should be used when the shopper adds an item required several API calls; which typically looked something like this:

1. GET v1/orders/{direction}?Status=Unsubmitted&SortBy=!DateCreated
2. Use the ID of most recently created Order
3. If none exists, call POST v1/orders/{direction}
4. Call POST v1/orders/{direction}/{orderID}/lineitems

One of the primary aims of the new Cart resource is to reduce this very common workflow into a single API call:

1. Call POST v1/cart/lineitems

• Cart always represents an unsubmitted Order, any action taken on the Cart is a proxy to take action on the corresponding order

• With a few exceptions, Cart endpoints will not return null or 404

  • GET v1/cart will return an empty Order with a null ID if the shopper does not yet have an unsubmitted order

    • This Order with a null ID does not actually exist in OrderCloud, but is returned as a convenience for the developer to be able to utilize the order model if needed for things like displaying the count of items on a cart icon

  • GET v1/cart/lineitems will return an empty list even if the order does not yet exist

• PUT v1/cart can be used to immediately create an Order, but should usually be deferred until an item is added

• POST v1/cart/lineitems or PUT v1/cart/lineitems will add an item to the Cart, with the benefit of creating the unsubmitted Order if it does not exist

1. Call GET v1/cart on initial page load to display Order.LineItemCount on the cart icon
2. Call POST v1/cart/lineitems to add an item to the Cart
3. Calls to POST v1/cart/payments, POST v1/cart/validate, etc. to prepare the Cart for submission
4. Call POST v1/cart/submit

In a single cart shopping experience Cart endpoints should be used as an alternative to Order endpoints, in order to avoid creating multiple unsubmitted orders for a given user. In the event that multiple unsubmitted orders exist, the most recently created unsubmitted order will be selected as the Cart. If the Cart is submitted, the next unsubmitted order will become the Cart which made lead to confusion for the shopper.

1. Call GET v1/orders/{direction}?Status=Unsubmitted to get the shopper’s unsubmitted Orders

• for this purposes of this example, two Orders are returned. Order.ID: ABC and Order.ID: 123

• if multiple unsubmitted orders do not yet exist, you will need to create them using POST v1/orders/{direction} or PUT v1/orders/{direction}/{orderID}

  • PUT v1/cart only creates a new cart if none exists and PUT v1/cart/{orderID} is only used to designate an unsubmitted order as the active cart

2. Call PUT v1/cart/ABC to designate that Order as the active Cart
3. Call POST v1/cart/lineitems to add an item to Order.ID: ABC
4. Call PUT v1/cart/123 to change the active Cart to Order.ID: 123
5. Call POST v1/cart/lineitems to add an item to Order.ID: 123
6. Calls to POST v1/cart/payments, POST v1/cart/validate, etc. to prepare Order.ID: 123 for submission
7. Call POST v1/cart/submit to submit Order.ID: 123
8. Order.ID: ABC is now the Cart, as it is the only unsubmitted Order remaining

• In the event that multiple unsubmitted Orders remain, using PUT v1/cart/{orderID} would designate which Order should be the Cart
• If none is designated, the most recently created unsubmitted Order will be the Cart

Multi-Cart is not supported for Anonymous Shopping

All of the Cart endpoints (with the exception of PUT v1/cart/{orderID} are proxy endpoints to existing Orders endpoints, with the added benefit of not needing to pass a Direction or orderID.

• For Single-Cart Shopping experiences, the Cart endpoints will return the most recently created unsubmitted Order, when following best practices there would only be one
• For Multi-Cart Shopping experiences, the Cart endpoints return the Order designated as the Cart OR if none has been designated, it will return the most recently created unsubmitted Order