Skip to main content

​
Before You Begin

Before you can start using the Commerce Engine API, you’ll need a Commerce Engine account with at least one store configured. If you haven’t already signed up, create an account and set up your first store through the Commerce Engine dashboard.

​
Understanding Channels

Commerce Engine uses Channels to organize how customers interact with your store across different platforms. When you create a new store, Commerce Engine automatically creates a default Web channel for you.

​
Channel Types

Commerce Engine supports four channel types:
  • Web - For browser-based storefronts
  • App - For mobile applications (iOS/Android)
  • POS - For point-of-sale systems
  • Marketplace - For third-party integrations (advanced use cases)
Important: API keys are scoped to both a store and a specific channel. A key generated for your Web channel should not be used for App or POS channel requests. Each channel requires its own API key.

​
Step 1: Generate Your API Key

To interact with the Commerce Engine Storefront API, you need to generate an API key for your channel.
1

Navigate to Settings

Log in to your Commerce Engine dashboard and navigate to Settings > Channels from the left sidebar.
2

Select Your Channel

Click on the channel you want to generate an API key for (typically your Web channel to get started).
3

Generate API Key

In the channel settings, find the API Keys section and click Generate New API Key.The dashboard will display your new API key. Copy this key immediately and store it somewhere secure.
API Key SecurityWhile Storefront API keys are designed to be client-safe (they can be exposed in frontend code), you should still:
  • Never commit API keys directly to version control
  • Use environment variables in your projects
  • Rotate keys periodically for security
  • Use separate keys for staging and production environments

​
Step 2: Choose Your Environment

Commerce Engine provides two environments for API access:
EnvironmentBase URLPurpose
Staginghttps://staging.api.commercengine.io/api/v1Testing and development
Productionhttps://prod.api.commercengine.io/api/v1Live production traffic
Environment IsolationData is completely isolated between staging and production environments. However, the same API key works in both environments, making it easy to test in staging before deploying to production.We recommend using staging for all development and testing activities.

​
Step 3: Make Your First Request

Let’s make your first API request to authenticate an anonymous user. This is the starting point for any Commerce Engine storefront integration.

​
Authenticate an Anonymous User

Every visitor to your storefront starts as an anonymous user. This initial authentication step:
  • Assigns a unique user ID for tracking
  • Returns access and refresh tokens for the session
  • Enables server-side analytics from the first interaction
curl -X POST 'https://staging.api.commercengine.io/api/v1/{store_id}/storefront/auth/anonymous' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'
Replace {store_id} with your actual store ID (found in your dashboard) and YOUR_API_KEY with the API key you generated.

​
Expected Response

If successful, you’ll receive a response like this:
Response
{
  "message": "Anonymous user created successfully.",
  "success": true,
  "content": {
    "user": {
      "id": "01HXXXXXXANONYMOUSUSERID",
      "first_name": null,
      "last_name": null,
      "email": null,
      "phone": null,
      "is_anonymous": true,
      "is_logged_in": false,
      "created_at": "2024-10-28T10:30:00.000Z"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "a1b2c3d4e5f6g7h8i9j0..."
  }
}
Store These Tokens SecurelyThe access_token and refresh_token are critical for all subsequent API requests:
  • Access Token - Include this in the Authorization: Bearer header for API calls
  • Refresh Token - Use this to obtain a new access token when the current one expires
Store these securely on the client side (HttpOnly cookies for web, secure storage for mobile).

​
Step 4: Make an Authenticated Request

Now that you have an access token, you can make authenticated requests to other API endpoints. Let’s fetch the product catalog: 
curl -X GET 'https://staging.api.commercengine.io/api/v1/{store_id}/storefront/catalog/products' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json'
You should receive a list of products from your catalog. Congratulations - you’ve made your first authenticated API request!

​
Understanding the API Structure

All Commerce Engine Storefront API endpoints follow this URL structure: 
https://{environment}.api.commercengine.io/api/v1/{store_id}/storefront/{resource}
  • {environment} - Either staging or api (for production)
  • {store_id} - Your unique store identifier
  • {resource} - The API resource you’re accessing (e.g., auth, catalog, carts, orders)

​
What You Can Do With the API

The Commerce Engine Storefront API enables you to build complete e-commerce experiences:
  • Authentication - Anonymous users, passwordless login via OTP, social auth
  • Catalog - Browse products, search, filter, and recommendations
  • Cart Management - Add items, apply coupons, calculate shipping
  • Checkout - Place orders, process payments, manage fulfillment
  • Customer Accounts - Profile management, order history, addresses
  • Subscriptions - Recurring orders and subscription management
  • Loyalty & Rewards - Points, credits, and promotional campaigns

​
Next Steps

Now that you’re authenticated, explore these guides to build out your storefront:

Authentication Guide

Learn about user login, registration, and token management

Catalog & Products

Display products, handle search, and show recommendations

Cart & Checkout

Build shopping cart and checkout experiences

SDK Documentation

Use our type-safe SDK for faster development

​
Rate Limits & Best Practices

API Rate LimitsCommerce Engine enforces rate limits to ensure API stability:
  • Staging: 100 requests per minute per API key
  • Production: 1000 requests per minute per API key
Rate limit headers are included in all responses to help you monitor usage.

​
Best Practices

  1. Token Management - Implement automatic token refresh to maintain uninterrupted sessions
  2. Error Handling - Always check response status codes and handle errors gracefully
  3. Caching - Cache catalog data and configuration to reduce API calls
  4. Webhooks - Use webhooks for real-time order and payment updates instead of polling

​
Getting Help

Need assistance? We’re here to help: Ready to build? Dive into the Authentication Guide to learn how to handle user login and registration.