Order Tracking

If your store doesn’t use one of the platforms we integrate with directly—such as Shopify, WooCommerce, or others—you can still enable order tracking by providing access to an endpoint that returns customer order data.

This allows our AI to answer customer questions like “Where’s my order?”, “What’s the status of order #12345?”, or “What did I buy using this email/phone number?”

Supported Integration Methods

We can retrieve order data via the following methods:

• Custom API endpoints (preferred) - the documentation below assumes this method

• Scheduled order data exports via email or webhook - contact us if this approach is needed

Required Parameters for API endpoint

Your endpoint should support filtering by at least one of the following:

Parameter	Type	Notes
email	string	Returns all orders matching the given email
order_id	string	Returns a single order (or none)
phone	string	Match based on normalized phone number (last N digits only)
ref_id	string	Optional: Alternative internal or external reference ID

⚠️ At least one parameter must be provided in the request.

Phone Number Normalization

To avoid format mismatches, phone numbers should be normalized by removing non-digit characters and comparing the last 7 digits.

For example:

Raw Input	Normalized (last 7 digits)
[phone]	8675309
[phone]	3456789
4151234567	1234567

Expected API Response Format

Your endpoint should return an array of order objects, even if only one match is found.

Example:

[
  {
    "id": "ORD-12345",
    "status": "shipped",
    "created_at": "2024-10-10T14:21:00Z",
    "customer": {
      "email": "[email protected]",
      "phone": "[phone]",
      "name": "Jane Doe"
    },
    "shipping_address": {
      "line1": "123 Main Street",
      "city": "San Francisco",
      "postal_code": "94103",
      "country": "US"
    },
    "items": [
      {
        "sku": "ABC123",
        "name": "Wireless Earbuds",
        "quantity": 1,
        "price": 59.99
      }
    ],
    "total": 59.99,
    "currency": "USD",
    "tracking_number": "1Z999999",
    "external_ref_id": "XYZ987"
  }
]

Minimum Required Fields

To enable basic order tracking, your data must include:

• Order ID

• Status (pending, shipped, delivered, etc.)

• Customer email or phone

• At least one product item

• Total and currency

💡 Your field names don’t need to match exactly. We’ll map them internally.

Recommended Fields (for better responses)

Including additional fields improves the quality of answers your customers receive:

Field	Description
tracking_number	Helps the AI give tracking updates
shipping_address	For delivery-related questions
external_ref_id	Useful if your business uses alt IDs
updated_at	For status timelines
item.sku	Helps identify exact products
item.image_url	For visual display in UI integrations

Suggested Schema (TypeScript Reference)

type Order = {
  id: string;
  status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
  created_at: string;
  updated_at?: string;
  customer: {
    email: string;
    phone?: string;
    name?: string;
  };
  shipping_address?: {
    line1: string;
    city: string;
    postal_code: string;
    country: string;
  };
  items: Array<{
    sku: string;
    name: string;
    quantity: number;
    price: number;
    image_url?: string;
  }>;
  total: number;
  currency: string;
  tracking_number?: string;
  external_ref_id?: string;
};

Need Help?

If your order schema differs or you’d like us to review your API or file format, let us know. We’re happy to validate a sample and suggest improvements to ensure full compatibility.

Contact Support →