Order Management API Documentation

The Order Management API provides comprehensive functionality for managing orders, tracking order status, maintaining order timelines, and generating order analytics. This API supports the complete order lifecycle from creation to completion.

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

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
email	string	Customer email
final_amount	number	Total order amount
delivery_method	string	Delivery method
payment_status	string	Payment status
delivery_details	object	Delivery information
product_items	array	List of ordered products

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: Order is created with status pending
2. Confirmation: Status updated to confirmed
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

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