Orders API Documentation

Access and manage order data through our comprehensive API.

Endpoints

GET /orders

Retrieve a list of orders. Supports filtering and pagination.

HTTP Method

GET

Path

/orders

Requires Authentication

Yes (Bearer Token)

Query Parameters

Name Type Required Description
status String No Filter orders by status (e.g., pending, processing, shipped, delivered, cancelled).
limit Integer No Number of results to return per page. Defaults to 20.
offset Integer No Number of results to skip. Defaults to 0.
sortBy String No Field to sort by (e.g., createdAt, updatedAt).
sortOrder String No Sort order: asc or desc. Defaults to desc.
Example Request
curl -X GET \
  'https://api.example.com/v1/orders?status=processing&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example Success Response (200 OK)
{
  "data": [
    {
      "orderId": "ORD123456789",
      "customerId": "CUST98765",
      "status": "processing",
      "totalAmount": 150.75,
      "currency": "USD",
      "createdAt": "2023-10-27T10:30:00Z",
      "updatedAt": "2023-10-27T10:35:00Z",
      "items": [
        {
          "productId": "PROD001",
          "quantity": 2,
          "price": 50.00
        },
        {
          "productId": "PROD002",
          "quantity": 1,
          "price": 50.75
        }
      ]
    },
    {
      "orderId": "ORD123456790",
      "customerId": "CUST98766",
      "status": "processing",
      "totalAmount": 75.00,
      "currency": "USD",
      "createdAt": "2023-10-27T09:00:00Z",
      "updatedAt": "2023-10-27T09:05:00Z",
      "items": [
        {
          "productId": "PROD003",
          "quantity": 3,
          "price": 25.00
        }
      ]
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 10,
    "offset": 0,
    "nextOffset": 10,
    "prevOffset": null
  }
}
Example Error Response (401 Unauthorized)
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authentication token is invalid or expired."
  }
}

POST /orders

Create a new order.

HTTP Method

POST

Path

/orders

Requires Authentication

Yes (Bearer Token)

Request Body (JSON)

Name Type Required Description
customerId String Yes The ID of the customer placing the order.
items Array of Objects Yes An array of items to include in the order. Each item object should have:
  • productId (String, Required): The ID of the product.
  • quantity (Integer, Required): The quantity of the product.
shippingAddress Object No The shipping address for the order. Can include fields like street, city, state, zipCode, country.
paymentMethodId String No The ID of the customer's saved payment method.
Example Request
curl -X POST \
  'https://api.example.com/v1/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "CUST98765",
    "items": [
      {
        "productId": "PROD001",
        "quantity": 1
      },
      {
        "productId": "PROD004",
        "quantity": 2
      }
    ],
    "shippingAddress": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zipCode": "90210",
      "country": "USA"
    }
  }'
Example Success Response (201 Created)
{
  "orderId": "ORD123456801",
  "customerId": "CUST98765",
  "status": "pending",
  "totalAmount": 220.50,
  "currency": "USD",
  "createdAt": "2023-10-27T11:00:00Z",
  "updatedAt": "2023-10-27T11:00:00Z",
  "items": [
    {
      "productId": "PROD001",
      "quantity": 1,
      "price": 50.00
    },
    {
      "productId": "PROD004",
      "quantity": 2,
      "price": 85.25
    }
  ]
}

GET /orders/{orderId}

Retrieve details for a specific order.

HTTP Method

GET

Path

/orders/{orderId}

Requires Authentication

Yes (Bearer Token)

Path Parameters

Name Type Required Description
orderId String Yes The unique identifier of the order.
Example Request
curl -X GET \
  'https://api.example.com/v1/orders/ORD123456789' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example Success Response (200 OK)
{
  "orderId": "ORD123456789",
  "customerId": "CUST98765",
  "status": "processing",
  "totalAmount": 150.75,
  "currency": "USD",
  "createdAt": "2023-10-27T10:30:00Z",
  "updatedAt": "2023-10-27T10:35:00Z",
  "shippingAddress": {
    "street": "456 Oak Ave",
    "city": "Othertown",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "items": [
    {
      "productId": "PROD001",
      "quantity": 2,
      "price": 50.00
    },
    {
      "productId": "PROD002",
      "quantity": 1,
      "price": 50.75
    }
  ]
}
Example Error Response (404 Not Found)
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Order with ID ORD999999999 not found."
  }
}

PUT /orders/{orderId}

Update an existing order. Note: Not all fields are mutable after creation.

HTTP Method

PUT

Path

/orders/{orderId}

Requires Authentication

Yes (Bearer Token)

Path Parameters

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

Request Body (JSON)

Name Type Required Description
status String No New status for the order (e.g., shipped, cancelled). Subject to business logic rules.
shippingAddress Object No Updated shipping address.
Example Request
curl -X PUT \
  'https://api.example.com/v1/orders/ORD123456789' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "shipped",
    "shippingAddress": {
      "street": "456 Oak Ave",
      "city": "Anytown",
      "state": "CA",
      "zipCode": "90210",
      "country": "USA"
    }
  }'
Example Success Response (200 OK)
{
  "orderId": "ORD123456789",
  "customerId": "CUST98765",
  "status": "shipped",
  "totalAmount": 150.75,
  "currency": "USD",
  "createdAt": "2023-10-27T10:30:00Z",
  "updatedAt": "2023-10-27T11:30:00Z",
  "shippingAddress": {
    "street": "456 Oak Ave",
    "city": "Anytown",
    "state": "CA",
    "zipCode": "90210",
    "country": "USA"
  },
  "items": [
    {
      "productId": "PROD001",
      "quantity": 2,
      "price": 50.00
    },
    {
      "productId": "PROD002",
      "quantity": 1,
      "price": 50.75
    }
  ]
}

DELETE /orders/{orderId}

Cancel an order. This action may be subject to availability based on order status.

HTTP Method

DELETE

Path

/orders/{orderId}

Requires Authentication

Yes (Bearer Token)

Path Parameters

Name Type Required Description
orderId String Yes The unique identifier of the order to cancel.
Example Request
curl -X DELETE \
  'https://api.example.com/v1/orders/ORD123456789' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example Success Response (204 No Content)

A 204 response indicates the order was successfully cancelled.

Example Error Response (400 Bad Request - Order cannot be cancelled)
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Order ORD123456789 cannot be cancelled as it has already been shipped."
  }
}