list_shipments
Retrieve shipment data from ShipBob's fulfillment API by filtering with order ID, date range, or pagination parameters for efficient tracking and management.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | No | End date for filtering (YYYY-MM-DD) | |
| limit | No | Number of shipments per page | |
| orderId | No | Filter by order ID | |
| page | No | Page number for pagination | |
| startDate | No | Start date for filtering (YYYY-MM-DD) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"endDate": {
"description": "End date for filtering (YYYY-MM-DD)",
"type": "string"
},
"limit": {
"description": "Number of shipments per page",
"type": "number"
},
"orderId": {
"description": "Filter by order ID",
"type": "string"
},
"page": {
"description": "Page number for pagination",
"type": "number"
},
"startDate": {
"description": "Start date for filtering (YYYY-MM-DD)",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/tools/fulfillment-tools.js:15-31 (handler)The main handler function for the 'list_shipments' tool. It collects parameters, calls shipbobClient.getShipments(), formats the response as JSON text, or returns an error message.handler: async ({ page, limit, orderId, startDate, endDate }) => { try { const params = { page, limit, orderId, startDate, endDate }; const shipments = await shipbobClient.getShipments(params); return { content: [{ type: "text", text: JSON.stringify(shipments, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error listing shipments: ${error.message}` }], isError: true }; } }
- src/tools/fulfillment-tools.js:9-14 (schema)Zod schema defining the input parameters for the list_shipments tool, all optional with descriptions.page: z.number().optional().describe("Page number for pagination"), limit: z.number().optional().describe("Number of shipments per page"), orderId: z.string().optional().describe("Filter by order ID"), startDate: z.string().optional().describe("Start date for filtering (YYYY-MM-DD)"), endDate: z.string().optional().describe("End date for filtering (YYYY-MM-DD)") },
- src/tools/fulfillment-tools.js:5-32 (registration)The complete tool definition object for 'list_shipments', including name, description, schema, and handler, added to the fulfillmentTools export array.{ name: "list_shipments", description: "List shipments in your ShipBob account", schema: { page: z.number().optional().describe("Page number for pagination"), limit: z.number().optional().describe("Number of shipments per page"), orderId: z.string().optional().describe("Filter by order ID"), startDate: z.string().optional().describe("Start date for filtering (YYYY-MM-DD)"), endDate: z.string().optional().describe("End date for filtering (YYYY-MM-DD)") }, handler: async ({ page, limit, orderId, startDate, endDate }) => { try { const params = { page, limit, orderId, startDate, endDate }; const shipments = await shipbobClient.getShipments(params); return { content: [{ type: "text", text: JSON.stringify(shipments, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Error listing shipments: ${error.message}` }], isError: true }; } } },
- src/server.js:50-58 (registration)Calls registerTools(fulfillmentTools) which loops over the array and registers each tool (including list_shipments) with the MCP server using server.tool().registerTools(productTools); registerTools(orderTools); registerTools(inventoryTools); registerTools(fulfillmentTools); registerTools(webhookTools); registerTools(returnTools); registerTools(locationTools); registerTools(channelTools); registerTools(reportingTools);
- src/api-client.js:106-108 (helper)Helper method in ShipBobClient that makes the actual API request to list shipments, called by the tool handler.async getShipments(params) { return this.request('GET', '/shipments', null, params); }