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

json

{
  "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)

json

{
  "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:

json

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

json

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

json

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

Use Cases

Website Checkout: Create orders from your e-commerce website
Mobile App Orders: Submit orders from iOS/Android apps
Third-Party Integrations: Sync orders from Shopify, WooCommerce, etc.
POS Systems: Create orders from point-of-sale systems
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)

json

{
  "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)

json

{
  "_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

json

{
  "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)

json

{
  "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

json

{
  "status": "shipped"
}

Response (200 OK)

json

{
  "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)

json

[
  {
    "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

json

{
  "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)

json

{
  "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)

json

{
  "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:

json

{
  "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

Use pagination: Always implement pagination when fetching order lists to avoid performance issues.
Track order timeline: Use timeline events to maintain a complete audit trail of order progress.
Implement status updates: Regularly update order status to keep customers informed.
Monitor order metrics: Use order statistics to analyze business performance and identify trends.
Handle errors gracefully: Implement proper error handling for all API calls.
Use filtering: Leverage filtering options to efficiently find specific orders.
Export for analysis: Use the export functionality for offline analysis and reporting.

Workflow Examples

Complete Order Lifecycle

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

Create Order from External System

bash

# 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

Order Management API Documentation ​

Base URL ​

Authentication ​

Rate Limiting ​

Endpoints ​

Create Order ​

Request Body ​

Product Item Object ​

Delivery Details Object ​

Payment Info Object ​

Request Example ​

Response (201 Created) ​

Error Responses ​

Use Cases ​

Get Orders ​

Query Parameters ​

Response (200 OK) ​

Get Order by ID ​

Parameters ​

Response (200 OK) ​

Update Order ​

Parameters ​

Request ​

Response (200 OK) ​

Update Order Status ​

Parameters ​

Request ​

Response (200 OK) ​

Get Order Timeline ​

Parameters ​

Response (200 OK) ​

Add Timeline Event ​

Parameters ​

Request ​

Event Types ​

Response (201 Created) ​

Get Order Statistics ​

Query Parameters ​

Response (200 OK) ​

Export Orders ​

Query Parameters ​

Response (200 OK) ​

Data Types ​

Order Object ​

Timeline Event Object ​

Common Order Statuses ​

Error Handling ​

Common Error Codes ​

Best Practices ​

Workflow Examples ​

Complete Order Lifecycle ​

Create Order from External System ​

Timeline Management ​

Integration Notes ​

Order Management API Documentation

Base URL

Authentication

Rate Limiting

Endpoints

Create Order

Request Body

Product Item Object

Delivery Details Object

Payment Info Object

Request Example

Response (201 Created)

Error Responses

Use Cases

Get Orders

Query Parameters

Response (200 OK)

Get Order by ID

Parameters

Response (200 OK)

Update Order

Parameters

Request

Response (200 OK)

Update Order Status

Parameters

Request

Response (200 OK)

Get Order Timeline

Parameters

Response (200 OK)

Add Timeline Event

Parameters

Request

Event Types

Response (201 Created)

Get Order Statistics

Query Parameters

Response (200 OK)

Export Orders

Query Parameters

Response (200 OK)

Data Types

Order Object

Timeline Event Object

Common Order Statuses

Error Handling

Common Error Codes

Best Practices

Workflow Examples

Complete Order Lifecycle

Create Order from External System

Timeline Management

Integration Notes