Supplier API Guide: Processing Manual Orders

Prerequisites

Before you begin, make sure you have:

• A supplier account with API access
• Your API key (you can generate it from your supplier dashboard)
• Access to the Admin API v2 endpoints

Step 1: Get Your API Key

1. Log in to your supplier dashboard
2. Navigate to API Settings (/api-settings)
3. Click "Generate API Key" if you don't have one
4. Copy your API key and keep it secure

Important: Your API key should be kept secret. Never share it publicly or commit it to version control.

Step 2: Get Manual Orders

Use the GET /api/admin/v2/orders endpoint to fetch pending and processing manual orders.

API Request

curl -X GET "https://your-domain.com/api/admin/v2/orders?status=pending,processing&productType=manual&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

Request Parameters

• status (optional): Order status filter. Supports comma-separated values: pending,processing
• productType (required for manual orders): Set to manual
• entityType (optional): Filter by product or smm_service
• subCategory (optional): Filter by subcategory name
• limit (optional): Number of orders to return (max 500, default 50)
• offset (optional): Pagination offset (default 0)

Example Response

{
  "orders": [
    {
      "id": 12345,
      "order": 12345,
      "status": "pending",
      "paymentStatus": "completed",
      "quantity": 10,
      "user": {
        "id": "507f1f77bcf86cd799439011",
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "items": [
        {
          "product": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Instagram Followers",
            "type": "product"
          },
          "quantity": 10,
          "unitPrice": 5.00,
          "totalPrice": 50.00
        }
      ],
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "total": 1
}

Important Notes

• Only orders with paymentStatus: "completed" are returned
• Orders are filtered to prevent duplicate processing (30-minute interval)
• You can only see orders for products/services that belong to you as a supplier

Step 3: Process Orders and Submit Accounts

Once you have the orders, process them and prepare the account credentials. Then use the POST /api/admin/v2/orders-update endpoint to submit accounts and update order status.

API Request

curl -X POST "https://your-domain.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "username1:password1",
      "username2:password2",
      "username3:password3"
    ],
    "supplierOrderId": "SUP-ORDER-12345"
  }'

Request Body Parameters

• order (required): The order ID (number)
• status (optional): New order status. Valid values: pending, processing, completed, partial, cancelled, error
• accounts (optional, for product orders): Array of account credentials in format "username:password" or "email:password"
• supplierOrderId (optional): Your internal order ID for tracking

Account Format

For product orders, accounts should be provided as an array of strings. Each string represents one account:

• Format: "username:password" or "email:password"
• Example: ["user1:pass123", "user2:pass456"]
• Quantity: Provide accounts matching the order quantity

Complete Workflow Example

Here's a complete example using JavaScript/Node.js:

const axios = require('axios');

const API_BASE_URL = 'https://your-domain.com/api/admin/v2';
const API_KEY = 'YOUR_API_KEY';

// Step 1: Get pending and processing manual orders
async function getOrders() {
  try {
    const response = await axios.get(`${API_BASE_URL}/orders`, {
      params: {
        status: 'pending,processing',
        productType: 'manual',
        limit: 50,
        offset: 0
      },
      headers: {
        'X-Api-Key': API_KEY
      }
    });
    
    return response.data.orders;
  } catch (error) {
    console.error('Error fetching orders:', error.response?.data || error.message);
    throw error;
  }
}

// Step 2: Process order and submit accounts
async function updateOrder(orderId, accounts, supplierOrderId) {
  try {
    const response = await axios.post(
      `${API_BASE_URL}/orders-update`,
      {
        order: orderId,
        status: 'completed',
        accounts: accounts,
        supplierOrderId: supplierOrderId
      },
      {
        headers: {
          'X-Api-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error updating order:', error.response?.data || error.message);
    throw error;
  }
}

// Main workflow
async function processOrders() {
  try {
    // Get orders
    const orders = await getOrders();
    console.log(`Found ${orders.length} orders to process`);
    
    // Process each order
    for (const order of orders) {
      console.log(`Processing order ${order.id}...`);
      
      // Prepare accounts (this is where you would fetch from your system)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... more accounts matching order.quantity
      ];
      
      // Update order with accounts and mark as completed
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Order ${order.id} completed successfully`);
    }
  } catch (error) {
    console.error('Error in workflow:', error);
  }
}

// Run the workflow
processOrders();

Error Handling

Common Errors

1. Invalid API Key

   {
         "error": "INVALID_API_KEY",
         "message": "Invalid API key"
       }

   Solution: Check that your API key is correct and active.

2. Order Not Found

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Order not found"
       }

   Solution: Verify the order ID exists and belongs to you.

3. Access Denied

   {
         "error": "ACCESS_DENIED",
         "message": "You do not have access to this order"
       }

   Solution: Ensure the order contains products/services that belong to you.

4. Invalid Accounts

   {
         "error": "INVALID_ACCOUNTS",
         "message": "No valid accounts provided after deduplication"
       }

   Solution: Ensure accounts array is not empty and contains valid strings.

Best Practices

1. Polling Frequency: Don't poll too frequently. The API prevents duplicate processing with a 30-minute interval.
2. Error Handling: Always implement proper error handling and retry logic.
3. Account Validation: Validate accounts before submitting to ensure they're in the correct format.
4. Order Tracking: Use supplierOrderId to track orders in your system.
5. Status Updates: You can update status incrementally:
   • First set to processing when you start working on it
   • Then set to completed when accounts are ready
6. Partial Orders: If you can only fulfill part of an order, set status to partial and submit available accounts.

Summary

The complete workflow is:

1. Get Orders: GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. Process Orders: Prepare accounts for each order
3. Submit Accounts: POST /api/admin/v2/orders-update with accounts and status: "completed"

This simple three-step process allows you to fully automate your order fulfillment workflow!

Both are core supplier documentation guides. Linking them helps suppliers navigate from product setup to order processing, creating a logical workflow. product management guide.