Pular para o conteúdo principal

​
Shopify Quickstart

Integrate Alana with your Shopify store for AI-powered product feeds and semantic search. This guide uses the Shopify Admin API and a custom app.

​
Prerequisites

  • Shopify store (any plan)
  • Alana API key (get one at app.alana.shopping → Settings → API Keys)
  • Node.js 18+ for the integration scripts

​
1. Configure your API key

In your Shopify app environment (.env or Shopify app settings): 
ALANA_API_KEY=your-api-key-here
ALANA_WORKSPACE_ID=your-workspace-id
In the Shopify admin panel: go to Apps → Alana Shopping → Configuration and paste your API key.

​
2. Fetch the product feed

Alana generates Shopify-compatible JSON feeds from your catalog: 
// fetch-alana-feed.js
const ALANA_BASE = "https://api.alana.shopping";

async function fetchAlanaFeed(limit = 50, offset = 0) {
  const response = await fetch(
    `${ALANA_BASE}/api/mcp/feed/shopify?limit=${limit}&offset=${offset}`,
    {
      headers: { "X-API-Key": process.env.ALANA_API_KEY },
    }
  );

  if (!response.ok) {
    throw new Error(`Feed fetch failed: ${response.status}`);
  }

  return response.json(); // { platform, products, total, limit, offset }
}

// Sync all products in batches of 50
async function syncCatalog() {
  let offset = 0;
  let total = Infinity;

  while (offset < total) {
    const { products, total: t } = await fetchAlanaFeed(50, offset);
    total = t;

    // Process products — e.g. upsert into Shopify via Admin API
    for (const product of products) {
      console.log(`Syncing: ${product.title}`);
    }

    offset += 50;
  }

  console.log(`Synced ${total} products`);
}

syncCatalog();
Using curl: 
curl -X GET "https://api.alana.shopping/api/mcp/feed/shopify?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"
Response: 
{
  "platform": "shopify",
  "products": [
    {
      "id": "gid://shopify/Product/001",
      "title": "Running Shoes Pro",
      "vendor": "BrandName",
      "product_type": "Footwear",
      "variants": [{ "price": "299.90", "inventory_quantity": 42 }]
    }
  ],
  "total": 1250,
  "limit": 50,
  "offset": 0
}

​
3. Add Alana search to your storefront

Replace Shopify’s Predictive Search with Alana’s semantic search using a Liquid + JavaScript integration: 
{%- comment -%} In your theme's search snippet (snippets/predictive-search.liquid) {%- endcomment -%}
<div id="alana-search-results"></div>

<script>
  const ALANA_API_KEY = {{ shop.metafields.alana.api_key | json }};

  async function alanaSearch(query) {
    const res = await fetch("https://api.alana.shopping/api/v1/search", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": ALANA_API_KEY,
      },
      body: JSON.stringify({ query, limit: 10 }),
    });

    const { hits } = await res.json();
    renderResults(hits);
  }

  function renderResults(products) {
    const container = document.getElementById("alana-search-results");
    container.innerHTML = products
      .map(p => `<a href="/products/${p.handle}">${p.title}</a>`)
      .join("");
  }

  // Debounce search on input
  let debounce;
  document.querySelector("#search-input").addEventListener("input", (e) => {
    clearTimeout(debounce);
    debounce = setTimeout(() => alanaSearch(e.target.value), 300);
  });
</script>

​
4. Configure feed webhooks

Receive push notifications when your feed updates: 
curl -X POST "https://api.alana.shopping/api/v1/feeds/shopify/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.myshopify.com/webhooks/alana",
    "events": ["feed.generated", "feed.failed"],
    "secret": "your-hmac-secret"
  }'
Verify the webhook signature in your handler: 
import { createHmac } from "crypto";

export function verifySignature(body, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return expected === signature;
}

// Express handler
app.post("/webhooks/alana", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-alana-signature"];
  if (!verifySignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, data } = JSON.parse(req.body);
  console.log(`Feed event: ${event}, products: ${data?.productCount}`);
  res.status(200).json({ received: true });
});

​
5. Verify integration

# Check feed is accessible
curl "https://api.alana.shopping/api/mcp/feed/shopify?limit=1" \
  -H "X-API-Key: YOUR_API_KEY" | jq '.total'

# Check consumption analytics
curl "https://api.alana.shopping/api/v1/feeds/shopify/analytics" \
  -H "X-API-Key: YOUR_API_KEY"

​
Next steps

Last modified on March 17, 2026