Orders API - Syngenta Warehouse Management System

This page describes planned API endpoints for the Syngenta Warehouse Management System. The application is currently in early development. No API endpoints are currently implemented.

Overview

The Orders API will provide endpoints for creating, managing, and fulfilling customer orders, including order status tracking and shipment management.

List Orders

Retrieve a paginated list of orders with optional filtering.

Endpoint

GET /api/v1/orders

Query Parameters

page

integer

default:"1"

Page number for pagination

limit

integer

default:"20"

Number of items per page (max: 100)

status

string

Filter by order status: pending, processing, shipped, delivered, cancelled

warehouse

string

Filter by warehouse code

customer

string

Filter by customer ID

startDate

string

Filter orders from this date (ISO 8601)

endDate

string

Filter orders until this date (ISO 8601)

sort

string

default:"-createdAt"

Sort field (prefix with - for descending)

Request Example

curl -X GET "https://api.syngenta-wms.com/api/v1/orders?status=pending&warehouse=WH001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

success

boolean

Request success status

data

array

Array of order objects

string

Unique order ID

orderNumber

string

Human-readable order number

customer

object

string

Customer ID

name

string

Customer name

string

Customer email

phone

string

Customer phone

warehouse

object

code

string

Warehouse code

name

string

Warehouse name

items

array

Array of order items

inventoryId

string

Inventory item ID

sku

string

Product SKU

name

string

Product name

quantity

number

Ordered quantity

unit

string

Unit of measurement

unitPrice

number

Price per unit

totalPrice

number

Total price (quantity × unitPrice)

status

string

Order status: pending, processing, shipped, delivered, cancelled

shippingAddress

object

street

string

Street address

city

string

City

state

string

State/Province

zipCode

string

ZIP/Postal code

country

string

Country

totalAmount

number

Total order amount

notes

string

Order notes

createdAt

string

Order creation timestamp (ISO 8601)

updatedAt

string

Last update timestamp (ISO 8601)

shippedAt

string

Shipment timestamp (ISO 8601)

deliveredAt

string

Delivery timestamp (ISO 8601)

Response Example

{
  "success": true,
  "data": [
    {
      "id": "ord_123456",
      "orderNumber": "ORD-2026-001234",
      "customer": {
        "id": "cust_789012",
        "name": "Green Valley Farms",
        "email": "[email protected]",
        "phone": "+1-515-555-1234"
      },
      "warehouse": {
        "code": "WH001",
        "name": "Central Distribution Center"
      },
      "items": [
        {
          "inventoryId": "inv_123456",
          "sku": "SYN-SEED-001",
          "name": "NK603 Corn Seed",
          "quantity": 2000,
          "unit": "kg",
          "unitPrice": 8.50,
          "totalPrice": 17000.00
        },
        {
          "inventoryId": "inv_123457",
          "sku": "SYN-FERT-002",
          "name": "Atrazine 4L Herbicide",
          "quantity": 500,
          "unit": "liters",
          "unitPrice": 12.75,
          "totalPrice": 6375.00
        }
      ],
      "status": "pending",
      "shippingAddress": {
        "street": "1234 Farm Road",
        "city": "Ames",
        "state": "IA",
        "zipCode": "50010",
        "country": "USA"
      },
      "totalAmount": 23375.00,
      "notes": "Deliver to loading dock on east side",
      "createdAt": "2026-03-12T08:00:00Z",
      "updatedAt": "2026-03-12T08:00:00Z",
      "shippedAt": null,
      "deliveredAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 342,
    "totalPages": 18
  },
  "metadata": {
    "timestamp": "2026-03-12T10:30:00Z",
    "requestId": "req_abc123"
  }
}

Get Order

Retrieve detailed information about a specific order.

Endpoint

GET /api/v1/orders/{id}

Path Parameters

string

required

Order ID

Request Example

curl -X GET https://api.syngenta-wms.com/api/v1/orders/ord_123456 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Returns a single order object with the same structure as the list endpoint, including full order history.

Create Order

Create a new order in the system.

Endpoint

POST /api/v1/orders

Request Body

customerId

string

required

Customer ID

warehouse

string

required

Warehouse code to fulfill the order

items

array

required

Array of order items

inventoryId

string

required

Inventory item ID

quantity

number

required

Quantity to order (must be positive)

unitPrice

number

required

Price per unit

shippingAddress

object

required

Shipping address

street

string

required

Street address

city

string

required

City

state

string

required

State/Province

zipCode

string

required

ZIP/Postal code

country

string

required

Country

notes

string

Additional order notes

priority

string

default:"normal"

Order priority: low, normal, high, urgent

Request Example

curl -X POST https://api.syngenta-wms.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_789012",
    "warehouse": "WH001",
    "items": [
      {
        "inventoryId": "inv_123456",
        "quantity": 2000,
        "unitPrice": 8.50
      },
      {
        "inventoryId": "inv_123457",
        "quantity": 500,
        "unitPrice": 12.75
      }
    ],
    "shippingAddress": {
      "street": "1234 Farm Road",
      "city": "Ames",
      "state": "IA",
      "zipCode": "50010",
      "country": "USA"
    },
    "notes": "Deliver to loading dock on east side",
    "priority": "normal"
  }'

Response

Returns the created order object with status code 201.

Creating an order automatically reserves inventory quantities. If insufficient stock is available, the order creation will fail.

Update Order

Update an existing order’s information.

Endpoint

PUT /api/v1/orders/{id}

Path Parameters

string

required

Order ID

Only orders with status pending can be updated. Orders that are processing, shipped, or delivered cannot be modified.

Request Body

items

array

Updated array of order items

shippingAddress

object

Updated shipping address

notes

string

Updated order notes

priority

string

Updated order priority

Request Example

curl -X PUT https://api.syngenta-wms.com/api/v1/orders/ord_123456 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "high",
    "notes": "Rush delivery requested - deliver by 3 PM"
  }'

Response

Returns the updated order object.

Update Order Status

Update the status of an order.

Endpoint

POST /api/v1/orders/{id}/status

Path Parameters

string

required

Order ID

Request Body

status

string

required

New order status: processing, shipped, delivered, cancelled

trackingNumber

string

Shipping tracking number (required when status is shipped)

carrier

string

Shipping carrier (e.g., “FedEx”, “UPS”, “USPS”)

notes

string

Status change notes

Request Example

curl -X POST https://api.syngenta-wms.com/api/v1/orders/ord_123456/status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "trackingNumber": "1Z999AA10123456784",
    "carrier": "UPS",
    "notes": "Package picked up at 2:30 PM"
  }'

Response

{
  "success": true,
  "data": {
    "id": "ord_123456",
    "status": "shipped",
    "trackingNumber": "1Z999AA10123456784",
    "carrier": "UPS",
    "shippedAt": "2026-03-12T14:30:00Z"
  },
  "metadata": {
    "timestamp": "2026-03-12T14:30:00Z",
    "requestId": "req_status1"
  }
}

Status transitions follow a workflow: pending → processing → shipped → delivered. Orders can be cancelled from any status except delivered.

Cancel Order

Cancel an existing order.

Endpoint

POST /api/v1/orders/{id}/cancel

Path Parameters

string

required

Order ID

Request Body

reason

string

required

Cancellation reason

notes

string

Additional cancellation notes

Request Example

curl -X POST https://api.syngenta-wms.com/api/v1/orders/ord_123456/cancel \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer requested cancellation",
    "notes": "Customer changed delivery location and will reorder"
  }'

Response

{
  "success": true,
  "data": {
    "id": "ord_123456",
    "status": "cancelled",
    "cancelledAt": "2026-03-12T15:00:00Z",
    "cancelReason": "Customer requested cancellation"
  },
  "metadata": {
    "timestamp": "2026-03-12T15:00:00Z",
    "requestId": "req_cancel1"
  }
}

Cancelling an order automatically releases any reserved inventory quantities back to available stock.

Error Responses

Insufficient Stock

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_STOCK",
    "message": "Insufficient inventory to fulfill order",
    "details": [
      {
        "inventoryId": "inv_123456",
        "sku": "SYN-SEED-001",
        "requested": 5000,
        "available": 3000
      }
    ]
  },
  "metadata": {
    "timestamp": "2026-03-12T10:30:00Z",
    "requestId": "req_error1"
  }
}

Invalid Status Transition

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS_TRANSITION",
    "message": "Cannot transition from 'delivered' to 'processing'",
    "details": {
      "currentStatus": "delivered",
      "requestedStatus": "processing"
    }
  },
  "metadata": {
    "timestamp": "2026-03-12T10:30:00Z",
    "requestId": "req_error2"
  }
}

Getting Started

Endpoints

​Overview

​List Orders

​Endpoint

​Query Parameters

​Request Example

​Response

​Get Order

​Endpoint

​Path Parameters

​Request Example

​Response

​Create Order

​Endpoint

​Request Body

​Request Example

​Response

​Update Order

​Endpoint

​Path Parameters

​Request Body

​Request Example

​Response

​Update Order Status

​Endpoint

​Path Parameters

​Request Body

​Request Example

​Response

​Cancel Order

​Endpoint

​Path Parameters

​Request Body

​Request Example

​Response

​Error Responses

​Insufficient Stock

​Invalid Status Transition

Build docs developers (and LLMs) love

Overview

List Orders

Endpoint

Query Parameters

Request Example

Response

Get Order

Endpoint

Path Parameters

Request Example

Response

Create Order

Endpoint

Request Body

Request Example

Response

Update Order

Endpoint

Path Parameters

Request Body

Request Example

Response

Update Order Status

Endpoint

Path Parameters

Request Body

Request Example

Response

Cancel Order

Endpoint

Path Parameters

Request Body

Request Example

Response

Error Responses

Insufficient Stock

Invalid Status Transition