PleasureStock API v1.0 Documentation - AI Optimized

👤 Interactive Version for Humans With tabs, code playground and copy buttons

Base URL for API calls: https://pleasurestock.com/api/v1
⚠️ Note: This is not a web page URL - use it in your code for API requests
Format: JSON
Rate Limits: Standard API: 1000/hour, External API: 5000/hour, Smart Reordering: 100/hour
Authentication: API Key required (Bearer token for External API)

Authentication

All API requests require authentication using an API key. Get your key from Settings → API Keys in the PleasureStock dashboard.

Standard API Authentication

X-API-Key: pk_live_your_api_key_here

External API Authentication

Authorization: Bearer pk_live_your_api_key_here

Standard API Endpoints

GET /api/v1/products

Retrieve product catalog with pagination and filtering.

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (max: 1000, default: 100)
supplier_id	integer	No	Filter by supplier ID

Response Example:

{
  "success": true,
  "data": [
    {
      "internal_id": "pl_1234567890",
      "name": "Premium Widget",
      "sku": "WDG-001",
      "price": "29.99",
      "currency": "EUR",
      "supplier_id": 12,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-20T14:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1250,
    "pages": 13
  }
}

POST /api/v1/sales

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

✨ Updated 2025-11-03: Now supports both UUID and ps_id formats!

Request Body:

{
  "sales": [
    {
      "internal_id": "ps_uypjz2vraa",  // Format: UUID or ps_id (ps_XXXXXXXXXX)
      "date": "2025-11-03",            // Format: YYYY-MM-DD
      "quantity": 15,                  // Non-negative integer
      "stock_on_hand": 120             // Optional, non-negative integer
    },
    {
      "internal_id": "b421eb2c-e1ee-4537-9c19-056d63a337c4",  // UUID format also supported
      "date": "2025-11-03",
      "quantity": 8,
      "stock_on_hand": 45
    }
  ]
}

Field Formats:

Field	Type	Required	Format
internal_id	string	✅ Yes	UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) OR ps_id (ps_XXXXXXXXXX)
date	string	✅ Yes	YYYY-MM-DD
quantity	integer	✅ Yes	≥ 0
stock_on_hand	integer	❌ No	≥ 0

Success Response:

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

Error Response:

{
  "error": "Validation errors",
  "errors": [
    {
      "index": 0,
      "error": "Invalid internal_id format",
      "expected": "UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) or ps_id (ps_XXXXXXXXXX)",
      "received": "invalid_id_123"
    }
  ],
  "processed": 0
}

How to Find internal_id:

What Happens After:

Data stored in PleasureStock
AI calculates Smart Reordering recommendations (daily)
View at: Cart → Smart Reordering tab
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

🌍 Idempotency (World-Class Best Practice):
You can safely send the same data multiple times - the system automatically deduplicates by date.
Example: If you send data for 2025-11-03 twice, the system will aggregate:

quantity → SUM (total sales for the day)
stock_on_hand → MAX (highest stock level = total across warehouses)

This design follows Amazon MWS and Shopify API patterns.

Multiple Warehouses Support:

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

{
  "sales": [
    {
      "internal_id": "ps_abc123",
      "date": "2025-11-03",
      "quantity": 10,          // Warehouse A sales
      "stock_on_hand": 500     // Warehouse A stock
    },
    {
      "internal_id": "ps_abc123",  // 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": [{
    "internal_id": "ps_abc123",
    "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:

Parameter	Type	Required	Description
date	string	No	Target date for predictions (default: today)

Response Example:

{
  "success": true,
  "date": "2024-03-20",
  "recommendations": [
    {
      "product_internal_id": "pl_1234567890",
      "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:

Parameter	Type	Required	Description
amount	number	Yes	Amount to convert
currency	string	Yes	Source currency (EUR, USD, GBP)

Response Example:

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

External B2B Integration API

External API endpoints use Bearer token authentication and are designed for B2B partner integration.

Base URL: https://pleasurestock.com/api/v1/external
Authentication: Bearer token required
Rate Limit: 5000 requests/hour per API key

POST /api/v1/external/smart-reorder

Submit comprehensive sales data for AI-powered reordering recommendations.

Request Body:

{
  "products": [
    {
      "ps_id": "ps_1234567890",      // Must start with "ps_"
      "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:

ps_id must start with "ps_" prefix
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": [
    {
      "ps_id": "ps_1234567890",    // Product ID (ps_ format)
      "quantity": 10,
      "customPrice": 25.50          // Optional: override product price
    },
    {
      "ps_id": "ps_0987654321",    // Another product (different supplier)
      "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
  }
}

Important: Items are automatically grouped by supplier. One API call may create multiple orders.

GET /api/v1/external/orders

Retrieve orders for your company with optional filtering.

Query Parameters:

Parameter	Type	Required	Description
status	string	No	Filter by status (created, part_paid, paid, on_the_way, accepted)
limit	integer	No	Results per page (default: 20)
offset	integer	No	Skip records (default: 0)

Response Example:

{
  "success": true,
  "data": {
    "orders": [
      {
        "orderId": 1234,
        "orderNumber": "ORD-2024-001234",
        "externalOrderId": "EXT-123456",
        "status": "paid",
        "supplierName": "TechSupplier Co.",
        "totalAmount": 1549.99,
        "currency": "EUR",
        "itemsCount": 12,
        "createdAt": "2024-03-15T10:00:00Z",
        "statusChangedAt": "2024-03-16T14:30:00Z"
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0
    }
  }
}

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

Get detailed information about a specific order.

Response Example:

{
  "success": true,
  "data": {
    "orderId": 1234,
    "orderNumber": "ORD-2024-001234",
    "externalOrderId": "EXT-123456",
    "status": "paid",
    "supplier": {
      "id": 12,
      "name": "TechSupplier Co."
    },
    "items": [
      {
        "productId": 567,
        "psId": "ps_1234567890",
        "name": "Premium Widget",
        "sku": "WDG-001",
        "quantity": 5,
        "unitPrice": 29.99,
        "totalPrice": 149.95,
        "currency": "EUR",
        "imageUrl": "https://pleasurestock.com/uploads/products/wdg001.jpg"
      }
    ],
    "totalAmount": 1549.99,
    "currency": "EUR",
    "estimatedDeliveryDate": "2024-03-25T00:00:00Z",
    "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:

Workflow: created → part_paid → paid → on_the_way → accepted

Status	Set By	Description	Notifications
`created`	System	Order created, awaiting payment	None
`part_paid`	External API	Partial payment received	Email to supplier
`paid`	External API	Full payment confirmed	Email to supplier
`on_the_way`	External API	Shipment dispatched	Email to buyer
`accepted`	External API	Goods received by buyer	Email to supplier

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:

Event	Trigger	Description
`order.created`	New order via API	Full order details with items
`order.status_changed`	Status update	Old/new status with timestamp
`order.cancelled`	Order cancelled	Cancellation details and reason

Webhook Security:

All webhook requests include HMAC-SHA256 signature for verification:

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

Webhook Payload Examples:

order.created Event:

{
  "event": "order.created",
  "timestamp": "2025-01-14T10:00:00Z",
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-000123",
    "deliveryId": "PS-2025-0114",
    "status": "created",
    "supplierId": "550e8400-e29b-41d4-a716-446655440001",
    "totalAmount": 255.00,
    "currency": "USD",
    "items": [
      {
        "ps_id": "ps_1234567890",
        "quantity": 10,
        "unitPrice": 25.50,
        "totalPrice": 255.00
      }
    ],
    "externalOrderId": "ERP-2025-001",
    "createdAt": "2025-01-14T10:00:00Z"
  }
}

order.status_changed Event:

{
  "event": "order.status_changed",
  "timestamp": "2025-01-14T11:00:00Z",
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-000123",
    "oldStatus": "created",
    "newStatus": "paid",
    "changedBy": "external_api",
    "comment": "Payment confirmed via bank transfer",
    "changedAt": "2025-01-14T11:00:00Z"
  }
}

Webhook Retry Mechanism:

Automatic Retries: Failed webhook deliveries are retried with exponential backoff:
• 1st retry: After 2 seconds
• 2nd retry: After 4 seconds
• 3rd retry: After 8 seconds
• Timeout: 10 seconds per request
• Failed webhooks are queued for manual retry

Error Handling

All API endpoints return consistent error responses with appropriate HTTP status codes.

Error Response Format:

{
  "success": false,
  "error": "Invalid request",
  "message": "The request payload is invalid",
  "details": ["Missing required field: internal_id"]
}

HTTP Status Codes:

Code	Description	Common Causes
200	Success	Request processed successfully
400	Bad Request	Invalid parameters, validation errors
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions (not a manager role)
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Code Examples

cURL - Get Products

curl -X GET "https://pleasurestock.com/api/v1/products?limit=10" \
  -H "X-API-Key: pk_live_your_api_key_here"

Python - Create Order via External API

import requests
import hashlib
import hmac

class PleasureStockAPI:
    def __init__(self, api_key, webhook_secret=None):
        self.api_key = api_key
        self.webhook_secret = webhook_secret
        self.base_url = "https://pleasurestock.com/api/v1"
    
    def create_order(self, items, external_order_id=None, comment=None):
        """Create a new order in PleasureStock"""
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
        
        payload = {
            "items": items,
            "externalOrderId": external_order_id,
            "comment": comment
        }
        
        response = requests.post(
            f"{self.base_url}/external/orders",
            json=payload,
            headers=headers
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"API Error: {response.text}")
    
    def update_order_status(self, order_number, status, comment=None):
        """Update order status"""
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
        
        payload = {"status": status}
        if comment:
            payload["comment"] = comment
        
        response = requests.put(
            f"{self.base_url}/external/orders/{order_number}/status",
            json=payload,
            headers=headers
        )
        
        return response.json()
    
    def verify_webhook(self, signature, timestamp, body):
        """Verify webhook signature"""
        if not self.webhook_secret:
            return False
        
        message = f"{timestamp}.{body}"
        expected = hmac.new(
            self.webhook_secret.encode(),
            message.encode(),
            hashlib.sha256
        ).hexdigest()
        
        return f"sha256={expected}" == signature

# Example usage
api = PleasureStockAPI("pk_live_your_api_key_here")

# Create order
order = api.create_order(
    items=[
        {"ps_id": "ps_1234567890", "quantity": 10, "customPrice": 25.50},
        {"ps_id": "ps_0987654321", "quantity": 5}
    ],
    external_order_id="ERP-2025-001",
    comment="Urgent order"
)

print(f"Created {order['data']['totalOrders']} orders")
for o in order['data']['orders']:
    print(f"  - {o['orderNumber']}: ${o['totalAmount']}")

# Update status to paid
api.update_order_status(
    order['data']['orders'][0]['orderNumber'],
    "paid",
    "Payment confirmed"
)

Node.js - External API Integration

const axios = require('axios');

class PleasureStockAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://pleasurestock.com/api/v1';
  }

  async getOrders(status = null) {
    try {
      const params = status ? { status } : {};
      
      const response = await axios.get(
        `${this.baseURL}/external/orders`,
        {
          headers: {
            'Authorization': `Bearer ${this.apiKey}`
          },
          params
        }
      );
      
      return response.data;
    } catch (error) {
      console.error('API Error:', error.response?.data || error.message);
      throw error;
    }
  }

  async createOrder(items, externalOrderId = null, comment = null) {
    try {
      const payload = { items };
      if (externalOrderId) payload.externalOrderId = externalOrderId;
      if (comment) payload.comment = comment;
      
      const response = await axios.post(
        `${this.baseURL}/external/orders`,
        payload,
        {
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json'
          }
        }
      );
      
      return response.data;
    } catch (error) {
      console.error('API Error:', error.response?.data || error.message);
      throw error;
    }
  }

  async updateOrderStatus(orderNumber, status, comment = '') {
    try {
      const response = await axios.put(
        `${this.baseURL}/external/orders/${orderNumber}/status`,
        { status, comment },
        {
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json'
          }
        }
      );
      
      return response.data;
    } catch (error) {
      console.error('API Error:', error.response?.data || error.message);
      throw error;
    }
  }

  async submitSmartReorder(products) {
    try {
      const response = await axios.post(
        `${this.baseURL}/external/smart-reorder`,
        { products },
        {
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json'
          }
        }
      );
      
      return response.data;
    } catch (error) {
      console.error('API Error:', error.response?.data || error.message);
      throw error;
    }
  }
}

// Usage examples
const api = new PleasureStockAPI('pk_live_your_api_key_here');

// Create new order
const items = [
  { ps_id: 'ps_1234567890', quantity: 10, customPrice: 25.50 },
  { ps_id: 'ps_0987654321', quantity: 5 }
];

api.createOrder(items, 'ERP-2025-001', 'Urgent order')
  .then(result => {
    console.log(`Created ${result.data.totalOrders} orders`);
    result.data.orders.forEach(order => {
      console.log(`  - ${order.orderNumber}: $${order.totalAmount}`);
    });
  });

// Get pending orders
api.getOrders('created')
  .then(orders => {
    console.log(`Found ${orders.data.orders.length} created orders`);
  });

// Update order status to paid
api.updateOrderStatus('ORD-2025-000123', 'paid', 'Payment confirmed')
  .then(result => {
    console.log('Order updated:', result);
  });

// Submit smart reorder data
const products = [
  {
    ps_id: 'ps_1234567890',
    quantity: 15,
    current_stock: 85,
    sales_history: [5, 8, 12, 6, 9, 11, 7]
  }
];

api.submitSmartReorder(products)
  .then(result => {
    console.log('Smart reorder created:', result);
  });

Integration Best Practices

Security: Never expose your API key in client-side code or public repositories. Keep it secure on your server.

Rate Limiting: Respect rate limits. Implement exponential backoff for retries. Headers X-RateLimit-Limit and X-RateLimit-Remaining are included in responses.

Order Creation: Items are automatically grouped by supplier. One API call may create multiple orders if items belong to different suppliers.

Webhook Processing: Always verify webhook signatures using HMAC-SHA256. Respond with 200 OK immediately and process asynchronously.

Status Updates: Only external API can set statuses part_paid, paid, on_the_way, and accepted. The system automatically sets created status.

Retry Mechanism: Implement retry logic with exponential backoff for failed requests. The system retries webhooks 3 times automatically.

Testing

Use the test script to verify your integration:

cd /root/b2b-supplier-system/backend
./test-external-api.sh

Replace YOUR_API_KEY_HERE in the script with your actual API key.

Support

Email: support@pleasurestock.com
API Documentation: https://pleasurestock.com/api-docs
Interactive API Playground: https://pleasurestock.com/api-docs#playground
GitHub Issues: https://github.com/pleasurestock/api-integration