Optimize a purchase cart (tenant:purchase-cart:write)
POST /api/trade/v1/purchase-carts/{id}/optimize
Module: Trade · operationId: optimizePurchaseCart · Tag: Purchasing · Auth: access token (Authorization: Bearer <accessToken>)
Gathers the offers of every enabled distributor connector (and the supplier prices of masterdata articles) for
the lines not ordered yet and splits them by the lowest landed cost (goods plus shipping, surcharges and drop-ship
fees per shipment, procurement settings). The proposal is stored at the cart for its current version; a
connector that failed is named in warnings, a line no usable offer covers in unassigned. Accept it with
acceptPurchaseCartProposal before the offers expire (procurement.offerTtlMinutes).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Responses
- 200 The proposal (
application/json) - 401 No valid session or bearer token (no body).
- 403 Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (
application/json) - 404 Not found in the tenant. (
application/json) - 409 The cart does not allow it (
code):cart_not_open(ordered or discarded),recommendation_not_open,line_ordered(the line is on a purchase order),nothing_to_order,no_proposal(optimize first),proposal_stale/cart_changed(optimize again),accept_in_progress(an optimization, accept or order of the cart is running; retry shortly),drop_ship_no_address(a drop-ship order has no delivery address). (application/json) - 502 A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (
application/json) - 503 Offers are not available in this installation. (
application/json)
Fields of the 200 answer:
accepted(object): Per group (supplier and ship-to) the purchase order it became.acceptedAt(string (date-time)): Set when every group is accepted.cartVersion(integer): Version of the cart the proposal was computed for.id(string): Id of the proposal.maxDays(integer): Longest delivery time of the proposal in days.method(string): Solver that found the proposal (exact,subsets,heuristic).naiveTotalCents(integer): Every line at its cheapest offer, each from its own shipment.offers(object): The offers used, per article key.optimizedAt(string (date-time)): When the proposal was computed.savingsCents(integer): Savings against buying every line at its cheapest offer separately, in cents.shipments(array of object): One future purchase order each (offer key and ship-to).assignments(array of object): Cart lines the shipment carries.lineCents(integer): Line total in cents: round(priceCents×quantity).lineId(string (uuid)): Id of the cart line.offerKey(string): Key of the distributor offer.priceCents(integer): Unit price in cents.quantity(number): Quantity assigned.
days(integer): Delivery days.dropShip(boolean): The shipment goes straight to the customer.dropShipFeeCents(integer): Drop-ship fee in cents.freightQuoted(boolean):shippingCentsis the distributor's freight estimate (Ingram) instead of the configured shipping cost.goodsCents(integer): Goods value in cents.offerKey(string): Key of the distributor offer the shipment uses.shipToKey(string):stockor the drop-ship address key.shippingCents(integer): Shipping cost in cents.supplierAddressId(string): Masterdata address of the supplier.surchargeCents(integer): Minimum-order surcharge in cents.totalCents(integer): Total of the shipment in cents.
totalCents(integer): Total of the proposal in cents.unassigned(array of object): Lines (or rests) no usable offer covers.lineId(string (uuid)): Id of the cart line.missingQty(number): Quantity no offer covers.reason(string): Why it could not be assigned (e.g.insufficient_availability,minimum_order_not_reached).
warnings(array of object): Sources that failed while the offers were gathered; their offers are missing.connector(string): Connector that did not answer fully.message(string): What went wrong.
Example 200 answer:
{
"cartVersion": 4,
"id": "c4f1a2b3-wk47-optimum",
"maxDays": 2,
"method": "exact",
"naiveTotalCents": 222650,
"offers": {
"HW-1007": [
{
"available": 140,
"days": 1,
"distributorId": "70044",
"distributorName": "Nordlicht IT-Distribution GmbH",
"fetchedAt": "2026-11-19T07:39:58Z",
"key": "egis:70044",
"priceCents": 7900,
"source": "egis",
"supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
"supplierArticleNumber": "NL-HS-USB-ANC",
"supplierName": "Nordlicht IT-Distribution GmbH"
}
],
"NW-2002": [
{
"available": null,
"days": 2,
"distributorId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
"fetchedAt": "2026-11-19T07:39:58Z",
"key": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
"priceCents": 15900,
"source": "masterdata",
"supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
"supplierArticleNumber": "KW-AP-WIFI6",
"supplierName": "Kabelwerk Süd GmbH"
}
]
},
"optimizedAt": "2026-11-19T07:40:00Z",
"savingsCents": 0,
"shipments": [
{
"assignments": [
{
"lineCents": 95400,
"lineId": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
"offerKey": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
"priceCents": 15900,
"quantity": 6
}
],
"days": 2,
"dropShip": false,
"dropShipFeeCents": 0,
"freightQuoted": false,
"goodsCents": 95400,
"offerKey": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
"shipToKey": "stock",
"shippingCents": 0,
"supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
"surchargeCents": 0,
"totalCents": 95400
},
{
"assignments": [
{
"lineCents": 126400,
"lineId": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
"offerKey": "egis:70044",
"priceCents": 7900,
"quantity": 16
}
],
"days": 1,
"dropShip": false,
"dropShipFeeCents": 0,
"freightQuoted": false,
"goodsCents": 126400,
"offerKey": "egis:70044",
"shipToKey": "stock",
"shippingCents": 850,
"supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
"surchargeCents": 0,
"totalCents": 127250
}
],
"totalCents": 222650,
"unassigned": [],
"warnings": []
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/optimize' \
-H "Authorization: Bearer $ACCESS_TOKEN"