AI Agents for Shopify

{
  "name": "order_status",
  "description": "Look up the fulfilment status and tracking link of a Shopify order. Use when the caller asks where their order is, whether it shipped, or when it will arrive.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_number": { "type": "string" },
      "email": { "type": "string" }
    },
    "required": ["order_number"],
    "additionalProperties": false
  },
  "responseTimeoutMs": 4000,
  "enabled": true
}

// POST /agent/order-status  →  called by your bitpull tool wiring
import { json } from './http.js'

const SHOP = process.env.SHOPIFY_SHOP          // my-shop.myshopify.com
const TOKEN = process.env.SHOPIFY_ADMIN_TOKEN  // Admin API access token
const API = '2024-10'

export async function orderStatus({ order_number, email }) {
  const q = new URLSearchParams({ name: `#${order_number}`, status: 'any', limit: '1' })
  const res = await fetch(
    `https://${SHOP}/admin/api/${API}/orders.json?${q}`,
    { headers: { 'X-Shopify-Access-Token': TOKEN } }
  )
  if (!res.ok) return { found: false, reason: 'lookup_failed' }

  const [order] = (await res.json()).orders ?? []
  if (!order) return { found: false, reason: 'not_found' }

  // Only hand back what the agent is allowed to say out loud. Never return the
  // full order object - it carries addresses, prices and customer records that
  // have no business in a spoken answer to an unverified caller.
  if (email && order.email?.toLowerCase() !== email.toLowerCase()) {
    return { found: false, reason: 'mismatch' }
  }

  const shipment = order.fulfillments?.[0]
  return {
    found: true,
    status: order.fulfillment_status ?? 'unfulfilled',
    placed_at: order.created_at,
    tracking_url: shipment?.tracking_url ?? null,
    carrier: shipment?.tracking_company ?? null
  }
}

// Your endpoint, configured as the agent's outbound webhook URL.
export default async function handler(req, res) {
  const body = req.body ?? {}

  // Read defensively: the envelope is not a published contract, so pull the
  // fields out by several plausible names rather than assuming one shape.
  const summary   = body.summary ?? body.session?.summary ?? {}
  const outcome   = summary.outcome ?? 'UNKNOWN'
  const transcript = body.messages ?? body.transcript ?? []

  if (outcome === 'RESOLVED') return res.status(200).end()   // nothing to do

  await fetch(`https://${SHOP}/admin/api/2024-10/customers/${customerId}.json`, {
    method: 'PUT',
    headers: {
      'X-Shopify-Access-Token': process.env.SHOPIFY_ADMIN_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customer: {
        id: customerId,
        note: [summary.title, ...(summary.keyPoints ?? [])].filter(Boolean).join('\n')
      }
    })
  })

  res.status(200).end()   // always answer fast; do the slow work out of band
}