Store Kit
Order

Create Order

Create a new order for a customer

Create Order

Create a new order for a customer. This endpoint allows you to place orders with customer details, shipping information, and order items.

Endpoint

POST /v1/order

Base URL: https://api.storekit.app

Authentication

Info: All API requests require authentication using an API key. Generate your API key from the StoreKit Dashboard under API Key Usage section.

Headers

NameTypeRequiredDescription
x-api-keystringYesYour API key for authentication
Content-TypestringYesMust be application/json

Request Body

The request body must contain the following order information:

Schema

FieldTypeRequiredDescription
customerEmailstringYesCustomer's email address (must be valid email)
customerNamestringYesCustomer's full name
customerPhonestringYesCustomer's phone number
shippingAddressstringYesComplete shipping address
totalnumberYesTotal amount of the order (must be positive)
itemsarrayYesArray of order items (at least one required)

Order Item Schema

Each item in the items array must contain:

FieldTypeRequiredDescription
productIdstringYesID of the product being ordered
quantitynumberYesQuantity of the product (must be positive integer)
pricenumberYesPrice per unit (must be positive)

Example Request

{
  "customerEmail": "[email protected]",
  "customerName": "Random",
  "customerPhone": "+1234567890",
  "shippingAddress": "kurnool,Andhra Pradesh",
  "total": 150.00,
  "items": [
    {
      "productId": "prod_abc123",
      "quantity": 2,
      "price": 50.00
    },
    {
      "productId": "prod_def456",
      "quantity": 1,
      "price": 50.00
    }
  ]
}

Response

Success Response (200 OK)

{
  "success": true,
  "message": "order added successfully...!!!"
}

Error Responses

401 Unauthorized - Missing API Key

{
  "error": "API key is required"
}

422 Unprocessable Entity - Validation Errors

Invalid Email:

{
  "success": false,
  "errors": {
    "issues": [
      {
        "validation": "email",
        "code": "invalid_string",
        "message": "Invalid email",
        "path": ["customerEmail"]
      }
    ],
    "name": "ZodError"
  }
}

Missing Required Fields:

{
  "success": false,
  "errors": {
    "issues": [
      {
        "code": "too_small",
        "minimum": 1,
        "type": "string",
        "inclusive": true,
        "exact": false,
        "message": "Name is required",
        "path": ["customerName"]
      },
      {
        "code": "too_small",
        "minimum": 1,
        "type": "string",
        "inclusive": true,
        "exact": false,
        "message": "Phone no is required",
        "path": ["customerPhone"]
      }
    ],
    "name": "ZodError"
  }
}

Missing Shipping Address:

{
  "success": false,
  "errors": {
    "issues": [
      {
        "code": "too_small",
        "minimum": 1,
        "type": "string",
        "inclusive": true,
        "exact": false,
        "message": "Shipping Address is required",
        "path": ["shippingAddress"]
      }
    ],
    "name": "ZodError"
  }
}

Missing Product ID:

{
  "success": false,
  "errors": {
    "issues": [
      {
        "code": "too_small",
        "minimum": 1,
        "type": "string",
        "inclusive": true,
        "exact": false,
        "message": "Product ID is required",
        "path": ["items", 0, "productId"]
      }
    ],
    "name": "ZodError"
  }
}

404 Not Found - Product Not Found

{
  "success": false,
  "message": "Some products are not available or not found",
  "unavailableProducts": ["prod_invalid123"]
}

500 Internal Server Error

{
  "success": false,
  "message": "Failed to add to order"
}

Code Examples

curl -X POST "https://api.storekit.app/v1/order" \
  -H "x-api-key: sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "[email protected]",
    "customerName": "John Doe",
    "customerPhone": "+1234567890",
    "shippingAddress": "123 Main St, City, State 12345",
    "total": 150.00,
    "items": [
      {
        "productId": "prod_abc123",
        "quantity": 2,
        "price": 50.00
      },
      {
        "productId": "prod_def456",
        "quantity": 1,
        "price": 50.00
      }
    ]
  }'
const orderData = {
  customerEmail: "[email protected]",
  customerName: "John Doe",
  customerPhone: "+1234567890",
  shippingAddress: "123 Main St, City, State 12345",
  total: 150.00,
  items: [
    {
      productId: "prod_abc123",
      quantity: 2,
      price: 50.00
    },
    {
      productId: "prod_def456",
      quantity: 1,
      price: 50.00
    }
  ]
};

const response = await fetch("https://api.storekit.app/v1/order", {
  method: "POST",
  headers: {
    "x-api-key": "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(orderData),
});

const result = await response.json();

if (result.success) {
  console.log("Order created successfully:", result.message);
} else {
  console.error("Error creating order:", result.message);
  if (result.errors) {
    console.error("Validation errors:", result.errors);
  }
  if (result.unavailableProducts) {
    console.error("Unavailable products:", result.unavailableProducts);
  }
}
import axios from "axios";

const orderData = {
  customerEmail: "[email protected]",
  customerName: "John Doe",
  customerPhone: "+1234567890",
  shippingAddress: "123 Main St, City, State 12345",
  total: 150.00,
  items: [
    {
      productId: "prod_abc123",
      quantity: 2,
      price: 50.00
    },
    {
      productId: "prod_def456",
      quantity: 1,
      price: 50.00
    }
  ]
};

try {
  const response = await axios.post("https://api.storekit.app/v1/order", orderData, {
    headers: {
      "x-api-key": "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
      "Content-Type": "application/json",
    },
  });

  const { success, message } = response.data;

  if (success) {
    console.log("Order created successfully:", message);
  } else {
    console.error("Error creating order:", message);
  }
} catch (error) {
  if (error.response) {
    const { data } = error.response;
    console.error("Error response:", data);
    
    if (data.errors) {
      console.error("Validation errors:", data.errors);
    }
    if (data.unavailableProducts) {
      console.error("Unavailable products:", data.unavailableProducts);
    }
  } else {
    console.error("Request failed:", error.message);
  }
}
const https = require("https");

const orderData = {
  customerEmail: "[email protected]",
  customerName: "John Doe",
  customerPhone: "+1234567890",
  shippingAddress: "123 Main St, City, State 12345",
  total: 150.00,
  items: [
    {
      productId: "prod_abc123",
      quantity: 2,
      price: 50.00
    },
    {
      productId: "prod_def456",
      quantity: 1,
      price: 50.00
    }
  ]
};

const postData = JSON.stringify(orderData);

const options = {
  hostname: "api.storekit.app",
  port: 443,
  path: "/v1/order",
  method: "POST",
  headers: {
    "x-api-key": "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json",
    "Content-Length": Buffer.byteLength(postData),
  },
};

const req = https.request(options, (res) => {
  let data = "";

  res.on("data", (chunk) => {
    data += chunk;
  });

  res.on("end", () => {
    const result = JSON.parse(data);

    if (result.success) {
      console.log("Order created successfully:", result.message);
    } else {
      console.error("Error creating order:", result.message);
      if (result.errors) {
        console.error("Validation errors:", result.errors);
      }
      if (result.unavailableProducts) {
        console.error("Unavailable products:", result.unavailableProducts);
      }
    }
  });
});

req.on("error", (error) => {
  console.error("Request failed:", error);
});

req.write(postData);
req.end();
import requests
import json

url = "https://api.storekit.app/v1/order"
headers = {
    "x-api-key": "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json"
}

order_data = {
    "customerEmail": "[email protected]",
    "customerName": "John Doe",
    "customerPhone": "+1234567890",
    "shippingAddress": "123 Main St, City, State 12345",
    "total": 150.00,
    "items": [
        {
            "productId": "prod_abc123",
            "quantity": 2,
            "price": 50.00
        },
        {
            "productId": "prod_def456",
            "quantity": 1,
            "price": 50.00
        }
    ]
}

try:
    response = requests.post(url, headers=headers, json=order_data)
    response.raise_for_status()

    data = response.json()

    if data.get('success'):
        print(f"Order created successfully: {data['message']}")
    else:
        print(f"Error creating order: {data.get('message', 'Unknown error')}")
        
        if 'errors' in data:
            print("Validation errors:")
            for issue in data['errors']['issues']:
                print(f"  - {issue['message']} (path: {' -> '.join(map(str, issue['path']))})")
        
        if 'unavailableProducts' in data:
            print(f"Unavailable products: {data['unavailableProducts']}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")
    if hasattr(e, 'response') and e.response is not None:
        try:
            error_data = e.response.json()
            print(f"Error response: {error_data}")
        except:
            print(f"Error response: {e.response.text}")
<?php
$orderData = [
    'customerEmail' => '[email protected]',
    'customerName' => 'John Doe',
    'customerPhone' => '+1234567890',
    'shippingAddress' => '123 Main St, City, State 12345',
    'total' => 150.00,
    'items' => [
        [
            'productId' => 'prod_abc123',
            'quantity' => 2,
            'price' => 50.00
        ],
        [
            'productId' => 'prod_def456',
            'quantity' => 1,
            'price' => 50.00
        ]
    ]
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.storekit.app/v1/order",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($orderData),
    CURLOPT_HTTPHEADER => [
        "x-api-key: sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
        "Content-Type: application/json"
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$data = json_decode($response, true);

if ($httpCode === 200 && $data['success']) {
    echo "Order created successfully: " . $data['message'] . "\n";
} else {
    echo "Error creating order: " . ($data['message'] ?? 'Unknown error') . "\n";
    
    if (isset($data['errors'])) {
        echo "Validation errors:\n";
        foreach ($data['errors']['issues'] as $issue) {
            echo "  - " . $issue['message'] . " (path: " . implode(' -> ', $issue['path']) . ")\n";
        }
    }
    
    if (isset($data['unavailableProducts'])) {
        echo "Unavailable products: " . implode(', ', $data['unavailableProducts']) . "\n";
    }
}
?>
const orderData = {
  customerEmail: "[email protected]",
  customerName: "John Doe",
  customerPhone: "+1234567890",
  shippingAddress: "123 Main St, City, State 12345",
  total: 150.00,
  items: [
    {
      productId: "prod_abc123",
      quantity: 2,
      price: 50.00
    },
    {
      productId: "prod_def456",
      quantity: 1,
      price: 50.00
    }
  ]
};

$.ajax({
  url: "https://api.storekit.app/v1/order",
  method: "POST",
  headers: {
    "x-api-key": "sk_live_be186797384f05ff038e1751e8ff9572cf8a05adfdba79abb7e8bcd165f2c402",
    "Content-Type": "application/json",
  },
  data: JSON.stringify(orderData),
  success: function (data) {
    if (data.success) {
      console.log("Order created successfully:", data.message);
      
      // Example: Show success message to user
      $("#order-form").hide();
      $("#success-message").show().text(data.message);
      
      // Example: Reset form or redirect
      // window.location.href = '/order-confirmation';
    } else {
      console.error("Error creating order:", data.message);
      
      // Handle validation errors
      if (data.errors) {
        $("#error-list").empty();
        data.errors.issues.forEach(function(issue) {
          $("#error-list").append(`<li>${issue.message}</li>`);
        });
        $("#error-container").show();
      }
      
      // Handle unavailable products
      if (data.unavailableProducts) {
        $("#unavailable-products").text(data.unavailableProducts.join(', '));
        $("#unavailable-container").show();
      }
    }
  },
  error: function (xhr, status, error) {
    console.error("Request failed:", error);
    
    try {
      const errorData = JSON.parse(xhr.responseText);
      console.error("Error response:", errorData);
    } catch (e) {
      console.error("Could not parse error response");
    }
  },
});

Authentication & Session Management

This endpoint automatically handles both authenticated and anonymous users:

  • Authenticated users: Orders are created based on their customer account
  • Anonymous users: Orders are tracked using session cookies that are automatically managed

No manual session management is required - the API handles this automatically through cookies.

Important Notes

  • Session data is automatically managed through cookies
  • API key is required for all requests and can be generated in your StoreKit Dashboard

Validation Rules

Customer Information

  • Email: Must be a valid email address format
  • Name: Required, cannot be empty
  • Phone: Required, cannot be empty
  • Shipping Address: Required, cannot be empty

Order Details

  • Total: Must be a positive number
  • Items: Must contain at least one item

Item Validation

  • Product ID: Required, cannot be empty
  • Quantity: Must be a positive integer
  • Price: Must be a positive number

Business Logic

Product Verification

The API performs the following checks before creating an order:

  1. Store Existence: Verifies that the store exists
  2. Product Availability: Checks that all products in the order exist and are available
  3. Product Status: Validates that products are active (future enhancement)

Customer Handling

The API automatically handles both authenticated and anonymous customers:

  • Authenticated users: Orders are associated with their customer account
  • Anonymous users: Orders are tracked using session cookies

Status Codes

Status CodeDescriptionResponse Example
200Success - Order created successfully{ "success": true, "message": "order added successfully...!!!" }
401Unauthorized - Missing or invalid API key{ "error": "API key is required" }
422Unprocessable Entity - Invalid input data{ "success": false, "errors": { "issues": [...], "name": "ZodError" } }
404Not Found - Product(s) not found{ "success": false, "message": "Some products are not available or not found", "unavailableProducts": [...] }
500Internal Server Error - Failed to create order{ "success": false, "message": "Failed to add to order" }

Important Notes

  • Product IDs must be valid and exist in your store
  • Session management is handled automatically through cookies
  • API key can be generated in your StoreKit Dashboard

Use Cases

  • Create orders from checkout pages
  • Process customer orders with full validation
  • Handle both guest and authenticated customer orders
  • Integrate with e-commerce platforms
  • Build custom order processing systems

Quick Start

Step 1: Get your API Key

Navigate to your StoreKit Dashboard and go to the API Key Usage section to generate your API key.

Step 2: Prepare order data

Collect customer information and order items with valid product IDs.

Step 3: Submit the order

Use any of the code examples above to create the order with proper validation.

Step 4: Handle the response

Check the success field and handle any validation errors or unavailable products appropriately.

Get Orders

Retrieve all orders for the customer

Get Cart Items

Retrieve all items from the customer's cart