Skip to main content

External warehouse integration

An external warehouse can integrate with OMS through GraphQL queries and mutations. The integration has three goals:

  • Pull the orders to fulfil from OMS, with everything needed to prepare the shipments — order lines, shipping details and, when the waybill is produced by Calicantus, the shipping labels to apply to the parcels.
  • Declare the fulfilment — only in projects where the warehouse validates each shipping before OMS ships it: report the parcels prepared and the quantities packed, or cancel the fulfilment when nothing is shipped, so that OMS can book the carrier and issue the shipping label. Many integrations do not include this step: OMS books the carrier on its own and the warehouse only pulls the orders and their labels.
  • Handle the returns: pick up the repayment requests waiting for the warehouse, report the goods actually received and their condition, and confirm the reception — so that the approval and any refund can proceed in OMS.
note

The orders reach OMS through the e-commerce channel, not through this integration: the scope described here is only the direct exchange between OMS and the warehouse. If the warehouse produces its own waybills, that part of the flow is agreed with Calicantus during onboarding and is not covered by this page.

How the integration works​

Pull the orders to fulfil​

How the work queue is built depends on how your project is configured in OMS — Calicantus tells you which setup applies to you during onboarding:

  • Standard setup — OMS books the carrier on its own. The queue is the orders query filtered on status: completed: the order has been processed by OMS but not shipped yet — from that moment it is in the warehouse's court. The Filter by order status guide documents the status filter; instead of polling, OMS can notify you when an order becomes completed with the Order / completed webhook event. The fulfilment mutations of the next section are not part of this setup.
  • The warehouse validates the shippings (next section): OMS holds the carrier booking until the warehouse declares what was packed, so the shippings to prepare are those with fulfillmentStatus: pending and bookingStatus: pending — the orders query filtered on the shippings (see Filtering). The order itself is still processing at this stage.

Order and shipping statuses explains the full order lifecycle and the three statuses of a shipping.

The same orders query can include everything needed to prepare the shipments: lines with SKUs and quantities, billing data, shippings and the shipping documents. The Get order details and Get order documents guides document the available fields; keep an eye on the query cost (see Rate limiting).

Declare the fulfilment​

This section applies only to projects where the warehouse validates the shippings (see above); skip it otherwise. In this setup each shipping waits for your declaration before OMS books the carrier. Once the goods are packed, close the step with one of two mutations, documented field by field, with the validation rules, in Confirm or cancel a fulfilment:

  1. Confirm the fulfilment with shippingFulfillmentConfirm: the parcels prepared and, when the shipping is not packed in full, the quantity packed for each item line (lines not listed have nothing packed), with the serial or batch numbers if you track them. Without lines, the whole shipping is fulfilled.
  2. Cancel the fulfilment with shippingFulfillmentCancel when nothing is packed and nothing will be shipped.

Things to know:

  • Each shipping accepts one declaration and there are no follow-up calls: a partial confirmation is final too (the missing items are not shipped with it), so send it when the parcels are closed.
  • After the confirmation OMS books the carrier with the parcels you declared and the shipping label is issued — see the next section.
  • There is no webhook event for shippings waiting to be fulfilled: poll the orders query periodically, as for the returns.

The shipping labels​

When the waybill is produced by Calicantus, the shipping labels are available on the order as soon as the carrier booking is confirmed — right away for an order that is completed in the standard setup, after your fulfilment confirmation when the warehouse validates the shippings: one shipping label (waybill) per parcel — a multi-parcel shipping has multiple labels. The shipping's bookingStatus field tells where the booking process stands: confirmed means the shipping label has been generated. The Get order details and Get order documents guides show how to read it and retrieve the labels. OMS can also notify your integration when a shipping label is issued — see the ShippingLabel / issued webhook event.

Handle the returns​

Returns enter OMS as repayment requests (see their lifecycle): when customer care confirms a return, the repayment request moves to waiting_warehouse_reception — from that moment it is in the warehouse's court.

  1. Pick up the returns to process with the repaymentRequests query, filtering on status: waiting_warehouse_reception — the Filter by status and update date guide documents this filter, with the updatedAt condition to pick up only what changed since your last poll. Each repayment request carries its return shipping: its status uses the same values as order shippings, so delivered means the returned goods have reached the warehouse.
  2. Inspect the goods and report the evaluation. For each returned line, record how many items actually came back and how many are in acceptable condition with the repaymentReturnedLineSetQuantities mutation (quantityReceived and quantityCompliant — the compliant quantity cannot exceed the received one). If the parcel contains an item that was not expected as part of the return, add it with the repaymentReturnedLineCreate mutation. Both are documented field by field, with verified examples, in Manage returned lines.
  3. Confirm the reception with the repaymentReturnLinesEvaluationConfirm mutation once the evaluation is complete: the repayment request moves from waiting_warehouse_reception to waiting_for_approval, and the approval and any refund proceed in OMS — see Confirm return line reception.

Things to know:

  • There is no webhook event for new repayment requests: poll the repaymentRequests query periodically to pick up the returns waiting for the warehouse.
  • Quantities can be adjusted only while the repayment request is in waiting_warehouse_reception or waiting_for_approval (any other status is rejected), but the confirmation is accepted only in waiting_warehouse_reception: review the evaluation before confirming.
  • An order can have multiple repayment requests over time — always work at the repayment request level, not at the order level.
  • The full detail of a repayment request — lines, returned lines, return reason and shipping — is returned by the repaymentRequest query, documented in Get repayment request details.

What you need to get started​

Everything below is agreed with and configured by Calicantus — to start the onboarding, contact developers@calicant.us:

  1. API credentials — the integration authenticates like any other API client: see Authentication.
  2. Your warehouse configured in OMS — the orders and the returns the integration works on are the ones assigned to your warehouse, configured for you by Calicantus.

Before going live, also review the core concepts of the API in Getting started — in particular Errors and Rate limiting.