​
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. 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: Anonymous Authentication

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.

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.

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:

{
  "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...",
  }
}

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.

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.

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

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.