Developer Docs

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0">
  <channel>
    <title>My Store</title>
    <item>
      <g:id>SKU-001</g:id>
      <g:title>Nike Air Max 90</g:title>
      <g:description>Classic everyday sneaker.</g:description>
      <g:price>129.99 USD</g:price>
      <g:image_link>https://mystore.com/img/nike.jpg</g:image_link>
      <g:link>https://mystore.com/products/nike-air-max-90</g:link>
      <g:product_type>Sneakers</g:product_type>
      <g:availability>in stock</g:availability>
    </item>
  </channel>
</rss>

{
  "products": [
    {
      "id": "123",
      "name": "Nike Air Max 90",
      "description": "Classic everyday sneaker, available in 5 colors.",
      "price": 129.99,
      "image": "https://mystore.com/img/nike.jpg",
      "url": "https://mystore.com/products/nike-air-max-90",
      "category": "Sneakers",
      "in_stock": true,
      "variant_id": "123-42"
    }
  ]
}

window.ChatAxonHooks = {
  /**
   * Add a product to the cart.
   * productId  — your product ID from the feed
   * variantId  — variant ID if applicable (size, color…); undefined for simple products
   * quantity   — always ≥ 1
   * name       — product name (for optimistic UI feedback)
   */
  addToCart: async ({ productId, variantId, quantity, name }) => {
    // Your implementation here
    return {
      success:   true,        // required
      cartCount: 3,           // optional — total items in cart after add
      cartTotal: 259.97,      // optional — new cart total
      message:   'Added!',   // optional — shown briefly in the widget
    };
    // On failure:
    // return { success: false, message: 'Item is out of stock' };
  },

  // Optional: remove a line item by its cart ID.
  // NOTE: the AI does NOT trigger removeFromCart — this hook is only called
  // if your own widget UI exposes a remove button inside the chat window.
  removeFromCart: async ({ lineItemId }) => ({ success: true }),

  // Optional: return current cart so the widget shows an item count badge
  getCart: async () => ({
    count: 2,
    total: 129.98,
    items: [{ id: '123', name: 'Nike Air Max', quantity: 1, price: 129.99 }],
  }),
};

<script>
  window.ChatAxonConfig = {
    apiKey: 'chataxon_YOUR_API_KEY',
    apiUrl: 'https://api.chataxon.com',
    hooks: {
      addToCart: async ({ productId, quantity }) => {
        // your implementation
        return { success: true };
      },
    },
  };
</script>

window.ChatAxonHooks = {
  applyDiscount: async ({ code }) => {
    return {
      success:         true,              // required
      message:         '10% off applied!', // required — shown in chat
      discountAmount:  12.99,             // optional — absolute value
      discountPercent: 10,                // optional — percentage
    };
    // On failure:
    // return { success: false, message: 'Code expired or invalid' };
  },
};

GET https://your-store.com/chataxon/orders?email=customer@email.com&order_id=12345

Headers:
  X-ChatAxon-Secret: <your_webhook_secret>   # same value as GET /api/store/feed/webhook-secret
  Accept:            application/json

{
  "found": true,
  "order": {
    "id":                 "12345",
    "status":             "shipped",
    "status_label":       "Shipped",
    "date":               "2026-06-08T14:30:00Z",
    "total":              129.99,
    "currency":           "USD",
    "items": [
      { "name": "Nike Air Max 90", "quantity": 1, "price": 129.99 }
    ],
    "tracking_number":    "1Z999AA10123456784",
    "tracking_url":       "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "estimated_delivery": "2026-06-15",
    "shipping_address": {
      "city":    "New York",
      "country": "US"
    },
    "notes": "Left at front door"
  }
}

{ "found": false, "message": "No order found for this email / ID combination." }

window.ChatAxonHooks = {
  addToCart: async ({ variantId, quantity }) => {
    // variantId = Shopify numeric variant ID (auto-extracted from /products.json feed)
    const res = await fetch('/cart/add.js', {
      method:  'POST',
      headers: { 'Content-Type': 'application/json' },
      body:    JSON.stringify({ id: Number(variantId), quantity }),
    });

    if (!res.ok) {
      const err = await res.json().catch(() => ({}));
      return { success: false, message: err.description || 'Could not add to cart' };
    }

    // Fetch updated cart totals
    const cart = await fetch('/cart.js').then(r => r.json());
    return {
      success:   true,
      cartCount: cart.item_count,
      cartTotal: cart.total_price / 100, // Shopify stores prices in cents
    };
  },

  getCart: async () => {
    const cart = await fetch('/cart.js').then(r => r.json());
    return {
      count: cart.item_count,
      total: cart.total_price / 100,
      items: cart.items.map(i => ({
        id:       String(i.variant_id),
        name:     i.title,
        quantity: i.quantity,
        price:    i.final_price / 100,
      })),
    };
  },
};

// /api/chataxon-orders.js  (Vercel, Netlify, or any Node server)
// Register this URL in Dashboard → Store Settings → Order Tracking

export default async function handler(req, res) {
  // 1. Verify ChatAxon secret
  if (req.headers['x-chataxon-secret'] !== process.env.CHATAXON_WEBHOOK_SECRET) {
    return res.status(401).json({ found: false });
  }

  const { email, order_id } = req.query;

  // 2. Query Shopify Admin API (REST)
  const query = order_id
    ? `name=%23${order_id}`             // search by order name e.g. #1234
    : `email=${encodeURIComponent(email)}&status=any&limit=1`;

  const sfRes = await fetch(
    `https://${process.env.SHOPIFY_SHOP_DOMAIN}/admin/api/2024-01/orders.json?${query}`,
    {
      headers: {
        'X-Shopify-Access-Token': process.env.SHOPIFY_ADMIN_TOKEN,
        'Content-Type': 'application/json',
      },
    }
  );

  const { orders } = await sfRes.json();
  const order = orders?.[0];

  if (!order) return res.json({ found: false, message: 'No order found.' });

  const fulfillment = order.fulfillments?.[0];

  return res.json({
    found: true,
    order: {
      id:                 String(order.order_number),
      status:             order.fulfillment_status ?? order.financial_status ?? 'pending',
      status_label:       (order.fulfillment_status ?? order.financial_status ?? 'pending')
                            .replace(/_/g, ' '),
      date:               order.created_at,
      total:              parseFloat(order.total_price),
      currency:           order.currency,
      items:              order.line_items.map(i => ({
        name:     i.name,
        quantity: i.quantity,
        price:    parseFloat(i.price),
      })),
      tracking_number:    fulfillment?.tracking_number ?? null,
      tracking_url:       fulfillment?.tracking_url ?? null,
      estimated_delivery: null,
      shipping_address: {
        city:    order.shipping_address?.city,
        country: order.shipping_address?.country_code,
      },
    },
  });
}

POST https://api.chataxon.com/api/store/feed/webhook

Headers:
  x-api-key: chataxon_YOUR_API_KEY
  Content-Type: application/json
  X-ChatAxon-Signature: <your_webhook_secret>   # optional but strongly recommended

Body (all fields optional):
{
  "event": "product.updated"  // product.created | product.deleted | catalog.updated
}

# Run once. Store the returned webhook_secret in your server's environment variables.
curl -s https://api.chataxon.com/api/store/feed/webhook-secret \
  -H "x-api-key: chataxon_YOUR_API_KEY"

# Response:
# { "webhook_secret": "a3f1c8...64 hex chars..." }

POST https://api.chataxon.com/api/store/track
x-api-key: chataxon_YOUR_API_KEY
x-session-id: <current chat session UUID>
Content-Type: application/json

{
  "event_type": "csat",
  "metadata": {
    "rating": "positive"   // "positive" | "negative"
  }
}

// Call this after showing the thumbs-up / thumbs-down prompt
async function sendCSAT(rating) {
  await fetch('https://api.chataxon.com/api/store/track', {
    method: 'POST',
    headers: {
      'Content-Type':  'application/json',
      'x-api-key':     window.ChatAxonConfig.apiKey,
      'x-session-id':  window.ChatAxon.getSessionId(), // exposed by the widget
    },
    body: JSON.stringify({
      event_type: 'csat',
      metadata:   { rating }, // 'positive' | 'negative'
    }),
  });
}

// Wire up your buttons
document.getElementById('thumbs-up').addEventListener('click',   () => sendCSAT('positive'));
document.getElementById('thumbs-down').addEventListener('click', () => sendCSAT('negative'));

<!-- ChatAxon Widget -->
<div id="chataxon-root"></div>
<script>
  window.ChatAxonConfig = {
    apiKey:  'chataxon_YOUR_API_KEY',
    apiUrl:  'https://api.chataxon.com',
  };
</script>
<script
  src="https://cdn.chataxon.com/widget.js"
  data-cfasync="false"
  data-no-defer="1"
  defer
></script>

<script>
  window.ChatAxonConfig = {
    // Required
    apiKey:  'chataxon_YOUR_API_KEY',
    apiUrl:  'https://api.chataxon.com',

    // Appearance
    themeColor:     '#1E364B',      // hex color for buttons and accents
    widgetPosition: 'bottom-right', // 'bottom-right' | 'bottom-left'
    offsetBottom:   24,             // pixels from bottom edge
    offsetSide:     24,             // pixels from side edge

    // Mobile overrides (null = inherit from desktop)
    mobileWidgetPosition: null,
    mobileOffsetBottom:   null,
    mobileOffsetSide:     null,

    // Behaviour
    defaultOpen:    false,          // open chat on page load
    bubbleText:     'Need help?',   // speech bubble above widget
    welcomeMessage: 'Hi! How can I help you today?',

    // Internationalisation
    currency: '€',                  // symbol passed to price display

    // Transactional hooks (optional — enables add-to-cart, discounts)
    hooks: {
      addToCart:     async ({ productId, variantId, quantity }) => { /* ... */ return { success: true }; },
      applyDiscount: async ({ code })                          => { /* ... */ return { success: true, message: 'Applied!' }; },
      getCart:       async ()                                  => ({ count: 0, total: 0, items: [] }),
    },
  };
</script>