Integrating a sales system

Your sales system must be represented as a sales channel in Thetis IMS. This will allow you to distinguish events relevant for you from events relevant to other sales systems.

Pushing orders

Unless you want to consolidate or split the delivery of your orders, you must create a shipment in Thetis IMS for each order. You can do that using this endpoint:

POST /shipments

When creating a shipment you must refer to a customer. Therefore, you may want to check if the customer in question already exists before creating the shipment. You can do that using this endpoint and filter:

GET /customers?customerNumberMatch={customer_number}

If the customer does not exist, you can create it using this endpoint:

POST /customers

If you want to store information in Thetis IMS related to customers or shipments that are not relevant to the system, you may use the dataDocument field for this purpose.

Pushing items

If you choose to use your sales system as your item master, you will need to push items to Thetis IMS at regular intervals. You can do that using these endpoints:

POST /products
POST /globalTradeItems

Using your sales system as your item master may be a good idea, if you only employ one sales system. If you have more sales channels, you will probably be better off using Thetis IMS as your item master. You will then push new items from Thetis IMS to your sales systems as described below.

Handling events

Delivery note created

The event is described here. The relevant events will have document type equal to ‘DELIVERY_NOTE’.

This event is fired when the warehouse finishes the packing of a shipment. At this point in time the shipment is waiting for the forwarder to pick it up. The shipment consists of one or more shipping containers (pallets, boxes, etc). Each of these shipping containers has been assigned a tracking number by the forwarder.

At this point in time you may want to send a mail to your customer that the order has been packed.

The event object contains the id of the shipment. You can use that to lookup the shipment using this endpoint:

GET /shipments/{shipment_id}

The shipment object returned from this endpoint contains an array of shipping containers.

Consignment note created

The event is described here. The relevant events will have document type equal to ‘CONSIGNMENT_NOTE’.

This event is fired when the warehouse hands over the shipments to the carrier. The carrier leaves the warehouse with the shipments. In B2C sales this point in time typically constitutes the formal time of delivery.

At this point in time you may want to invoice your customer.

If payment has been approved beforehand, you are now legally allowed to capture it.

The event object contains the ids of the shipments that were consigned to the carrier. You can use these ids to lookup the shipments using this endpoint:

GET /shipments/{shipment_id}

Available stock changed

The event is described here.

When the available stock in hand changes, you will want to adjust the quantity for sales in your sales system. However, if the available stock in hand changed due to an order being placed in your sales system, the quantity for sales has already been adjusted. Hence, you should ignore events that derives from the sales system itself. You can do that by checking the sellerId property of the event object. If it is equal to the id of the sales channel that corresponds to your sales system, then you should ignore the event.

Notice that corrections to the quantity for sales must be done incrementally. You must add the value of the delta property to the quantity for sales. You may want to establish a routine that overwrites the quantity for sales with the currently available stock in hand. Clearly, this routine must run at a time when none or few orders are created in your sales system. You can obtain the current stock in hand from the trade items:

GET /globalTradeItems

If you have many trade items, you should use pagination:

GET /globalTradeItems?maxNumRows=1000&firstRow=2000

Trade item created

The event is described here.

If you are using Thetis IMS as your item master, you should listen for this event, so that you can create new items in your sales system as they are created in Thetis IMS.

If you want to store information in Thetis IMS - for instance to make it possible to look up corresponding items in your sales system - you may use the dataDocument field of the trade item or the product.