Creating Orders via API

Create orders by sending a POST request to the orders endpoint.

Endpoint

POST /api/v1/orders

Request Body

Send a JSON body with order details:

• customer.name (required) - Customer name
• customer.email (required) - Customer email
• items (required) - Array of line items
• orderNumber (optional) - Custom order number
• notes (optional) - Internal notes

Line Item Fields

• name (required) - Product name
• quantity (required) - Quantity ordered
• price (required) - Unit price
• sku (optional) - Product SKU

Example Request

{
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "items": [
    {
      "name": "Custom T-Shirt",
      "quantity": 2,
      "price": 25.00,
      "sku": "TSHIRT-001"
    }
  ],
  "notes": "Rush order"
}

Response

Successful creation returns:

{
  "success": true,
  "data": {
    "id": "abc123",
    "orderNumber": "ORD-001",
    "platform": "api",
    "customer": { "name": "John Doe", "email": "john@example.com" },
    "items": [...],
    "totals": { "subtotal": 50.00, "total": 50.00 },
    "stage": "stage_id",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}

Error Handling

Check the response status code:

• 201 - Order created successfully
• 400 - Invalid request body (missing fields, bad item data)
• 401 - Invalid or missing API key
• 500 - Internal server error

All errors include a machine-readable code field (e.g., VALIDATION_ERROR, UNAUTHORIZED).