Saltar al contenido principal
Routal
API ReferenceStop

Move stops between plans

Moves one or more stops to a different plan.

POST
/v2/stop/move

Moves one or more stops to a different plan. Omit plan_id to unassign the stops at the project level (they go to your unassigned inbox).

Typical use cases:

  • Reschedule orders from today's plan to tomorrow's.
  • Pull a stop out of a plan when the customer requests a different day.
  • Park stops in the unassigned inbox while you decide how to handle them.

⚠️ Traceability warning

Routal models each stop as a single delivery attempt. Moving a stop after it has been executed (delivered, failed, cancelled) rewrites history and breaks audit trails.

Recommended pattern:

  1. Do not move stops in terminal states.
  2. Create a new stop in the new plan instead — that's the right way to model a retry.
  3. Only move stops that have not yet started execution.

If you are unsure, contact support — we'll help you model it correctly.

Authorization

api_key
private_key<token>

The Routal API authenticates requests with an API key passed as the private_key query string parameter. Generate and rotate your keys from the Developer Settings section of your Routal workspace.Never ship API keys to a browser or mobile app — they must stay server-side.

In: query

Query Parameters

plan_id?string

The plan where the stops will be moved. If left empty, the stop will be unassigned.

Match^[0-9a-f]{24}

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/stop/move" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "4f75d991ac359f8c4c79d762",
  "fixed_id": "1",
  "organization_id": "4f75d991ac359f8c4c79d762",
  "project_id": "4f75d991ac359f8c4c79d762",
  "plan_id": "4f75d991ac359f8c4c79d762",
  "type": "delivery",
  "route_id": "4f75d991ac359f8c4c79d762",
  "vehicle_id": "4f75d991ac359f8c4c79d762",
  "client_id": "4f75d991ac359f8c4c79d762",
  "client_external_id": "CUST-58291",
  "external_id": "ORD-2026-58291",
  "location": {
    "location_id": "4f75d991ac359f8c4c79d762",
    "label": "Location label",
    "country": "Spain",
    "country_code": "ES",
    "state": "Catalonia",
    "city": "Barcelona",
    "street": "Calle de Pau Claris",
    "postal_code": "08302",
    "comments": "Location comments",
    "lat": 40.45,
    "lng": -3.68,
    "main_text": "Calle de Pau Claris 12",
    "secondary_text": "Barcelona, Catalonia, Spain"
  },
  "location_details": "Local 2, junto a la entrada principal",
  "label": "Acme Pharmacy — Aragó branch",
  "comments": "Ring intercom 2B. Do not leave at reception.",
  "phone": "+34612345678",
  "email": "sarah.johnson@example.com",
  "url": "https://shop.example.com/orders/58291",
  "reference_person": "Sarah Johnson",
  "duration": 180,
  "requires": [
    "refrigerated",
    "fragile"
  ],
  "cluster": "eixample-norte",
  "reward": 5,
  "time_windows": [
    [
      28800,
      61200
    ]
  ],
  "volume": 0.12,
  "weight": 8.4,
  "max_delivery_time": 7200,
  "status": "pending",
  "plan_execution_date": "2026-05-29T14:55:24.491Z",
  "order": 0,
  "planned_arrival_time": 29500,
  "planned_departure_time": 30000,
  "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
  "estimated_departure_time": "2026-05-29T14:55:24.491Z",
  "pickup_id": "4f75d991ac359f8c4c79d762",
  "distance_to_previous_stop": 30000,
  "distance_to_next_stop": 20000,
  "optimization_warning": true,
  "chain_id": "order-58291",
  "chain_position": 1,
  "custom_fields": {
    "order_reference": "ORD-2026-58291",
    "parcel_count": 2,
    "cod_amount": 24.9
  },
  "tasks": [
    {
      "id": "4f75d991ac359f8c4c79d762",
      "stop_id": "4f75d991ac359f8c4c79d762",
      "label": "Deliver refrigerated parcel 1/2",
      "comments": "Keep cold chain. Weight 12.4 kg.",
      "barcode": "8410076472158",
      "status": "completed",
      "custom_fields": {
        "sku": "SKU-4582",
        "quantity": 2,
        "lot_number": "L-2026-038"
      },
      "created_by": "4f75d991ac359f8c4c79d762",
      "created_at": "2026-05-29T14:55:24.485Z",
      "updated_at": "2026-05-29T14:55:24.485Z",
      "deleted_at": "2026-05-29T14:55:24.485Z"
    }
  ],
  "reports": [
    {
      "id": "4f75d991ac359f8c4c79d762",
      "stop_id": "4f75d991ac359f8c4c79d762",
      "route_id": "4f75d991ac359f8c4c79d762",
      "project_id": "4f75d991ac359f8c4c79d762",
      "plan_id": "4f75d991ac359f8c4c79d762",
      "type": "service_report_completed",
      "comments": "Customer not present. Notice left in the mailbox.",
      "images": [
        {
          "id": "4f75d991ac359f8c4c79d762",
          "url": "https://api.routal.com"
        }
      ],
      "signature": {
        "id": "4f75d991ac359f8c4c79d762",
        "url": "https://api.routal.com"
      },
      "tasks": [
        {
          "task_id": "4f75d991ac359f8c4c79d762",
          "status": "completed",
          "comments": "Parcel delivered in perfect condition.",
          "custom_fields": {
            "sku": "SKU-4582",
            "quantity": 2,
            "lot_number": "L-2026-038"
          }
        }
      ],
      "cancel_reason": "nobody",
      "location": {
        "location_id": "4f75d991ac359f8c4c79d762",
        "label": "Location label",
        "country": "Spain",
        "country_code": "ES",
        "state": "Catalonia",
        "city": "Barcelona",
        "street": "Calle de Pau Claris",
        "postal_code": "08302",
        "comments": "Location comments",
        "lat": 40.45,
        "lng": -3.68,
        "main_text": "Calle de Pau Claris 12",
        "secondary_text": "Barcelona, Catalonia, Spain"
      },
      "time_in_stop": 180,
      "custom_fields": {
        "delivered_to": "neighbor 2A",
        "cod_collected": 24.9,
        "photo_count": 2
      },
      "created_at": "2026-05-29T14:55:24.486Z"
    }
  ],
  "report_attempts": 2,
  "survey": {
    "stop_id": "4f75d991ac359f8c4c79d762",
    "route_id": "4f75d991ac359f8c4c79d762",
    "rating": 1,
    "rating_tag": "time",
    "comments": "The delivery was very professional and punctual.",
    "created_at": "2026-05-29T14:55:24.489Z",
    "updated_at": "2026-05-29T14:55:24.489Z"
  },
  "pin": "4729",
  "customer_text_field": "Leave at reception if I'm not home.",
  "supervisors": [
    "4f75d991ac359f8c4c79d762"
  ],
  "location_validation_sent": false,
  "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
  "location_validated": false,
  "location_validated_at": "2026-05-29T14:55:24.500Z",
  "created_by": "4f75d991ac359f8c4c79d762",
  "created_at": "2026-05-29T14:55:24.339Z",
  "updated_at": "2026-05-29T14:55:24.339Z",
  "deleted_at": "2026-05-29T14:55:24.339Z",
  "deleted": true,
  "pickup": {
    "id": "4f75d991ac359f8c4c79d762",
    "fixed_id": "1",
    "organization_id": "4f75d991ac359f8c4c79d762",
    "project_id": "4f75d991ac359f8c4c79d762",
    "plan_id": "4f75d991ac359f8c4c79d762",
    "type": "delivery",
    "route_id": "4f75d991ac359f8c4c79d762",
    "vehicle_id": "4f75d991ac359f8c4c79d762",
    "client_id": "4f75d991ac359f8c4c79d762",
    "client_external_id": "CUST-58291",
    "external_id": "ORD-2026-58291",
    "location": {
      "location_id": "4f75d991ac359f8c4c79d762",
      "label": "Location label",
      "country": "Spain",
      "country_code": "ES",
      "state": "Catalonia",
      "city": "Barcelona",
      "street": "Calle de Pau Claris",
      "postal_code": "08302",
      "comments": "Location comments",
      "lat": 40.45,
      "lng": -3.68,
      "main_text": "Calle de Pau Claris 12",
      "secondary_text": "Barcelona, Catalonia, Spain"
    },
    "location_details": "Local 2, junto a la entrada principal",
    "label": "Acme Pharmacy — Aragó branch",
    "comments": "Ring intercom 2B. Do not leave at reception.",
    "phone": "+34612345678",
    "email": "sarah.johnson@example.com",
    "url": "https://shop.example.com/orders/58291",
    "reference_person": "Sarah Johnson",
    "duration": 180,
    "requires": [
      "refrigerated",
      "fragile"
    ],
    "cluster": "eixample-norte",
    "reward": 5,
    "time_windows": [
      [
        28800,
        61200
      ]
    ],
    "volume": 0.12,
    "weight": 8.4,
    "max_delivery_time": 7200,
    "status": "pending",
    "plan_execution_date": "2026-05-29T14:55:24.491Z",
    "order": 0,
    "planned_arrival_time": 29500,
    "planned_departure_time": 30000,
    "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
    "estimated_departure_time": "2026-05-29T14:55:24.491Z",
    "pickup_id": "4f75d991ac359f8c4c79d762",
    "distance_to_previous_stop": 30000,
    "distance_to_next_stop": 20000,
    "optimization_warning": true,
    "chain_id": "order-58291",
    "chain_position": 1,
    "custom_fields": {
      "order_reference": "ORD-2026-58291",
      "parcel_count": 2,
      "cod_amount": 24.9
    },
    "tasks": [
      {
        "id": "4f75d991ac359f8c4c79d762",
        "stop_id": "4f75d991ac359f8c4c79d762",
        "label": "Deliver refrigerated parcel 1/2",
        "comments": "Keep cold chain. Weight 12.4 kg.",
        "barcode": "8410076472158",
        "status": "completed",
        "custom_fields": {
          "sku": "SKU-4582",
          "quantity": 2,
          "lot_number": "L-2026-038"
        },
        "created_by": "4f75d991ac359f8c4c79d762",
        "created_at": "2026-05-29T14:55:24.485Z",
        "updated_at": "2026-05-29T14:55:24.485Z",
        "deleted_at": "2026-05-29T14:55:24.485Z"
      }
    ],
    "reports": [
      {
        "id": "4f75d991ac359f8c4c79d762",
        "stop_id": "4f75d991ac359f8c4c79d762",
        "route_id": "4f75d991ac359f8c4c79d762",
        "project_id": "4f75d991ac359f8c4c79d762",
        "plan_id": "4f75d991ac359f8c4c79d762",
        "type": "service_report_completed",
        "comments": "Customer not present. Notice left in the mailbox.",
        "images": [
          {
            "id": "4f75d991ac359f8c4c79d762",
            "url": "https://api.routal.com"
          }
        ],
        "signature": {
          "id": "4f75d991ac359f8c4c79d762",
          "url": "https://api.routal.com"
        },
        "tasks": [
          {
            "task_id": "4f75d991ac359f8c4c79d762",
            "status": "completed",
            "comments": "Parcel delivered in perfect condition.",
            "custom_fields": {
              "sku": "SKU-4582",
              "quantity": 2,
              "lot_number": "L-2026-038"
            }
          }
        ],
        "cancel_reason": "nobody",
        "location": {
          "location_id": "4f75d991ac359f8c4c79d762",
          "label": "Location label",
          "country": "Spain",
          "country_code": "ES",
          "state": "Catalonia",
          "city": "Barcelona",
          "street": "Calle de Pau Claris",
          "postal_code": "08302",
          "comments": "Location comments",
          "lat": 40.45,
          "lng": -3.68,
          "main_text": "Calle de Pau Claris 12",
          "secondary_text": "Barcelona, Catalonia, Spain"
        },
        "time_in_stop": 180,
        "custom_fields": {
          "delivered_to": "neighbor 2A",
          "cod_collected": 24.9,
          "photo_count": 2
        },
        "created_at": "2026-05-29T14:55:24.486Z"
      }
    ],
    "report_attempts": 2,
    "survey": {
      "stop_id": "4f75d991ac359f8c4c79d762",
      "route_id": "4f75d991ac359f8c4c79d762",
      "rating": 1,
      "rating_tag": "time",
      "comments": "The delivery was very professional and punctual.",
      "created_at": "2026-05-29T14:55:24.489Z",
      "updated_at": "2026-05-29T14:55:24.489Z"
    },
    "pin": "4729",
    "customer_text_field": "Leave at reception if I'm not home.",
    "supervisors": [
      "4f75d991ac359f8c4c79d762"
    ],
    "location_validation_sent": false,
    "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
    "location_validated": false,
    "location_validated_at": "2026-05-29T14:55:24.500Z",
    "created_by": "4f75d991ac359f8c4c79d762",
    "created_at": "2026-05-29T14:55:24.339Z",
    "updated_at": "2026-05-29T14:55:24.339Z",
    "deleted_at": "2026-05-29T14:55:24.339Z",
    "deleted": true
  }
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
Empty

Create multiple stops

Bulk-creates stops with already known coordinates.

Create stops with automatic geocoding

Bulk-creates stops from free-text addresses.