Online Postman Documentation

To explore and test the Order Management APIs using ready-made Postman requests and environment variables,
please refer to the Muvx Order Management Postman documentation.

Endpoints (Shop → Muvx)

1. Create Order

POST /v1/orders

Creates a new delivery order in Muvx.

Request Body

{
  "integration_order_id": "SHOP123456",
  "pickup": {
    "name": "Store Name",
    "address": "789 Elm St, Kuwait City",
    "lat": 29.3375,
    "lng": 48.0286,
    "phone": "+96500000000"
  },
  "dropoff": {
    "name": "Customer Name",
    "address": {
      "area": "Salmiya",
      "block": "3",
      "street": "Al Muqawil",
      "building": "21A",
      "floor": "1",
      "flat": "2"
    },
    "lat": 29.3759,
    "lng": 47.9774,
    "phone": "+96511111111"
  },
  "items": [
    {
      "name": "Product A",
      "quantity": 2,
      "price": 1.25,
      "weight": 0.53
    }
  ],
  "notes": "Leave at the door",
  "cod_amount": 3.5,
  "destination_id": "ks7fzcatg65zdv4b1plihw0qz57q5qcs",
  "auto_pickup": true,
  "scheduled_pickup_time": "2025-07-16T15:00:00Z"
}

Destination Routing

• If you provide destination_id, the order will be created for that specific destination.
• If omitted, the order will automatically route to the Source’s default destination.
• You can fetch available destinations (and see which one is default) via the Destinations List API or in the panel under Source → Overview.

Pickup Flow & Auto-Dispatch

Auto Pickup controls when the order is sent to the Delivery Provider:

• auto_pickup: false → The order is created and stored in Muvx but not dispatched until you manually call Trigger Pickup.

• auto_pickup: true →
– Without scheduled_pickup_time → The order is dispatched to the Delivery Provider immediately.
– With scheduled_pickup_time → The order is first stored in Muvx and held until the scheduled time. At that moment, it is automatically dispatched to the Delivery Provider.

Notes:
• You can always trigger dispatch earlier or adjust timing using Trigger Pickup (depending on the order status).
• scheduled_pickup_time must use ISO-8601 UTC format, e.g. 2025-07-16T15:00:00Z.

Required Fields

When creating an order in Muvx, some of fields are strictly required. All other fields are either optional (e.g. items, notes, cod_amount, coordinates, scheduled_pickup_time).

The following fields must always be provided :

Field	Requirement	Description
integrationOrderId	Required	Unique order ID from your system (must not be duplicated). Muvx also generates its own `id` in the response.
pickup.name	Required	-
pickup.address	Required	-
pickup.phone	Required	-
dropoff.name	Required	-
dropoff.address	Required	-
dropoff.phone	Required	-
auto_pickup	Required	defaults to false if not provided

200 OK Response

{
  "success": true,
  "id": "MOV123",
  "status": "created",
  "tracking_url": "https://sample.com/track/MOV123", // optional
  "status_url": "https://api.sample.com/v1/orders/MOV123/status"
}

400 Bad Request

{
  "success": false,
  "error": "validation_error",
  "message": "Missing required field: dropoff.phone"
}

409 Conflict

{
  "success": false,
  "error": "duplicate_order",
  "message": "An order with this integration_order_id already exists."
}

2. Cancel Order

POST /v1/orders/{id}/cancel

Cancels a previously created order.

200 OK Response

{
  "success": true,
  "id": "MOV123",
  "status": "cancelled"
}

404 Not Found

{
  "success": false,
  "error": "not_found",
  "message": "Order not found"
}

400 Bad Request

{
  "success": false,
  "error": "invalid_action",
  "message": "Cannot cancel an order that has already been delivered."
}

3. Get Order Status

GET /v1/orders/{id}/status

Fetches the latest delivery status of a given order.

200 OK Response

{
  "success": true,
  "id": "MOV123",
  "integration_order_id": "SHOP123456",
  "status": "in_transit",
  "last_updated": "2025-07-16T09:42:00Z"
}

404 Not Found

{
  "success": false,
  "error": "not_found",
  "message": "Order not found"
}

4. Trigger Pickup

POST /v1/orders/{id}/pickup

Manually triggers a pickup for an existing order if auto-pickup is disabled or delayed.

200 OK Response

{
  "success": true,
  "id": "MOV123",
  "status": "dispatched"
}

404 Not Found

{
  "success": false,
  "error": "not_found",
  "message": "Order not found"
}

400 Bad Request

{
  "success": false,
  "error": "invalid_status",
  "message": "Pickup cannot be triggered. Current status: picked_up"
}

5. Destinations List

GET /v1/destinations

Returns all Active destinations linked to the calling Source (the Source is inferred from the API key used to call this endpoint). Use the returned id to target a specific destination when creating an order — pass it as destination_id in Create Order (POST /v1/orders) to route the order to that destination.

200 OK Response

{
  "success": true,
  "destinations": [
    {
      "id": "ks7871ycvns4h4nx530c0ss0ks7q4dqt",
      "name": "beep beep DMS",
      "is_default": true,
      "environment": "sandbox",
      "provider": "beepbeep"
    },
    {
      "id": "ks7fzcatg65zdv4b1gmqhw0qz57q5qcs",
      "name": "autobot test",
      "is_default": false,
      "environment": "sandbox",
      "provider": "autobot"
    }
  ]
}

Notes

• Only destinations with status Active are returned.
• Each destination includes its environment (sandbox or production) and provider identifier.
• Exactly one destination per Source is always marked as is_default: true.