> ## Documentation Index
> Fetch the complete documentation index at: https://partner-integrations.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wismotion

Wismotion is a real-time logistics visibility platform that provides tracking and communication around order deliveries. The integration connects Wismotion to Engage via the Orders API, enabling order data storage and automated messaging based on shipment events.

<Warning>
  Consult your Voyado account manager before activating this integration. Also involve Wismotion before starting the implementation.
</Warning>

## Posting an order

Wismotion can create or update orders in Engage depending on how the integration is configured. Orders are posted to:

```http theme={null}
POST /api/v3/orders
```

Use this endpoint when:

* an order has not already been created in Engage by another system, or
* Wismotion is responsible for creating the order record in Engage.

The payload contains order information, a contact reference, and any additional metadata required by the merchant. Once stored, the order data is available for use in automations and messaging.

## Creating a contact

If the contact referenced in an order does not yet exist in Engage, Wismotion can create the contact before posting the order.

```http theme={null}
POST /api/v3/contacts
```

```json Example payload theme={null}
{
  "email": "john.doe@example.com",
  "mobilePhone": "+46123456789",
  "firstName": "John",
  "lastName": "Doe",
  "contactType": "Member"
}
```

After the contact is created, post the order using `POST /api/v3/orders`.

## Updating order status

Wismotion can update the status of an order in Engage when the status changes in Wismotion's system.

```http theme={null}
PUT /api/v3/orders/{orderId}
```

Typical order statuses used in Engage:

* `InProgress`
* `Completed`

Keeping order status in sync lets you branch automation logic — for example, sending different messages depending on whether an order is still being prepared or has been completed.

## Triggering Order Actions from Wismotion

Wismotion's rule engine defines when a shipment event should trigger an **Order Action** in Engage. Order Actions can be used as entry points or conditions in automations.

Supported Order Actions:

* **ConfirmShipment**
* **ConfirmDelivery**
* **ConfirmCancellation**
* **ConfirmCompletion**
* **Custom** – with a custom status text

Order Actions are sent to Engage using:

```http theme={null}
POST /api/v3/orders/{orderId}/action
```

Because order creation and updates are asynchronous, Wismotion must wait until Engage has finished processing the order and returned a `versionTag` before triggering an action. A retry mechanism that polls for a valid `versionTag` is required. See [Orders and actions](https://developer.voyado.com/docs/orders/orders-and-actions) on the Voyado Developer site for details.

<Accordion title="Example payload">
  ```json theme={null}
  {
    "action": "ConfirmShipment",
    "versionTag": "kyvic4wloxoljyfeshtxodig5i",
    "data": {
      "shipment": {
        "id": "6521770000",
        "shipmentNumber": "6521771052",
        "milestoneId": "preparation",
        "statusId": "created",
        "scenarioId": "outbound_delivery",
        "senderReference": "41007232",
        "buyerReference": "41007232",
        "serviceProviderId": "dhlfreight_sweden",
        "serviceProviderParentName": "DHL",
        "numberOfPackages": 1,
        "grossWeight": 2.0,
        "volume": 0.0,
        "notifyAddress": {
          "name": "...",
          "address1": "...",
          "zipCode": "...",
          "city": "...",
          "countryCode": "SE",
          "email": "customer@example.com",
          "smsNumber": "+46123456789",
          "phoneNumber": "+46123456789"
        },
        "trackingUrl": "https://customer.wismotion.com/tracking?mmxat=********"
      }
    }
  }
  ```
</Accordion>

The `action` field determines which Order Action is registered in Engage. The `data` object contains shipment-specific information that can be referenced in automations and communication.

<Tip>
  Order Actions are sent at shipment level. A single order may have multiple shipments — for example, split deliveries. Each shipment event can trigger its own automation and message in Engage.
</Tip>

## Building the automation

Set up an automation in Engage that starts when a relevant Order Action is received from Wismotion.

You can either:

* create one automation per action (e.g. **ConfirmShipment**, **ConfirmDelivery**), or
* use a value split in a single automation and branch on the Order Action type or shipment data.

The automation can send different messages depending on the shipment milestone, carrier, delivery method, or any other field in the `data.shipment` payload.