list_customers
Retrieve and filter customer data from ShipStation API by page, size, name, location, or marketplace ID. Sort results by specific fields and directions for efficient customer management.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| countryCode | No | Filter by country code | |
| marketplaceId | No | Filter by marketplace ID | |
| name | No | Filter by customer name | |
| page | No | Page number | |
| pageSize | No | Number of customers per page (max 500) | |
| sortBy | No | Sort customers by a specific field | |
| sortDir | No | Sort direction | |
| stateCode | No | Filter by state code |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"countryCode": {
"description": "Filter by country code",
"type": "string"
},
"marketplaceId": {
"description": "Filter by marketplace ID",
"type": "number"
},
"name": {
"description": "Filter by customer name",
"type": "string"
},
"page": {
"description": "Page number",
"type": "number"
},
"pageSize": {
"description": "Number of customers per page (max 500)",
"type": "number"
},
"sortBy": {
"description": "Sort customers by a specific field",
"type": "string"
},
"sortDir": {
"description": "Sort direction",
"enum": [
"ASC",
"DESC"
],
"type": "string"
},
"stateCode": {
"description": "Filter by state code",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/tools/customer-tools.js:18-30 (handler)The handler function that executes the list_customers tool by fetching customers from ShipStation API and returning formatted JSON response or error.handler: async (params) => { try { const customers = await shipStationClient.getCustomers(params); return { content: [{ type: "text", text: JSON.stringify(customers, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: error.message }], isError: true }; } }
- src/tools/customer-tools.js:8-17 (schema)Zod schema defining the input parameters for the list_customers tool, including pagination, sorting, and filtering options.schema: { page: z.number().optional().describe("Page number"), pageSize: z.number().optional().describe("Number of customers per page (max 500)"), sortBy: z.string().optional().describe("Sort customers by a specific field"), sortDir: z.enum(["ASC", "DESC"]).optional().describe("Sort direction"), name: z.string().optional().describe("Filter by customer name"), stateCode: z.string().optional().describe("Filter by state code"), countryCode: z.string().optional().describe("Filter by country code"), marketplaceId: z.number().optional().describe("Filter by marketplace ID") },
- src/server.js:173-191 (registration)Registration loop that adds the list_customers tool (from customerTools) to the MCP server using server.tool().// Register all tools [ ...orderTools, ...shipmentTools, ...carrierTools, ...warehouseTools, ...productTools, ...customerTools, ...storeTools, ...webhookTools, ...fulfillmentTools ].forEach(tool => { server.tool( tool.name, tool.schema, tool.handler, { description: tool.description } ); });