Customer API

Customer API Reference

Build custom storefronts, mobile apps, and customer experiences with our comprehensive Customer API. Perfect for headless commerce and custom integrations.

Authentication

JWT Bearer tokens for secure access

Rate Limits

1000 requests per hour per user

Response Format

JSON with consistent error handling

Authentication Endpoints

Handle customer login, registration, and token management

POST
/auth/register

Register a new customer account

Request Body 
{
  "email": "[email protected]",
  "password": "securePassword123",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890"
}
Response (201 Created) 
{
  "success": true,
  "data": {
    "user": {
      "id": "cust_123456789",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}
POST
/auth/login

Authenticate customer and get access token

Request Body 
{
  "email": "[email protected]",
  "password": "securePassword123"
}
Response (200 OK) 
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "user": {
      "id": "cust_123456789",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

Error Handling

Standard error responses and status codes

Error Response Format 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}

Common Status Codes

200 Success
201 Created
400 Bad Request
401 Unauthorized
404 Not Found
429 Rate Limited

Error Codes

VALIDATION_ERROR Invalid input
AUTHENTICATION_ERROR Auth failed
PRODUCT_NOT_FOUND Product missing
INSUFFICIENT_STOCK Out of stock
PAYMENT_FAILED Payment error

SDK Examples

Quick examples using our JavaScript SDK

JavaScript SDK Usage 
import { CommerceFull } from '@commercefull/sdk';

const client = new CommerceFull({
  apiKey: 'your-api-key',
  environment: 'production' // or 'sandbox'
});

// Authenticate customer
const { token } = await client.auth.login({
  email: '[email protected]',
  password: 'password123'
});

// Set auth token for subsequent requests
client.setAuthToken(token);

// Get products
const products = await client.products.list({
  page: 1,
  limit: 20,
  category: 'clothing'
});

// Add to cart
await client.cart.addItem({
  productId: 'prod_123456789',
  quantity: 1,
  variantId: 'var_123'
});

// Create order
const order = await client.orders.create({
  shippingAddress: { /* address */ },
  paymentMethod: { /* payment */ }
});