Order Management API Documentation

The Order Management API provides comprehensive functionality for creating and managing orders, tracking order status, maintaining order timelines, and generating order analytics. This API supports the complete order lifecycle from creation to completion, including integration with external systems like websites, mobile apps, and third-party platforms.

Base URL

https://api.talkingshops.com/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-tenant-api-key: your_api_key_here

API keys are tenant-specific and automatically provide access to the correct order data for your business.

Rate Limiting

The API implements rate limiting to prevent abuse. By default, each tenant is limited to 100 requests per minute.

Endpoints

Create Order

POST /orders

Create a new order with customer details and product items. This endpoint allows external systems (websites, mobile apps, third-party integrations) to programmatically create orders.

Request Body

Field	Type	Required	Description
mobile	string	Yes	Customer mobile number
name	string	No	Customer name
email	string	No	Customer email
user_id	string	No	User ID for existing customers
product_items	array	Yes	List of products in the order (min: 1 item)
status	string	No	Initial order status (default: "PENDING")
final_amount	number	No	Total amount (auto-calculated if not provided)
delivery_method	string	No	Delivery method (default: "Local Delivery")
delivery_details	object	No	Delivery information
product_customizations	object	No	Product-specific customizations
payment_info	object	No	Payment information
referenceId	string	No	Custom order reference ID (auto-generated if not provided)
external_order_source	string	No	Source system (e.g., "website", "mobile_app", "shopify")
external_order_id	string	No	External system order ID
external_order_number	string	No	External system order number
notes	string	No	Order notes

Product Item Object

Field	Type	Required	Description
product_retailer_id	string	No	Product SKU/ID
name	string	Yes	Product name
quantity	number	Yes	Quantity ordered (min: 1)
price	number	Yes	Unit price (min: 0)

Delivery Details Object

Field	Type	Description
recipient_name	string	Recipient name
email	string	Delivery email
phone	string	Delivery phone number
alternate_phone	string	Alternate phone number
address	string	Delivery address
notes	string	Delivery notes
location	object	GPS coordinates (lat/lng)

Payment Info Object

Field	Type	Description
status	string	Payment status
amount	number	Payment amount
currency	string	Currency code (e.g., "INR", "USD")
payment_id	string	Payment gateway ID
method	string	Payment method

Request Example

{
  "mobile": "+919876543210",
  "name": "John Doe",
  "email": "john@example.com",
  "product_items": [
    {
      "product_retailer_id": "SKU-001",
      "name": "Premium T-Shirt",
      "quantity": 2,
      "price": 599.00
    },
    {
      "product_retailer_id": "SKU-002",
      "name": "Classic Jeans",
      "quantity": 1,
      "price": 1299.00
    }
  ],
  "delivery_method": "Local Delivery",
  "delivery_details": {
    "recipient_name": "John Doe",
    "phone": "+919876543210",
    "address": "123 Main Street, Apartment 4B, Mumbai, Maharashtra 400001"
  },
  "external_order_source": "website",
  "external_order_id": "WEB-12345",
  "notes": "Please deliver before 6 PM"
}

Response (201 Created)

{
  "success": true,
  "message": "Order created successfully",
  "order": {
    "_id": "64a1b2c3d4e5f6789abc1234",
    "referenceId": "ORD1702345678ABCD",
    "status": "PENDING",
    "mobile": "+919876543210",
    "name": "John Doe",
    "email": "john@example.com",
    "final_amount": 2497.00,
    "delivery_method": "Local Delivery",
    "product_items": [
      {
        "product_retailer_id": "SKU-001",
        "name": "Premium T-Shirt",
        "quantity": 2,
        "price": 599.00
      },
      {
        "product_retailer_id": "SKU-002",
        "name": "Classic Jeans",
        "quantity": 1,
        "price": 1299.00
      }
    ],
    "delivery_details": {
      "recipient_name": "John Doe",
      "phone": "+919876543210",
      "address": "123 Main Street, Apartment 4B, Mumbai, Maharashtra 400001"
    },
    "external_order_source": "website",
    "external_order_id": "WEB-12345",
    "created_at": "2024-12-12 15:30:00",
    "updated_at": "2024-12-12 15:30:00"
  }
}

Error Responses

400 Bad Request - Missing required fields:

{
  "error": {
    "code": "ValidationError",
    "message": "Customer mobile number is required"
  }
}

{
  "error": {
    "code": "ValidationError",
    "message": "At least one product item is required"
  }
}

{
  "error": {
    "code": "ValidationError",
    "message": "Each product item must have name, quantity, and price"
  }
}

Use Cases

1. Website Checkout: Create orders from your e-commerce website
2. Mobile App Orders: Submit orders from iOS/Android apps
3. Third-Party Integrations: Sync orders from Shopify, WooCommerce, etc.
4. POS Systems: Create orders from point-of-sale systems
5. Bulk Order Import: Programmatically create multiple orders

---

Get Orders

GET /orders

Retrieve a paginated list of orders with advanced filtering, sorting, and search capabilities.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page (1-100, default: 10)
status	string	Filter by order status
startDate	string	Filter by creation date (ISO 8601)
endDate	string	Filter by creation date (ISO 8601)
searchTerm	string	Search in order ID, customer name, or mobile
sortBy	string	Sort field (created_at, updated_at, final_amount, status, name, mobile, referenceId)
sortDirection	string	Sort direction (asc, desc)

Response (200 OK)

{
  "orders": [
    {
      "_id": "64a1b2c3d4e5f6789abc1234",
      "referenceId": "ORD-001",
      "status": "processing",
      "created_at": "2023-06-21T14:35:12Z",
      "updated_at": "2023-06-21T15:20:30Z",
      "mobile": "919876543210",
      "name": "John Doe",
      "final_amount": 1250.50,
      "delivery_method": "home_delivery",
      "product_items": [
        {
          "name": "Premium T-Shirt",
          "quantity": 2,
          "price": 500.00
        },
        {
          "name": "Jeans",
          "quantity": 1,
          "price": 750.50
        }
      ]
    }
  ],
  "total": 256,
  "totalPages": 26
}

Get Order by ID

GET /orders/{orderId}

Retrieve detailed information about a specific order.

Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Unique order ID

Response (200 OK)

{
  "_id": "64a1b2c3d4e5f6789abc1234",
  "referenceId": "ORD-001",
  "status": "processing",
  "created_at": "2023-06-21T14:35:12Z",
  "updated_at": "2023-06-21T15:20:30Z",
  "mobile": "919876543210",
  "name": "John Doe",
  "email": "john@example.com",
  "final_amount": 1250.50,
  "delivery_method": "home_delivery",
  "payment_status": "paid",
  "delivery_details": {
    "address": "123 Main St, City, State",
    "tracking_number": "TRK123456789",
    "estimated_delivery": "2023-06-25T18:00:00Z"
  },
  "product_items": [
    {
      "name": "Premium T-Shirt",
      "quantity": 2,
      "price": 500.00,
      "sku": "TSH-PREM-001"
    }
  ],
  "order_history": [
    {
      "status": "confirmed",
      "timestamp": "2023-06-21T14:35:12Z",
      "note": "Order confirmed by customer"
    }
  ]
}

Update Order

PUT /orders/{orderId}

Update order information.

Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Unique order ID

Request

{
  "updates": {
    "status": "shipped",
    "delivery_method": "express_delivery",
    "payment_status": "paid",
    "delivery_details": {
      "tracking_number": "TRK987654321",
      "estimated_delivery": "2023-06-23T18:00:00Z"
    }
  }
}

Response (200 OK)

{
  "success": true,
  "message": "Order updated successfully"
}

Update Order Status

PUT /orders/{orderId}/status

Update only the order status with automatic timeline generation.

Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Unique order ID

Request

{
  "status": "shipped"
}

Response (200 OK)

{
  "success": true,
  "message": "Order status updated to shipped"
}

Get Order Timeline

GET /orders/{orderId}/timeline

Retrieve the complete timeline of events for an order.

Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Unique order ID

Response (200 OK)

[
  {
    "id": "evt_001",
    "title": "Order Confirmed",
    "description": "Customer confirmed the order",
    "type": "success",
    "timestamp": "2023-06-21T14:35:12Z",
    "metadata": {
      "payment_method": "online",
      "amount": 1250.50
    }
  },
  {
    "id": "evt_002", 
    "title": "Payment Received",
    "description": "Payment processed successfully",
    "type": "success",
    "timestamp": "2023-06-21T14:37:45Z",
    "metadata": {
      "transaction_id": "txn_abc123"
    }
  },
  {
    "id": "evt_003",
    "title": "Order Shipped",
    "description": "Order dispatched from warehouse",
    "type": "info",
    "timestamp": "2023-06-22T10:15:30Z",
    "metadata": {
      "tracking_number": "TRK987654321"
    }
  }
]

Add Timeline Event

POST /orders/{orderId}/timeline

Add a custom event to the order timeline.

Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Unique order ID

Request

{
  "event": {
    "title": "Customer Called",
    "description": "Customer contacted regarding delivery preference",
    "type": "info",
    "metadata": {
      "agent": "John Support",
      "duration": "5 minutes"
    }
  }
}

Event Types

Type	Description	Color Indicator
success	Positive events (completion)	Green
pending	In-progress events	Yellow
error	Issues or problems	Red
info	Informational events	Blue

Response (201 Created)

{
  "success": true,
  "message": "Timeline event added successfully",
  "eventId": "evt_004"
}

Get Order Statistics

GET /orders/stats

Retrieve comprehensive order analytics and statistics.

Query Parameters

Parameter	Type	Description
period	string	Statistics period (daily, weekly, monthly)

Response (200 OK)

{
  "totalOrders": 1250,
  "revenue": 325750.50,
  "averageOrderValue": 260.60,
  "period": {
    "start": "2023-06-01T00:00:00Z",
    "end": "2023-06-30T23:59:59Z"
  }
}

Export Orders

GET /orders/export

Export orders to CSV format with optional filtering.

Query Parameters

Parameter	Type	Description
status	string	Filter by order status
startDate	string	Filter by creation date (ISO 8601)
endDate	string	Filter by creation date (ISO 8601)
searchTerm	string	Search in orders

Response (200 OK)

Returns a CSV file with the following headers:

• Order ID
• Reference ID
• Customer Name
• Mobile
• Status
• Amount
• Created Date
• Updated Date

Content-Type: text/csv
Content-Disposition: attachment; filename=orders-2023-06-21.csv

Data Types

Order Object

Field	Type	Description
_id	string	Unique order identifier
referenceId	string	Human-readable order reference
status	string	Current order status
created_at	string	Order creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)
mobile	string	Customer mobile number
name	string	Customer name
user_id	string	User ID for existing customers (optional)
email	string	Customer email
final_amount	number	Total order amount
totalPrice	number	Alternative total price field
delivery_method	string	Delivery method
payment_status	string	Payment status
external_order_number	string	External system order number
external_order_source	string	Source system (website, mobile_app, shopify, etc.)
product_items	array	List of ordered products
product_customizations	object	Product-specific customizations
delivery_details	object	Delivery information
status_history	array	Status change history
payment_info	object	Payment information
notes	string	Order notes

Order Product Item Object

Field	Type	Description
name	string	Product name
quantity	number	Quantity ordered
price	number | string	Unit price
product_retailer_id	string	Product SKU/ID

Delivery Details Object

Field	Type	Description
recipient_name	string	Recipient name
email	string	Delivery email
phone	string	Delivery phone
alternate_phone	string	Alternate phone
address	string	Delivery address
notes	string	Delivery notes
location	object	GPS coordinates

Payment Info Object

Field	Type	Description
status	string	Payment status
amount	number	Payment amount
currency	string	Currency code
payment_id	string	Payment gateway ID
method	string	Payment method
timestamp	string	Payment timestamp
reference_id	string	Payment reference

Timeline Event Object

Field	Type	Description
id	string	Unique event identifier
title	string	Event title
description	string	Event description
type	string	Event type (success, pending, error, info)
timestamp	string	Event timestamp (ISO 8601)
metadata	object	Additional event data

Common Order Statuses

Status	Description
pending	Order placed, awaiting confirmation
confirmed	Order confirmed by customer
processing	Order being prepared
shipped	Order dispatched
delivered	Order delivered to customer
completed	Order completed successfully
cancelled	Order cancelled
refunded	Order refunded

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

{
  "error": {
    "code": "ErrorType",
    "message": "Human-readable error message",
    "details": {
      // Additional error details, if applicable
    }
  }
}

Common Error Codes

Code	Status	Description
AuthenticationError	401	Invalid or missing API key
ValidationError	400	Invalid request parameters
NotFoundError	404	Order not found
InternalServerError	500	Server error

Best Practices

1. Use pagination: Always implement pagination when fetching order lists to avoid performance issues.

2. Track order timeline: Use timeline events to maintain a complete audit trail of order progress.

3. Implement status updates: Regularly update order status to keep customers informed.

4. Monitor order metrics: Use order statistics to analyze business performance and identify trends.

5. Handle errors gracefully: Implement proper error handling for all API calls.

6. Use filtering: Leverage filtering options to efficiently find specific orders.

7. Export for analysis: Use the export functionality for offline analysis and reporting.

Workflow Examples

Complete Order Lifecycle

1. Order Creation: Create order via POST /orders with status PENDING
2. Confirmation: Status updated to confirmed via PUT /orders/{id}/status
3. Processing: Status updated to processing
4. Shipping: Status updated to shipped with tracking details
5. Delivery: Status updated to delivered
6. Completion: Status updated to completed

Create Order from External System

# Example: Create order from website checkout
curl -X POST https://api.talkingshops.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "x-tenant-api-key: your_api_key_here" \
  -d '{
    "mobile": "+919876543210",
    "name": "John Doe",
    "product_items": [
      {"name": "Product A", "quantity": 1, "price": 500}
    ],
    "external_order_source": "website",
    "external_order_id": "CHECKOUT-123"
  }'

Timeline Management

• Automatically generated events for status changes
• Custom events for customer interactions
• Integration points for external systems
• Historical audit trail maintenance

Integration Notes

• Orders are linked to customers through mobile numbers
• Timeline events support rich metadata for custom integrations
• Export functionality supports business intelligence tools
• Status updates can trigger webhook notifications (if configured)
• Compatible with WhatsApp messaging API for order notifications