Connect Malomo to AI Agents: Automate Fulfillment & Order Data

You want to connect Malomo to an AI agent so your system can autonomously look up shipments, track fulfillment events, update orders, and manage webhooks based on natural language inputs or background workflows. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to hand-code integrations for your agent framework.

Giving a Large Language Model (LLM) read and write access to your fulfillment infrastructure is an engineering headache. You either spend weeks building, hosting, and maintaining custom API wrappers, or you use an infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Malomo to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Malomo to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Malomo, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex fulfillment ops. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Malomo Connectors

Building AI agents is straightforward; connecting them safely to external APIs like Malomo is not. In a local prototype, writing a single fetch request wrapped in an @tool decorator works fine. In production, an AI agent interacting with a fulfillment API will immediately expose the underlying quirks of the vendor's data model.

If you build a custom integration layer for Malomo, you are responsible for the entire API lifecycle. You must write massive JSON schemas for every endpoint you want the LLM to access. More importantly, Malomo's API introduces several specific integration challenges that break standard LLM assumptions.

The Destructive Shipment Array Quirk

When updating a Malomo order to add a new tracking code, the API expects a complete replacement of the shipments array. If an LLM decides to perform a partial update by only passing the new carrier and tracking_code to the update endpoint, Malomo will delete all existing shipments attached to that order.

An AI agent must understand that it cannot just execute a naive PATCH. It must first read the order, extract the existing shipments array, append the new shipment data to that array, and send the complete list back. If you hand-code these tools, you must explicitly encode this operational hazard into the tool description. Truto handles this by surfacing the strict schema requirements directly to the agent.

Fragmented Order Identification

In fulfillment, an "order ID" is a fluid concept. Malomo issues its own internal id. Your commerce platform (like Shopify) issues an alternate_id. The customer knows the number (e.g., #10024) or their tracking_code. When a user prompts an agent to "find the status for order 10024," the agent must know which specific lookup endpoint to use, rather than blindly attempting to inject a string into a generic GET /orders/:id path. This requires exposing highly specific, parameterized tools for different lookup vectors.

Strict Rate Limit Handling

When an AI agent is scraping order events or iterating through customer lists, it will hit rate limits. It is a critical architectural fact that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Malomo API returns an HTTP 429, Truto passes that error directly to the caller.

However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This means your agent framework can rely on predictable, standard headers to calculate its own retry delays, rather than parsing Malomo-specific error payloads. You must implement the backoff logic in your agent loop.

Essential Malomo Tools for AI Agents

Truto maps Malomo's API endpoints to Proxy APIs, returning them as a strictly typed list of tools via the /integrated-account/<id>/tools endpoint. Here are the highest-leverage tools you should expose to your AI agents when managing Malomo.

get_single_malomo_orders_by_tracking_code_by_id

This is the primary entry point for "Where is my order?" (WISMO) workflows. It accepts a tracking code and returns the associated order data, allowing the agent to establish the Malomo id for subsequent actions.

Contextual usage notes: Agents should use this when the user provides an alphanumeric string resembling a carrier tracking number.

"Find the order details for FedEx tracking number 789456123012."

get_single_malomo_orders_by_number_by_id

Often, customers or support reps only have the storefront order number or email address. This tool acts as the bridge between the commerce platform's naming convention and Malomo's internal records.

Contextual usage notes: This tool is strictly for lookups via number or customer_email. The agent must use the result's id for any subsequent update commands.

"Look up the Malomo order ID for order number #99887 from customer j.doe@example.com."

list_all_malomo_order_events

Malomo is heavily event-driven. An order's current status is often derived from the latest event in its timeline. This tool fetches all shipment events (e.g., In Transit, Out for Delivery, Delivered) for a given order_id.

Contextual usage notes: The agent must have already resolved the Malomo order_id before calling this tool.

"What are all the recent tracking events for order ID 12345-abcde?"

update_a_malomo_order_by_id

This tool modifies an existing order. Due to the destructive array quirk mentioned earlier, it is critical for updating shipment tracking data.

Contextual usage notes: The agent must provide the full, complete list of shipments in the payload. Any omitted shipments will be permanently removed from the order.

"Add tracking code UPS-999 to order ID 555-444, but make sure to retain the existing FedEx tracking code on the order."

create_a_malomo_webhook

For agents building automated monitoring systems, this tool creates a new webhook subscription to listen for specific Malomo events.

Contextual usage notes: Used when a user requests proactive notifications rather than polling for status.

"Create a new webhook in Malomo that sends delivery events to https://api.mycompany.com/webhooks/malomo."

get_single_malomo_customer_by_id

Retrieves the customer record attached to a specific order, providing the agent with contact details like phone numbers for SMS alerts.

Contextual usage notes: Agents should use the customer ID found in the order payload to query this tool.

"Get the phone number for the customer attached to customer ID cust_98765."

For the complete tool inventory and granular JSON schemas, refer to the Malomo integration page.

Workflows in Action

Exposing tools to an LLM transforms a static script into an autonomous fulfillment operator. Here is how an AI agent executes real-world Malomo workflows using these tools.

Scenario 1: Automated WISMO Resolution

A customer support representative needs to know the exact status of a delayed package, but only has the tracking code.

"What is the latest delivery status and estimated arrival for tracking code 1Z999999999?"

Step-by-step execution:

1. The agent calls get_single_malomo_orders_by_tracking_code_by_id with tracking_code: "1Z999999999".
2. The tool returns the order payload, revealing the internal Malomo order_id.
3. The agent immediately calls list_all_malomo_order_events using that order_id.
4. The agent reads the event array, identifies the most recent chronological event, and parses the status and timestamp.

Result: The agent replies with a concise summary: "The package is currently 'In Transit' as of 10:00 AM today and is scheduled for delivery tomorrow. It is tied to order #5544."

Scenario 2: Correcting a Split Shipment

A fulfillment associate needs to append a second tracking number to an order that was split into two boxes, without breaking the first tracking link.

"Order 445566 had a second box shipped. Add tracking code FEDEX-123 to it. Do not delete the existing shipment."

Step-by-step execution:

1. The agent calls get_single_malomo_orders_by_number_by_id using number: "445566" to resolve the Malomo id.
2. The agent calls get_single_malomo_order_by_id to retrieve the full, current state of the order, specifically isolating the shipments array.
3. The agent constructs a new payload in memory, combining the existing shipments array with a new object containing carrier: "FedEx" and tracking_code: "FEDEX-123".
4. The agent calls update_a_malomo_order_by_id, passing the fully merged array to ensure no previous data is destroyed.

Result: The order successfully updates in Malomo with both tracking numbers intact.

Building Multi-Step Workflows

To implement these workflows, you need an orchestration loop. Using the Truto SDK, you can fetch the Malomo tools and bind them directly to a LangChain agent. This approach works identically for CrewAI, Vercel AI SDK, or any framework that supports standard JSON schema tool calling.

Because Truto normalizes standard IETF rate limit headers, you must wrap your agent execution in a resilience layer that respects ratelimit-reset when a 429 error occurs.

The Agent Execution Flow

sequenceDiagram
    participant UserApp as User Prompt
    participant Agent as AI Agent
    participant TrutoSDK as Truto SDK
    participant MalomoAPI as Malomo API
    
    UserApp->>Agent: "Add tracking X to order Y"
    Agent->>TrutoSDK: Fetch Malomo Tools
    TrutoSDK-->>Agent: Tools Schema Injected
    
    Agent->>TrutoSDK: Call get_single_malomo_order_by_id
    TrutoSDK->>MalomoAPI: GET /orders/Y
    MalomoAPI-->>TrutoSDK: 200 OK (Existing shipments)
    TrutoSDK-->>Agent: JSON Order State
    
    Agent->>TrutoSDK: Call update_a_malomo_order_by_id (Merged)
    TrutoSDK->>MalomoAPI: PATCH /orders/Y
    
    alt Rate Limit Hit
        MalomoAPI-->>TrutoSDK: 429 Too Many Requests
        TrutoSDK-->>Agent: Throw 429 with ratelimit-reset header
        Agent->>Agent: Wait for ratelimit-reset seconds
        Agent->>TrutoSDK: Retry update_a_malomo_order_by_id
        TrutoSDK->>MalomoAPI: PATCH /orders/Y
        MalomoAPI-->>TrutoSDK: 200 OK
    else Success
        MalomoAPI-->>TrutoSDK: 200 OK
    end
    
    TrutoSDK-->>Agent: Updated Order State
    Agent-->>UserApp: "Shipment tracking updated successfully."

Binding Tools in TypeScript

Here is how you initialize the Truto toolset, bind it to an LLM, and explicitly handle the IETF rate limit headers if the underlying vendor throttles the request.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function runMalomoAgent() {
  // 1. Initialize Truto Tool Manager for the Malomo Integrated Account
  const trutoManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: process.env.MALOMO_ACCOUNT_ID,
  });
 
  // 2. Fetch all Malomo tools dynamically
  const tools = await trutoManager.getTools();
 
  // 3. Initialize the LLM and bind the Malomo tools
  const llm = new ChatOpenAI({ 
    modelName: "gpt-4o",
    temperature: 0 
  });
  
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a fulfillment operations agent. You manage Malomo orders. If updating shipments, you MUST fetch existing shipments first and include them in the update payload to prevent data loss."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  const agent = createToolCallingAgent({ llm, tools, prompt });
  const executor = new AgentExecutor({ 
    agent, 
    tools, 
    handleParsingErrors: true
  });
 
  try {
    // 4. Execute a multi-step workflow
    const result = await executor.invoke({
      input: "Order 10024 had a second box shipped. Add tracking code UPS-888 to it. Do not delete the existing shipment.",
    });
    console.log(result.output);
 
  } catch (error) {
    // 5. Handle Rate Limits using standardized IETF headers provided by Truto
    if (error.status === 429) {
      const resetTime = error.headers['ratelimit-reset'];
      console.warn(`Malomo rate limit hit. Agent must wait ${resetTime} seconds before retrying.`);
      // Implement custom backoff logic here
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}
 
runMalomoAgent();

By leveraging the /tools endpoint, you abstract away the manual mapping of Malomo's API specs, while retaining full control over critical agent behaviors like rate-limit backoffs and complex array manipulations.

Moving from Script to System

Connecting Malomo to AI agents unlocks powerful fulfillment automation, transforming tedious order tracking and webhook management into conversational, autonomous tasks. The difference between a prototype and a production-grade agent lies in how you handle API realities: destructive array updates, nested lookups, and standardized rate limit headers.

Using an infrastructure layer to provide AI-ready tools allows your engineering team to focus on agentic reasoning and prompt optimization, rather than maintaining static REST wrappers. Treat integrations as dynamic configurations, respect the IETF rate limit specs, and give your agents the precise tools they need to operate safely.