Skip to main content

​
Quickstart Guide

This guide will walk you through making your first API calls to the E-commerce API. You’ll create an account, authenticate, and retrieve a list of products.
This guide assumes you have already installed and started the API locally. If not, follow the Installation Guide first.

​
Prerequisites

  • API running at http://localhost:8000
  • cURL, Postman, or any HTTP client
  • Basic understanding of REST APIs and JSON

​
Step-by-Step Tutorial

1

Create a Customer Account

First, create a customer account to access the API:
curl -X POST http://localhost:8000/api/v1/customers/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-15",
    "password": "securepassword123",
    "password2": "securepassword123"
  }'
Response (201 Created):
{
  "id": 1,
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-15"
}
The password2 field is used for password confirmation. Both password fields must match.
2

Obtain Access Token

Authenticate using your credentials to receive JWT tokens:
curl -X POST http://localhost:8000/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'
Response:
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzA5NTY3ODkwLCJpYXQiOjE3MDk1NjQyOTAsImp0aSI6IjJkNWY4ZTgxYjYxNDQ4OGNhNjVjOTEyZGQwZjk4NTUwIiwidXNlcl9pZCI6MX0.abc123...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTcwOTgyMzQ5MCwiaWF0IjoxNzA5NTY0MjkwLCJqdGkiOiI5ZTRlYjk4NzgwNTQ0MmI2OTY4YTQ4MTQxZmE3YjUwMCIsInVzZXJfaWQiOjF9.xyz789..."
}
Save the access token - you’ll need it for all authenticated requests. Access tokens expire after 1 hour.
3

Retrieve Products

Now make your first authenticated request to retrieve the product catalog:
curl -X GET http://localhost:8000/api/v1/products/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Replace YOUR_ACCESS_TOKEN with the actual access token from Step 2.Response:
{
  "count": 25,
  "next": "http://localhost:8000/api/v1/products/?limit=10&offset=10",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Wireless Bluetooth Headphones",
      "slug": "wireless-bluetooth-headphones",
      "description": "High-quality wireless headphones with noise cancellation",
      "price": "79.99",
      "stock": 50,
      "category": "Electronics",
      "image": "http://localhost:8000/media/products/headphones.jpg",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-20T14:22:00Z"
    },
    {
      "id": 2,
      "name": "Smart Fitness Watch",
      "slug": "smart-fitness-watch",
      "description": "Track your health and fitness goals with this smartwatch",
      "price": "129.99",
      "stock": 30,
      "category": "Electronics",
      "image": "http://localhost:8000/media/products/watch.jpg",
      "created_at": "2024-01-16T09:15:00Z",
      "updated_at": "2024-02-18T11:45:00Z"
    }
  ]
}
The API uses limit-offset pagination. Use ?limit=20&offset=0 to control page size and position.
4

Get a Single Product

Retrieve detailed information about a specific product:
curl -X GET http://localhost:8000/api/v1/products/1/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response:
{
  "id": 1,
  "name": "Wireless Bluetooth Headphones",
  "slug": "wireless-bluetooth-headphones",
  "description": "High-quality wireless headphones with active noise cancellation, 30-hour battery life, and premium sound quality.",
  "price": "79.99",
  "stock": 50,
  "category": {
    "id": 3,
    "name": "Electronics",
    "slug": "electronics"
  },
  "images": [
    {
      "id": 1,
      "image": "http://localhost:8000/media/products/headphones.jpg",
      "alt_text": "Wireless headphones front view"
    }
  ],
  "average_rating": 4.5,
  "review_count": 12,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-02-20T14:22:00Z"
}

​
Complete Example with Python

Here’s a complete Python script that performs all the steps above: 
import requests

BASE_URL = "http://localhost:8000"

# Step 1: Create account
register_data = {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-15",
    "password": "securepassword123",
    "password2": "securepassword123"
}

response = requests.post(f"{BASE_URL}/api/v1/customers/", json=register_data)
print(f"Account created: {response.status_code}")

# Step 2: Get access token
auth_data = {
    "email": "[email protected]",
    "password": "securepassword123"
}

response = requests.post(f"{BASE_URL}/auth/token/", json=auth_data)
tokens = response.json()
access_token = tokens["access"]
print(f"Access token: {access_token[:50]}...")

# Step 3: Get products
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(f"{BASE_URL}/api/v1/products/", headers=headers)
products = response.json()

print(f"\nFound {products['count']} products:")
for product in products['results'][:3]:
    print(f"  - {product['name']}: ${product['price']}")

​
Token Refresh

Access tokens expire after 1 hour (config/settings.py:209). When this happens, use your refresh token to get a new access token: 
curl -X POST http://localhost:8000/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'
Response: 
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Refresh tokens are valid for 3 days (config/settings.py:210). After that, users must log in again.

​
Next Steps

Now that you’ve made your first API calls, explore more features:

Add Products to Cart

Learn how to manage shopping cart items

Create Orders

Process orders and manage customer purchases

Product Reviews

Add and retrieve product reviews

Payment Processing

Integrate Braintree payment processing

​
Common Issues

This means your access token is missing, invalid, or expired. Check that:
  • You’re including the Authorization: Bearer YOUR_TOKEN header
  • Your token hasn’t expired (1 hour lifetime)
  • The token is copied correctly without extra spaces
If expired, use the refresh token endpoint to get a new access token.
Your token is valid, but you don’t have permission to access this resource. Some endpoints require specific user roles or ownership of the resource.
The API server is not running. Make sure you’ve started it with:
docker-compose up
The email address is already registered. Either use a different email or authenticate with the existing account.
Visit http://localhost:8000/swagger/ to explore all available endpoints interactively in your browser!

Build docs developers (and LLMs) love

Get started for freeTalk to us