pixiUpdateSOrderline · Pixi API documentation

Changes a single line of a supplier order (purchase order), identified by SorderlineKey (SupplierOrderLine.Id).

Validation (each failure returns one row with ReturnCode = 'Error' and nothing is changed):

The line must exist.
A non-zero QtyNotDelivered is only accepted if the supplier order has status CON (confirmed).
If the supplier order has status CON or CLS, neither SupplPrice (not NULL) nor OrderQty (non-zero) may be passed.

Preparation

UserName NULL becomes API; the user is resolved by name for the modification stamp.
EstimatedDelivery NULL keeps the current estimated delivery date of the line.
QtyNotDelivered passed explicitly as NULL keeps the current undelivered quantity.

Update (performed by the internal procedure GOS_SOrderlinesUpdate):

Always: comment (Comment = Note), estimated delivery date, modification user/date and row version of the line.
Supplier order in an editable status (internal status id 1 or 2): Qty (an OrderQty of 0 keeps the current quantity), number of packaging units (quantity divided by packaging unit, rounded up), SupplierPrice (only if SupplPrice is non-zero), discount amount/percent and line total are recalculated.
Supplier order with status CON (internal status id 3): UndeliveredQty is set to QtyNotDelivered.
The order header (SupplierOrder) is recalculated: subtotal from all line totals, header discount, freight cost (reset to 0 if the free-of-freight limit is reached), total amount including the minimum order surcharge.
The location quantity record of the line (SupplierOrderLineLocQty) gets the quantity and, for status CON, the undelivered quantity.
If the line has an estimated delivery date after the update, the item is queued for a forced export to the shop.

On success one row with ReturnCode = 'OK' is returned.

Notes

Comment is always overwritten: Note defaults to an empty string, so omitting it clears the existing comment of the line. Pass the current comment to keep it.
Undelivered quantity in status CON: QtyNotDelivered defaults to 0. For a confirmed order, omitting it sets UndeliveredQty to 0. Send it explicitly as NULL (nil) or with the current value to keep it.
QtyReceived is obsolete and ignored.
The line update is built as dynamic SQL; Note is concatenated without escaping, so a single quote (') in the comment breaks the statement. SQL errors from the internal procedure come back as SqlMessage; the final OK row may still be returned in that case.
Internal status ids 1, 2 and 3 are used for the update branches; id 3 corresponds to CON according to a code comment. For other statuses (e.g. CLS) only comment and estimated delivery date are changed.
Discount recalculation divides by quantity × price for amount-based discounts (DiscountType = 1); a zero price or quantity with an existing discount can cause a division-by-zero error.
The shop export is triggered whenever the line has an estimated delivery date, even if EstimatedDelivery was not passed. The export procedure Pixi_ExportItemChangesToShop is not attached.
No explicit transaction; reads use NOLOCK, updates use ROWLOCK.

Tables used

SupplierOrderLine · Write SupplierOrder · Write SupplierOrderStatus · Read SupplierOrderLineLocQty · Write

Parameter	Type	Default	Description
`SorderlineKey` Required	int	–	Id of the supplier order line (`SupplierOrderLine.Id`) to update. Example: `48213`
`UserName` Required	varchar(50) string	–	Pixi user name stored as modifier. NULL is replaced by `API`. Example: `API`
`OrderQty`	int	0	New order quantity. 0 or NULL keeps the current quantity. Only allowed while the supplier order is not in status `CON` or `CLS`. Example: `120`
`Note`	varchar(1024) string	–	Comment of the line. Always written; an empty value clears the existing comment. Must not contain single quotes. Example: `Lieferung in zwei Teilen`
`QtyReceived`	int	0	Obsolete, ignored. Example: `0`
`QtyNotDelivered`	int	0	Undelivered quantity. A non-zero value is only allowed if the supplier order has status `CON`; there it is written to `UndeliveredQty` (also the default 0). Explicit NULL keeps the current value. Example: `10`
`EstimatedDelivery`	datetime dateTime	NULL	New estimated delivery date of the line. NULL keeps the current date. Example: `2024-07-15T00:00:00`
`SupplPrice`	decimal(9, 2) decimal	NULL	New supplier price per unit. NULL or 0 keeps the current price. Only allowed while the supplier order is not in status `CON` or `CLS`. Example: `12.50`

Result set 1 · Always; exactly one row (error row on validation failure, otherwise success row).

Status of the update.

Column	Type	Description
`ReturnCode`	varchar(5) string	`OK` on success, `Error` on a validation failure.
`Message`	varchar(max) string	Success or error text.

Response example

<SqlRowSet1>
  <row>
    <ReturnCode>OK</ReturnCode>
    <Message>Update done successfully.</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	The specified supplier orderline id does not exists: {SorderlineKey}	No supplier order line with the given `SorderlineKey` exists (or it is not linked to a supplier order with a status). Check the line id.
Error	@QtyNotDelivered can only be updated when supplier order is on status CON and @SupplPrice is NULL and @OrderQty is NULL or 0	A non-zero `QtyNotDelivered` was passed while the supplier order is not in status `CON`. Send 0 or omit it for other statuses.
Error	The supplier price and order quantity can not be updated when the purchase order has status confirmed or closed (CON, CLS).	`SupplPrice` (not NULL) or a non-zero `OrderQty` was passed while the supplier order has status `CON` or `CLS`. Omit both for confirmed or closed orders.

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiUpdateSOrderline>
      <SorderlineKey>48213</SorderlineKey>
      <UserName>API</UserName>
      <!-- <OrderQty>120</OrderQty> -->
      <!-- <Note>Lieferung in zwei Teilen</Note> -->
      <!-- <QtyReceived>0</QtyReceived> -->
      <!-- <QtyNotDelivered>10</QtyNotDelivered> -->
      <!-- <EstimatedDelivery>2024-07-15T00:00:00</EstimatedDelivery> -->
      <!-- <SupplPrice>12.50</SupplPrice> -->
    </ns1:pixiUpdateSOrderline>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiUpdateSOrderline>
      <SorderlineKey>48213</SorderlineKey>
      <UserName>API</UserName>
      <!-- <OrderQty>120</OrderQty> -->
      <!-- <Note>Lieferung in zwei Teilen</Note> -->
      <!-- <QtyReceived>0</QtyReceived> -->
      <!-- <QtyNotDelivered>10</QtyNotDelivered> -->
      <!-- <EstimatedDelivery>2024-07-15T00:00:00</EstimatedDelivery> -->
      <!-- <SupplPrice>12.50</SupplPrice> -->
    </ns1:pixiUpdateSOrderline>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    'SorderlineKey' => '48213',
    'UserName' => 'API',
    // 'OrderQty' => '120',
    // 'Note' => 'Lieferung in zwei Teilen',
    // 'QtyReceived' => '0',
    // 'QtyNotDelivered' => '10',
    // 'EstimatedDelivery' => '2024-07-15T00:00:00',
    // 'SupplPrice' => '12.50',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiUpdateSOrderline', $soapArguments);