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
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.
{ "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 } } ]}
{ "order_event_type": "ready-for-pickup"}
{ "order_event_type": "closed"}
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.
{ "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 }, } ]}
{ "order_event_type": "ready-for-pickup"}
{ "order_event_type": "closed"}
It is up to the middleware to take action on the event callbacks.
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
andklarna-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
andadyen-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:
{ "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 } } ]}
Deliver the products connected to the order. Only delivered products can be refunded
{ "warehouseid": 51, "orderdeliveryitems": [ { "orderitemid": 0, "quantity": 1 }, { "orderitemid": 1, "quantity": 1 } ]}
{ "orderstateid": 10 // Order state = Closed}
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.
A web order refund is handled similar to a new order but with negative values for cost and quantity:
{ "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 } } ]}
Create a order delivery with negative quantity of the products that has been refunded.
{ "warehouseid": 51, "orderdeliveryitems": [ { "orderitemid": 0, "quantity": -1 } ]}
{ "orderstateid": 10 // Order state = Closed}