Creating Orders

This guide explains how e-commerce partners can create new orders using the Nowpost API.

Endpoint

POST /orders

Authentication

You must be authenticated to create an order. Generate your API token using the Partner API Token Generation endpoint. Include your API token in the Authorization header as a Bearer token in every request.

Headers:

Authorization: Bearer <your_api_token_from_/partner/api-keys>
Content-Type: application/json

Request Body

Send a JSON object with the order details. The required and optional fields are:

Fields for CreateOrderInput

• partnerId (string, required): Partner's UUID
• receiverEmail (string, required): Receiver's email address
• receiverFirstName (string, required): Receiver's first name
• receiverLastName (string, required): Receiver's last name
• receiverPhone (string, optional): Receiver's phone number
• pickupPudoId (string, optional): Pickup PUDO point UUID
• dropoffPudoId (string, optional): Dropoff PUDO point UUID
• items (array, required): List of order items (see below)
• deliveryFee (number, optional): Delivery fee
• note (string, optional): Additional note

Fields for each item in items (CreateOrderItemInput)

• description (string, required): Item description
• weight (number, required): Item weight
• length (number, required): Item length
• width (number, required): Item width
• height (number, required): Item height
• quantity (integer, required): Quantity
• value (number, required): Item value

Example:

{
  "partnerId": "<partner_id>",
  "receiverEmail": "customer@example.com",
  "receiverFirstName": "Jane",
  "receiverLastName": "Doe",
  "receiverPhone": "+2348012345678",
  "pickupPudoId": "<pickup_pudo_id>",
  "dropoffPudoId": "<dropoff_pudo_id>",
  "items": [
    {
      "description": "Product Name",
      "weight": 2.5,
      "length": 10.0,
      "width": 5.0,
      "height": 3.0,
      "quantity": 2,
      "value": 1000
    }
  ],
  "deliveryFee": 500,
  "note": "Handle with care"
}

Response

201 Created

{
  "data": {
    "id": "order-id",
    "partnerId": "<partner_id>",
    "receiverEmail": "customer@example.com",
    "items": [
      {
        "name": "Product Name",
        "quantity": 2,
        "price": 1000
      }
    ],
    "deliveryAddress": {
      "street": "123 Main St",
      "city": "Lagos",
      "state": "Lagos",
      "country": "Nigeria"
    },
    "notes": "Handle with care",
    "createdAt": "2025-08-12T12:00:00Z"
  }
}

Error Responses

• 400 Bad Request: Invalid request payload or missing required fields.
• 401 Unauthorized: Authentication failed or missing token.
• 500 Internal Server Error: Server error.

---

For more details, see the API Reference.