🛠 Complete API Reference

Build Secure Integrations with the SKALIA API

Everything you need to authenticate, manage stores, process orders, configure storefronts, and integrate payments with the SKALIA backend.

📄 Version 1.0 📅 April 2026 🔗 REST + JSON

SKALIA Backend API Documentation

Version 1.0 | April 2026

Complete REST API reference for the SKALIA e-commerce platform backend.

Overview

The SKALIA API is a RESTful API that allows you to programmatically interact with the SKALIA e-commerce platform. All API requests must be made over HTTPS and authenticated using JWT tokens.

Key Features

  • RESTful Design: Standard HTTP methods (GET, POST, PATCH, PUT, DELETE)
  • JSON Format: All requests and responses use JSON
  • JWT Authentication: Secure token-based authentication
  • Pagination: Efficient data retrieval for large datasets
  • Error Handling: Consistent error response format
  • Rate Limiting: Fair usage policies to ensure service stability

Authentication

All API requests (except authentication endpoints) require a valid JWT token in the Authorization header.

Authentication Header

Authorization: Bearer <your_jwt_token>

Token Lifecycle

  • Expiration: Tokens expire after 24 hours
  • Refresh: Obtain a new token by logging in again
  • Storage: Store tokens securely (never in localStorage for sensitive apps)

Base URL & Versioning

Base URL

Production: https://api.skalia.ma
Development: http://localhost:8000

API Version

All endpoints are prefixed with /api/v1/

Example:

https://api.skalia.ma/api/v1/auth/login

Common Response Formats

Success Response

{
  "item": { /* single resource */ },
  "message": "Operation successful"
}

List Response (Paginated)

{
  "items": [ /* array of resources */ ],
  "total": 100,
  "page": 1,
  "size": 20,
  "pages": 5
}

Error Response

{
  "detail": "Error message describing what went wrong",
  "status": 400
}

Error Handling

HTTP Status Codes

Code Meaning Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource not found
409 Conflict Resource conflict (e.g., duplicate)
422 Unprocessable Entity Validation error
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

Error Response Format

{
  "detail": "Detailed error message",
  "status": 400,
  "errors": {
    "field_name": ["Error message for this field"]
  }
}

Authentication Endpoints

1. Register New User

Create a new user account.

Endpoint: POST /api/v1/auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "displayName": "John Doe"
}

Response: 201 Created

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "usr_1234567890",
    "email": "user@example.com",
    "displayName": "John Doe"
  }
}

Validation Rules:

  • Email must be valid and unique
  • Password minimum 8 characters
  • Display name required

2. Login

Authenticate with email and password.

Endpoint: POST /api/v1/auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response: 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "usr_1234567890",
    "email": "user@example.com",
    "displayName": "John Doe"
  }
}

3. Firebase Authentication

Authenticate using Firebase token.

Endpoint: POST /api/v1/auth/firebase

Request Body:

{
  "token": "firebase_id_token_here"
}

Response: 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "usr_1234567890",
    "email": "user@example.com",
    "displayName": "John Doe"
  }
}

4. Get Current User

Retrieve authenticated user information.

Endpoint: GET /api/v1/auth/me

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "id": "usr_1234567890",
  "email": "user@example.com",
  "displayName": "John Doe",
  "photoURL": "https://example.com/photo.jpg",
  "role": "user",
  "createdAt": "2026-01-01T00:00:00Z",
  "subscription": {
    "plan": "pro",
    "status": "active",
    "billingCycle": "monthly",
    "startedAt": "2026-01-01T00:00:00Z",
    "nextBillingDate": "2026-02-01T00:00:00Z",
    "amount": 299,
    "currency": "MAD",
    "storeLimit": 5,
    "productLimit": 1000
  },
  "preferences": {
    "language": "en",
    "currency": "MAD",
    "compactMode": false
  }
}

5. Logout

Invalidate current session.

Endpoint: POST /api/v1/auth/logout

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "message": "Logged out successfully"
}

Store Management

1. List All Stores

Get all stores for the authenticated user.

Endpoint: GET /api/v1/stores

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter Type Description
page integer Page number (default: 1)
size integer Items per page (default: 20)
status string Filter by status: LIVE, DRAFT, MAINTENANCE

Response: 200 OK

{
  "items": [
    {
      "id": "store_1234567890",
      "name": "My Awesome Store",
      "category": "fashion",
      "publicSlug": "my-awesome-store",
      "customDomain": "shop.example.com",
      "language": "en",
      "status": "LIVE",
      "isPublished": true,
      "publishedAt": "2026-01-15T10:00:00Z",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "size": 20,
  "pages": 1
}

2. Create Store

Create a new online store.

Endpoint: POST /api/v1/stores

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "name": "My New Store",
  "category": "electronics",
  "publicSlug": "my-new-store",
  "language": "en"
}

Response: 201 Created

{
  "item": {
    "id": "store_9876543210",
    "name": "My New Store",
    "category": "electronics",
    "publicSlug": "my-new-store",
    "language": "en",
    "status": "DRAFT",
    "isPublished": false,
    "createdAt": "2026-04-08T14:00:00Z",
    "updatedAt": "2026-04-08T14:00:00Z"
  }
}

Validation:

  • Name: Required, 3-100 characters
  • Category: Required
  • Public Slug: Required, unique, lowercase, alphanumeric with hyphens
  • Language: Must be one of: en, fr, ar

3. Check Slug Availability

Check if a public slug is available.

Endpoint: GET /api/v1/stores/check-slug

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter Type Required Description
publicSlug string Yes Slug to check

Response: 200 OK

{
  "publicSlug": "my-store",
  "available": true
}

4. Update Store Status

Change store status (LIVE, DRAFT, MAINTENANCE).

Endpoint: PATCH /api/v1/stores/{storeId}/status

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "status": "LIVE"
}

Response: 200 OK

{
  "item": {
    "id": "store_1234567890",
    "name": "My Store",
    "status": "LIVE",
    "updatedAt": "2026-04-08T14:30:00Z"
  }
}

Valid Status Values:

  • LIVE: Store is publicly accessible
  • DRAFT: Store is not published
  • MAINTENANCE: Store shows maintenance page

5. Update Custom Domain

Set or update custom domain for a store.

Endpoint: PATCH /api/v1/stores/{storeId}/custom-domain

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "domain": "shop.example.com"
}

Response: 200 OK

{
  "item": {
    "id": "store_1234567890",
    "customDomain": "shop.example.com",
    "updatedAt": "2026-04-08T14:35:00Z"
  }
}

Note: Custom domains require DNS configuration and are available on Pro and Enterprise plans.

6. Update Store Language

Change store language.

Endpoint: PATCH /api/v1/stores/{storeId}/language

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "language": "fr"
}

Response: 200 OK

{
  "item": {
    "id": "store_1234567890",
    "language": "fr",
    "updatedAt": "2026-04-08T14:40:00Z"
  }
}

Supported Languages:

  • en: English
  • fr: French
  • ar: Arabic

Product Management

1. List All Products

Get all products across all stores.

Endpoint: GET /api/v1/products

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter Type Description
page integer Page number (default: 1)
size integer Items per page (default: 20)
storeId string Filter by store ID
status string Filter by status: active, draft, out_of_stock
category string Filter by category

Response: 200 OK

{
  "items": [
    {
      "id": "prod_1234567890",
      "storeId": "store_1234567890",
      "name": "Premium Wireless Headphones",
      "description": "High-quality wireless headphones with noise cancellation",
      "price": 1299.00,
      "compareAtPrice": 1599.00,
      "sku": "WH-1000XM5",
      "barcode": "1234567890123",
      "category": "Electronics",
      "tags": ["audio", "wireless", "premium"],
      "images": [
        "https://cdn.skalia.ma/products/prod_123/image1.jpg",
        "https://cdn.skalia.ma/products/prod_123/image2.jpg"
      ],
      "inventory": {
        "quantity": 50,
        "trackInventory": true,
        "lowStockThreshold": 10
      },
      "variants": [
        {
          "id": "var_001",
          "name": "Black",
          "sku": "WH-1000XM5-BLK",
          "price": 1299.00,
          "inventory": 30
        },
        {
          "id": "var_002",
          "name": "Silver",
          "sku": "WH-1000XM5-SLV",
          "price": 1299.00,
          "inventory": 20
        }
      ],
      "seo": {
        "title": "Premium Wireless Headphones - Best Noise Cancellation",
        "description": "Shop premium wireless headphones with industry-leading noise cancellation",
        "slug": "premium-wireless-headphones"
      },
      "status": "active",
      "createdAt": "2026-01-10T00:00:00Z",
      "updatedAt": "2026-04-08T10:00:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "size": 20,
  "pages": 3
}

2. Create Product

Add a new product to a store.

Endpoint: POST /api/v1/products

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "storeId": "store_1234567890",
  "name": "Organic Cotton T-Shirt",
  "description": "Comfortable 100% organic cotton t-shirt",
  "price": 199.00,
  "compareAtPrice": 249.00,
  "sku": "TSHIRT-ORG-001",
  "barcode": "9876543210987",
  "category": "Clothing",
  "tags": ["organic", "cotton", "sustainable"],
  "images": [
    "https://cdn.skalia.ma/uploads/image1.jpg"
  ],
  "inventory": {
    "quantity": 100,
    "trackInventory": true,
    "lowStockThreshold": 20
  },
  "variants": [
    {
      "name": "Small",
      "sku": "TSHIRT-ORG-001-S",
      "price": 199.00,
      "inventory": 30
    },
    {
      "name": "Medium",
      "sku": "TSHIRT-ORG-001-M",
      "price": 199.00,
      "inventory": 40
    },
    {
      "name": "Large",
      "sku": "TSHIRT-ORG-001-L",
      "price": 199.00,
      "inventory": 30
    }
  ],
  "seo": {
    "title": "Organic Cotton T-Shirt - Sustainable Fashion",
    "description": "Shop our comfortable organic cotton t-shirt",
    "slug": "organic-cotton-tshirt"
  },
  "status": "active"
}

Response: 201 Created

{
  "item": {
    "id": "prod_9876543210",
    "storeId": "store_1234567890",
    "name": "Organic Cotton T-Shirt",
    "price": 199.00,
    "status": "active",
    "createdAt": "2026-04-08T15:00:00Z"
  }
}

Validation:

  • Name: Required, 3-200 characters
  • Price: Required, must be positive
  • SKU: Optional but recommended, must be unique per store
  • Images: At least one image recommended

3. Update Product

Update an existing product.

Endpoint: PATCH /api/v1/products/{productId}

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body: (partial update supported)

{
  "price": 179.00,
  "inventory": {
    "quantity": 150
  },
  "status": "active"
}

Response: 200 OK

{
  "item": {
    "id": "prod_9876543210",
    "price": 179.00,
    "inventory": {
      "quantity": 150
    },
    "updatedAt": "2026-04-08T15:30:00Z"
  }
}

Order Management

1. List All Orders

Get all orders for the authenticated user's stores.

Endpoint: GET /api/v1/orders

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter Type Description
page integer Page number (default: 1)
size integer Items per page (default: 20)
storeId string Filter by store ID
status string Filter by status
startDate string Filter orders from date (ISO 8601)
endDate string Filter orders to date (ISO 8601)

Response: 200 OK

{
  "items": [
    {
      "id": "order_1234567890",
      "orderNumber": "ORD-2026-001234",
      "storeId": "store_1234567890",
      "storeName": "My Store",
      "customer": {
        "id": "cust_1234567890",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "+212612345678"
      },
      "items": [
        {
          "productId": "prod_1234567890",
          "productName": "Premium Wireless Headphones",
          "variantId": "var_001",
          "variantName": "Black",
          "quantity": 1,
          "price": 1299.00,
          "total": 1299.00
        }
      ],
      "subtotal": 1299.00,
      "shipping": 50.00,
      "tax": 0.00,
      "discount": 0.00,
      "total": 1349.00,
      "currency": "MAD",
      "status": "processing",
      "paymentStatus": "paid",
      "paymentMethod": "card",
      "shippingAddress": {
        "name": "Jane Smith",
        "address": "123 Main Street",
        "city": "Casablanca",
        "postalCode": "20000",
        "country": "Morocco",
        "phone": "+212612345678"
      },
      "trackingNumber": "TRK123456789",
      "notes": "Please handle with care",
      "createdAt": "2026-04-08T10:00:00Z",
      "updatedAt": "2026-04-08T11:00:00Z"
    }
  ],
  "total": 127,
  "page": 1,
  "size": 20,
  "pages": 7
}

Order Status Values:

  • pending: Order received, awaiting payment
  • processing: Payment confirmed, preparing order
  • shipped: Order dispatched
  • delivered: Order delivered to customer
  • cancelled: Order cancelled
  • refunded: Order refunded

2. Update Order

Update order status and details.

Endpoint: PATCH /api/v1/orders/{orderId}

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "status": "shipped",
  "trackingNumber": "TRK987654321",
  "notes": "Shipped via DHL Express"
}

Response: 200 OK

{
  "item": {
    "id": "order_1234567890",
    "status": "shipped",
    "trackingNumber": "TRK987654321",
    "updatedAt": "2026-04-08T16:00:00Z"
  }
}

Customer Management

1. List All Customers

Get all customers from user's stores.

Endpoint: GET /api/v1/customers

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter Type Description
page integer Page number (default: 1)
size integer Items per page (default: 20)
storeId string Filter by store ID
search string Search by name or email

Response: 200 OK

{
  "items": [
    {
      "id": "cust_1234567890",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+212612345678",
      "totalOrders": 5,
      "totalSpent": 6745.00,
      "currency": "MAD",
      "averageOrderValue": 1349.00,
      "lastOrderDate": "2026-04-08T10:00:00Z",
      "createdAt": "2026-01-15T00:00:00Z",
      "tags": ["vip", "repeat-customer"]
    }
  ],
  "total": 234,
  "page": 1,
  "size": 20,
  "pages": 12
}

Store Configuration

1. Get Store Pages

Retrieve custom pages for a store.

Endpoint: GET /api/v1/store-config/{storeId}/pages

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "items": [
    {
      "id": "page_1234567890",
      "title": "About Us",
      "slug": "about",
      "content": "<h1>About Our Store</h1><p>We are...</p>",
      "isPublished": true,
      "order": 1,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-03-15T00:00:00Z"
    },
    {
      "id": "page_0987654321",
      "title": "Contact",
      "slug": "contact",
      "content": "<h1>Contact Us</h1><p>Email: contact@store.com</p>",
      "isPublished": true,
      "order": 2,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ]
}

2. Save Store Pages

Update all pages for a store.

Endpoint: PUT /api/v1/store-config/{storeId}/pages

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "items": [
    {
      "id": "page_1234567890",
      "title": "About Us",
      "slug": "about",
      "content": "<h1>About Our Store</h1><p>Updated content...</p>",
      "isPublished": true,
      "order": 1
    }
  ]
}

Response: 200 OK

{
  "items": [ /* updated pages */ ]
}

3. Update Store Settings

Update store configuration settings.

Endpoint: PATCH /api/v1/store-config/{storeId}/settings

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "storeName": "My Updated Store",
  "storeDescription": "New description",
  "contactEmail": "contact@mystore.com",
  "contactPhone": "+212612345678",
  "currency": "MAD",
  "shippingZones": [
    {
      "name": "Morocco",
      "countries": ["MA"],
      "rate": 50.00
    }
  ],
  "taxRate": 0.20,
  "socialMedia": {
    "facebook": "https://facebook.com/mystore",
    "instagram": "https://instagram.com/mystore",
    "twitter": "https://twitter.com/mystore"
  }
}

Response: 200 OK

{
  "item": {
    "storeName": "My Updated Store",
    "updatedAt": "2026-04-08T17:00:00Z"
  }
}

4. Get Store Theme

Retrieve theme configuration.

Endpoint: GET /api/v1/store-config/{storeId}/theme

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "item": {
    "colors": {
      "primary": "#3b82f6",
      "secondary": "#64748b",
      "accent": "#f59e0b",
      "background": "#ffffff",
      "text": "#1e293b"
    },
    "fonts": {
      "heading": "Inter",
      "body": "Inter"
    },
    "layout": {
      "headerStyle": "centered",
      "footerStyle": "minimal"
    },
    "homepage": {
      "hero": {
        "title": "Welcome to Our Store",
        "subtitle": "Discover amazing products",
        "image": "https://cdn.skalia.ma/hero.jpg",
        "ctaText": "Shop Now",
        "ctaLink": "/products"
      },
      "sections": [
        {
          "type": "featured-products",
          "title": "Featured Products",
          "productIds": ["prod_123", "prod_456"]
        }
      ]
    }
  }
}

5. Save Store Theme

Update theme configuration.

Endpoint: PUT /api/v1/store-config/{storeId}/theme

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "item": {
    "colors": {
      "primary": "#2563eb"
    }
  }
}

Response: 200 OK

{
  "item": { /* updated theme */ }
}

6. Publish Store

Publish store changes to make them live.

Endpoint: POST /api/v1/store-config/{storeId}/publish

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "publishedAt": "2026-04-08T18:00:00Z",
  "isPublished": true
}

Billing & Subscriptions

1. Get Subscription

Retrieve current subscription details.

Endpoint: GET /api/v1/billing/subscription

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "item": {
    "plan": "pro",
    "status": "active",
    "paymentStatus": "paid",
    "billingCycle": "monthly",
    "startedAt": "2026-01-01T00:00:00Z",
    "nextBillingDate": "2026-05-01T00:00:00Z",
    "lastPaymentDate": "2026-04-01T00:00:00Z",
    "amount": 299,
    "currency": "MAD",
    "storeLimit": 5,
    "productLimit": 1000,
    "notes": null
  }
}

2. Get Billing Requests

List all billing requests for the user.

Endpoint: GET /api/v1/billing/requests

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "items": [
    {
      "id": "req_1234567890",
      "userId": "usr_1234567890",
      "plan": "pro",
      "billingCycle": "monthly",
      "amount": 299,
      "currency": "MAD",
      "status": "approved",
      "paymentMethod": "card",
      "payzoneTransactionId": "TXN123456",
      "payzoneOrderId": "ORD789012",
      "payzoneStatus": "success",
      "submittedAt": "2026-04-01T10:00:00Z",
      "reviewedAt": "2026-04-01T10:05:00Z",
      "reviewedBy": "admin_001",
      "reviewNotes": "Payment verified"
    }
  ]
}

3. Create Billing Request

Submit a new billing request (bank transfer).

Endpoint: POST /api/v1/billing/requests

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "plan": "pro",
  "billingCycle": "monthly",
  "senderName": "John Doe",
  "paymentReference": "REF123456789",
  "notes": "Bank transfer completed on 2026-04-08"
}

Response: 201 Created

{
  "item": {
    "id": "req_9876543210",
    "plan": "pro",
    "billingCycle": "monthly",
    "amount": 299,
    "currency": "MAD",
    "status": "pending",
    "paymentMethod": "bank_transfer",
    "submittedAt": "2026-04-08T18:30:00Z"
  }
}

PayZone Payment Integration

1. Create PayZone Transaction

Initialize a card payment transaction.

Endpoint: POST /api/v1/billing/payzone/transaction

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "plan": "pro",
  "billingCycle": "monthly",
  "returnUrl": "https://skalia.ma/dashboard?payment=success",
  "cancelUrl": "https://skalia.ma/dashboard?payment=cancelled",
  "notifyUrl": "https://api.skalia.ma/api/v1/billing/payzone/callback"
}

Response: 201 Created

{
  "transaction": {
    "transactionId": "TXN123456789",
    "orderId": "ORD987654321",
    "paymentUrl": "https://payzone.ma/payment/abc123def456",
    "amount": 299,
    "currency": "MAD",
    "status": "pending"
  }
}

Next Steps:

  1. Redirect user to paymentUrl
  2. User completes payment on PayZone
  3. User redirected back to returnUrl or cancelUrl
  4. Backend receives callback at notifyUrl

2. Verify PayZone Payment

Verify payment status after return from PayZone.

Endpoint: POST /api/v1/billing/payzone/verify

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "orderId": "ORD987654321"
}

Response: 200 OK

{
  "subscription": {
    "plan": "pro",
    "status": "active",
    "billingCycle": "monthly",
    "startedAt": "2026-04-08T19:00:00Z",
    "amount": 299,
    "currency": "MAD"
  }
}

3. Get Transaction Status

Check PayZone transaction status.

Endpoint: GET /api/v1/billing/payzone/transaction/{orderId}

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "transaction": {
    "orderId": "ORD987654321",
    "transactionId": "TXN123456789",
    "status": "success",
    "amount": 299,
    "currency": "MAD",
    "createdAt": "2026-04-08T18:45:00Z",
    "completedAt": "2026-04-08T18:50:00Z"
  }
}

Status Values:

  • pending: Payment initiated, awaiting completion
  • success: Payment successful
  • failed: Payment failed
  • cancelled: Payment cancelled by user

4. PayZone Callback (Server-to-Server)

Note: This endpoint is called by PayZone servers, not by clients.

Endpoint: POST /api/v1/billing/payzone/callback

Request Body (from PayZone):

{
  "orderId": "ORD987654321",
  "transactionId": "TXN123456789",
  "status": "success",
  "amount": 299,
  "currency": "MAD",
  "signature": "hash_signature_from_payzone"
}

Response: 200 OK

{
  "message": "Callback processed successfully"
}

Security:

  • Always verify the signature
  • Validate the amount matches expected value
  • Handle idempotently (same callback may arrive multiple times)

Dashboard & Analytics

1. Get Dashboard Summary

Retrieve dashboard overview data.

Endpoint: GET /api/v1/dashboard/summary

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter Type Description
range string Time range: last7, last30, last90, all (default: last7)

Response: 200 OK

{
  "revenue": {
    "total": 45678.00,
    "currency": "MAD",
    "change": 12.5,
    "trend": "up"
  },
  "orders": {
    "total": 127,
    "change": 8.3,
    "trend": "up"
  },
  "customers": {
    "total": 234,
    "new": 15,
    "change": 6.4,
    "trend": "up"
  },
  "averageOrderValue": {
    "value": 359.67,
    "currency": "MAD",
    "change": 3.8,
    "trend": "up"
  },
  "stores": [
    {
      "id": "store_1234567890",
      "name": "My Store",
      "status": "LIVE",
      "revenue": 35000.00,
      "orders": 97
    }
  ],
  "recentOrders": [
    {
      "id": "order_1234567890",
      "orderNumber": "ORD-2026-001234",
      "customer": "Jane Smith",
      "total": 1349.00,
      "status": "processing",
      "createdAt": "2026-04-08T10:00:00Z"
    }
  ],
  "topProducts": [
    {
      "id": "prod_1234567890",
      "name": "Premium Wireless Headphones",
      "revenue": 12990.00,
      "unitsSold": 10
    }
  ]
}

2. Get Analytics

Retrieve detailed analytics data.

Endpoint: GET /api/v1/analytics

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter Type Description
storeId string Filter by store ID
startDate string Start date (ISO 8601)
endDate string End date (ISO 8601)
metrics string Comma-separated metrics to include

Response: 200 OK

{
  "salesByDay": [
    {
      "date": "2026-04-01",
      "revenue": 2345.00,
      "orders": 8
    },
    {
      "date": "2026-04-02",
      "revenue": 3456.00,
      "orders": 12
    }
  ],
  "salesByProduct": [
    {
      "productId": "prod_1234567890",
      "productName": "Premium Wireless Headphones",
      "revenue": 12990.00,
      "quantity": 10
    }
  ],
  "salesByCategory": [
    {
      "category": "Electronics",
      "revenue": 25000.00,
      "orders": 45
    }
  ],
  "customerSegments": {
    "new": 15,
    "returning": 112,
    "vip": 8
  },
  "conversionRate": 3.2,
  "cartAbandonmentRate": 68.5
}

3. Admin: Get All Billing Requests

Admin Only - Retrieve all billing requests across all users.

Endpoint: GET /api/v1/billing/admin/requests

Headers:

Authorization: Bearer <admin_token>

Query Parameters:

Parameter Type Description
status string Filter by status: pending, approved, rejected
page integer Page number
size integer Items per page

Response: 200 OK

{
  "items": [
    {
      "id": "req_1234567890",
      "userId": "usr_1234567890",
      "userEmail": "user@example.com",
      "userDisplayName": "John Doe",
      "plan": "pro",
      "billingCycle": "monthly",
      "amount": 299,
      "currency": "MAD",
      "status": "pending",
      "paymentMethod": "bank_transfer",
      "paymentReference": "REF123456789",
      "senderName": "John Doe",
      "notes": "Bank transfer completed",
      "submittedAt": "2026-04-08T18:30:00Z"
    }
  ],
  "total": 23,
  "page": 1,
  "size": 20,
  "pages": 2
}

4. Admin: Review Billing Request

Admin Only - Approve or reject a billing request.

Endpoint: PATCH /api/v1/billing/admin/requests/{requestId}

Headers:

Authorization: Bearer <admin_token>
Content-Type: application/json

Request Body:

{
  "status": "approved",
  "notes": "Payment verified. Bank transfer confirmed."
}

Response: 200 OK

{
  "item": {
    "id": "req_1234567890",
    "status": "approved",
    "reviewedAt": "2026-04-08T20:00:00Z",
    "reviewedBy": "admin_001",
    "reviewNotes": "Payment verified. Bank transfer confirmed."
  }
}

Rate Limiting

To ensure fair usage and system stability, API requests are rate-limited.

Limits

Plan Requests per Minute Requests per Hour
Trial 30 500
Starter 60 1,000
Pro 120 5,000
Enterprise 300 20,000

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1712598000

Exceeding Limits

When rate limit is exceeded:

Response: 429 Too Many Requests

{
  "detail": "Rate limit exceeded. Please try again later.",
  "status": 429,
  "retryAfter": 60
}

Webhooks

Configure webhooks to receive real-time notifications about events in your stores.

Supported Events

  • order.created: New order placed
  • order.updated: Order status changed
  • order.cancelled: Order cancelled
  • product.created: New product added
  • product.updated: Product updated
  • product.deleted: Product deleted
  • subscription.updated: Subscription changed
  • payment.succeeded: Payment successful
  • payment.failed: Payment failed

Webhook Payload

{
  "event": "order.created",
  "timestamp": "2026-04-08T20:30:00Z",
  "data": {
    "id": "order_1234567890",
    "orderNumber": "ORD-2026-001234",
    "storeId": "store_1234567890",
    "total": 1349.00,
    "status": "pending"
  }
}

Webhook Security

  • Verify webhook signatures using HMAC-SHA256
  • Signature included in X-Webhook-Signature header
  • Use your webhook secret to verify authenticity

Best Practices

1. Authentication

  • Store JWT tokens securely
  • Implement token refresh logic
  • Never expose tokens in URLs or logs
  • Use HTTPS for all API calls

2. Error Handling

  • Always check HTTP status codes
  • Parse error responses for detailed messages
  • Implement retry logic with exponential backoff
  • Log errors for debugging

3. Pagination

  • Use pagination for large datasets
  • Start with reasonable page sizes (20-50 items)
  • Cache results when appropriate
  • Implement infinite scroll or pagination UI

4. Performance

  • Use query parameters to filter data
  • Request only needed fields
  • Implement caching strategies
  • Batch operations when possible

5. Idempotency

  • Use idempotency keys for critical operations
  • Handle duplicate requests gracefully
  • Implement proper error recovery

6. Testing

  • Use sandbox/test environment
  • Test error scenarios
  • Validate webhook handling
  • Test rate limiting behavior

Support & Resources

API Support

Developer Resources

  • API Changelog: Track API updates and changes
  • SDKs: Official SDKs for popular languages (coming soon)
  • Postman Collection: Import ready-to-use API collection
  • Code Examples: Sample implementations in various languages

Community

  • Developer Forum: Connect with other developers
  • GitHub: Report issues and contribute
  • Discord: Real-time chat with the community

Changelog

Version 1.0.0 (April 2026)

  • Initial API release
  • Authentication endpoints
  • Store management
  • Product management
  • Order management
  • Customer management
  • Store configuration
  • Billing & subscriptions
  • PayZone payment integration
  • Dashboard & analytics
  • Admin endpoints
  • Webhook support

SKALIA API Documentation v1.0
© 2026 Skalia Inc. All rights reserved.

For the latest updates, visit: https://docs.skalia.ma