Getting Started

The User API provides endpoints for customer interactions on your commerce platform. These APIs enable customers (end users) to:

• Register and authenticate

• View and update their profile

• Manage their orders and order history

• Handle payment methods

• Interact with customer support

How It Works

These APIs can be integrated in different ways depending on your architecture:

Integration Type	Description	Example
Headless / Server-side	Your backend server makes API calls on behalf of the customer. You must store and manage cookies programmatically.	Django Zero Storefront
Mobile apps	Mobile app makes API calls directly. Cookies must be stored and sent with each request.	Custom mobile apps

Reference implementations: Django Zero Storefront and Next.js Zero Storefront both use these endpoints. You can refer to their source code for real-world integration examples.

Important:

• Each session is unique to the end user (customer)

• Even guest users have sessions - a session is created before login to track cart, preferences, etc.

• Always store and resend cookies with every request to maintain session continuity

• When a guest user logs in, their session is associated with their account

Base URL

All API endpoints in this documentation use the following base URL:

{commerce_url}

Replace {commerce_url} with your commerce service URL.

Note: This is the customer-facing commerce API, not the management/admin API. These endpoints are designed for end-user interactions on your storefront.

---

Quick Start

Follow these three steps to authenticate a customer and make API requests on their behalf.

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  1. Get CSRF    │ ──►  │  2. Login       │ ──►  │  3. API Calls   │
│     Token       │      │     Customer    │      │     (authenticated)
└─────────────────┘      └─────────────────┘      └─────────────────┘
     csrftoken              osessionid            Both cookies +
     cookie                 cookie                x-csrftoken header

Note: In browser-based apps, cookies are handled automatically. In headless/mobile apps, you must store cookies from every response and send them with each subsequent request—even for guest users.

Step 1: Get CSRF Token

Before making any non-GET request, obtain a CSRF token.

Request:

# Get CSRF token (saved to cookies.txt, extract to variable)
curl -s -c cookies.txt "{commerce_url}/csrf_token/"
CSRF_TOKEN=$(awk '/csrf_token/ {print $7}' cookies.txt)

import requests

COMMERCE_URL = "https://commerce.example.com"

session = requests.Session()
session.get(f"{COMMERCE_URL}/csrf_token/")

print(f"CSRF Token: {session.cookies.get('csrftoken')}")

Response:

The response sets a csrftoken cookie. Store this value for subsequent requests.

---

Step 2: Customer Login

Authenticate the customer using their credentials to obtain a session cookie.

Request:

curl -X POST "{commerce_url}/users/login/" -H "Content-Type: application/json" -H "x-csrftoken: $CSRF_TOKEN" -b cookies.txt -c cookies.txt -d '{"email": "[email protected]", "password": "your_password"}'

import requests

COMMERCE_URL = "https://commerce.example.com"

session = requests.Session()
session.get(f"{COMMERCE_URL}/csrf_token/")

response = session.post(
    f"{COMMERCE_URL}/users/login/",
    headers={"x-csrftoken": session.cookies.get("csrftoken")},
    json={"email": "[email protected]", "password": "customer_password"}
)

print(f"Login: {response.status_code}")

Response:

On successful login, the response sets an osessionid cookie. The customer session is now authenticated.

---

Step 3: Make Authenticated Requests

Include cookies in all requests. Add x-csrftoken header only for POST/PUT/DELETE requests.

Important: Always store cookies from responses—they may be refreshed by the server.

Request:

curl -X GET "{commerce_url}/current_user/" -b cookies.txt

import requests

COMMERCE_URL = "https://commerce.example.com"

session = requests.Session()
session.get(f"{COMMERCE_URL}/csrf_token/")   
session.post(
    f"{COMMERCE_URL}/users/login/",
    headers={"x-csrftoken": session.cookies.get("csrftoken")},
    json={"email": "[email protected]", "password": "customer_password"}
)

# Now make authenticated requests (GET doesn't need x-csrftoken)
response = session.get(f"{COMMERCE_URL}/current_user/")

print(response.json())

---

Authentication

Endpoint Type	Authentication Required	Example Use Cases
Public	No	Product listings, store info, categories
Authenticated	Yes (session cookie)	Profile, orders, addresses, payments

Public endpoints can be called without any authentication.

Authenticated endpoints require the customer to be logged in. The osessionid cookie proves the customer's identity and gives access to their personal data.

---

Session Cookie

The session cookie identifies the customer's authenticated session.

Default cookie name: osessionid

Example:

Cookie: osessionid=yji6ppwys9a2k2myv3k9e5q2jifggqt9

Custom cookie name:

The session cookie name can be customized via the SESSION_COOKIE_NAME environment variable through Akinon Commerce Cloud (ACC). If modified, use the updated cookie name in your requests:

Cookie: <custom_session_cookie_name>=yji6ppwys9a2k2myv3k9e5q2jifggqt9

---

CSRF Token

For all API requests except GET, CSRF verification is required. The CSRF token must be included in both:

1. The csrftoken cookie

2. The x-csrftoken header (must match the cookie value)

Obtaining the CSRF Token:

To fetch the CSRF token for the first time, call the /csrf_token/ endpoint. The response will include a csrftoken cookie.

Important: Always store both the session cookie and CSRF token after each request, as they may be refreshed.

Example (CSRF token only):

Cookie: csrftoken=KxlMDi8Nfy0HljwuWTRnJwDMfGtP5Zh8xHn4BMOEJFAxaRAFJx6MarlaHDM66LZ7
x-csrftoken: KxlMDi8Nfy0HljwuWTRnJwDMfGtP5Zh8xHn4BMOEJFAxaRAFJx6MarlaHDM66LZ7

Example (with session cookie):

Cookie: osessionid=yji6ppwys9a2k2myv3k9e5q2jifggqt9; csrftoken=KxlMDi8Nfy0HljwuWTRnJwDMfGtP5Zh8xHn4BMOEJFAxaRAFJx6MarlaHDM66LZ7
x-csrftoken: KxlMDi8Nfy0HljwuWTRnJwDMfGtP5Zh8xHn4BMOEJFAxaRAFJx6MarlaHDM66LZ7

---

Common Errors

Error Code	Description	Solution
403 Forbidden	CSRF token missing or invalid	Ensure the x-csrftoken header matches the csrftoken cookie value
401 Unauthorized	Session expired or invalid	Re-authenticate by logging in again
400 Bad Request	Invalid request data	Check your request body and parameters

---

Quick Reference

Cookies to manage:

Cookie	Purpose	When Set
csrftoken	Security token for POST/PUT/DELETE requests	After calling /csrf_token/
osessionid	Session identifier (guest or logged-in)	On first request or after login

Remember: Store cookies from every response and resend them with the next request. This applies to both guest and logged-in users.

Headers for authenticated requests:

Cookie: osessionid=<session_id>; csrftoken=<csrf_token>
x-csrftoken: <csrf_token>

Key endpoints:

Endpoint	Method	Purpose
/csrf_token/	GET	Get CSRF token
/users/login/	POST	Customer login
/current_user/	GET	Get current customer profile