Omni Sales

In this guide we will go through some of the common omni use-cases. We will go through on a high level how to implement and what is expected for certain flows to work from a Sitoo perspective.

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 fulfull the order in Sitoo POS and your middleware will be notified during the order lifecycle with event triggered callbacks.

BOPIS
1
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
}
}
]
}
2
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"
}
3
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": "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 fulfull the order in Sitoo POS and your middleware will be notified during the order lifecycle with event triggered callbacks.

BOSFS
1
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
},
}
]
}
2
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"
}
3
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": "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, it needs to exist in Sitoo and also have it's order items delivered. When it comes to refunding the customer, you basically have 4 options from a Sitoo perspective:

  • Payment handled by e-com system: In this scenario a custom payment option should be created and used when returning web orders and it is up to the middleware to make sure the return order is refunded correctly.
  • Payment handled by Klarna: If e-com and store is using Klarna for payments and the correct additionaldata properties are set (klarna-klarnareference, klarna-orderid and klarna-merchantid) on the payment object for the original web order, Sitoo will notify Klarna to refund the customer when a return order is created.
  • Payment handled by Adyen: If e-com and store is using Adyen for payments and the correct additionaldata properties are set (payment-method, adyen-pspreference and adyen-amountcurrency) on the payment object for the original web order, Sitoo will notify Adyen to refund the customer when a return order is created.
  • 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
1
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 identifer 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
2
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
}
]
}
3
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_event_type: 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
1
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 identifer 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
}
}
]
}
2
Deliver Order
POST /sites/{siteid}/orders/{orderid}/orderdeliveries.json
Create a order delivery with negative quantity of the products that has been refunded.
{
"warehouseid": 51,
"orderdeliveryitems": [
{
"orderitemid": 0,
"quantity": -1
}
]
}
3
Archive Order
PUT /sites/{siteid}/orders/{orderid}.json
{
"orderstateid": 10 // Order state = Closed
}
Done!