Prerequisites

Before you begin, you’ll need a Commerce Engine account and at least one Store configured. You can manage your account, stores, and API credentials through the Commerce Engine Admin Portal.

​
Obtaining Credentials

You’ll need two key pieces of information from the Admin Portal to interact with the Storefront API for a specific store:

  1. store_id: This unique identifier represents your specific store within your Commerce Engine organization. All data (products, orders, customers, etc.) is scoped to a store. You’ll find this ID in the Store settings section of the Admin Portal.

  2. API Key (X-Api-Key): This secret key is used only for the initial authentication step to identify your application when requesting an anonymous user token.

    Security Notice

    Treat this key securely like a password; it should not be exposed in frontend code. Find this key in the API Credentials or Developer settings section for your store in the Admin Portal.

​
Environments and Base URLs

Commerce Engine provides distinct environments for development/testing and live production use:

  • Staging: For development, testing, and integration.
    • Base URL: https://staging.api.commercengine.io/api/v1/{store_id}/storefront
  • Production: For your live application serving real customers.
    • Base URL: https://prod.api.commercengine.io/api/v1/{store_id}/storefront

Simply replace {store_id} in the URL with your actual Store ID obtained from the Admin Portal. You’ll switch between these base URLs as you move from development to production.

​
Core Concept: Headless Interaction

Commerce Engine is a headless platform. This means we provide the backend commerce functionality via APIs, and you build the entire customer-facing frontend (the “head”) – whether it’s a website, mobile app, or other digital interface. You have complete control over the look, feel, and user experience.

All interactions with Commerce Engine happen through standard HTTP requests to our API endpoints. You’ll typically use JSON for request and response bodies.

​
Your First API Call: Step-by-Step

Every user interaction, even before they log in or sign up, should be associated with a unique identity. This is crucial for providing personalized experiences and enabling powerful server-side analytics from the very first click.

1

Obtain an Anonymous User Token

The first step in any storefront integration is to obtain an anonymous user token. This token identifies the user’s session even before they are known.

You’ll make a POST request to the /auth/anonymous endpoint, providing your store’s API Key in the X-Api-Key header.

Get Anonymous Token Request
curl -X POST \
  'https://staging.api.commercengine.io/api/v1/YOUR_STORE_ID/storefront/auth/anonymous' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

Response:

Anonymous Token Response
{
  "message": "Anonymous user session initiated successfully.",
  "success": true,
  "content": {
    "user": {
      "id": "01HXXXXXXANONYMOUSUSERID",
      "is_anonymous": true,
      "is_logged_in": false,
      "first_name": null,
      "last_name": null,
      "phone": null,
      "email": null,
      "is_email_verified": false,
      "is_phone_verified": false,
      "profile_image_url": null,
      "created_at": "2023-10-27T10:00:00Z",
      "modified_at": "2023-10-27T10:00:00Z"
      // ... other user fields might be null initially
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "def50200720ddb1c1ef789a641556a..."
  }
}
2

Understand the Response

Key takeaways from the response:

  • content.user.id: A unique ID for this anonymous user.
  • content.access_token: A short-lived Bearer token used to authenticate subsequent API calls for this user’s session.
  • content.refresh_token: A longer-lived token used to obtain a new access_token when it expires.

Important: Token Storage

Crucially, you must securely store both the access_token and refresh_token on the client-side. We’ll cover how to use and manage these tokens in the Authentication section.

3

Make Authenticated Requests

Now that you have an access_token, you can make authenticated requests to other Storefront API endpoints by including it in the Authorization header:

Example Authenticated Request
curl -X GET \
  'https://staging.api.commercengine.io/api/v1/YOUR_STORE_ID/storefront/catalog/products' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

You’ve successfully made your first authenticated call! Next, let’s dive deep into authentication mechanisms.