Scenario: Calculate pre-purchase pick-up and shipment assignments using finite capacity windows

The Calculate pre-purchase shipment assignments API provides the ship date, delivery dates, and shipment breakup information for a cart or checkout that consists of one or more multi-quantity order lines. The API supports both the ship and the pickup delivery methods.

A cart holds items that the user intends to order, which is displayed on a cart page. The cart page is the summary page in an online shopping experience that displays all the items and item quantities that the shopper selected from product detail pages. Each order line contains a unique SKU identifier with multiple quantities.

The checkout page is a page in an online shopping experience that is displayed before the shopper confirms the order.

The Calculate pre-purchase shipment assignments API calculates the best solution that is based on the item, inventory availability, and capacity availability across all order lines. If the order-line quantity cannot be fulfilled from one ship node, the API distributes the order line across multiple shipments. During the process, multiple delivery estimates are given for each order line.

In addition to the delivery dates, the shipment date is also provided on each shipment so that the shopper is aware when a particular item is shipped from an assigned ship node. For more information, see the Calculate pre-purchase shipment assignments version 2 API.

Important: You must pass one shipping group as an input to the Calculate pre-purchase shipment assignments API.

The estimated delivery dates are calculated both by order line and by shipment. This API returns the first delivery date, which is the earliest delivery date for the entire cart, and the last delivery date, which is the last delivery date for the entire cart.

Important: The Calculate shipment assignments API expects that each SKU request line is not repeated across order lines.

Differences between v1 and v2

Capabilities	Version 1	Version 2
Transit duration	Transit duration (and summary)	Transit duration between zones
Capacity calculations	capacity schedules, overrides, and processing time	Uses category IDs to differentiate capacities, then tracks the capacity through slots and quantity. You can also search for relevant capacity by using tags. This does not consider processing time for calculations.
Promising date calculations and estimations	as soon as possible (the default option)	options for as fast as possible or minimize shipments (the default option)

Transit duration between zones

The transit duration is the amount of time a carrier service, for example, Shipping Company Ground, takes to deliver the package from the source address to the destination address after pickup. Configure this parameter to calculate the estimated delivery date and shipment assignments during a pre-purchase request cart by using parameters, such as your tenant information, item identifiers, destination information. The application considers details like inventory distribution, available capacities, and carrier service pickups, before making an intelligent promise date.

Ship independently

Some orders might require you to ship the items separately, for example, when the ordered items are fragile. The API also considers the constraint to ship an item independently of other items within an order. To fulfill such orders, the API generates separate packages for each of such items. However, to minimize shipments, multiple such separately-shipped items can be included within the same shipment.

Override node list

While making fulfillment decisions, you can configure the API to calculate and display the capacity and inventory availability for a preselected node or list of nodes. For more information about override node list, see Buy online and pick-up in store (BOPIS).

Note: When the overrideNodeList attribute is enabled, the application ignores the sourcing and Promising rules while making promising calculations.

Requested fulfillment delivery and pick up dates

While calculating the estimated delivery and pickup dates, the API now returns the earliest delivery or pick-up date on or after the requested date.

For more information about requested fulfillment date for delivery, see Scenario: Ship from store (SFS). For more information about requested fulfillment date for pickup, see Buy online and pick-up in store (BOPIS).

Ship to store

While making promising calculations and estimating the pick-up date, you can configure the Transfer rules at the node level. In the events when an inventory is not available in a store, the required inventory can be transferred from the nearby nodes. For more information, see Ship to store (STS).

Note: The ship to store is available for only the pick delivery method.

When the delivery method is set to pickup, the API evaluates transfer rules for a match. If the match is found, the API accounts for the possibility of transferring the inventory from another node to the node from which the inventory is to be picked by the customer. For more information, see Ship to store. For more information about Transfer rules APIs, see Configuring transfer rules.

Delivery optimization options

When calculating promise dates, the following options are available:

Compute dates such that the products are delivered to the shopper while minimizing the shipments within the soft constraint of maximum shipping days. This is the default option. To take advantage of this option:
- Configure the Default transit time for the shipping group by using the user interface. This is the maximum transit duration within which the product must be delivered to the shopper. You can configure this duration taking into consideration the service-level agreement (SLA) provided by the carrier for the carrier services and your own SLAs.
- To minimize shipment, set considerMaxSLADays to true by using the API.
Compute dates such that the products are delivered to the shopper as fast as possible. To deliver as fast as possible, set considerMaxSLADays to false.

Using custom attributes to extend Promising rules

Use the user interface to add new custom attributes. Then, when you involve the Calculate pre-purchase shipment assignments API (version 2 uses finite capacity windows), pass the custom attribute in the API input using the sourcingCriteria parameter. For more information, see Configuring custom attributes.

Checkout view options

The Calculate shipment assignments API can provide two alternative views on an e-commerce checkout page. The data set is returned both by order lines and by shipment lines.

Order line format: In the order line format, each order line includes one or more shipment assignments that are sourced from a ship node, with the associated fulfillment quantity. The total of the fulfillment quantities for each order line comprises the total requested quantity.
Shipment line format: In the shipment line format, the shopper can understand which SKU or SKUs are included in each shipment. A shipment might consist of more than one SKU, each with various fulfillment quantities.

Handling shortage quantities

The Calculate shipment assignments API also accounts for possible inventory and capacity shortages. In this case, Sterling Intelligent Promising attempts to locate a ship node that can provide partial quantities and reports any shortage amount. The shortage amount is the difference between the requested SKU quantity and the SKU quantity that cannot be fulfilled by the seller.

Cart use cases

In addition to supporting multiple order lines, calculate shipment assignments can be modeled to handle a single order line request in a cart use case. In a standard cart use case, the seller might want to list a separate delivery date estimate for each order line. This action can be performed by using the Calculate shipment assignments API with a single order line request.

Capacity availability calculations

You can categorize capacity by tags and assign availability to each capacity category. For example, you might want to tag the capacity as capacity for pickup or capacity for shipping. Therefore, you can tag the capacity based on the delivery method. Once configured, the calculateCheckoutAssignments API version 2 considers the configured capacity for a given slot while making promising decisions.

Calculate shipment assignments example

Consider a typical shopper checkout workflow on an e-commerce site. The shopper adds two items to the cart, each with a different request quantity. In the example, it is assumed that availability exists for both inventory and capacity for each requested SKU.

Assume that a shopper wants to purchase the following items in the specified quantities, and adds the items to their online cart.

Table 1. Shopper cart request
Order line number	Item	Quantity
`001`	`sku01`	5
`002`	`sku02`	2

The Calculate shipment assignments API yields the following results.

Table 2. Order line and shipment assignments
Order line number	Shipment number	Ship node	Delivery date	Item	Assigned quantity
`001`	1	`node01`	1 July	`sku01`	2
`001`	2	`node02`	10 July	`sku01`	3
`002`	1	`node01`	1 July	`sku02`	1
`002`	3	`node03`	5 July	`sku02`	1

Result summary

None of the ship nodes have sufficient quantity, which leads to a shipment breakup that consists of three shipment assignments.

Node01 can fulfill sku01 and sku02 in one shipment. However, it does not have all of the requested inventory, so the remaining inventory must be sourced from alternative ship nodes.

Node02 can fulfill the remaining quantity for sku01 but does not have availability for sku02, so a second shipment is formed.

Node03 can fulfill sku02 and it does not have inventory for sku01, so a third shipment is formed to fulfill the remaining sku02 requested quantity.

As a result, the first delivery date is 1 July and the last delivery date is 10 July. The shopper is going to receive three separate deliveries that together fulfill the requested order lines. No shortages were encountered in this scenario.

The seller can use the Calculate shipment assignments API alternative shipment view to display the result by shipment view.

Table 3. Shipment view
Shipment number	Order line number	Ship node	Delivery date	Item	Assigned quantity
1	`001`	`node01`	1 July	`sku01`	2
1	`002`	`node01`	1 July	`sku02`	1
2	`001`	`node02`	10 July	`sku01`	3
3	`002`	`node03`	5 July	`sku02`	1

Note:

For more information about understanding and troubleshooting promising calculations, see Scenario: Troubleshooting promising calculations.

The capacity calculation is dependent on the following factors:

Lead time: For more information, see Lead time.
Capacity availability: For more information, see Capacity.
Use the Insert or update available capacity API to use this functionality.
Inventory availability: For more information, see Supply and demand.
Carrier Pickup: For more information, see Configuring carrier pickup schedules.
Use the Define node carrier pickup schedule API to use this functionality.
Carrier transit time: For more information, see Configuring carrier transit times.
Use the Upload transit duration (and optionally transit delay) by shipping zones API to use this functionality.
Radius from the shopper in case of PICK delivery