Change a purchase order (tenant:trade:purchasing:write)
PATCH /api/trade/v1/purchase-orders/{id}
Module: Trade · operationId: updatePurchaseOrder · Tag: Procurement · Auth: access token (Authorization: Bearer <accessToken>)
Only fields sent are changed. Closed and cancelled orders cannot be changed; lines replaces all lines and is only allowed while no goods were received (409). While a supplier API send of the order has no outcome yet or failed (supplierOrder.state sending, or failed through a distributor API), the order cannot be cancelled or closed and its lines cannot be replaced (409), because the distributor may hold it. Once an order went to a distributor API (supplierOrder.channel ingram or infinigate), its lines cannot be replaced at all (409; the supplier line map names the line ids). Orders sent through EGIS (egis, see sendEgisOrder) keep the EGIS rules, and their lines are not checked here. Publishes trade.purchaseorder.updated.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json (required)
currency(string): Currency (ISO 4217).lines(array of POLineInput): Replaces all lines; only before goods were received.description(string, required): Description of the line. (max length 500)orderedQty(number, required): Quantity ordered.articleNumber(string): Article number in masterdata. (max length 100)ean(string): EAN (GTIN) of the article. (max length 32)mpn(string): Manufacturer part number. (max length 100)position(integer): Unique within the order.productId(string (uuid)): Masterdata article (product) id.taxRate(number): Tax rate in percent. (max 100)unit(string): Unit of measure. (max length 20)unitPrice(number): Net unit price.
orderDate(string (date)): Order date.status(string): New status of the purchase order. (one ofdraft,open,closed,cancelled)
Example:
{
"lines": [
{
"articleNumber": "NW-2004",
"description": "Netzwerkschrank 19 Zoll 12 HE",
"orderedQty": 1,
"position": 1,
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
"taxRate": 19,
"unit": "STK",
"unitPrice": 289
},
{
"articleNumber": "NW-2005",
"description": "Verlegekabel Cat.7 Simplex, 100 m",
"orderedQty": 3,
"position": 2,
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
"taxRate": 19,
"unit": "PAK",
"unitPrice": 64
}
],
"orderDate": "2026-11-13",
"status": "open"
}
Responses
- 200 Updated (
application/json) - 400 Error (
application/json) - 401 No valid session or bearer token (no body).
- 404 Not found in the tenant. (
application/json) - 409 Error (
application/json) - 422 The input is not valid for the stored data. (
application/json) - 423 An active workflow locks the transaction. (
application/json)
Fields of the 200 answer:
createdAt(string (date-time)): When the purchase order was created.currency(string): Currency (ISO 4217).dropShip(object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.egis(EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.cargoInsurance(number): Cargo insurance charged.confirmations(array of object): Order confirmations of the distributor.date(string (date)): Date of the confirmation.distributorOrderNumber(string): The distributor's order number.id(integer): EGIS id of the confirmation.lines(array of object): Confirmed lines.deliveryDate(string (date)): Expected delivery date.position(integer): Purchase order line.quantity(number): Planned delivery quantity.supplierArticleNumber(string): The distributor's article number.unitPrice(number): Confirmed net unit price.
deliveryNotes(array of object): Delivery notes of the distributor.date(string (date)): Date of the delivery note.deliveryNoteId(string (uuid)): The inbound delivery note made from it.id(string): EGIS delivery note id.lines(array of object): Delivered lines.description(string): Description of the article.ean(string): EAN (GTIN) of the article.mpn(string): Manufacturer part number.position(integer): Position number of the line.quantity(number): Quantity delivered.serialNumbers(array of string): Serial numbers.supplierArticleNumber(string): The distributor's article number.unit(string): Unit of measure.
number(string): The distributor's delivery note number.packages(array of object): Packages of the shipment.number(string): Tracking number of the package.trackingUrl(string (uri)): Tracking link of the package.
shipper(string): Carrier of the shipment.
distributorId(string): EGIS distributor number.distributorName(string): Name of the distributor the order went to.distributorOrderNumber(string): The distributor's own order number (also stored as the external number of the order when empty).freightCharge(number): Freight including additional charges.invoices(array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.currency(string): Currency (ISO 4217).date(string (date)): Invoice date.grossAmount(number): Gross amount of the invoice.id(integer): EGIS id of the invoice.lines(array of object): Invoiced lines.description(string): Description of the article.netTotal(number): Net total of the line.position(integer): Purchase order line; missing for lines that were not ordered (freight, insurance).quantity(number): Quantity invoiced.supplierArticleNumber(string): The distributor's article number.taxRate(number): Percent.unitPrice(number): Net unit price.
netAmount(number): Net amount of the invoice.number(string): The distributor's invoice number.vatAmount(number): VAT amount of the invoice.
link(string (uri)): The order in the EGIS web application.orderDate(string (date)): Order date at EGIS.orderNumber(string): EGIS order number (leading zeros kept); invoices naming it find the order.paymentMethod(string): Payment method of the order at EGIS.sentAt(string (date-time)): When the order was sent to EGIS.smallQuantitiesMarkup(number): Small-quantity markup charged.statusCode(integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of-1,0,10,20,30,40,50)statusText(string): Status text of EGIS.
goodsReceipts(array of object): Goods receipts of the purchase order.grNumber(string): Number of the goods receipt.id(string (uuid)): Id of the goods receipt.receivedAt(string (date-time)): When the goods were received.status(string): Status of the goods receipt.
id(string (uuid)): Id of the purchase order.lines(array of POLine): Empty in lists.articleNumber(string): Article number in masterdata.description(string): Description of the line.ean(string): EAN (GTIN) of the article.id(string (uuid)): Id of the purchase order line.invoicedQty(number): Always 0.mpn(string): Manufacturer part number.orderedQty(number): Quantity ordered.pcsNumber(string): EGIS PCS number of the article (purchase cart orders).position(integer): Position number of the line.productId(string (uuid)): Masterdata article (product) id.receivedQty(number): Quantity received.sourceLineId(string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).supplierArticleNumber(string): The distributor's article number of the offer the purchase cart chose.taxRate(number): Tax rate in percent.unit(string): Unit of measure.unitPrice(number): Net unit price.
netTotal(number): Net total of the purchase order.orderDate(string (date)): Order date.poNumber(string): Number of the purchase order.sourceOrders(array of object): The sales orders the lines were bought for.id(string (uuid)): Id of the sales order.number(string): Number of the sales order.
sourcing(object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.cartId(string (uuid)): Purchase cart the order was made from.distributorId(string): Distributor the cart optimizer chose.goodsCents(integer): Goods value of the shipment in cents.offerKey(string): Key of the distributor offer.offerKeys(array of string): Every offer key of the order when several share the supplier.optimizedAt(string (date-time)): When the proposal was computed.priceCents(integer): Landed cost (goods and shipment costs) in euro cents.proposalId(string (uuid)): Proposal of the cart the order was made from.shippingCents(integer): Shipping cost of the shipment in cents.source(string): Offer source: egis, ingram, infinigate or masterdata.
status(PurchaseOrderStatus): (one ofdraft,open,partially_received,received,closed,cancelled)supplierAddressId(string (uuid)): Masterdata address of the supplier.supplierOrder(SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.attemptedAt(string (date-time)): When the last API send started.awaitingDocuments(boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.channel(string): How the order went out;manual: ordered by other means and recorded. (one ofingram,infinigate,mail,manual)comment(string): Remark of the last send; a mail sent again without one repeats it.error(string): Why the last send or refresh failed.expectedDeliveryDate(string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).followError(string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.invoices(array of object): Invoices the supplier reported.date(string (date)): Invoice date.grossTotal(number): Gross total.netTotal(number): Net total.number(string): Invoice number of the supplier.
lastFollowedAt(string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).lineMap(object): Supplier line number → purchase order line id.orderNumber(string): The supplier's order number (also stored as the external number of the order when empty).recipient(string (email)): Where the mail went (mail).rejectedLines(array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).lineId(string (uuid)): Id of the purchase order line.reason(string): The supplier's reason.supplierLineNumber(string): The line number the supplier got (key oflineMap).
related(array of string): Further order numbers when the supplier split the order.rematchPending(boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.requestedDeliveryDate(string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.revision(integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.sentAt(string (date-time)): When the order was sent.sentLines(object): What an API send asked for, by supplier line number (key oflineMap); a lost answer is compared with it.shipments(array of object): Shipments the supplier reported.carrier(string): Carrier of the shipment.deliveryNoteId(string (uuid)): The inbound delivery note made from it.handledManually(boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).id(string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).invoiceNumber(string): The supplier's invoice of the shipment.lines(array of object): Lines of the shipment.lineId(string (uuid)): Id of the purchase order line.quantity(number): Quantity shipped.serialNumbers(array of string): Serial numbers.
number(string): The supplier's delivery note number.shippedAt(string (date-time)): When it was shipped.subOrder(string): The supplier's sub order of the shipment (Ingram).takeoverAttempts(integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).takeoverError(string): Why the last hand-over failed.trackingNumber(string): Tracking number of the carrier.trackingUrl(string): Tracking link of the carrier.
shipmentsMissingSince(string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.state(string): State at the supplier (sending,sent,confirmed,partially_shipped,shipped,cancelled,failed). (one ofsending,sent,confirmed,partially_shipped,shipped,cancelled,failed)statusText(string): The supplier's status text.
updatedAt(string (date-time)): When the purchase order was last changed.
Example 200 answer:
{
"createdAt": "2026-11-13T09:12:00Z",
"currency": "EUR",
"goodsReceipts": [],
"id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
"lines": [
{
"articleNumber": "NW-2004",
"description": "Netzwerkschrank 19 Zoll 12 HE",
"id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
"invoicedQty": 0,
"orderedQty": 1,
"position": 1,
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
"receivedQty": 0,
"supplierArticleNumber": "KW-RACK12HE",
"taxRate": 19,
"unit": "STK",
"unitPrice": 289
},
{
"articleNumber": "NW-2005",
"description": "Verlegekabel Cat.7 Simplex, 100 m",
"id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
"invoicedQty": 0,
"orderedQty": 3,
"position": 2,
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
"receivedQty": 0,
"supplierArticleNumber": "KW-CAT7-100",
"taxRate": 19,
"unit": "PAK",
"unitPrice": 64
}
],
"netTotal": 481,
"orderDate": "2026-11-13",
"poNumber": "BE-2026-00068",
"status": "open",
"supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
"supplierOrder": {
"channel": "mail",
"comment": "Bitte an den Wareneingang, Tor 2, liefern.",
"recipient": "bestellung@kabelwerk-sued.example",
"requestedDeliveryDate": "2026-11-20",
"revision": 1,
"sentAt": "2026-11-13T09:20:00Z",
"state": "sent"
},
"updatedAt": "2026-11-13T09:20:00Z"
}
Example request
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"lines":[{"articleNumber":"NW-2004","description":"Netzwerkschrank 19 Zoll 12 HE","orderedQty":1,"position":1,"productId":"4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04","taxRate":19,"unit":"STK","unitPrice":289},{"articleNumber":"NW-2005","description":"Verlegekabel Cat.7 Simplex, 100 m","orderedQty":3,"position":2,"productId":"4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05","taxRate":19,"unit":"PAK","unitPrice":64}],"orderDate":"2026-11-13","status":"open"}'