Connect Linnworks to ChatGPT: Manage Inventory, Orders, and Shipping

If you need to connect Linnworks to ChatGPT so your AI agents can manage multi-channel inventory, process sales orders, and orchestrate warehouse shipments, you need a Model Context Protocol (MCP) server. If your team uses Claude, check out our guide on connecting Linnworks to Claude or explore our broader architectural overview on connecting Linnworks to AI Agents.

Giving a Large Language Model (LLM) read and write access to an enterprise commerce and logistics platform is a severe engineering challenge. You must handle complex relational data payloads, translate LLM JSON arguments into Linnworks's highly specific warehouse management structures, and maintain the infrastructure as APIs evolve. You either spend weeks building and hosting a custom MCP server, or you use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to use Truto to generate a secure MCP server for Linnworks, connect it natively to ChatGPT, and execute complex supply chain workflows using natural language.

Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds. :::

The Engineering Reality of the Linnworks API

A custom MCP server is essentially a self-hosted integration proxy. While the open MCP standard provides a predictable way for models to discover tools, implementing it against Linnworks's highly specific API is exceptionally painful. If you decide to build a custom MCP server for Linnworks, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Linnworks:

Multi-Channel SKU Mappings and Location Nuances

Linnworks is not just a flat inventory database; it is a complex routing engine mapping abstract inventory items to channel-specific SKUs across dozens of integrations like Amazon, eBay, and Shopify. Syncing stock means your MCP server must understand how to traverse StockItemChannelSKU structures, deal with MaxListedQuantity overrides, and navigate location-specific BinRacks. If an LLM simply tries to "update stock to 50", it will fail unless the tool explicitly handles the StockLocationId and determines if the item is part of a composite parent item that requires cascading updates.

Batch-Tracked vs. Standard Inventory Operations

Processing orders requires distinguishing between standard items and batched items, which carry explicit expiry dates, sell-by dates, and batch numbers. When programmatically delivering a purchase order or processing a sales order, you cannot use the same generic endpoint for both types of inventory. Processing an order with batched items requires explicit batch-scanning inputs or hitting specialized endpoints like PurchaseOrder_Deliver_PurchaseItemAll_ExceptBatchItemsRequest. If your custom MCP server lacks this contextual awareness, LLMs will consistently hallucinate payloads that the Linnworks API rejects.

Identifier Fragmentation: pkOrderId vs. NumOrderId

Linnworks utilizes dual identifiers across its system. An order has a human-readable NumOrderId (e.g., 102934) and a system-level UUID pkOrderId (e.g., 00000000-0000-0000-0000-000000000000). The API heavily enforces the use of the pkOrderId for write operations, but users interacting with ChatGPT will almost exclusively reference the NumOrderId or a channel-specific reference number. Your custom server must silently resolve these identifiers before executing actions, otherwise, the LLM will fall into an infinite loop of failed tool calls.

Linnworks to ChatGPT Quickstart Guide

If you want the fastest path from a fresh Truto account to ChatGPT calling the Linnworks API, follow these steps.

What you need:

• A Truto account with API access.
• Linnworks developer portal credentials (Application ID and Application Secret) for OAuth.
• A ChatGPT Pro, Plus, Business, Enterprise, or Education seat with Developer mode available.

Step 1: Connect Linnworks to Truto

First, establish the connection between Truto and Linnworks. Truto acts as the unified proxy, managing the OAuth lifecycle, token refreshes, and API normalizations.

In the Truto dashboard, navigate to Integrated Accounts -> New Integrated Account, select Linnworks, and run the OAuth flow. Truto securely stores the refresh token and automatically refreshes access tokens shortly before they expire. Your ChatGPT instance will never see an expired credential.

Step 2: Create the MCP Server

Truto automatically generates dynamic, documentation-driven MCP tools based on the resources available in the Linnworks API. You can create the server via the UI or the API.

Method A: Via the Truto UI

1. Navigate to the integrated account page for your Linnworks connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., filtering for specific tags like inventory or orders).
5. Copy the generated MCP server URL.

Method B: Via the API You can programmatically scope an MCP endpoint to a specific integrated account using a single POST call:

curl -X POST https://api.truto.one/integrated-account/$INTEGRATED_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Linnworks Ops Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["inventory", "orders", "shipping"]
    }
  }'

The response contains a url field resembling https://api.truto.one/mcp/<token>. This URL carries the routing instructions and cryptographic authentication needed to expose Linnworks to ChatGPT.

Step 3: Connect the Server to ChatGPT

Once you have the URL, you must register it as a custom connector in ChatGPT.

Method A: Via the ChatGPT UI

1. In ChatGPT, click your profile picture and go to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers / Custom connectors, click Add new server.
4. Enter a name (e.g., "Linnworks Logistics").
5. Paste the Truto MCP URL into the Server URL field.
6. Save the configuration. ChatGPT will immediately connect and discover the available Linnworks tools.

Method B: Via Manual Config File If you are using a local agent framework or standard MCP client configuration file, you can connect using the Server-Sent Events (SSE) transport protocol:

{
  "mcpServers": {
    "linnworks_ops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/<token>"
      ]
    }
  }
}

Security and Access Control

Exposing an ERP and logistics engine to an LLM requires strict boundaries. Truto provides embedded access control mechanisms to safely sandbox your MCP server.

• Method Filtering (config.methods): Restrict the AI agent to specific HTTP methods. Passing ["read"] ensures the LLM can only execute get and list operations, preventing it from accidentally updating stock levels or dispatching shipments during exploratory queries.
• Tag Filtering (config.tags): Scope the server by functional domains. If you only want ChatGPT to answer customer support queries, filter tags to ["orders", "returns"] and exclude ["inventory", "purchasing"].
• Time-To-Live (expires_at): Set an ISO datetime string when creating the server. Once the expiry is reached, Truto automatically cleans up the database records and Cloudflare KV entries, permanently revoking access.
• API Token Auth (require_api_token_auth): By default, the Truto MCP URL is self-authenticating via a cryptographic hash. If you set this flag to true, the client must also pass a valid Truto API token in the Authorization header, adding a required secondary layer of authentication.
• Rate Limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When Linnworks returns an HTTP 429, Truto passes that error directly to ChatGPT. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your MCP client is responsible for handling retry and backoff logic.

Hero Tools for Linnworks

Truto exposes the entirety of the Linnworks API surface. Here are six high-leverage tools available to your AI agents immediately upon connection.

Get Order by ID

Tool Name: get_single_linnworks_orders_get_order_by_id

Retrieves the comprehensive order detail for a single Linnworks order by its unique system ID (pkOrderId). This payload includes shipping info, customer delivery details, line items, stock levels, and subsource routing data.

"Fetch the complete order details for order ID 458a2f1b-9c3e-4b21-a123-5e8f9d0c1b2a. I need the customer's shipping address and the binrack locations for all items in the order."

Search Stock Items

Tool Name: list_all_linnworks_inventory_get_stock_items

Lists Linnworks stock items matching a keyword or SKU, optionally scoped to a specific warehouse location. It includes critical flags to filter out composites, variations, or batches from the report depending on the operational context.

"Search the inventory for all stock items containing the keyword 'Wireless Earbuds' in the 'Main Warehouse' location. Exclude composite parent items from the results."

Update Inventory Levels

Tool Name: update_a_linnworks_inventory_update_inventory_item_level_by_id

Updates stock level records for a specific stock item and automatically cascades updates to any related composite parent items in Linnworks.

"Update the inventory stock level for SKU 'WRL-EAR-001'. Add 50 units to the current stock level in the 'Overflow Facility' location."

Process Order

Tool Name: create_a_linnworks_orders_process_order

Advances a specific order through the processing workflow, changing its status from open/printed to processed, and deducting the corresponding stock from inventory. This operation requires strict validation of the provided UUID.

"The items for order 458a2f1b-9c3e-4b21-a123-5e8f9d0c1b2a have been packed. Process the order in Linnworks to deduct the inventory and move the order to the completed state."

Create Initial Purchase Order

Tool Name: create_a_linnworks_purchase_order_create_purchase_order_initial

Generates a new purchase order in PENDING status. This is the first step in the procurement workflow, establishing the PO header before stock item lines are subsequently added to the manifest.

"Create a new initial purchase order for supplier ID 88392. Set the expected delivery date for next Tuesday and mark the reference as 'Restock-Q3-Rush'."

Search Returns & Refunds

Tool Name: list_all_linnworks_returns_refunds_search_returns_refunds_pageds

Searches the Linnworks returns, refunds, and cancellations history matching date-range and text-search criteria. Returns a highly structured paged result detailing exactly what was returned and why.

"Search the returns and refunds history for the past 30 days for any records matching the customer email 'example@domain.com'."

Explore the complete Linnworks tool inventory and schema definitions in the Truto Integration Directory.

Workflows in Action

Connecting ChatGPT to Linnworks allows you to orchestrate complex logistics workflows autonomously. Here are two real-world scenarios.

Scenario 1: Resolving a Stock Outage and Reordering

When a warehouse manager notices low stock, they typically have to cross-reference SKUs, check supplier performance, and manually construct a Purchase Order. An AI agent handles this entire chain instantly.

"Check our inventory for 'Ceramic Mug'. If the available stock is below the minimum level, find the default supplier for that item and draft a new purchase order for 200 units. Finally, add a note to the PO indicating it was auto-generated due to low stock."

Execution Steps:

1. list_all_linnworks_inventory_get_stock_items: The agent searches for 'Ceramic Mug', retrieving the pkStockItemId and noting the current available stock and minimum level.
2. list_all_linnworks_inventory_get_stock_supplier_stats: The agent identifies the default supplier ID and the specific SupplierBarcode for the item.
3. create_a_linnworks_purchase_order_create_purchase_order_initial: ChatGPT creates the base PO header in PENDING state, capturing the newly generated PO ID.
4. create_a_linnworks_purchase_order_add_purchase_order_item: The agent adds 200 units of the Ceramic Mug to the pending PO.
5. create_a_linnworks_purchase_order_add_purchase_order_note: ChatGPT appends the required internal tracking note to the PO.

Result: The warehouse manager receives confirmation that the PO has been fully drafted and is sitting in the pending queue awaiting final human approval, entirely bypassing manual data entry.

Scenario 2: Investigating an Order and Processing an RMA

Customer support agents waste significant time switching between helpdesks and Linnworks to authorize returns. ChatGPT can unify this context.

"Look up order number 105822. Check if there are any existing returns or refunds logged against it. If not, generate a new RMA booking for the item 'Bluetooth Speaker' indicating it was 'Defective on arrival'."

Execution Steps:

1. get_orders_get_open_order_id_by_order_or_reference_id_by_id: The agent resolves the human-readable NumOrderId (105822) into the required pkOrderId UUID.
2. list_all_linnworks_processed_orders_get_returns_exchanges: The LLM queries the order history to verify no duplicate returns exist.
3. list_all_linnworks_orders_get_order_items: ChatGPT fetches the specific line items to identify the OrderItemRowId for the 'Bluetooth Speaker'.
4. create_a_linnworks_returns_refunds_create_rma_booking: The agent submits the RMA payload, logging the return against the correct line item and applying the 'Defective' categorization.

Result: The customer support agent gets an immediate response confirming the RMA is booked in Linnworks, along with the RMA authorization number, allowing them to instantly reply to the customer.

Moving Beyond Custom Server Maintenance

Building an integration with the Linnworks API means dealing with a massive surface area, strict dual-identifier requirements, and complex inventory allocation logic. Writing and maintaining a custom MCP server to handle this requires constant upkeep as endpoints evolve and new data models are introduced.

By leveraging Truto's dynamic, documentation-driven MCP generation, you completely eliminate infrastructure maintenance. Truto derives tools directly from its continuously updated integration blueprints. This guarantees that your AI agents always have accurate schemas, reliable OAuth token management, and secure boundary constraints - allowing your engineering team to focus on agent orchestration instead of chasing broken API proxies.