Shopify Integration Guide

This guide explains how to connect and use Shopify within the Paksa AI Assistant platform.

Overview

  • Use Shopify Admin API (GraphQL preferred for efficiency) to fetch products, create orders, and sync inventory.
  • For public apps, use OAuth; for internal/private deployments, API keys and Admin API access can be used.

Required credentials

  • SHOPIFY_API_KEY, SHOPIFY_API_SECRET (for OAuth)
  • SHOPIFY_SHOP (e.g. my-shop.myshopify.com)
  • SHOPIFY_ACCESS_TOKEN (for private app access)

Example: product search (Node-style pseudocode)

// fetch products by query
const res = await fetch(`https://${SHOPIFY_SHOP}/admin/api/2024-07/products.json?title=${encodeURIComponent(q)}`, {
	headers: { 'X-Shopify-Access-Token': SHOPIFY_ACCESS_TOKEN }
});
const data = await res.json();

GraphQL is recommended for complex queries to fetch variants and metafields in one request.

Order creation flow

  1. Collect order details from chat (customer, cart items, shipping address).
  2. Create order via Admin API: POST /admin/api/2024-07/orders.json.
  3. Handle payments (redirect to checkout or use Shopify Payments API depending on integration).

Webhook verification

Shopify sends an HMAC signature you must verify using your SHOPIFY_API_SECRET.

Example (Node pseudocode):

const hmac = req.headers['x-shopify-hmac-sha256'];
const body = await getRawBody(req);
const digest = crypto.createHmac('sha256', SHOPIFY_API_SECRET).update(body, 'utf8').digest('base64');
if (digest !== hmac) { return res.status(401).end('Invalid signature'); }

Rate limits and retries

  • Shopify uses a leaky bucket algorithm and returns 429 when rate limited. Implement exponential backoff and caching for product lookups.

Best practices

  • Cache product metadata for read-heavy chat flows.
  • Use webhooks to keep cache in sync.
  • Use background workers for heavy tasks (order fulfillment, batch updates).