+1 (925) 943-5558

Implementing BOPIS with Oracle Commerce Cloud

August 1, 2019

by

Rohit Nallapeta

BOPIS has been one of the most talked about features in the eCommerce industry in recent times. We’ve even talked about how BOPIS could be a definitive strategy to delight your customers and also increase traffic in your stores. Despite the many nuances of BOPIS, OCC has recently released this feature which allows it to be implemented with relative ease. In order to throw some light on the technical implementation, we decided to team up with our engineering team to write this article and do a deep dive into this subject.

Without much further ado, here we go!

BOPIS feature has 3 main pillars:

  1. Widgets that need to support the BOPIS experience
  2. Web APIs that handle the interactions
  3. Admin UI for configuring certain aspects of it

Let’s delve into the details by it’s different use cases and then map it to the changes that have been included in OCC to provide a complete BOPIS experience.

Cart Experience

The add-to-cart experience now allows for every line to be picked up from a local store. The following features enable this experience.

Store Availability Search

The cart widget now has an option to include an element that provides the capability to search for store locations where items can be picked up from. In order to display available store locations we must do the following prior to having BOPIS available on the site

  1. Populate store information
  2. Populate store inventory information
  3. Configure products and SKUs to be eligible for pickup in store

All these activities are completed via APIs that are provided by OCC.

Locations API

Store locations can be populated using the following Admin API

POST /ccadmin/v1/locations

Each API call is used to add a single location in OCC. An example of a request for creating a new location is given below:

{  
    "country": "USA",  
    "distance": null,  
    "city": "New York",  
    "endDate": "2020-12-31T00:00:00.000Z",  
    "postalCode": "10024",  
    "latitude": 40.78,  
    "county": "Upper West Side",  
    "stateAddress": "NY",  
    "pickUp": true,  
    "sites": [  
        {  
            "id": "siteUS"  
        }  
    ],  
    "type": "store",  
    "inventory": true,  
    "locationId": "29394934932",  
    "email": "store.00676@objectedge.com",  
    "longitude": -73.97,  
    "hours": null,  
    "address3": "",  
    "address2": "",  
    "address1": "2300 Broadway",  
    "externalLocationId": "00676",  
    "phoneNumber": "(212) 579-4599",  
    "siteGroups": [],  
    "repositoryId": "29394934932",  
    "name": "83rd St. and Broadway",  
    "faxNumber": "(212) 579-4588",  
    "startDate": "2019-04-01T00:00:00.000Z"  
}  

Note the boolean attribute named pickUp in the above request, this is a new option in the API to indicate whether or not the store accepts BOPIS orders.

Inventory API

When a customer searches for a pickup location, only locations that have the item in stock will be returned in the search results. To ensure that the right stores show up in the search results we must also add inventory for each store. 

OCC has the following Admin APIs that allows us to add/update inventory information for each SKU and store combination.

POST /ccadmin/v1/inventories (for creating new inventory records)
PUT /ccadmin/v1/inventories/{id} (for updating existing inventory records)

A sample request for adding or updating an inventory record is given below

{  
     "id": "sku12345", 
    "type": "variant",  
     "stockThreshold": 0,  
     "stockLevel": 200,  
     "locationId": "29394934932",  
     "backorderLevel": 50,  
     "backorderThreshold": 5,  
     "preorderLevel": 0,  
     "preorderThreshold": 0,  
     "availabilityDate": "2019-06-01T12:00:00.000Z"  

The above request adds inventory for store 29394934932 and SKU sku12345. The added inventory count is 200.

Product and SKU APIs

OCC now provides a new flag on products, as well as SKUs, that marks them eligible for pickup in store. The flag is called onlineOnly. If the value is set to false, then the item can be picked up from stores. The update Product and SKU APIs both allow setting the value of this flag. 

PUT /ccadmin/v1/products/{productId} (for updating products)
PUT /ccadmin/v1/sku/{skuId} (for updating SKUs)

The following is an example the request body for updating this flag on products (as well as on SKUs)

{
    "onlineOnly": false
}

Mixed Cart

OCC now provides the capability to have a cart with a mix of “store pickup” for some items and “ship to address” for the remaining items. The items that need to be picked up in store are part of a new type of shipping group called inStorePickupShippingGroup. The inStorePickupShippingGroup does not have a shipping address on it, instead it has an attribute called locationId. This tells us which store the items need to be picked up from. Given below is a sample inStorePickupShippingGroup. 

{
    "lastName":"Doe",
    "shippingMethod":"inStorePickupShippingGroup",
    "description":"sg123456",
    "submittedDate":null,
    "firstName":"John",
    "priceInfo":{
        "secondaryCurrencyTaxAmount":0,
        "discounted":false,
        "shippingTax":0,
        "secondaryCurrencyShippingAmount":0,
        "amount":0,
        "rawShipping":0,
        "amountIsFinal":false,
        "currencyCode":"USD"
    },
    "phoneNumber":"925-999-9999",
    "shipOnDate":null,
    "actualShipDate":null,
    "trackingInfo":[

    ],
    "locationId":"29394934932",
    "specialInstructions":{

    },
    "middleName":null,
    "commerceItemRelationships":[
        {
            "availablePickupDate":"2019-06-18T12:00:00.000Z",
            "commerceItemId":"ci11223300",
            "inventoryLocationId":"29394934932",
            "amount":0,
            "quantity":1,
            "relationshipType":"SHIPPINGQUANTITY",
            "returnedQuantity":0,
            "preferredPickupDate":"2019-06-20T12:00:00.000Z",
            "range":{
                "lowBound":0,
                "highBound":0,
                "size":1
            },
            "commerceItemExternalId":null,
            "state":"INITIAL",
            "id":"r112233"
        }
    ],
    "state":"INITIAL",
    "id":"sg123456",
    "stateDetail":null,
    "email":"john.doe@email.com",
    "handlingInstructions":[

    ],
    "shippingGroupClassType":"inStorePickupShippingGroup"
}

Checkout Experience

Pickup Options

The new checkout layout provides some additional fields that allow capturing the authorized picking up person’s identification information and a few other options. The following new fields/information are displayed on the checkout page if the order contains items that need to be picked up in store.

  1. Field to capture the first name of the authorized pickup person
  2. Field to capture the last name of the authorized pickup person
  3. Field to capture the phone number of the authorized pickup person
  4. Display expected date and time the order will be ready for pickup
  5. Field to capture preferred pickup date and time

Payment Experience

OCC now provides a new payment type called InStorePayment for use in BOPIS orders. The InStorePayment payment group acts as a placeholder payment group on the order until the order is picked up. 

Enabling In Store Payment Type

The InStorePayment type is not available by default. It needs to be enabled via Settings > Payment Processing > Payment Gateways

When we’re on the Payment Gateways screen we need to choose “In Store Payment” from the “Service Type” drop down, select the “enable” checkbox, and select the “In Store Payments” check boxes on the screen. Once this is saved, InStorePayment will be available on the site.

Pickup Experience

New Email Templates

There are two new optional email templates available for the BOPIS experience

Ready For Pickup Email

This email notifies the customer that the order is ready to be picked up from the store. This email is triggered when the shipping group state changes to PENDING_SHIPMENT.

Order Picked Up Email

This email notifies the customer that the order has been picked up successfully. The “order picked up” email is triggered when the shipping group state changes to NO_PENDING_ACTION.

Picked Up Items Webhook

The Picked Up Items Webhook is triggered when the state of the  inStorePickupShippingGroup changes to NO_PENDING_ACTION. As part of this webhook, the shipping group and order details are sent in the JSON request.

POS Integration

The pickup experience can be further enhanced by creating several different in-store integrations, between the POS system and OCC, to make the complete pickup order process seamless for customers. 

Retrieving Orders From OCC

Customer orders can be looked up easily using OCC’s Admin or Agent APIs. Since orders are exposed via APIs, the POS system can make use of these APIs to fetch the complete order information on being presented with the order number or any other queryable information on the order. The APIs that can be used for this are

GET /ccadmin/v1/orders/{id}
GET /ccagent/v1/orders?q=<query>

Updating Payment Information Post Pickup

Once the order is picked up, the InStorePayment payment group needs to be replaced with a new payment group containing the actual payment information that customer used at the store to pay for the order. Since this update is done via an API call, it can be done straight from the POS system so that the customer can see the update immediately on their account on the website. The API used for making this update is

PUT /ccadmin/v1/orders/{id}

Refunds and Cancellations

There is no customization required for refunds and cancellations. The regular OCC widgets and APIs can be used for performing these actions on in-store pickup orders.

List of Changed Widgets

A summary of all widgets that have been updated to cater to BOPIS are given below:

  1. Product Details Widget

    a. This now includes the “In Store Pickup” element that allows customers to search for stores that have the product in stock
  2. Shopping Cart Widget

    a. This now includes the “In Store Pickup” element that allows customers to search for stores that have the product in stock

    b. It also includes a new element that displays the store that the customer had previously selected on the product details page
  3. Shipping Options Widget

    a. Allows for split shipping between store pickup and ship to address
  4. Checkout Summary Widget

    a. Lists the different shipping groups on the order (in store pickup as well as ship to address)
  5. Payment Widget

    a. Now allows the customer to select the option to pay in store while picking up the items
  6. Order Details Widget

    a. Displays the BOPIS selections on the order and shipping groups
  7. Order Confirmation Widget

    a. Displays the BOPIS selections on the order and shipping groups

At this time Oracle has decided to provide mostly APIs and minimum Admin UI for BOPIS features, but we’re speculating that more Admin UI screens will be added soon. 

Hopefully, this BOPIS article was able to shed light on the implementation and you now are ready to start your integrations. Partnering with a team who knows not only their way around the technology but also ways to leverage the design and processes behind the scenes are paramount to creating an effective, scalable, and delightful BOPIS experience. Contact us.

About the Authors

Tausif Farooqi is a Senior Software Architect at Object Edge. He has more than a decade of experience in the eCommerce domain, with expertise in Oracle Commerce (on-prem) and Oracle Commerce Cloud platforms.

Rohit (Roy) Nallapeta heads pre-sales consulting for Object Edge. Previously he has held various positions as a product manager, delivery lead and business analyst at Object Edge. His experience spans retail, banking, healthcare, and eCommerce areas. He contributes to this blog on subjects of eCommerce, retail and technology trends.

Download White Paper

DOWNLOAD

Related Posts

Ready to start your project?

Start by doing what's necessary, then do what's possible.

Schedule a Consultation Call