Orders API

This API allows you to manage orders within the system. You can retrieve, create, update, and delete orders.

Base URL

All API endpoints are relative to the following base URL:

https://api.example.com/v1

Authentication

Authentication is performed via API keys passed in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Endpoints

GET /orders

Retrieves a list of all orders. Supports pagination and filtering.

GET
/orders

Query Parameters

Name Type Required Description
limit Integer No The maximum number of orders to return. Defaults to 20.
offset Integer No The number of orders to skip before returning results. Defaults to 0.
status String No Filter orders by status (e.g., pending, shipped, delivered, cancelled).
customerId String No Filter orders by the ID of the customer who placed the order.

Response (Success)

{
  "data": [
    {
      "orderId": "ORD123456",
      "customerId": "CUST7890",
      "orderDate": "2023-10-27T10:00:00Z",
      "totalAmount": 150.75,
      "status": "shipped",
      "items": [
        {"productId": "PROD001", "quantity": 2, "price": 50.00},
        {"productId": "PROD002", "quantity": 1, "price": 50.75}
      ]
    },
    {
      "orderId": "ORD123457",
      "customerId": "CUST1234",
      "orderDate": "2023-10-27T11:30:00Z",
      "totalAmount": 75.50,
      "status": "pending",
      "items": [
        {"productId": "PROD003", "quantity": 1, "price": 75.50}
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 2,
    "nextOffset": null
  }
}

Response (Error)

{
  "error": {
    "code": 400,
    "message": "Invalid status filter provided."
  }
}

POST /orders

Creates a new order.

POST
/orders

Request Body

{
  "customerId": "CUST1234",
  "items": [
    {"productId": "PROD001", "quantity": 1},
    {"productId": "PROD004", "quantity": 3}
  ]
}

Response (Success)

{
  "orderId": "ORD123458",
  "customerId": "CUST1234",
  "orderDate": "2023-10-27T12:00:00Z",
  "totalAmount": 125.00,
  "status": "pending",
  "items": [
    {"productId": "PROD001", "quantity": 1, "price": 50.00},
    {"productId": "PROD004", "quantity": 3, "price": 25.00}
  ]
}

Response (Error)

{
  "error": {
    "code": 400,
    "message": "Invalid input: Customer ID is required."
  }
}

GET /orders/{orderId}

Retrieves details for a specific order.

GET
/orders/{orderId}

Path Parameters

Name Type Required Description
orderId String Yes The unique identifier of the order.

Response (Success)

{
  "orderId": "ORD123456",
  "customerId": "CUST7890",
  "orderDate": "2023-10-27T10:00:00Z",
  "totalAmount": 150.75,
  "status": "shipped",
  "items": [
    {"productId": "PROD001", "quantity": 2, "price": 50.00},
    {"productId": "PROD002", "quantity": 1, "price": 50.75}
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "USA"
  },
  "trackingNumber": "TRK987654"
}

Response (Error)

{
  "error": {
    "code": 404,
    "message": "Order not found."
  }
}

PUT /orders/{orderId}

Updates an existing order. Primarily used for updating status or shipping information.

PUT
/orders/{orderId}

Path Parameters

Name Type Required Description
orderId String Yes The unique identifier of the order.

Request Body

{
  "status": "delivered",
  "trackingNumber": "TRK987654-UPDATED"
}

Response (Success)

{
  "orderId": "ORD123456",
  "customerId": "CUST7890",
  "orderDate": "2023-10-27T10:00:00Z",
  "totalAmount": 150.75,
  "status": "delivered",
  "items": [
    {"productId": "PROD001", "quantity": 2, "price": 50.00},
    {"productId": "PROD002", "quantity": 1, "price": 50.75}
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "USA"
  },
  "trackingNumber": "TRK987654-UPDATED"
}

Response (Error)

{
  "error": {
    "code": 400,
    "message": "Cannot change status to 'delivered' if already shipped."
  }
}

DELETE /orders/{orderId}

Deletes a specific order. This action is typically irreversible.

DELETE
/orders/{orderId}

Path Parameters

Name Type Required Description
orderId String Yes The unique identifier of the order.

Response (Success)

{
  "message": "Order ORD123456 deleted successfully."
}

Response (Error)

{
  "error": {
    "code": 404,
    "message": "Order not found."
  }
}

Data Models

Order Object

Field Type Description
orderId String Unique identifier for the order.
customerId String Identifier of the customer who placed the order.
orderDate DateTime Timestamp when the order was placed (ISO 8601 format).
totalAmount Number The total monetary value of the order.
status String Current status of the order (e.g., pending, processing, shipped, delivered, cancelled).
items Array of OrderItem Objects List of items included in the order.
shippingAddress Address Object Shipping details for the order. (Optional)
trackingNumber String Tracking number for the shipment. (Optional)

OrderItem Object

Field Type Description
productId String Identifier of the product.
quantity Integer Number of units of the product.
price Number Price per unit of the product at the time of order. (Included in GET responses)

Address Object

Field Type Description
street String Street address.
city String City name.
state String State or province.
zip String Postal or ZIP code.
country String Country name.
Copied to clipboard