Store-front API

Welcome to the Store-front API documentation! This API enables you to build complete e-commerce experiences with support for both authenticated users and guest checkout.

Quick Start

All API requests require an x-api-key header for authentication Your API key

Get it from the storekit dashboard and set it as an environment variable

Base URL

https://api.storekit.app

Authentication

Every request must include the API key in the header:

const headers = {
  "x-api-key": "your_api_key_here",
  "Content-Type": "application/json",
};

Key Features

Guest Checkout

Allow users to shop without creating an account

User Authentication

Full sign-up and sign-in flow with session management

Cart Management

Persistent cart for both guests and authenticated users

Wishlist

Save favorite products for later

Order Processing

Complete order management system

Product Search

Advanced search with filters and autocomplete

API Categories

Authentication - User sign-up, sign-in, and guest data merging
Products - Browse and retrieve product information
Cart - Manage shopping cart items
Wishlist - Save and manage favorite products
Orders - Place and track orders
Search - Search products with advanced filters
Feedback - Customer reviews and ratings
Banners - Promotional banner content

Understanding Guest vs Authenticated Users

This API supports both guest users and authenticated users with automatic data migration when guests sign up.

Guest Users

Receive a x-guest-token in response headers
Can add items to cart and wishlist
Cart and wishlist persist across sessions using the guest token

Authenticated Users

Use x-customer-id header with their user ID
Full access to all features
Can merge guest data after signing in

Token Management Helper

Here's a utility class to manage authentication tokens:

import "server-only";
import { cookies } from "next/headers";

class CookieManager {
  AUTH_TOKEN_KEY = "auth_token";
  USER_DATA_KEY = "user_data";
  GUEST_TOKEN_KEY = "guest_token";

  async buildApiHeaders() {
    const headers: Record = {
      "Content-Type": "application/json",
      "x-api-key": process.env.BACKEND_API_KEY || "",
    };

    const user = await this.getAuthUser();
    if (user?.id) {
      headers["x-customer-id"] = user.id;
    } else {
      const guestToken = await this.getGuestToken();
      if (guestToken) {
        headers["x-guest-token"] = guestToken;
      }
    }

    return headers;
  }

  async handleApiResponse(response: Response) {
    const newGuestToken = response.headers.get("x-guest-token");
    if (newGuestToken) {
      await this.setGuestToken(newGuestToken);
    }
  }

  async setGuestToken(token: string) {
    const cookieStore = await cookies();
    cookieStore.set(this.GUEST_TOKEN_KEY, token, {
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      sameSite: "lax",
      maxAge: 60 * 60 * 24 * 90,
    });
  }

  async getGuestToken(): Promise {
    const cookieStore = await cookies();
    const token = cookieStore.get(this.GUEST_TOKEN_KEY);
    return token?.value || null;
  }

  async getAuthUser() {
    const cookieStore = await cookies();
    const userData = cookieStore.get(this.USER_DATA_KEY);
    if (!userData?.value) return null;
    
    try {
      const decodedValue = decodeURIComponent(userData.value);
      return JSON.parse(decodedValue);
    } catch {
      return null;
    }
  }
}

export const cookieManager = new CookieManager();

import "server-only";
import { cookies } from "next/headers";

class CookieManager {
  AUTH_TOKEN_KEY = "auth_token";
  USER_DATA_KEY = "user_data";
  GUEST_TOKEN_KEY = "guest_token";

  async buildApiHeaders() {
    const headers = {
      "Content-Type": "application/json",
      "x-api-key": process.env.BACKEND_API_KEY || "",
    };

    const user = await this.getAuthUser();
    if (user?.id) {
      headers["x-customer-id"] = user.id;
    } else {
      const guestToken = await this.getGuestToken();
      if (guestToken) {
        headers["x-guest-token"] = guestToken;
      }
    }

    return headers;
  }

  async handleApiResponse(response) {
    const newGuestToken = response.headers.get("x-guest-token");
    if (newGuestToken) {
      await this.setGuestToken(newGuestToken);
    }
  }

  async setGuestToken(token) {
    const cookieStore = await cookies();
    cookieStore.set(this.GUEST_TOKEN_KEY, token, {
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      sameSite: "lax",
      maxAge: 60 * 60 * 24 * 90,
    });
  }

  async getGuestToken() {
    const cookieStore = await cookies();
    const token = cookieStore.get(this.GUEST_TOKEN_KEY);
    return token?.value || null;
  }

  async getAuthUser() {
    const cookieStore = await cookies();
    const userData = cookieStore.get(this.USER_DATA_KEY);
    if (!userData?.value) return null;
    
    try {
      const decodedValue = decodeURIComponent(userData.value);
      return JSON.parse(decodedValue);
    } catch {
      return null;
    }
  }
}

export const cookieManager = new CookieManager();

Response Codes

Code	Description
200	Success
204	Success (No Content)
400	Bad Request
401	Unauthorized - Invalid or missing API key
403	Forbidden - Not authorized
404	Not Found
409	Conflict - Resource already exists
422	Unprocessable Entity - Invalid input data
500	Internal Server Error

Example Store Implementation

Check out our complete example storefront built with Next.js to see best practices in action.

Need Help?

Join our Developer Community
Report issues on GitHub
Contact support: [email protected]

Quickstart