Connecting a system through the API

Summary

The API lets your customer's system —their ERP, their online store, their integrator— send advance ship notices and shipment orders directly, and look up stock and statuses, with nobody typing anything by hand at the warehouse.

It is a web service: the customer's system sends requests to a warehouse address with an access key that identifies it. That key belongs to a single customer and only sees that customer's data. What comes in through the API lands in the same flows as what is entered by hand: the same advance ship notice, the same receipt, the same shipment. For the full journey, read Integrations: API and EDI in daily operations.

This article is the overview. The detail of each operation, with request and response examples, is in:

Before you start

The API module has to be subscribed and active in the warehouse. We turn it on: no warehouse role can.
The customer has to exist in the system, with their warehouses assigned. See Setting up a customer.
Their products have to be in the catalog with the same SKU their system will send. An unknown SKU makes the whole request fail. See Products and units and Importing products.
If you want operators to hear about what comes in, check the warehouse notifications in Warehouse notifications.

What you can do

Operation	What it does	Detail
Announce what is coming	Creates an advance ship notice (ASN) with supplier, carrier, trailer, expected date, the customer's own reference, notes and lines (SKU, quantity, unit). Its receipt is created at the same time, ready in the receipt list.	See
Request a shipment	Creates a shipment with reference, carrier, requested date, destination (name, city, state), notes and lines. It arrives already confirmed, and the system reserves stock starting with what expires first. If there is not enough, it reserves what there is.	See
Look up a shipment	Returns its status and, per line, what was ordered and what is reserved.	See
Look up a receipt	Returns its status and, per line, what was expected and what was received.	See
Look up stock	Returns, per SKU, location and lot: the expiration date, the quantity on hand, the available quantity and the first receipt date. Comes in pages of up to 200 rows.	See
Send an EDI file	Only if the warehouse also has the EDI module.	See

What happens at the warehouse

An advance ship notice shows up in the ASN list with status Sent (the system records that it came through the API, but no screen shows it today), and its receipt shows up in the receipt list as Pending, with carrier, trailer and expected quantities already filled in. Users in the roles the warehouse picked for the "new receipt" notification get it, just like with a notice entered by hand. See Advance ship notices (ASN).
A shipment shows up in the shipment list already confirmed and, if there was stock, reserved (in full or in part), ready for picking. It also notifies operators. See The shipment flow.
Stock does not move through the API. It moves when someone confirms the receipt or closes the shipment, with the usual rules. See The life of stock.
Charges are created as always: when the receipt is confirmed and when the shipment is closed, according to the customer's rate card. Arriving through the API changes nothing. See Where each charge comes from.
Documents (goods received note, bill of lading, packing list) are generated as usual on confirm and close.
The customer sees the notice and the shipment in their client portal, if they have it, and gets the receipt-confirmed and shipment-dispatched emails they have turned on.

Setting up an integration

Important: today we do this for you. There is no screen for you to generate or revoke access keys or to register callback addresses. Write to us with the details below and we will hand you the key. Revoking one also goes through us, and it is worth doing right away if you think it leaked.

What we need to know:

Which customer owns the goods.
Which warehouse or warehouses they will work in, and which is the main one.
A technical contact email on their side.
Whether they want callbacks: the web address that receives them and which events they care about (receipt confirmed, shipment closed or both).

With that we create an integration user tied to that customer, give it access to their warehouses, turn on the API module, generate the key and hand it to you along with the service address, each warehouse code and the technical specification. If they asked for callbacks, we also hand over the secret used to sign them.

Tip: the key is shown only once when it is generated. Ask your integrator to store it somewhere safe in their system, never in a forwarded email or a shared spreadsheet.

What each key can see

A key is tied to one customer and to their warehouses. It can never see or touch another customer's data: that is the central guarantee of the design. Asking for another customer's receipt or shipment, even by guessing its number, returns "not found".

If the key covers several warehouses, the customer's system says in each request which one it works in, using the warehouse code; if it does not, the key's first active warehouse is used. See The key, the warehouse and error responses.

Important: today a valid key can use every operation in the table. There are no per-key permissions (for example, "read only"): the only limit is the customer and the warehouse. Keep that in mind when deciding who gets it.

Notifications back to the customer

The warehouse can also tell the customer's system when something happens, so it does not have to keep asking:

Receipt confirmed — when the warehouse confirms goods in, with expected, received and damaged quantities per line.
Shipment closed — with the carrier, the tracking number and, per line, what was ordered and what was loaded.

Each callback is signed with a shared secret so their system can check it really comes from the warehouse. They are best effort: if the customer's system is down, warehouse operations do not stop, but that callback is lost. The detail is in Callbacks.

Example: one week at Northern Trading Co.

Monday 9:00 — Northern Trading Co.'s ERP sends an advance ship notice with its purchase order PO-7781: 120 cases of SKU NT-1001 and 40 of NT-2040, expected Wednesday. The response carries ASN ASN-NT-00031 and receipt REC-NT-00058. The ERP stores both numbers.
Wednesday 11:30 — the truck arrives. The warehouse works the receipt like any other, counts 118 cases of the first SKU (2 damaged) and confirms. Stock goes up, the receiving charge is created, the goods received note is generated and the "receipt confirmed" callback goes out to the ERP.
Thursday 8:00 — the ERP requests a shipment with its order SO-5512: 60 cases of NT-1001 for Valley Distributors in Dallas. It arrives confirmed and fully reserved.
Thursday 16:00 — the warehouse loads and closes the shipment. The "shipment closed" callback with the loaded quantities, the bill of lading and the outbound charge all go out.
Friday — the ERP looks up stock and sees 58 cases of NT-1001 available.

What the API does not do (yet)

Common request	Today	Workaround
Cancel or change a notice or shipment already sent	Not available.	The warehouse cancels or corrects it on screen.
Create or change products	Not available.	Add them to the catalog or import them.
Move, adjust or transfer stock	Not available, on purpose.	Only through warehouse actions.
Find a receipt or shipment by its number or by the customer's reference	Not available: you look it up by the internal id returned when it was created.	Store that id on creation.
Look up stock for a single SKU	No filter: you page through everything.	Ask for pages of 200 and filter on the customer's side.
Detect repeated submissions	No: each request creates a new document.	See the FAQ below.
Per-key permissions	No: every key can do everything for its customer.	One key per system, revoked when no longer used.

Good practices for the integrator

Always send their own reference in external_ref: it is what later lets them match their orders to the warehouse documents.
Store the internal ids the response returns (the id of the notice, the receipt and the shipment): those are what you look things up with later.
Always send the Accept: application/json header. Without it, some errors do not come back as JSON.
Do not blindly retry a submission that may have gone through (see below).
Test first with a test customer or a few lines, and check the result on screen with the warehouse.

Troubleshooting

My customer says they sent a notice and it is not there.

Ask for the response they got. If it was a 422, the notice was not created (for example, because of an unknown SKU). If it was a 201, search the ASN list for the number it returned.
Check that you are looking at the right warehouse: if the key covers several, the notice landed in the one the request named.

The shipment arrived but nothing is reserved.

There was no available stock when it arrived. It stays confirmed and can be reserved later from the shipment, once there is stock.

Every request returns 401.

The key was copied wrong, is not sent in the right header, or we revoked it. See The key, the warehouse and error responses.

Frequently asked questions

My integrator says the address does not exist

It almost always means the API module is not on in that warehouse. When it is off, the addresses answer "not found" instead of "not authorized", so as not to reveal that they exist. Check it with us before your integrator keeps looking for the error on their side.

We sent the same notice twice and it was duplicated

That is expected today: the API does not detect repeated submissions. Each request creates a new notice or shipment even if it carries the same reference. If the customer's system retries after a network drop, it can duplicate. Cancel the extra one at the warehouse and ask your integrator to check whether the first one arrived before retrying. (EDI, on the other hand, does recognize repeated files.)

Is there technical documentation for my integrator?

Yes. Ask us and we will send the full specification, with every operation, its fields and examples. The articles in this category are the version for people running the warehouse.

Can I see on screen what came in through the API?

Yes and no. Notices, receipts and shipments show up in the usual lists, but today no screen says they came through the API: the system records the source without showing it. To tell them apart, ask the integrator to always send their reference in external_ref and put something identifying in notes. What does not exist is a log of rejected requests: a request with an error leaves no trace at the warehouse, only in the response the customer's system received.