Omni Sales

This guide explores common omni-channel use cases and their implementation requirements from a Sitoo perspective. We'll provide high-level overviews of how to implement these scenarios. It's essential to understand that the different flows are closely interconnected, relying on the middleware to interpret Sitoo events and order data to determine appropriate actions.

Prerequisites

Tip

Always tag orders with something that is defining what type of order it is. Eg. with the use of additional data fields.

Buy Online, Pick up In Store (BOPIS)

To notify the store about a web order that should be picked up in store, an order needs to be created in Sitoo and connected to the store warehouse using the warehouseid property. This should be done without setting the delivery address properties, since that would have it be treated as a delivery (BOSFS) instead of a pickup in store. The staff will fulfill the order in Sitoo POS and your middleware will be notified during the order lifecycle with event triggered callbacks.

BOPIS

Create Order

POST /sites/{siteid}/orders.json

{
  "ordertypeid": 10, // Type = Order
  "paymentstateid": 20,  // State = Successful
  "warehouseid": 43, // The warehouse ID where the order should be picked up at
  "additionaldata": {
    "weborder": "true", // Example tag for easier identification
    "weborder-bopis": "true" // Example tag for easier identification
  },
  "orderitems": [
    {
      "productname": "Shirt blue",
      "sku": "14785-5",
      "quantity": 1,
      "moneyrowprice": "399.00",
      "vatvalue": 25,
      "additionaldata": {
        "web-itemid" : "10" // Example tag to easier identify specific item
      }
    }
  ]
}

event: ready-for-pickup

When the store staff changes status on the order to ready-for-pickup, a callback is created to notify that the order is ready.

{
  "order_event_type": "ready-for-pickup"
}

event: closed

Customer collects order. The order in Sitoo will be closed with the products delivered from the POS and a callback is created.

{
  "order_event_type": "update",
  "order_state_changed": "closed"
}

Done!

It is up to the middleware to take action on the callback events.

Buy Online, Ship From Store (BOSFS)

A BOSFS integration is very similar to a BOPIS from a Sitoo perspective. The only big difference is that you add the delivery address properties to the order. The staff will fulfill the order in Sitoo POS and your middleware will be notified during the order lifecycle with event triggered callbacks.

BOSFS

Create Order

POST /sites/{siteid}/orders.json

{
  "ordertypeid": 10, // Type = Order
  "paymentstateid": 20,  // State = Successful
  "warehouseid": 43, // The warehouse ID where the order should be delivered from
  "delivery_address": "Storgatan 1",
  "delivery_zip":  "11219",
  "delivery_city": "Stockholm",
  "additionaldata": {
    "weborder": "true", // Example tag for easier identification
    "weborder-bosfs": "true" // Example tag for easier identification
  },
  "orderitems": [
    {
      "productname": "Cookbook",
      "sku": "121292-4",
      "quantity": 1,
      "moneyrowprice": "199.00",
      "vatvalue": 25,
      "additionaldata": {
        "web-itemid" : "10" // Example tag to easier identify specific item
      },
    }
  ]
}

event: ready-for-pickup

When the store staff changes status on the order to `ready-for-pickup`, a callback is created to notify that an order is ready.

{
  "order_event_type": "ready-for-pickup"
}

event: closed

Courier collects the order from store. The order in Sitoo will be closed with products delivered from the POS and a callback is created.

{
  "order_event_type": "update",
  "order_state_changed": "closed"
}

Done!

It is up to the middleware to take action on the event callbacks.

Note

The shipping process(book transportation, print package labels etc..) needs to be handled outside of Sitoo.

Buy Online, Return In Store (BORIS)

To be able to do a validated return on a web order, the order needs to exist in Sitoo and also have its order items delivered. When it comes to refunding the customer, you basically have 3 options from a Sitoo perspective:

Payment handled by e-com system: In this scenario a custom payment option should be created in Sitoo and used on the web orders created. Then it is up to the middleware to make sure the return order is refunded correctly. Meaning the middleware needs to look on all orders created in Sitoo and be able to identify when a refund is made on a web order and should be triggered back towards e-com or handled directly by the middleware.
Payment handled by Sitoo: When both the online store and physical store utilize the same payment provider, Sitoo can directly initiate refunds. To facilitate this, the original web order payments object must include specific details required by the payment provider. These details vary by provider and are essential for processing refunds.
- Klarna the additionaldata properties klarna-klarnareference, klarna-orderid and klarna-merchantid.
- Adyen the additionaldata properties payment-method, adyen-pspreference and adyen-amountcurrency.
- Vipps MobilePay the additionaldata properties payment-method and vipps-mobilepay-paymentid in the format of <MSN>-<REFERENCE>.
Other: Store handles the refund by choosing applicable payment method for refund.

Adding web orders to Sitoo and deliver them is a 3 step process:

BORIS

Create Order

POST /sites/{siteid}/orders.json

{
  "ordertypeid": 10, // Type = Order
  "paymentstateid": 20,  // Payment state = Successful
  "warehouseid": 51, // The warehouse ID that represents the central warehouse in Sitoo
  "externalid": "454545", // The unique identifier of the weborder
  "additionaldata": {
    "weborder": "true" // Example tag for easier identification
  },
  "orderitems": [
    { 
      "productname": "Cookbook",
      "sku": "121292-4",
      "quantity": 1,
      "moneyrowprice": "199.00",
      "vatvalue": 25,
      "additionaldata": {
        "web-itemid" : "10" // Example tag to easier identify specific item
      },
    },
    {
      "productname": "Sofa Cosy",
      "sku": "15457-4",
      "quantity": 1,
      "moneyrowprice": "2999.00",
      "vatvalue": 25,
      "additionaldata": {
        "web-itemid" : "11" // Example tag to easier identify specific item
      }
    }
  ]
}

Make sure to store the orderid in the response or use the `externalid` property for easy handling of the order

Deliver Order

POST /sites/{siteid}/orders/{orderid}/orderdeliveries.json
Deliver the products connected to the order. Only delivered products can be refunded

{   
  "warehouseid": 51,
  "orderdeliveryitems": [
    {
      "orderitemid": 0,
      "quantity": 1
    },
    {
      "orderitemid": 1,
      "quantity": 1
    }
  ]
}

Archive Order

PUT /sites/{siteid}/orders/{orderid}.json

{
  "orderstateid": 10 // Order state = Closed
}

Need to be closed to enable refund

Done!

Note

If the payment for the original e-commerce order is added to Sitoo, then Sitoo will suggest this payment method when processing the return in store (validated refund).

When an order is returned, a callback will be created and it is up to the middleware to react to the event. A new return order in Sitoo will be closed with a reference to the original web order (pos-originalsales-orderitemid) and deliveries with negative quantity. The callback from Sitoo when the order is closed will be order_state_changed: closed as for all closed orders. This means that the middleware needs to be able to filter out the specific orders that are BORIS and take action if needed.

Note

In the BORIS flow it is also important to create any online refund as an order in Sitoo. This to make sure that the customer cannot return the same items multiple times.

A web order refund is handled similar to a new order but with negative values for cost and quantity:

Online refund

Create Order

POST /sites/{siteid}/orders.json

{
  "ordertypeid": 10, // Type = Order
  "creditorderid": 10789 ,// Original Sitoo orderid
  "paymentstateid": 20,  // Payment state = Successful
  "warehouseid": 51, // The warehouse ID that represents the central warehouse in Sitoo
  "externalid": "454545-refund-1", // The unique identifier of the refund web order
  "additionaldata": {
    "pos-originalsales-orderid": "10789", // Original Sitoo orderid
    "weborder": "true", // Example tag for easier identification
    "weborder-refund": "true" // Example tag for easier identification
  },
  "orderitems": [
    {
      "productname": "Cookbook",
      "sku": "121292-4",
      "quantity": -1,
      "moneyrowprice": "-199.00",
      "vatvalue": 25,
      "additionaldata": {
        "web-itemid" : "10" // Example tag to easier identify specific item
      }
    }
  ]
}

Deliver Order

POST /sites/{siteid}/orders/{orderid}/orderdeliveries.json
Create an order delivery with negative quantity of the products that has been refunded.

{   
  "warehouseid": 51,
  "orderdeliveryitems": [
    {
      "orderitemid": 0,
      "quantity": -1
    }
  ]
}

Archive Order

PUT /sites/{siteid}/orders/{orderid}.json

{
  "orderstateid": 10 // Order state = Closed
}

Done!

Buy In Store, Ship From Central Warehouse (Endless Aisle)

In an endless aisle scenarios where products are out of stock but available for order through the central warehouse, the integration must identify orders placed at a designated "endless aisle" warehouse. Once an order with non-delivered orderitems is created in Sitoo for this warehouse, the middleware should initiate the order fulfillment process in the appropriate system.

Note

It's crucial to know that endless aisle orders are triggered post-purchase. Therefore, the middleware must implement robust error handling and notification mechanisms to address potential failures of the process.

Endless Aisle

event: add

POST /sites/{siteid}/orders.json
An endless aisle scenario will typically start with a webhook from Sitoo.

{
  "order_event_type": "add",
  "order_state_changed": "open"
}

Fetch Order

GET /sites/{siteid}/orders/{orderid}.json
You fetch the order and verify that it includes a `registerid` to confirm its origin from a Sitoo POS order, rather than a web order created via the API. Additionally, validate that the order is currently in the open state and placed towards the endless aisle `warehouseid`.

{
  "registerid": "{1E87C14A-B31B-A60D-682C-3E172191170C}",
  "warehouseid": 51,
  "orderstate": 0,
  "orderitems": [
     {
      "orderitemid": 0,
      "orderitemtype": 10,
      "sku": "15457-4"
     },
     {
      "orderitemid": 1,
      "orderitemtype": 10,
      "sku": "121292-4"
     },
  ]
}

Fetch Order Deliveries

GET /sites/{siteid}/orders/{orderid}/orderdeliveries.json
To determine which items have already been delivered, the integration must retrieve the order's delivery history. This is necessary as Sitoo allows for split orders, where parts of the order has already been delivered in store.

{
  "warehouseid": 1,
  "orderdeliveryitems": [
    {
      "orderitemid": 0,
      "quantity": 1
    }
  ]
}

Create order in fulfillment system

Using the gathered order information, create an order within the fulfillment system for the undelivered items.

Update Sitoo POS order

PUT /sites/{siteid}/orders/{orderid}.json
Once the fulfillment system processes the order, update the original Sitoo order with necessary information. To establish a link between the two systems, include the fulfillment order's id as `externalid` on the Sitoo order. Additionally, consider adding relevant details to the Sitoo order's `additionaldata` field for future reference when processing this specific order.

{
  "externalid": "ext-1234",
  "additionaldata": {
    ...sitooOrder.additionaldata,
    endless-aisle: "true",
    external-order-id: "ext-1234"
  }
}

NOTE The `additionaldata` field will be overwritten. To preserve existing information, merge the original `additionaldata` with the new data before updating the Sitoo order.

Deliver Order

POST /sites/{siteid}/orders/{orderid}/orderdeliveries.json
Upon fulfillment completion, update the original Sitoo order to reflect the delivered items.

{
  "warehouseid": 51,
  "orderdeliveryitems": [
    {
      "orderitemid": 1,
      "quantity": 1
    }
  ]
}

Archive Order

PUT /sites/{siteid}/orders/{orderid}.json

{
  "orderstateid": 10
}

Done!

Note

Sitoo offers two fulfillment options for endless aisle orders by default: "Delivery to Address" and "Pickup in Store". You can configure these options in the Sitoo Back Office to ensure Sitoo POS only allows customers to choose one of the options. Identifying "Pickup in Store" orders within the integration relies on the presence of a specific data field: `additionaldata.delivery-pickup-warehouseid` on the order. This field will be populated when a customer selects "Pickup in Store" as the fulfillment method in Sitoo POS. For "Pickup in Store" orders, the integration must update the `warehouseid` on the Sitoo order to match the destination store once shipping commences. This ensures order visibility on the store's POS. To prevent stock adjustments upon delivery, set the `delivery-ignore-stock` flag to true within the `additionaldata` field when updating the order.