In Kibo, a Shipment is the fundamental object in the fulfillment process. It’s a concrete, actionable instruction for a specific location (like a warehouse or a retail store) to pick, pack, and dispatch a set of items from an order.The key thing to understand is the separation of concerns:
An Order is the customer’s request—what they bought.
Order Routing is the decision—how the order should be fulfilled.
A Shipment is the action—the specific “to-do list” sent to a fulfillment location.
An order can be broken down into multiple shipments, each assigned to a different location. Managing the lifecycle of these individual shipments is the core of fulfillment in Kibo.
The Shipment is the workhorse of the post-purchase process. It’s where the digital order becomes a physical reality.
Order Routing: The output of the Order Routing engine is a “suggestion” that becomes the direct input for creating one or more shipments.
Inventory: When a shipment is created, Kibo firms up the inventory reservation. When it’s fulfilled, the onHand inventory at the assigned location is finally decremented.
Customer: The customer is notified about the progress of their shipments, including tracking numbers which are stored on the shipment record.
Returns: If a customer wants to return an item, the return is processed against the original shipment it came from.
Kibo’s Fulfillment data is built around a state machine, where a Shipment moves through various stages. The core objects are:
Shipment: The main object representing a fulfillment task.
shipmentNumber: A unique, Kibo-assigned number identifying the shipment.
orderId: The order this shipment belongs to.
locationCode: The specific location responsible for fulfilling this shipment.
workflowState: The current stage of the shipment (e.g., Ready, Fulfilled, Cancelled). This is the most important status field.
items: An array of ShipmentItem objects detailing the products and quantities to be fulfilled.
Pickup: For “Buy Online, Pick Up in Store” (BOPIS) shipments, a related Pickup object is created to manage the customer pickup process.
Task: This is an action you send. To change a shipment’s state (e.g., to fulfill it), you must execute a named task on it, like "Fulfill". This is a key Kibo pattern.
Task-Based Workflow:
This is the most important pattern in fulfillment. You cannot directly modify a shipment’s state. You must use the “Fulfill” task to move a shipment from Ready to Fulfilled. The request to execute a task looks like this:
Error Handling Approach:
If an API call fails, the SDK throws a structured error. A common error is a VALIDATION_ERROR if you try to execute a task that isn’t valid in the shipment’s current workflowState.API Documentation Reference:
Find complete specs under the “Fulfillment” section at:
/api-overviews/openapi_fulfillment_overview
Kibo developers typically work with Shipments in these scenarios:
Backend Integration: A Warehouse Management System (WMS) uses the API to get new shipments, and then notifies Kibo as they are packed and shipped.
In-Store Operations: Building a simple tablet application for store associates to manage BOPIS orders, marking them ready for pickup and then as collected.
Customer Service Tools: A custom UI for support agents to cancel or reassign shipments when a customer calls with an issue.
The following examples use the Task-Based Pattern to move shipments through their lifecycle, which is the correct and auditable way to manage shipment state in Kibo.
All examples rely on a base Configuration and ShipmentApi client instance.
// Essential imports for Fulfillment operations.import { Configuration } from "@kibocommerce/rest-sdk";import { ShipmentApi, PickupApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";import { Task, Pickup, PickupItem } from "@kibocommerce/rest-sdk/models/Fulfillment";// Configuration setup - this single object is reused for all API clients.const configuration = new Configuration({ tenantId: process.env.KIBO_TENANT_ID, siteId: process.env.KIBO_SITE_ID, clientId: process.env.KIBO_CLIENT_ID, sharedSecret: process.env.KIBO_SHARED_SECRET, authHost: process.env.KIBO_AUTH_HOST,});const shipmentApi = new ShipmentApi(configuration);
Issue 1: My shipment is “stuck” and I can’t update it.
Why it happens: The shipment object is largely read-only; its state is controlled by the task-based workflow. Developers mistakenly try to PUT an update to the shipment object to change its status.
How to fix it: You must use the performShipmentTask (or execute) endpoint for all state changes. Before trying to change a shipment, ask “What task do I need to execute?”
Issue 2: The order status is still “Awaiting Shipment” even after I fulfilled one of its shipments.
Why it happens: An order’s status is an aggregate of all its shipments. The order will not move to a Completed status until all of its constituent shipments have been fulfilled (or canceled).
How to fix it: Ensure your fulfillment process handles all shipments associated with the order.
