Order Status Update Ep

POST /v1/order/update_status

Update Order Status

Updates the delivery status of an order and sends it to the destination system.

Required Scopes (order:update_status)

Headers

Header	Type	Required	Description
X-Tenant-Name	str	No	Name of the origin tenant making the request. Optional if you are authenticated by API key.
X-Origin-Instance-Name	str \| None	No	Name of the instance creating the request. Optional if you are authenticated by API key.
X-Dest-Tenant-Name	str	Yes	Name of the destination tenant that will receive the request

Request

order: OrderRequest
Identifies the order to update. Provide either field - the system resolves direction automatically.

Show OrderRequest Attributes

order_id: str | None = None
The Crossroads order ID (if known).

order_number: str | None = None
Your order number. Crossroads will look for orders created by you and created by others and sent to you.

location: TerminalMappingKey | None = None
Location for load/drop status updates. Required unless progress_status is "complete".

Show MappingKey Attributes

At least one of source_id, source_name, or mapping_id must be provided. Crossroads recommends that you provide source_id.

source_id: str | None = None
Unique identifier of the counterparty in the source system. Matched against the mapping's source_id field.

source_name: str | None = None
Display name of the entity in the source system. Matched against the mapping's display_name field.

mapping_id: str | None = None
Database ID of the mapping record. Use when you have previously looked up or cached the mapping.

progress_status: OrderProgressStatus
Current delivery status.

Completing Orders

Please note that to mark an order as fully complete, the progress_status must be set to complete after all loads and drops have been submitted. The complete status indicates that the order has been fully processed and no further updates are expected.

Order Progress Status

assigned - Order has been assigned to a driver or carrier.

driving_to_load - Driver is en route to the loading terminal.

arrived_at_load - Driver has arrived at the loading terminal.

loading - Driver is actively loading product.

completed_load - Loading is complete.

driving_to_drop - Driver is en route to the delivery site.

arrived_at_drop - Driver has arrived at the delivery site.

dropping - Driver is actively delivering product.

completed_drop - Delivery is complete.

complete - Order is fully complete.

eta: datetime | None = None
Estimated time of arrival. For backwards compatibility, delivery_eta may copy the value in this field.

delivery_eta: datetime | None = None
Estimated time of delivery. If this field is not provided it will be copied from the eta field.

actual: datetime | None = None
Actual time of event.

assigned_to: str | None = None
Who the order is assigned to, typically a driver or counterparty. Maximum 50 characters.

hauled_by: str | None = None
The company hauling the order. If not provided, defaults to the originating tenant name.

Response

status: str
Crossroads integration status. Each status represents a step in the integration pipeline.

Integration Stages

pending
The request has been accepted and is being processed asynchronously.

requested
The order has been created and is awaiting manual acceptance by the destination tenant.

origin_mapped
The order has been received by crossroads and needs mapping to crossroads master data.

master_mapped
The order has been mapped to crossroads master data and needs mapping to the destination system.

destination_mapped
The order has been mapped to the destination system and is ready to be sent.

synced
The order has been successfully sent to the destination system.

canceled
The order has been canceled.

error
An error occurred during processing. Check the message and log for details.

rejected
The order was rejected by the destination system. Check the message and log for details.

message: str | None = None
Status message or error details.

log: CrossroadsLogV2 | None = None
Processing log entry.

status_update: OrderStatusUpdate | None = None
The status update record.

Show Child Attributes

progress_status: OrderProgressStatus
The delivery status that was set.

location: TerminalMappingKey | None
Location where the status update occurred.

eta: datetime | None
Estimated time of arrival if provided.

delivery_eta: datetime | None
Estimated time of delivery.

actual: datetime | None
Actual time of event if provided.

Responses

Successful Response

application/json

Example (from schema)

{
  "status": "origin_mapped",
  "status_update": {
    "location": {
      "mapping_id": "5eb7cf5a86d9755df3a6c593",
      "source_name": "string",
      "source_id": "string",
      "goid": "string",
      "goid_name": "string"
    },
    "site": {
      "mapping_id": "5eb7cf5a86d9755df3a6c593",
      "source_name": "string",
      "source_id": "string",
      "goid": "string",
      "goid_name": "string"
    },
    "progress_status": "no_progress",
    "eta": "2026-05-11T19:25:51.324Z",
    "delivery_eta": "2026-05-11T19:25:51.324Z",
    "actual": "2026-05-11T19:25:51.324Z",
    "assigned_to": "string"
  },
  "log": {
    "_id": "5eb7cf5a86d9755df3a6c593",
    "title": "string",
    "date": "2026-05-11T19:25:51.325Z",
    "status": "unknown",
    "severity": "low",
    "routing": {
      "origin_tenant_id": "string",
      "origin_tenant_name": "string",
      "origin_source_system": "string",
      "origin_source_system_id": "string",
      "origin_instance_id": "string",
      "origin_instance_name": "string",
      "destination_tenant_id": "string",
      "destination_tenant_name": "string",
      "destination_source_system": "string",
      "destination_source_system_id": "string",
      "destination_instance_id": "string",
      "destination_instance_name": "string"
    },
    "detail": {
      "category": "crossroads",
      "message": "Unhandled System Error. Please retry or contact support.",
      "message_short": "System Error",
      "traceback": "string"
    },
    "metadata": {
      "type": "order",
      "group_id": "string",
      "origin_order_number": "string",
      "crossroads_order_id": "string"
    },
    "worker_name": "Crossroads",
    "correlation_id": "string",
    "retried": false,
    "saga_id": "string",
    "saga_type": "string",
    "send_notification": true,
    "outbound_request": {},
    "inbound_request": {}
  },
  "message": "string"
}

Validation Error

application/json

Example (from schema)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Order Status Update Ep

/v1/order/update_status

Update Order Status

Headers​

Request​

Response​

Responses​

Headers

Request

Response

Responses