Documentation Home
Changelog

REST API Endpoints

All of the Broadleaf APIs are written using Spring MVC concepts like @RestController and @RequestMapping. Documentation for the REST APIs is generated using Swagger (an optional configuration in your demo) and are viewable at http://demo.broadleafcommerce.org/api/v1/swagger-ui.html.

Typical flow for a REST API shopping experience

While every ecommerce implementation can have unique requirements, there tends to be a common flow of transactions that constitute the shopping and checkout process. This section is meant to be a general override of a typical flow.

Browsing the Catalog

Several API endpoints are available to querying and displaying of categories, products, and skus from the catalog. These calls are available as part of the catalog-endpoint: https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#/catalog45endpoint

Creating a Customer

Before adding an item to a cart, both the Customer and the Cart need to be created. The cCustomer can be created by using the addCustomer endpoint of the Customer API. https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/customer45endpoint/addCustomerUsingPOST_3

Creating a Cart

Once the Customer is created, the Cart can be create. The Cart creation requires that the Customer exists so the Cart can be associated with that Customer. The createNewCartForCustomer endpoint of the Cart API would be used. https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/cart45endpoint/createNewCartForCustomerUsingPOST_3

Add Item to Cart

With the Cart now created and available, the Item can then be added. Typically a Sku and quantity would be specified in the addItemToOrder endpoint of the Cart API. https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/cart45endpoint/addItemToOrderUsingPOST_3

It's important to note that when an Item is added to the Cart a new Fulfillment Group is created and that Item is associated to that Fulfillment Group.

Add Fulfillment Group Updates

Once the Customer has added Items to the Cart and wants to start the checkout process, the Fulfillment Group details have to be added. At a minimum, these detaiils include Shipment Options and Shipping Address.

The Shipment Options can be queried from the findFulfillmentOptions of the Fulfillment API. https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/fulfillment45endpoint/findFulfillmentOptionsUsingGET_3

Once the ID of the preferred Fulfillment Option is known, that Option can be added to the Fulfillment Group (using the ID). The addFulfillmentOptionToFulfillmentGroup endpoint of the Fulfillment API can be used https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/fulfillment45endpoint/addFulfillmentOptionToFulfillmentGroupUsingPUT_3

The Shipping Address can be added using the updateFulfillmentGroup endpoint of the Fulfillment API https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/fulfillment45endpoint/updateFulfillmentGroupUsingPATCH_3

Payment

In addition to the Fulfillment information, prior to checking out Payment information be added to the order. Payment information would include the Payment Type and the transactions from processing those payments. The payments can be added using the addPaymentToOrder endpoint from the Checkout API https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/checkout45endpoint/addPaymentToOrderUsingPOST_3

Finally, before checkout, the Payment Transactions from Payment Gateway transactions have to be associated to the Order. Before an order is considered SUBMITTED the Checkout Workflow verifies that the total Cart amount is covered based on the Payment Transactions. A transaction can be added via the addOrderPaymentTransaction endpoint of the Checkout API https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/checkout45endpoint/addOrderPaymentTransactionUsingPUT_3

Checkout

Once all data requirements are complete, the final Checkout process can be called via the performCheckout endpoint of the Checkout API. https://demo.broadleafcommerce.org/api/v1/swagger-ui.html#!/checkout45endpoint/performCheckoutUsingPOST_3

It's important to note that one of the Checkout Activities will create a Fulfillment Order for each of the Fulfillment Groups in an Order. The FulfillmentOrder represents the actual fulfillment of the items in the Order.

Post-Checkout API Calls

Once Checkout is complete several endpoints are commonly used as part of the actual fulfullment and with integration with backend systems (i.e. ERP or WMS). These calls are available as part of the OMS API.

  • getFulfillmentOrders - used to sync the Broadleaf Order with the backed system.
  • shipItems - runs the fulfill workflow for the passed in item
  • cancelItem - runs cancel workflow for non-shipped items