> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce/users/getting-started.md).

# 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

## <mark style="color:red;">How It Works</mark>

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

## <mark style="color:red;">Base URL</mark>

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.

***

## <mark style="color:red;">Quick Start</mark>

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:**

```bash
# 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)
```

```python
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:**

```bash
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": "user@example.com", "password": "your_password"}'
```

```python
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": "customer@example.com", "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:**

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

```python
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": "customer@example.com", "password": "customer_password"}
)

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

print(response.json())
```

***

## <mark style="color:red;">Authentication</mark>

| 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.

***

## <mark style="color:red;">Session Cookie</mark>

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
```

***

## <mark style="color:red;">CSRF Token</mark>

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
```

***

## <mark style="color:red;">Common Errors</mark>

| 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                               |

***

## <mark style="color:red;">Quick Reference</mark>

**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 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.akinon.com/commerce/users/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.