Orders API Reference

Manage order creation, payment processing, and order lifecycle operations.

Base Path: /api/orders

Overview

The Orders API provides comprehensive endpoints for managing orders, including creation, payment processing, status tracking, and bulk operations. Supports order filtering, pagination, and data export.

Key Operations

API Endpoints

POST /api/orders/initiate-payment

Create Order with Payment

Creates new order with payment processing.

Authentication

Bearer Token

Request Body

{
  "customerId": "cust_123",
  "items": [
    {
      "offerId": "offer_456",
      "quantity": 1,
      "price": 99.99
    }
  ],
  "paymentMethod": "credit_card",
  "paymentGatewayId": "stripe_1"
}

Response

{
  "orderId": "ord_789",
  "status": "pending_payment",
  "totalAmount": 99.99,
  "paymentUrl": "https://payment-gateway.com/checkout",
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/orders/{id}

Get Order by ID

Gets order details by ID with items.

Authentication

Bearer Token or Service Token

Path Parameters

Parameter Type
id string

Response

{
  "id": "ord_789",
  "customerId": "cust_123",
  "status": "completed",
  "items": [
    {
      "id": "item_1",
      "offerId": "offer_456",
      "quantity": 1,
      "price": 99.99,
      "status": "fulfilled"
    }
  ],
  "totalAmount": 99.99,
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/orders/odata

List Orders (OData)

Gets orders with OData filtering and pagination.

Authentication

Bearer Token or Service Token

Query Parameters

Parameter Type Description
$filter string OData filter expression
$orderby string Sort by columns
$skip integer Skip n records
$top integer Take n records

Response

{
  "value": [
    {
      "id": "ord_789",
      "customerId": "cust_123",
      "status": "completed",
      "items": []
    }
  ],
  "count": 100
}
GET /api/orders/aggregated

Get Aggregated Metrics

Gets aggregated order metrics and statistics.

Authentication

Bearer Token

Query Parameters

Parameter Type
startDate date
endDate date
groupBy string

Response

{
  "totalOrders": 1000,
  "totalRevenue": 99999.99,
  "averageOrderValue": 99.99,
  "ordersByStatus": {
    "completed": 800,
    "pending": 150,
    "cancelled": 50
  }
}
PATCH /api/orders/{id}/status

Update Order Status

Updates order status.

Authentication

Bearer Token or Service Token

Request Body

{
  "status": "processing",
  "reason": "Payment confirmed"
}

Response

{
  "id": "ord_789",
  "status": "processing",
  "updatedAt": "2026-06-02T10:35:00Z"
}
POST /api/orders/bulk-cancel

Bulk Cancel Orders

Bulk cancels multiple orders.

Authentication

Bearer Token

Request Body

{
  "orderIds": ["ord_789", "ord_790", "ord_791"],
  "reason": "Customer request"
}

Response

{
  "cancelled": 3,
  "failed": 0,
  "results": [
    {
      "orderId": "ord_789",
      "status": "cancelled"
    }
  ]
}
POST /api/orders/cancel-items

Cancel Order Items

Cancels or verifies specific order items.

Authentication

Bearer Token

Request Body

{
  "orderId": "ord_789",
  "items": [
    {
      "itemId": "item_1",
      "action": "cancel",
      "reason": "Out of stock"
    }
  ]
}

Response

{
  "orderId": "ord_789",
  "items": [
    {
      "itemId": "item_1",
      "status": "cancelled"
    }
  ]
}
POST /api/orders/export

Export Orders

Exports orders to CSV or Excel file.

Authentication

Bearer Token

Request Body

{
  "format": "csv",
  "filters": {
    "status": "completed",
    "startDate": "2026-01-01",
    "endDate": "2026-06-02"
  },
  "columns": ["id", "customerId", "status", "totalAmount", "createdAt"]
}

Response

File download (CSV/Excel)

POST /api/orders/payment-workflow

Payment Workflow

Processes payment workflow for order.

Authentication

Bearer Token or Service Token

Request Body

{
  "orderId": "ord_789",
  "action": "process",
  "paymentDetails": {
    "method": "credit_card",
    "token": "tok_visa",
    "amount": 99.99
  }
}

Response

{
  "orderId": "ord_789",
  "paymentStatus": "completed",
  "transactionId": "txn_123456"
}

Error Responses

Code HTTP Status Description
ORDER_NOT_FOUND 404 Order does not exist
INVALID_STATUS 400 Invalid order status
PAYMENT_FAILED 402 Payment processing failed
INSUFFICIENT_INVENTORY 400 Not enough stock

Quick Links

← Back to Overview ← Accounts API Offers API → Try the Playground