Managing Orders

Overview

In the Ordermentum platform, an order represents a retailer's request to a supplier. Orders include product details, quantities, pricing, and delivery instructions. The Ordermentum API provides two endpoints to manage orders:

/v2/orders – Used for searching and retrieving a summary of orders.

/v1/orders/{id} – Used for retrieving detailed order information and making updates.

When working with these endpoints, it's essential to understand the difference between summary and detailed data, as well as how to create and modify orders effectively.

Key Differences Between v1 and v2 Endpoints

Retrieving Orders

Using the /v2/orders Endpoint for Summary Data

The /v2/orders endpoint provides a summarized view of orders, including key attributes such as order status, total cost, and timestamps. Use this endpoint when searching or filtering orders.

Example Request: Retrieve Summary Data

curl -X GET "https://api.ordermentum.com/v2/orders?supplierId=123e4567-e89b-12d3-a456-426614174000&pageSize=50&pageNo=1" \
     -H "Authorization: Bearer YOUR_API_TOKEN"
Example Response:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "status": "Placed",
      "createdAt": "2025-01-01T10:00:00Z",
      "updatedAt": "2025-01-01T12:00:00Z"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174002",
      "status": "Paid",
      "createdAt": "2025-01-02T09:00:00Z",
      "updatedAt": "2025-01-02T11:30:00Z"
    }
  ],
  "meta": {
    "totalResults": 100,
    "pageSize": 50,
    "pageNo": 1
  }
}

Filtering Orders

The v2/orders endpoint supports filtering orders based on various criteria, allowing efficient retrieval of relevant orders.

Common Filters:

Example Request: Filtering by Date Range

curl -X GET "https://api.ordermentum.com/v2/orders?updatedAt[gte]=2025-01-01T00:00:00Z&updatedAt[lte]=2025-01-15T23:59:59Z&pageSize=10" \
     -H "Authorization: Bearer YOUR_API_TOKEN"
Example Response (if any):

Creating Orders

Orders can be created using the POST /v1/orders endpoint. Before creating an order, ensure the required data such as retailer and product information is available.

Refer to the Managing Products Guide for product details and the Customer Management Guide for retrieving retailer IDs.

Example Request: Create an Order

curl -X POST "https://api.ordermentum.com/v1/orders" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "supplierId": "123e4567-e89b-12d3-a456-426614174000",
       "retailerId": "123e4567-e89b-12d3-a456-426614174001",
       "origin": "retailer",
       "deliveryDate": "2025-01-15T10:00:00Z",
       "lineItems": [
         {
           "productId": "123e4567-e89b-12d3-a456-426614174002",
           "quantity": 5,
           "price": 10.00
         }
       ]
     }'
Required Fields:

Updating Orders

To update an order, use the PATCH /v1/orders/{id} endpoint. This can be used to modify details such as delivery instructions or change order status.

Example Request: Update Order Details

curl -X PATCH "https://api.ordermentum.com/v1/orders/123e4567-e89b-12d3-a456-426614174001" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "deliveryInstructions": "Leave at back door",
       "status": "Delivered"
     }'

Locking Orders
Orders can be locked to prevent further modifications by setting the lockedAt timestamp.

Example Request: Lock an Order

curl -X PATCH "https://api.ordermentum.com/v1/orders/123e4567-e89b-12d3-a456-426614174001" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "lockedAt": "2025-01-26T12:00:00Z"
     }'

Once locked, no further updates can be made to the order.

Best Practices

• Use the /v2/orders endpoint for bulk operations.
• Fetch retailer and product details before creating an order.
• Handle validation errors gracefully, referring to the Order Validation Guide.