POST /sells
Create a new sale transaction.
Requires authentication. Automatically associates sale with authenticated user.
Request
Array of products in the sale
Variant ID (if applicable)
Response
Created sale object
Sale status (pending, confirmed, cancelled)
curl -X POST https://api.yourdomain.com/sells \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"products": [
{
"productId": "prod_123",
"quantity": 2,
"price": 1299.99
},
{
"productId": "prod_124",
"quantity": 1,
"price": 29.99,
"variantId": "var_001"
}
]
}'
{
"sell": {
"id": "sell_789",
"userId": "usr_123456",
"products": [
{
"productId": "prod_123",
"name": "Laptop Dell XPS 15",
"quantity": 2,
"price": 1299.99,
"subtotal": 2599.98
},
{
"productId": "prod_124",
"name": "Wireless Mouse",
"quantity": 1,
"price": 29.99,
"variantId": "var_001",
"subtotal": 29.99
}
],
"total": 2629.97,
"status": "pending",
"createdAt": "2026-03-07T14:30:00Z"
}
}
GET /sells
Retrieve all sales for the authenticated user.
Requires authentication. Returns sales associated with the authenticated user’s token.
Response
Total revenue from all sales
curl -X GET https://api.yourdomain.com/sells \
-H "Authorization: Bearer YOUR_TOKEN"
{
"sells": [
{
"id": "sell_789",
"products": [
{
"productId": "prod_123",
"name": "Laptop Dell XPS 15",
"quantity": 2,
"price": 1299.99,
"subtotal": 2599.98
}
],
"total": 2599.98,
"status": "confirmed",
"createdAt": "2026-03-07T14:30:00Z",
"confirmedAt": "2026-03-07T15:00:00Z"
},
{
"id": "sell_790",
"products": [
{
"productId": "prod_124",
"name": "Wireless Mouse",
"quantity": 5,
"price": 29.99,
"subtotal": 149.95
}
],
"total": 149.95,
"status": "pending",
"createdAt": "2026-03-07T16:00:00Z"
}
],
"totalSales": 2,
"totalRevenue": 2749.93
}
GET /sells/detail/:id
Get detailed information about a specific sale.
Requires authentication. Currently returns all sales (implementation note).
Path Parameters
Response
Detailed sale information
curl -X GET https://api.yourdomain.com/sells/detail/sell_789 \
-H "Authorization: Bearer YOUR_TOKEN"
{
"sell": {
"id": "sell_789",
"userId": "usr_123456",
"products": [
{
"productId": "prod_123",
"name": "Laptop Dell XPS 15",
"quantity": 2,
"price": 1299.99,
"subtotal": 2599.98,
"image": "https://cdn.example.com/laptop.jpg"
}
],
"total": 2599.98,
"status": "confirmed",
"createdAt": "2026-03-07T14:30:00Z",
"confirmedAt": "2026-03-07T15:00:00Z"
}
}
PUT /sells/confirm/:id
Confirm a pending sale.
Requires authentication. Updates sale status to ‘confirmed’ and finalizes inventory deduction.
Path Parameters
Response
curl -X PUT https://api.yourdomain.com/sells/confirm/sell_789 \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
{
"message": "Sale confirmed successfully",
"sell": {
"id": "sell_789",
"status": "confirmed",
"confirmedAt": "2026-03-07T15:00:00Z",
"products": [
{
"productId": "prod_123",
"quantity": 2,
"price": 1299.99
}
],
"total": 2599.98
}
}
PUT /sells/cancel/:id
Cancel a sale.
Requires authentication. Restores inventory and marks sale as cancelled.
Path Parameters
Response
curl -X PUT https://api.yourdomain.com/sells/cancel/sell_789 \
-H "Authorization: Bearer YOUR_TOKEN"
{
"message": "Sale cancelled successfully",
"sellId": "sell_789"
}
Sales Workflow
Common Use Cases
Complete Sale Flow
const completeSaleFlow = async (cartItems) => {
try {
// 1. Create sale
const products = cartItems.map(item => ({
productId: item.id,
quantity: item.quantity,
price: item.price,
variantId: item.variantId
}));
const sale = await createSell(products);
console.log('Sale created:', sale.id);
// 2. Process payment (external payment gateway)
const paymentSuccess = await processPayment(sale.total);
if (paymentSuccess) {
// 3. Confirm sale
const confirmed = await confirmSell(sale.id);
console.log('Sale confirmed:', confirmed.message);
return { success: true, sale: confirmed.sell };
} else {
// 4. Cancel if payment fails
await deleteSell(sale.id);
return { success: false, error: 'Payment failed' };
}
} catch (error) {
console.error('Sale flow error:', error);
return { success: false, error: error.message };
}
};
Display Sales History
const displaySalesHistory = async () => {
const salesData = await getUserSells();
console.log(`Total Sales: ${salesData.totalSales}`);
console.log(`Total Revenue: $${salesData.totalRevenue.toFixed(2)}`);
console.log('\nRecent Sales:');
salesData.sells.forEach(sale => {
console.log(`\nSale ID: ${sale.id}`);
console.log(`Status: ${sale.status}`);
console.log(`Total: $${sale.total.toFixed(2)}`);
console.log(`Date: ${new Date(sale.createdAt).toLocaleDateString()}`);
console.log('Products:');
sale.products.forEach(p => {
console.log(` - ${p.name} x${p.quantity} = $${p.subtotal.toFixed(2)}`);
});
});
};
Handle Sale Cancellation
const handleCancellation = async (sellId) => {
try {
const confirmed = window.confirm('Are you sure you want to cancel this sale?');
if (!confirmed) return;
await deleteSell(sellId);
console.log('Sale cancelled and inventory restored');
// Refresh sales list
const updatedSales = await getUserSells();
return updatedSales;
} catch (error) {
console.error('Cancellation error:', error.message);
}
};
Error Codes
| Status | Description |
|---|
200 | Success |
201 | Sale created |
400 | Invalid request data |
401 | Unauthorized |
404 | Sale not found |
409 | Insufficient stock |
500 | Server error |
Sale Status Values
| Status | Description |
|---|
pending | Sale created but not confirmed |
confirmed | Sale confirmed and inventory deducted |
cancelled | Sale cancelled and inventory restored |