Allocation API (BETA)

The Allocation API runs the allocation engine as a simulation: it answers which warehouses (stores) an order or basket would ship from, how many shipments that makes, and which alternatives exist. Nothing is written - the order, the cart, and inventory are left as they are. A typical use is a checkout that wants to show delivery options or split-shipment information before the order is placed.

This is the same simulation the allocation simulator runs in the Omnium UI.

Endpoints

The endpoint requires the Admin or ApiUser role.

Simulate allocation

Send exactly one subject:

• orderId or cartId for an order or a cart that already exists in Omnium.
• order or cart for a basket that does not exist in Omnium yet. A checkout normally sends the basket, since it does not exist in Omnium until the order is placed.

Request

Profiles

A profile is a ranking policy. The primary profile decides selectedPlan and is always the first ranking. Omnium picks it in this order:

1. The order's or cart's requestedAllocationProfileKey.
2. The default profile in the allocation settings - set globally, and optionally overridden for the order's market or sales store.
3. Balanced.

An unknown key is skipped and the next source is used. Profiles in profileKeys add more rankings after the primary one, so you can compare policies in one call. The plans are worked out once and each profile only orders them, so asking for three profiles costs little more than asking for one.

Inventory overrides

A checkout that already holds its own availability can pass it in inventoryOverrides instead of relying on Omnium's inventory. You can also use overrides to try a scenario, such as a warehouse running out of a product. The given values replace what Omnium holds for that SKU and warehouse; entries without a skuId or warehouseId are ignored.

Example: simulate a basket at checkout

POST /api/Allocation/Simulate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "cartId": "C123456",
  "profileKeys": ["Closest"],
  "inventoryOverrides": [
    { "skuId": "1003456-42", "warehouseId": "S077", "available": 0 }
  ],
  "includeTrace": false
}

Response

Plan

Planned shipment

Planned line

Ranking

In a ranked plan, score runs from 0 to 1 and the lowest score ranks first, the same direction as rule priority. It is the score of the profile's first tier; later tiers only break ties. breakdown holds the score per objective across all tiers, where lower is also better. labels says what the plan is best at, for showing to a customer: Recommended marks the first plan in that ranking, and FewestShipments, Cheapest, Closest, and MostLikelyToDeliver mark the plans that are best on that measure across all plans.

Unallocatable line and trace entry

An unallocatable line has lineId, skuId, quantity, and reasons - a list of trace entries.

Example response

{
  "requestId": "7f3c2a9e-51b4-4c8e-9d2a-0b6e1f4a8c73",
  "outcome": "Simulated",
  "primaryProfileKey": "Balanced",
  "selectedPlan": {
    "planId": "a41f09c2",
    "shipments": [
      {
        "warehouseId": "S012",
        "sourceShipmentId": null,
        "shippingMethodName": "HomeDelivery",
        "allowedShippingMethodNames": ["HomeDelivery", "PickupPoint"],
        "totalWeightKg": 2.4,
        "distanceKm": 18.6,
        "lines": [
          { "lineId": "1", "skuId": "1003456-42", "quantity": 1, "arrivesOn": null, "purchaseOrderId": null, "purchaseOrderLineId": null, "deliveryId": null },
          { "lineId": "2", "skuId": "2004871-M", "quantity": 2, "arrivesOn": null, "purchaseOrderId": null, "purchaseOrderLineId": null, "deliveryId": null }
        ]
      }
    ],
    "estimatedShippingCost": 79,
    "totalDistanceKm": 18.6,
    "deliveryProbability": 0.83,
    "isPartial": false,
    "shipmentCount": 1
  },
  "plans": [],
  "rankings": [
    {
      "profileKey": "Balanced",
      "selectedPlanId": "a41f09c2",
      "plans": [
        {
          "planId": "a41f09c2",
          "score": 0.12,
          "labels": ["Recommended", "FewestShipments", "Closest"],
          "breakdown": { "SplitCount": 0, "ShippingCost": 0.32, "Distance": 0.04, "DeliveryProbability": 0.17, "WarehousePriority": 0.25, "CurrentWarehouse": 0 }
        }
      ]
    },
    {
      "profileKey": "Closest",
      "selectedPlanId": "a41f09c2",
      "plans": [
        {
          "planId": "a41f09c2",
          "score": 0.04,
          "labels": ["Recommended", "FewestShipments", "Closest"],
          "breakdown": { "Distance": 0.04, "SplitCount": 0, "DeliveryProbability": 0.17 }
        }
      ]
    }
  ],
  "unallocatableLines": [],
  "trace": null,
  "configurationVersion": "3f9a1c07be42",
  "totalMs": 42
}

plans is shortened in this example; in a real response it lists every feasible plan, including the selected one.

Outcomes

Errors

Related documentation

• Allocation simulator - run the same simulation in the Omnium UI and see why the engine decided as it did
• Allocation workflow steps - the workflow steps that allocate and reallocate orders
• Cart API - build the basket you send for simulation

For the full interactive API reference, see the swagger documentation.