Substitute Products

If a product is unavailable after an order has been placed, you can substitute a similar product during the fulfillment process. These substitutes are pre-configured at the product level, and then either performed automatically or manually selected by a fulfiller. This allows you to fulfill the order for the original sale price, improve customer experience by delivering products similar to their desired product, and supports business models that may frequently use substitutes such as groceries.

This feature requires Order Management and either eCommerce or an OMS catalog. If you are using a catalog, ensure that all products in imported order data are valid products in your catalog.

How Substitutions Work

If a product is out of stock and not configured for substitutes, then any unavailable quantity must be transferred or rejected. But if a product is configured for substitutions, there are a few different scenarios where replacing it with another product may be useful:

• A product is substituted one-to-one with a different product. 
  • For example, 1 quantity of Product A is substituted with 1 quantity of Product B. 
• A product is partially substituted with a different product.
  • For example, a shipment requires 5 quantity of Product A but only 2 are in stock. The remaining 3 quantity is substituted with Product B. 
  • If there is not enough substitute quantity available to fulfill the original amount, then the remaining quantity can be transferred or rejected. If the above Product B only had 1 quantity available, then that would be substituted into the shipment and a transfer or rejection would be made for the final 2 quantity.
  • Alternatively, more than one substitute product may be used. For example, 1 quantity of Product B and 2 quantity of a Product C could be substituted.

Manual and Automatic Substitutions

Enabling substitutions will allow fulfiller users to perform manual substitutions in the Fulfiller UI, but you can also allow substitutions to be made automatically upon shipment creation. If no inventory is available for an item at that point, then the system will attempt to perform a substitute before considering a transfer (if transfers are enabled). Substitute products are attempted in order of a given priority.

For example:

• The system goes to create a shipment and finds that there isn't enough inventory for a product that is a 60-ounce bottle. It automatically substitutes that line item with a 40-ounce bottle that has available inventory. 
• The system goes to create a shipment and finds that there isn't enough inventory for a product that is a 60-ounce bottle. It attempts to automatically substitute the item with a 40-ounce bottle, but inventory is not available. The system moves to the second-highest priority substitute, a 60-ounce bottle from another brand, and that product has available inventory so the substitution is performed.
• A shipment is being consolidated and inventory is not available at the consolidation location, so the system attempts to substitute based on inventory at that specific location before attempting a transfer via Order Routing. 

Substitutions in Order Details

After a substitution has been made, the Admin UI's order shipment details will indicate the affected products.

Configure Substitutions

Contact Kibo Support to have this feature enabled in your tenant settings. Then you will be able to enable repricing, add the substitute attribute to product types, and select the substitutes on products.

Enable Repricing

Repricing on substitutions is optional. When a reprice occurs, the substitute's item price will be applied but discounts will not be re-evaluated. Any discounts on the original item will be copied to the substitute item as-is. Shipping and handling will be copied from the original item to the substitute item, tax will be refreshed, and the shipment total will be recalculated. Payment may or may not be affected, depending on the difference between the substitute item and original item's pricing:

• If the substitute item's price is lower than the original item, then the difference will be credited to the customer. If Auto Capture is enabled, then the system will do this automatically as long as a payment has already been captured. If Auto Capture is not enabled, you will have to credit the amount manually. 
• If the substitute item's price is higher than the original item, the payment status will be set to Errored and all shipments on the order will be blocked from fulfillment until an additional payment for the difference is authorized. An email notification can be sent to the shopper informing them of this and directing them to Customer Care for more details.
• If the substitute item's price is the same as the original item, there will be no impact to payment.
• In the case of bundled products, pricing is distributed across all items in the bundle before substitutions are made. When repricing is enabled, the substitute item's catalog price will replace the original item's distributed price without affecting other items in the bundle. If repricing was not enabled, then the original item's distributed price would still be applied to the substitute item.

Repricing is disabled by default. To enable repricing on all substitutions:

1. Go to System > Settings > General > Site.
2. Locate the Fulfillment Settings section.
3. Toggle Reprice on Substitution. 
4. Click Save.

Enable Email Notifications

In order to send optional email notifications to shoppers, enable them under your email settings:

1. Go to System > Settings > General > Email.
2. Scroll down to Shipment Emails and toggle on Substitution - payment required to send an email notification when the substitute item's price is higher than the original item after repricing. This prompts the customer to provide additional payment before the order can be fulfilled.
3. Scroll down to Order Emails and toggle on Item Substituted to send an email notification when an automatic substitution takes place.
4. Click Save.

Add Attribute to Product Types

Enable substitutions in your catalog using the substitute property in the product type configurations. 

1. Go to System > Schema > Product Types.
2. Select a product type. All usage types are supported.
3. In the Properties tab of the product type settings, select the Substitute Products attribute. 
   • If the product is a Configurable Product, then substitutes must be set up at the variant level as each of its product variants has its own product code. In this case, select the Substitute Variants attribute instead.
   
4. Click Done to add it to the product type.
5. If you want the system to perform automatic substitutions on this product type, also add the Allow Auto Substitutions attribute. If this attribute is not added, then substitutions can only be performed manually by fulfillers.
6. Click Save.

Select Substitutes on Products

After adding the attribute to product types, select any product of that type in your master catalog and set up its substitute(s). Substitutions may be made for any standard products, variant products, product extras, bundles, bundle components, items in collections, and digital items, with the exception of service items. 

1. Go to Main > Catalog > Products.
2. Click the product that you want to configure substitutes for.
3. In the Properties tab of the product settings, enter eligible substitutes in the Substitute Products field. If the product usage is Configurable Product with Options, use the Substitute Variants field to select eligible variants as substitutes instead.
   • The order in which you add these substitutes will be the order of priority used by automatic substitutions, from highest to lowest.
     
4. If you want to perform automatic substitutions, toggle on Allow Automatic Substitutions.
5. Click Save when you have finished adding all desired substitutes to your product.

Shopper Preferences

Shoppers can indicate whether they're open to substitutions during the cart or checkout process, except when creating a B2B quote or creating a subscription.

• If the shopper is willing to accept substitutions, the list of potential substitutes for that product will be displayed. The shopper can select one as their preference, and the system will attempt to substitute with that item first when an automatic substitution is performed. If the shopper doesn't indicate a preferred item, then the system will attempt substitution in order of priority as defined in the product settings. 
• If the shopper indicates that they will only accept substitutions at fulfillment, then substitutions will not be performed automatically and fulfillers will be responsible for contacting the shopper and manually performing any substitutions. 
• If the shopper is not willing to accept substitutions, then substitutions will not be performed automatically nor available during fulfillment.

Customer service representatives can also indicate whether substitutions are allowed when creating an offline order on behalf of the shopper. Use the dropdown menu shown below to select Yes, No, or Requires Shopper Consent (meaning that they will only accept substitutions at fulfillment).

Headless Storefront Integration

When making calls to add cart, checkout, or order items, use optIn and substituteProductCode (or substituteVariantCode if using a product variant as a substitute) in the item-level data to indicate the shopper's preferences. You can edit these preferences again with the Update Substitution Info endpoints for checkouts and orders, as long as the order is not yet Accepted. All the API schemas will be updated soon and the new endpoints will be linked here when their API documentation is available.

{ 
  ...
      "fulfillmentLocationCode": "WarehouseLocationCode001",
      "fulfillmentMethod": "Pickup",
      "lineId": 1,
      "product": {
        "productCode": "product_01",
        "name": "product_01"
      },
      "quantity": 1,
      "substituteInfo": {
        "optIn": "Yes",
        "substituteProductCode": "product_02"
      }
  ...
}

Substitutions in Fulfiller UI

Substitutions are available for all fulfillment types except Curbside or Delivery. Items that include Assembly are not able to be substituted.

Substitutions occur in the Validate Stock step of shipment fulfillment and are independent of any reassignments or transfers. When a non-Assembly item in an STH or BOPIS (not Curbside or Delivery) shipment is unavailable and substitutions are set up for the product, the Substitute button will be displayed for that item.

1. At the Validate Stock step, if the In Stock Quantity is less than the required Quantity then Substitute will appear next to that line item. Click this to begin the substitution process.
2. Eligible substitutes and their available inventory at the fulfillment location will be displayed. Enter the quantity of the substitute(s) you want to use and a reason for the substitution.
3. Click Confirm.
4. The substitutes will be displayed in a new table underneath the original line items, where you can click Remove to remove them from the shipment if desired. 
5. You can now continue with the fulfillment process as usual. The substitute item's inventory will be allocated while the original item's quantity will be deallocated. The substitutions will also be included on any packing slips and pick sheets.

Once a substitution has been made, information about the item and substituted quantity is listed on the shipment details and can be displayed in Shipment Confirmation notifications. 

Cancel and Return Substitutions

If the original line item is cancelled from the shipment, any associated substitute item(s) will be removed from the shipment as well.

If a substitute item is returnable, then it will be listed in the Create Return and Process Return modals. Substitutes will be labelled to help identify them and which shipment item they were originally substituted for.