API Documentation - Salloq REST API

Introduction

Welcome to the Salloq REST API documentation. This API provides programmatic access to your ecommerce platform, allowing you to:

Manage products and inventory
Create and process orders
Access customer data
Manage subscriptions
View loyalty program information

Need API Access? Contact your administrator to create API keys with appropriate permissions.

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security: Never expose your API key in client-side code or public repositories. Always use HTTPS for API requests.

Authentication Errors

Status Code	Description
`401`	Missing or invalid API key
`403`	Valid key but insufficient permissions

Base URL

All API endpoints are relative to the base URL:

https://your-domain.com/api

Example full endpoint:

https://your-domain.com/api/products

Response Format

All responses are returned in JSON format with a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 150,
      "total_pages": 6
    }
  }
}

Error Response

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": 400,
    "details": {
      // Additional error information
    }
  }
}

Error Handling

The API uses standard HTTP status codes:

Status Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`422`	Unprocessable Entity - Validation errors
`500`	Internal Server Error

Pagination

List endpoints support pagination using query parameters:

Parameter	Default	Maximum	Description
`page`	1	-	Page number
`per_page`	25	100	Items per page

Example:

GET /api/products?page=2&per_page=50

Products

GET /products

Retrieve a list of products with optional filtering.

Required Scope

products:read

Query Parameters

Parameter	Type	Description
`category`	string	Filter by category slug
`search`	string	Search in product name/description
`in_stock`	boolean	Filter by stock availability (true/false)
`subscription_enabled`	boolean	Filter subscription products only

Example Request

curl -X GET "https://your-domain.com/api/products?category=perfume&in_stock=true" \
  -H "X-API-Key: ak_live_xxxxx"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 163,
      "name": "Iris Élysée",
      "slug": "iris-elysee",
      "price": 145.00,
      "description": "A sophisticated iris fragrance...",
      "stock_qty": 25,
      "subscription_enabled": true,
      "categories": ["perfume", "floral"],
      "images": [
        {
          "url": "https://...",
          "is_primary": true
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 45,
      "total_pages": 2
    }
  }
}

GET /products/{id}

Retrieve detailed information about a specific product.

Required Scope

products:read

Path Parameters

Parameter	Type	Description
`id`	integer or string	Product ID or slug

Example Request

curl -X GET "https://your-domain.com/api/products/163" \
  -H "X-API-Key: ak_live_xxxxx"

GET /products/{id}/inventory

Check inventory levels for a specific product.

Required Scope

products:read

Example Response

{
  "success": true,
  "data": {
    "product_id": 163,
    "stock_qty": 25,
    "in_stock": true
  }
}

POST /products

Create a new product.

Required Scope

products:write

Request Body

{
  "name": "New Product",
  "slug": "new-product",
  "description": "Product description",
  "price": 99.99,
  "stock_qty": 100,
  "subscription_enabled": false
}

PATCH /products/{id}

Update an existing product.

Required Scope

products:write

Request Body

{
  "price": 109.99,
  "stock_qty": 75
}

Orders

GET /orders

Retrieve a list of orders with optional filtering.

Required Scope

orders:read

Query Parameters

Parameter	Type	Description
`customer_id`	integer	Filter by customer
`status`	string	Filter by status (pending, processing, shipped, delivered, cancelled)
`date_from`	date	Orders created after this date (YYYY-MM-DD)
`date_to`	date	Orders created before this date (YYYY-MM-DD)
`is_subscription`	boolean	Filter subscription orders

Example Request

curl -X GET "https://your-domain.com/api/orders?status=shipped&date_from=2025-12-01" \
  -H "X-API-Key: ak_live_xxxxx"

GET /orders/{id}

Retrieve complete order details including items and shipping information.

Required Scope

orders:read

Example Response

{
  "success": true,
  "data": {
    "id": 307,
    "customer_id": 2186,
    "status": "shipped",
    "subtotal": 145.00,
    "tax": 12.18,
    "shipping": 8.00,
    "total": 165.18,
    "tracking_number": "1Z999AA1234567890",
    "items": [
      {
        "product_id": 163,
        "product_name": "Iris Élysée",
        "qty": 1,
        "price": 145.00,
        "subtotal": 145.00
      }
    ],
    "shipping_address": "123 Main St",
    "shipping_city": "San Francisco",
    "shipping_state": "CA",
    "shipping_zip": "94102",
    "created_at": "2025-12-08T10:30:00Z"
  }
}

POST /orders

Create a new order. Automatically calculates totals and decrements inventory.

Required Scope

orders:write

Request Body

{
  "customer_id": 2186,
  "items": [
    {
      "product_id": 163,
      "qty": 2
    }
  ],
  "shipping_address": "123 Main St",
  "shipping_city": "San Francisco",
  "shipping_state": "CA",
  "shipping_zip": "94102",
  "shipping_country": "US",
  "promo_code": "SAVE10"
}

The API automatically validates stock availability, calculates tax and totals, applies promo codes, and decrements inventory in a transaction.

PATCH /orders/{id}/status

Update order status and tracking information.

Required Scope

orders:write

Request Body

{
  "status": "shipped",
  "tracking_number": "1Z999AA1234567890"
}

Customers

GET /customers/{id}

Retrieve customer information.

Required Scope

customers:read

Example Response

{
  "success": true,
  "data": {
    "id": 2186,
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "555-0123",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

GET /customers/{id}/orders

Retrieve a customer's order history.

Required Scope

customers:read

GET /customers/{id}/loyalty

Retrieve customer's loyalty points balance.

Required Scope

customers:read

Example Response

{
  "success": true,
  "data": {
    "customer_id": 2186,
    "current_balance": 2500,
    "lifetime_points": 5000,
    "dollar_value": 25.00
  }
}

POST /customers

Create a new customer account.

Required Scope

customers:write

Request Body

{
  "email": "newcustomer@example.com",
  "password": "securepassword123",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "555-0199"
}

PATCH /customers/{id}

Update customer information.

Required Scope

customers:write

Request Body

{
  "first_name": "Jane",
  "phone": "555-9876"
}

Subscriptions

GET /subscriptions/{id}

Retrieve subscription details.

Required Scope

subscriptions:read

Example Response

{
  "success": true,
  "data": {
    "id": 42,
    "customer_id": 2186,
    "product_id": 163,
    "frequency_id": 2,
    "frequency_name": "Every 30 days",
    "quantity": 1,
    "price": 130.50,
    "status": "active",
    "next_billing_date": "2026-01-08",
    "created_at": "2025-12-08T10:00:00Z"
  }
}

GET /subscriptions/{id}/upcoming

Preview the next scheduled subscription order.

Required Scope

subscriptions:read

POST /subscriptions

Create a new subscription.

Required Scope

subscriptions:write

Request Body

{
  "customer_id": 2186,
  "product_id": 163,
  "frequency_id": 2,
  "quantity": 1,
  "start_date": "2025-12-08"
}

PATCH /subscriptions/{id}

Update subscription details.

Required Scope

subscriptions:write

Request Body

{
  "quantity": 2,
  "frequency_id": 3,
  "next_billing_date": "2026-02-01"
}

POST /subscriptions/{id}/cancel

Cancel a subscription.

Required Scope

subscriptions:write

Request Body

{
  "reason": "Customer request"
}

Loyalty

GET /loyalty/settings

Retrieve loyalty program configuration.

Required Scope

loyalty:read

Example Response

{
  "success": true,
  "data": {
    "points_per_dollar": 100,
    "point_value": 0.01,
    "min_redeem_points": 500,
    "enabled": true
  }
}

Rate Limits

API rate limits are enforced to ensure fair usage and system stability:

Limit	Window
1000 requests	Per hour

When you exceed rate limits, you'll receive a 429 Too Many Requests response.

Permission Scopes

API keys are assigned specific scopes that determine which operations they can perform:

Scope	Description
`products:read`	View products and inventory
`products:write`	Create and update products
`orders:read`	View orders
`orders:write`	Create orders and update status
`customers:read`	View customer information
`customers:write`	Create and update customers
`subscriptions:read`	View subscriptions
`subscriptions:write`	Manage subscriptions
`loyalty:read`	View loyalty program data
`*`	Full admin access to all endpoints

Code Examples

JavaScript / Node.js

// Using fetch API
const response = await fetch('https://your-domain.com/api/products', {
  headers: {
    'X-API-Key': 'ak_live_xxxxx'
  }
});

const data = await response.json();
console.log(data);

PHP

$ch = curl_init('https://your-domain.com/api/products');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ak_live_xxxxx'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

print_r($data);

Python

import requests

headers = {
    'X-API-Key': 'ak_live_xxxxx'
}

response = requests.get('https://your-domain.com/api/products', headers=headers)
data = response.json()

print(data)

cURL

curl -X GET "https://your-domain.com/api/products" \
  -H "X-API-Key: ak_live_xxxxx"