Guidelines for integrating a goods owner's IT system
Table of contents
Introduction
Ongoing WMS' open API allows developers to connect an IT system, such as an ERP system or ecommerce platform, to Ongoing WMS. This enables companies to take use of Ongoing WMS for their warehousing needs no matter if they have outsourced their Logistics or if they have their own warehouse. This means that the developer is responsible for the development, configuration and maintenance of the integration. All the developer needs from Ongoing are the API keys, allowing the developer to build integration with Ongoing WMS' API. If the developer needs it, Ongoing will charge according to our hourly rate for giving support or assistance during the development.
Ongoing has also developed a few integrations to commonly used ecommerce platforms and some ERP systems. Those integrations have a standard set up that is easy to set up and start running. A set of settings allows some customization of the integrations. If you need a more tailored integration than the settings provide, you should find a developer to build the integration towards Ongoing WMS' API according to you needs. These and integrations built by other developers are listed on Ongoing WMS' integrations page.
This document points out a few things to consider when a developer is building an integration to Ongoing WMS. It is a good idea to go through this document up front and consider what information the integration must contain, what reports you want to extract from Ongoing WMS and what information is required to pass on to other systems along the supply chain e.g. the transport administration system. Ongoing WMS itself requires very little information for an integration to work. For example, you only need an article number to create an article. It is the work processes at the warehouse or legal reasons which will determine the information required (e.g. scanning requires barcodes and customs requires statistic numbers, country of origin and product prices).
This document also contains a few references to where to read/write data in Ongoing WMS' API. Those are written in italic and are aimed for the developer building the integration. Depending on your system set up, deviations may occur.
A typical integration
Below outlines a typical integration. There are plenty of other features in Ongoing which also can be used to fulfill your requirements.
- Synchronize the product information from the other IT system to Ongoing WMS' article register. Master data is in the other IT system. This synchronizes the article definitions, not the stock numbers.
- Transfer purchase orders from the other IT system to Ongoing WMS.
- Register the in Ongoing WMS received stock numbers (per purchase order) in the other IT system.
- Transfer sales orders to Ongoing WMS from the other IT system.
- Register sales orders which have been delivered in Ongoing WMS in the other IT system.
- Synchronize the stock numbers from Ongoing WMS to the other IT system. Master data is in Ongoing WMS.
The integration set up differs depending on the system to which the integration is built. E.g. a ecommerce platform integration does not normally contain purchase orders. Further messages may be needed for e.g. handling returns or tracking numbers.
Articles and stock values
Article numbers
Article numbers are normally used as a unique identifier in Ongoing WMS and need to be matched to a unique identifier, or unique combination, in the other IT system. The article number can contain letters, numbers and characters. The characters ! % _ ^ \ are used as special search values in Ongoing WMS and should not be part of the article number.
Scanning
If the warehouse intends to use scanning, a barcode (or another code that is used in the warehouse scanning module) should be specified on each article definition. Barcodes are placed at ArticleDefinition - BarCode. This field refers to the barcode for the stock keeping unit (SKU), if other barcodes are used per package, those can be set at ArticleDefinition - BarCodePackage.
Customs information
If you wish to extract proformas from Ongoing WMS, or if custom information needs to be forwarded to another system, e.g. a TA-system, at least the following information should be sent to Ongoing WMS. Make sure this information is available in the system.
- County of origin per article definition (ArticleDefinition - CountryOfOriginCode)
- Statistical number/ HTS code per article definition (ArticleDefinition - StatisticsNumber)
- Price per order row – 2 different prices can be set per order row. (CustomerOrderLine – CustomerLinePrice and LinePrice)
- Currency per order row (CustomerOrderLine – CurrencyCode)
- Possibly VAT per order row (CustomerOrderLine – VatCode)
Synchronizing stock values
Please see our page about Inventory for thorough information about how stock values are handled in the API.
Purchase orders and orders
Purchase orders
Purchase orders (advising an inbound delivery) can be used in an integration, but it is not mandatory. Purchase orders make it easier to report received goods back to the other IT system than if the goods are received without a purchase order.
Tracking
Ongoing WMS is typically integrated to a shipping platform or directly to the carrier. When a delivery has been booked, Ongoing receives tracking information which is stored. These can be retrieved by the other IT system through the API in Ongoing WMS. The information is typically available when an order is sent and can therefore be retrieved at the same time as you get other information about the shipped order. If you use the REST API tracking information is visible directly on the order using the tracking or returnTracking object. Here you find the tracking URL and waybill number. Not all carriers provide a tracking number on this level but instead provide tracking for each parcel. Tracking URLs for these parcels are found on the tracking object in the list of parcels. If you are using the SOAP API, please refer to this guide about how to get tracking information.
Customer information
When creating an order in Ongoing WMS, we recommend that you always specify the customer's address. If you are using the SOAP API, we also recommend that you set CustomerIdentification = FullNameAndAddress or CustomerIdentification = CustomerNumber.
The address must be split up in name, address row, zip code, city and country. It cannot be sent in as one text string.
Set transporter and transporter service
The transporter and transporter service can be set on the order though the integration. The codes sent to Ongoing WMS must match the codes listed in Ongoing WMS. Make sure the developer setting up the integration has access to those codes. They can also be fetched using the API function GetTransporterContracts.
Partial deliveries
Discuss with your customer how to work with partial deliveries, and who should have control of the partial deliveries. Some integrations are set up in such way, that orders should not be able to contain goods out of stock. However, due to missing goods, or errors at in- or outbound deliveries, damaged goods, or missing goods, it might still occur that the warehouse receives orders which they cannot satisfy fully.
Even if you do not plan to use partial deliveries it is good to have discussed the procedure. Below are some common ways to handle partial deliveries.
- No partial deliveries: Orders are only sent if all goods are available to pick. The order will be on hold until all items can be picked.
- Stock value based: In this case, all items available to pick will be shipped. As soon as a missing item returns in stock the order will be picked again. This may result in multiple deliveries of one order, and the goods owner does not have control over the partial deliveries. Ongoing WMS can be set up automatically create a back order when picking parts of an order, or you can continue to pick from the same order.
- Goods owner controlled: Another way of working with partial deliveries is to let the goods owner control the partial deliveries. The warehouse will pick all available goods and report the delivered number of items to the other IT system. If the rest of the goods should be sent in a partial delivery, the goods owner should create a back order and send it to Ongoing WMS.
Returns
A returned item can be handled in different ways in Ongoing WMS:
- It can be returned on the outbound order which was originally used to send the item to the customer.
- It can be returned using a purchase order which has been marked as being a return.
- It can be returned on a return order.
If the return should be linked to a specific order and there is no need to advise the warehouse of the incoming return, then the return can be done directly on the outbound order.
Discuss with the warehouse and the warehouse client which process is used. If they have not selected one, the warehouse's contact person at Ongoing can help you decide which way is most suitable for your business.
Orders
If the return should be linked to a specific order and there is no need to advise the warehouse of the incoming return, the return is done directly on the outbound order. Returns takes place continuously until the warehouse is done with all article returns on an order. Finally, the status of the order is changed to Returned (800). Please make sure such a status exists in the Ongoing WMS account before relying on it.
To make sure that all returns are performed against an order before an action is performed in the other IT system it is recommended to wait for the order to get status Returned (800) before further actions are taken.
REST API
To get returns connected to an outbound order you can query the API endpoint /api/v1/orders periodically with the query parameters orderStatusChangedTimeFrom where you specify a date and time, orderStatusFrom = 800 and orderStatusTo = 800.
SOAP API
To get returns connected to an outbound order you can query the API function GetOrdersByQuery periodically and filter by OrderStatusChangedTimeFrom where you specify a date and time. Also use the filter OrderStatusFrom and OrderStatusTo set to 800 (Returned).
Webhooks
Subscribe to the webhooks Order status is changed and Article is returned. When you receive the webhooks you check to order status and additional information using SOAP or REST API. If it is Returned (800), you can perform additional actions.
Return orders
A return order is used when there is only one original order being returned, the returned orders were shipped from same Ongoing WMS account and there is a need to advise the warehouse about the return. An advised return can help them plan their staffing and it can also help them to know why something is returned to handle it more efficiently.
REST
Return order are advised. If you want to advise the warehouse on an incoming return order, send a PUT to /api/v1/returnOrder to create or update a return order. To get returns you can query the API endpoint api/v1/returnOrders periodically using the query parameters goodsReturnedFromDate where you specify a date and time, orderStatusFrom = 400 and orderStatusTo = 500.
SOAP
Return orders are advised. If you want to advise the warehouse on an incoming return order, use ProcessReturnOrder to send the information to the warehouse. Query GetReturnOrdersByQuery periodically to read information about the returns. Use the query filters GoodsReturnedFromDate, ReturnOrderStatusFrom = 400 and ReturnOrderStatusTo = 500.
Webhooks
Subscribe to the webhook Article is returned. When you receive the webhook you check the return order status using SOAP or REST API. If it is Deflection (400) or Received (500), you can perform additional actions based on the data received.
Purchase order (Inbound order)
A purchase order is used when some advice for the return is required and there are multiple original orders returned in the same shipment or there is no original order in the Ongoing WMS account. The latter is common when Ongoing WMS is used in an ecommerce return hub while the former is common when returns are sent back from B2B customers or retail shops.
REST
To advise the warehouse of an incoming return, send a PUT to api/v1/purchaseOrders to add or update it in Ongoing WMS. Make sure to set InOrderIsReturnType to true.
To get the returns you can query the API endpoint API/v1/purchaseOrders periodically using the query parameters purchaseOrderStatusChangedTimeFrom where you specify a date and time, purchaseOrderStatusFrom = 400 and purchaseOrderStatusTo = 500.
SOAP
To advise the warehouse of an incoming return you can use ProcessInOrder to add or update it in Ongoing WMS. Make sure to set InOrderIsReturnType to true.
You can fetch the returns by periodically polling the API function GetInOrdersByQuery and filter by IsReturnType, InOrderStatusChangedTimeFrom, InOrderStatusFrom = 400 and InOrderStatusTo = 500.
Webhooks
Subscribe to the webhooks Purchase order is received and Inbound transaction has been performed. Lookup the purchase order using either SOAP or REST API. Do not perform any additional actions such as repayment until the purchase order is received.
Delivery notes and other reports
Go through the delivery notes and reports your customer wants to extract from Ongoing WMS and make sure the integration will contain all this information. E.g. if the delivery note will contain invoicing address, this must be passed on to Ongoing WMS.