Integrating as a warehouse/3PL provider

This guide is aimed at warehouse or 3PL providers who want to provide kitting and/or fulfilment for the Hurdle network.

Basic Flow

Not all steps may be applicable to you.
If you are only providing kitting (step 3 only) or fulfilment (all steps apart from 3).

1. Retrieve a list of orders that need fulfilling
2. [Optional] Lock the order so it cant be modified while you process it
3. Create a kit
4. Assign kits to the order
5. Mark order as dispatched

📘

The Warehouse API uses a different authentication method/token than outlined here. Please contact your account manage to get this.

Terminology

Order Number: Our internal reference to the order. Normally in the form of RT12345. Currently orders only ever contain items of the same type (but with possible multiple quantities).

Kit ID: 8 digit code (ie KLRR8451) that identifies the box and is normally printed on the box or instructions.

Barcode: Long barcode that is printed on the collection device

We will supply you with a list of Kit IDs to be used.

Walkthrough

1. Retrieve a list of orders that need fulfilling

First up, you need a list of orders to fulfil.

You can do this by calling Get list of orders at regular intervals (suggested every 1 hour) with dispatched=false or processAtGte=[timestamp you last called this] to ensure you only get order than need processing OR we can send orders to your SFTP server at regular internals to process.

2. [Optional] Lock the order

This lets us know you are starting to process the order and prevents us canceling or changing the order while you are processing it. Call Update an order with processing=true

3. Create a kit

When you physical build the kit (place all the components such as collection device and IFUs into the box) we need to know what those components are and link them back to the kit.

Call Create a new sample kit with the kitId and other information.
tubeBarcode is optional but should always be provided where possible so we know what tubes are in which kit.
returnPostageLabel is the shipping tracking number from the return postage label inside the kit (ie UPS shipping number)
returnLab is the ID of the lab on the return shipping label (Hurdle will provide)

4. Assign kits to the order

Now you need to tell us which order you are assigning the newly created kit to.

Call Assign package (kit) to the order item with the required information.
orderNumber is the order number you retrieved in step 1.
itemId is the items.orderItemId from the order data in step 1.
packageId is the Kit ID that is printed on the box.
packageType should be KIT

If an order has multiple items in it, you will need to call this multiple times for each kit to assign it to the order.

5. Mark order as dispatched

Once all the required kits have been assigned to an order and you have shipped then you can mark the whole order as dispatched and provide the shipping tracking to us.

Call Order update again with dispatched=true and the shippingLabel. In case of any issues with the order (ie bad address) you can call Flagging order as dropped to let us know you cant process the order.