Integration Guide

This guide shows the recommended production integration flow.

1) Initialize the API Client

import { createEcommapsClient } from "@ecommaps/client";
 
const client = createEcommapsClient({
  apiUrl: process.env.NEXT_PUBLIC_ECOMMAPS_API_URL!,
  apiKey: process.env.ECOMMAPS_API_KEY!,
});

2) Build Product Discovery

const products = await client.products.list({ limit: 12, offset: 0 });
const product = await client.products.retrieve("product-slug");
const search = await client.products.search("shirt", { limit: 10 });

3) Build Cart and Checkout Flow

const cart = await client.cart.create();
await client.cart.addItem(cart.id, {
  product_id: "<product_uuid>",
  variant_id: "<variant_uuid>",
  quantity: 1,
});
 
const order = await client.orders.create({
  cart_id: cart.id,
  customer_name: "Customer",
  customer_phone: "0555000000",
});

4) Add Customer Auth

const auth = await client.auth.login({
  email: "customer@example.com",
  password: "StrongPass123",
});

Use Authorization: Bearer <token> for customer-profile and address routes.

5) Add Storefront Logic Kit (Optional)

Use @ecommaps/storefront-kit when you need deterministic variant and promotion logic on the server side.

6) Add AI Sales Agent (Optional)

Use @ecommaps/ai-sales-agent for buyer-facing conversational shopping flows.

Overview @ecommaps/client