PleasureStock API — AI-Optimized Documentation

GET /api/v1/products

Retrieve product catalog with pagination and filtering.

✨ Updated 2025-11-10: Now supports Category, TCC (Total Current Cost), and TSP (Total Sale Price) fields!

Query Parameters:

Response Example (Basic):

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "internal_id": "ps_vj31ucxsab",
      "name": "Premium Widget",
      "sku": "WDG-001",
      "price": "29.99",
      "currency": "USD",
      "supplier_id": "61dcd6b4-58e8-4945-85dc-b00a35db3a72",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-20T14:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1250,
    "pages": 13
  }
}

Response Example (With Category, TCC, TSP):

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "internal_id": "ps_vj31ucxsab",
      "name": "Premium Widget",
      "sku": "WDG-001",
      "price": "29.99",
      "currency": "USD",
      "supplier_id": "61dcd6b4-58e8-4945-85dc-b00a35db3a72",

      // Category fields (includeCategory=true) — single-axis taxonomy
      "category_id": "61dcd6b4-58e8-4945-85dc-b00a35db3a72",
      "category_name": "Vibrators",
      "category_name_en": "Vibrators",

      // NOTE: v1 returns category only. Product FEATURES (Rabbit, Thrusting, Realistic…) are TAGS,
      // available via External API v2: GET /api/v2/external/catalog?include=tags

      // TCC fields (includeTcc=true) — landed cost, computed in TRY
      "tcc_enabled": true,
      "tcc_coefficient": 2,
      "tcc_total_cost": 748.98,
      "tcc_currency": "TRY",

      // TSP fields (includeTsp=true) — target selling price, in TRY
      "tsp_enabled": true,
      "tsp_value": 1976.46,
      "tsp_formula": "TCC * 2.5 + 104",
      "tsp_currency": "TRY",

      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-20T14:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1250,
    "pages": 13
  }
}

🚀 Batch Query - Get Specific Products by IDs

Request specific products using the ids parameter instead of fetching all products:

GET /api/v1/products?ids=ps_vj31ucxsab,ps_w2as53xl1z,ps_j2y58ajsit&includeCategory=true&includeTcc=true&includeTsp=true

Parameters:

GET /api/v1/products/:id

Get a single product by ID (UUID or ps_* format).

URL Parameters:

Query Parameters:

Usage Examples:

GET /api/v1/products/ps_vj31ucxsab?includeCategory=true&includeTcc=true&includeTsp=true
GET /api/v1/products/db57e260-b151-4bf1-ac63-175baef9f96d?includeCategory=true&includeTcc=true&includeTsp=true

Response Example:

{
  "success": true,
  "data": {
    "id": "db57e260-b151-4bf1-ac63-175baef9f96d",
    "internal_id": "ps_vj31ucxsab",
    "sku": "SL2505044-XCM",
    "price": "8.00",
    "currency": "USD",
    "category_id": "61dcd6b4-58e8-4945-85dc-b00a35db3a72",
    "category_name": "Vibrators",
    "category_name_en": "Vibrators",
    "tcc_enabled": true,
    "tcc_coefficient": 2,
    "tcc_total_cost": 748.98,
    "tcc_currency": "TRY",
    "tsp_enabled": true,
    "tsp_value": 1976.46,
    "tsp_formula": "TCC * 2.5 + 104",
    "tsp_currency": "TRY"
  }
}

POST /api/v1/sales

Submit sales data for Smart Reordering AI predictions and inventory tracking.

✨ Updated 2025-12-08: API v2.0 - Now uses only UUID (productId) format.

Request Body:

{
  "sales": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",  // Format: UUID only
      "date": "2025-11-03",            // Format: YYYY-MM-DD
      "quantity": 15,                  // Non-negative integer
      "stock_on_hand": 120             // Optional, non-negative integer
    },
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",  // UUID format required
      "date": "2025-11-03",
      "quantity": 8,
      "stock_on_hand": 45
    }
  ]
}

Field Formats:

Success Response:

{
  "success": true,
  "message": "Sales data submitted successfully",
  "processed": 2
}

Error Response:

{
  "error": "Validation errors",
  "errors": [
    {
      "index": 0,
      "error": "Invalid productId format",
      "expected": "UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "received": "invalid_id_123"
    }
  ],
  "processed": 0
}

How to Find productId (UUID):

Login to PleasureStock → Products → Column "PleasureStock ID" shows the productId (UUID)

What Happens After:

1. Data stored in PleasureStock
2. AI calculates Smart Reordering recommendations (daily)
3. View at: Cart → Smart Reordering tab
4. See recommended quantities, stock levels, forecast accuracy

Best Practices:

• 📅 Frequency: Send daily (minimum) or every 2-4 hours (optimal)
• 📊 Historical data: Can submit 30-90 days for better AI predictions
• 📦 Batch size: Up to 1000 records per request
• 🎯 Accuracy: Always include stock_on_hand for best results

Multiple Warehouses Support:

If you have multiple warehouses, send data from each warehouse separately:

{
  "sales": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "date": "2025-11-03",
      "quantity": 10,          // Warehouse A sales
      "stock_on_hand": 500     // Warehouse A stock
    },
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",  // Same product, different warehouse
      "date": "2025-11-03",
      "quantity": 5,           // Warehouse B sales
      "stock_on_hand": 300     // Warehouse B stock
    }
  ]
}

Result: System aggregates to quantity: 15 (total sales) and stock_on_hand: 500 (max = total stock).

Out-of-Stock Days:

When product is out of stock, send stock_on_hand: 0. The AI will:

• Exclude these days from average sales calculations
• Mark them as OOS periods
• Provide more accurate forecasts

{
  "sales": [{
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "date": "2025-11-03",
    "quantity": 0,           // No sales possible
    "stock_on_hand": 0       // ⚠️ Out of stock!
  }]
}

GET /api/v1/smart-reordering

Get AI-powered inventory recommendations based on sales history.

Query Parameters:

Response Example:

{
  "success": true,
  "date": "2024-03-20",
  "recommendations": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "product_name": "Premium Widget",
      "product_sku": "WDG-001",
      "recommended_quantity": 25,
      "current_stock": 10,
      "average_daily_sales": 3.5,
      "forecast_accuracy": 0.87,
      "calculation_date": "2024-03-20T00:00:00Z"
    }
  ],
  "total": 15
}

GET /api/v1/currency/convert-to-try

Convert amounts to Turkish Lira using real-time exchange rates.

Query Parameters:

Response Example:

{
  "success": true,
  "originalAmount": 100,
  "originalCurrency": "EUR",
  "convertedAmount": 3487.50,
  "targetCurrency": "TRY",
  "exchangeRate": 34.875,
  "lastUpdated": "2024-03-20T12:00:00Z"
}

POST /api/v1/external/smart-reorder

Submit comprehensive sales data for AI-powered reordering recommendations.

Request Body:

{
  "products": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440001",      // UUID format
      "quantity": 15,                 // Non-negative number
      "current_stock": 85,            // Non-negative number
      "sales_history": [5, 8, 12, 6, 9, 11, 7]  // Min 7 days of data
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "smartReorderId": 123,
    "lastUpdated": "2024-03-20T15:30:00Z",
    "isActive": true
  }
}

Validation Rules:

• quantity must be non-negative number
• current_stock must be non-negative number
• sales_history must contain at least 7 days of numeric data

POST /api/v1/external/orders

Create new orders in PleasureStock system. Items are automatically grouped by supplier.

Request Body:

{
  "items": [
    {
      "productId": "550e8400-e29b-41d4-a716-446655440001",    // Product ID (UUID format)
      "quantity": 10,
      "customPrice": 25.50          // Optional: override product price
    },
    {
      "productId": "550e8400-e29b-41d4-a716-446655440001",    // Another product
      "quantity": 5
    }
  ],
  "externalOrderId": "ERP-2025-001",  // Optional: your reference ID
  "comment": "Urgent order"           // Optional: order comment
}

Response Example:

{
  "success": true,
  "data": {
    "orders": [
      {
        "orderNumber": "ORD-2025-000123",
        "deliveryId": "PS-2025-0114",
        "supplierId": 12,
        "status": "created",
        "totalAmount": 255.00,
        "currency": "USD",
        "items": 1,
        "createdAt": "2025-01-14T10:00:00Z"
      },
      {
        "orderNumber": "ORD-2025-000124",
        "deliveryId": "PS-2025-0115",
        "supplierId": 15,
        "status": "created",
        "totalAmount": 125.00,
        "currency": "USD",
        "items": 1,
        "createdAt": "2025-01-14T10:00:00Z"
      }
    ],
    "totalOrders": 2,
    "totalAmount": 380.00
  }
}

GET /api/v1/external/orders

Retrieve orders for your company with optional filtering.

Query Parameters:

Response Example:

{
  "success": true,
  "data": {
    "orders": [
      {
        "orderId": "a9e312b9-d5bb-4961-8db6-7ea1007e672b",
        "orderNumber": "ORD-20251103-78XZ70",
        "deliveryId": "PS-2025-1103/2",
        "status": "created",
        "statusDisplay": {
          "label": "Created",
          "color": "blue",
          "cssClass": "bg-blue-100 text-blue-800"
        },
        "supplier": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Example Supplier" },
        "items": [
          {
            "isCustom": false,
            "productId": "b421eb2c-e1ee-4537-9c19-056d63a337c4",
            "sku": "VIB-001",
            "name": "Premium Silicone Vibrator",
            "imageUrl": "https://pleasurestock.com/uploads/products/vib001.jpg",
            "quantity": 5,
            "unitPrice": "29.99",
            "totalPrice": "149.95",
            "currency": "USD"
          }
        ],
        "totalAmount": "5669.57",
        "currency": "USD",
        "shippingMethod": "sea",
        "estimatedArrivalDate": null,
        "estimatedArrivalBasis": null,
        "estimatedDeliveryDate": null,
        "createdAt": "03/11/25"
      },
      {
        "orderId": "c7f45a1e-2b8d-4e6f-9a3c-1d5e8f012ab3",
        "orderNumber": "ORD-20251108-91QW42",
        "deliveryId": "PS-2025-1108/1",
        "status": "on_the_way",
        "statusDisplay": {
          "label": "On the way",
          "color": "purple",
          "cssClass": "bg-purple-100 text-purple-800"
        },
        "supplier": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Example Supplier" },
        "items": [
          {
            "isCustom": false,
            "productId": "b421eb2c-e1ee-4537-9c19-056d63a337c4",
            "sku": "VIB-001",
            "name": "Premium Silicone Vibrator",
            "imageUrl": "https://pleasurestock.com/uploads/products/vib001.jpg",
            "quantity": 5,
            "unitPrice": "29.99",
            "totalPrice": "149.95",
            "currency": "USD"
          }
        ],
        "totalAmount": "5669.57",
        "currency": "USD",
        "shippingMethod": "air",
        "estimatedArrivalDate": "2025-12-16",
        "estimatedArrivalBasis": "shipped",
        "estimatedDeliveryDate": "2025-12-16",
        "createdAt": "08/11/25"
      }
    ],
    "pagination": {
      "total": 8,
      "limit": 20,
      "offset": 0
    }
  }
}

GET /api/v1/external/orders/{orderNumber}

Get detailed information about a specific order.

Response Example:

{
  "success": true,
  "data": {
    "orderId": "a9e312b9-d5bb-4961-8db6-7ea1007e672b",
    "orderNumber": "ORD-20251103-78XZ70",
    "deliveryId": "PS-2025-1103/2",
    "externalOrderId": null,
    "status": "created",
    "statusDisplay": {
      "label": "Created",
      "color": "blue",
      "cssClass": "bg-blue-100 text-blue-800"
    },
    "supplier": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Example Supplier"
    },
    "hasCustomItems": true,
    "items": [
      {
        "isCustom": false,
        "productId": "b421eb2c-e1ee-4537-9c19-056d63a337c4",
        "sku": "WDG-001",
        "name": "Premium Widget",
        "imageUrl": "https://pleasurestock.com/uploads/products/wdg001.jpg",
        "quantity": 5,
        "unitPrice": 29.99,
        "totalPrice": 149.95,
        "currency": "EUR",
        "product": { "name": "Premium Widget", "sku": "WDG-001", "imageUrl": "https://pleasurestock.com/uploads/products/wdg001.jpg" }
      },
      {
        "isCustom": true,
        "productId": null,
        "customSku": "CUSTOM-7788",
        "customName": "OEM packaging insert (client artwork)",
        "customCategory": "Packaging",
        "customDescription": "Printed insert, 90x50mm, matte",
        "imageUrl": null,
        "quantity": 2000,
        "unitPrice": 0.12,
        "totalPrice": 240.00,
        "currency": "EUR"
      }
    ],
    "totalAmount": 1549.99,
    "currency": "EUR",
    "shippingMethod": "sea",
    "estimatedArrivalDate": "2024-06-28",
    "estimatedArrivalBasis": "first_payment",
    "estimatedDeliveryDate": "2024-06-28",
    "actualDeliveryDate": null,
    "createdAt": "2024-03-15T10:00:00Z",
    "confirmedAt": "2024-03-15T10:15:00Z",
    "paidAt": "2024-03-16T14:30:00Z",
    "shippedAt": null,
    "acceptedAt": null
  }
}

PUT /api/v1/external/orders/{orderNumber}/status

Update order status in the workflow.

Request Body:

{
  "status": "paid",                     // Required: paid, on_the_way, accepted
  "externalOrderId": "EXT-123456",      // Optional: your reference
  "comment": "Payment confirmed"        // Optional: status comment
}

Order Status Lifecycle:

📋 Best Practices for Working with Order Statuses

Using statusDisplay Field

The API returns a statusDisplay object with formatted status information:

{
  "status": "cancelled",
  "statusDisplay": {
    "label": "Cancelled",
    "color": "red",
    "cssClass": "bg-red-100 text-red-800"
  }
}

This field is useful for displaying order status in your UI with appropriate styling. The cssClass uses Tailwind CSS classes.

Response:

{
  "success": true,
  "data": {
    "orderId": 1234,
    "orderNumber": "ORD-2024-001234",
    "status": "paid",
    "statusChangedAt": "2024-03-20T15:45:00Z"
  }
}

POST /api/v1/external/webhook

Endpoint for receiving webhook notifications about order events.

Webhook Events:

PleasureStock emits one outbound event, order.updated, carrying the full current state of the order — so a single handler covers creation, payment, shipping and cancellation.

Webhook Security:

All webhook requests include HMAC-SHA256 signature for verification:

Headers:
X-Webhook-Signature: sha256=4f8b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
X-Webhook-Timestamp: 1736850600

Webhook Payload Examples:

{
  "event": "order.updated",
  "timestamp": "2025-01-14T10:00:00Z",
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-000123",
    "deliveryId": "PS-2025-0114",
    "externalOrderId": "ERP-2025-001",
    "status": "on_the_way",
    "shippingMethod": "sea",
    "trackingNumber": "TRK-998877",
    "supplier": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Example Supplier" },
    "items": [
      {
        "isCustom": false,
        "productId": "b421eb2c-e1ee-4537-9c19-056d63a337c4",
        "sku": "VIB-001",
        "name": "Premium Silicone Vibrator",
        "imageUrl": "https://pleasurestock.com/uploads/products/vib001.jpg",
        "quantity": 10,
        "unitPrice": 25.50,
        "totalPrice": 255.00,
        "currency": "USD"
      }
    ],
    "totalAmount": 255.00,
    "currency": "USD",
    "estimatedArrivalDate": "2025-03-22",
    "estimatedArrivalBasis": "shipped",
    "estimatedDeliveryDate": "2025-03-22",
    "orderUrl": "https://pleasurestock.com/orders/550e8400-e29b-41d4-a716-446655440000",
    "paidAt": "2025-01-16T14:30:00Z",
    "onTheWayAt": "2025-01-18T09:00:00Z",
    "createdAt": "2025-01-14T10:00:00Z"
  }
}

Webhook Retry Mechanism: