PostEx Orders API

openapi: 3.2.0
info:
  title: PostEx Merchant Order Integration Orders API
  description: PostEx is a Pakistani e-commerce logistics and courier platform offering cash-on-delivery fulfilment with instant upfront payments. This OpenAPI definition describes PostEx's merchant Order Integration API, used by merchants and order-management systems to book shipments, look up operational cities, retrieve their registered pickup addresses, track parcels, and list orders not yet booked. Every operation authenticates with a merchant API token supplied in the `token` request header (issued from the PostEx merchant dashboard). This definition was constructed by live-probing the production host https://api.postex.pk — each path below was confirmed to exist (returns HTTP 400 "Missing request header 'token'" when called without credentials rather than 404). Request and response bodies are intentionally left as generic objects where they could not be verified without an authenticated token, to avoid fabricating field-level schema.
  version: '3'
  x-api-evangelist-note: Servers, paths, auth model, and error envelope verified against the live api.postex.pk host on 2026-07-20. No provider-published OpenAPI/Swagger was found (/v3/api-docs, /swagger-ui.html both 404).
  contact:
    name: PostEx Support
    url: https://postex.pk
    email: info@postex.pk
servers:
- url: https://api.postex.pk/services/integration/api/order
  description: PostEx merchant Order Integration API (production)
security:
- merchantToken: []
tags:
- name: Orders
  description: Booking, tracking, and listing shipment orders
paths:
  /v3/create-order:
    post:
      operationId: createOrder
      tags:
      - Orders
      summary: Create an order (v3)
      description: Book a new shipment order with PostEx (latest version). Requires the merchant `token` header. Request body carries the consignee, pickup address code, order reference, item count, and COD amount.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Order created
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/create-order:
    post:
      operationId: createOrderV2
      tags:
      - Orders
      summary: Create an order (v2)
      description: Book a new shipment order (prior version). Requires the merchant `token` header.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Order created
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/create-order:
    post:
      operationId: createOrderV1
      tags:
      - Orders
      summary: Create an order (v1)
      description: Book a new shipment order (original version). Requires the merchant `token` header.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Order created
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/track-order/{trackingNumber}:
    get:
      operationId: trackOrder
      tags:
      - Orders
      summary: Track an order
      description: Retrieve the current status and tracking history of a shipment by its PostEx tracking number. Requires the merchant `token` header.
      parameters:
      - name: trackingNumber
        in: path
        required: true
        description: PostEx tracking number of the order.
        schema:
          type: string
      responses:
        '200':
          description: Order tracking detail
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/get-unbooked-orders:
    get:
      operationId: getUnbookedOrders
      tags:
      - Orders
      summary: List unbooked orders
      description: List the merchant's orders that have been created but not yet booked into a load sheet. Requires the merchant `token` header.
      responses:
        '200':
          description: List of unbooked orders
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    Error:
      type: object
      description: PostEx / Spring Boot error envelope returned on failed requests (Content-Type application/json). Not RFC 9457 problem+json.
      properties:
        timestamp:
          type: string
          format: date-time
          example: 2026-07-21T07:35:03.040+0500
        status:
          type: integer
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Missing request header 'token' for method parameter of type String
        path:
          type: string
          example: /api/order/v1/get-merchant-address
  responses:
    BadRequest:
      description: Bad request (e.g. missing `token` header or invalid parameters)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    merchantToken:
      type: apiKey
      in: header
      name: token
      description: Merchant API token issued from the PostEx merchant dashboard, supplied in the `token` request header on every call.