pixiUpdateOrderline · Pixi API documentation

Changes a single order line (OrderlineKey) or a bundle order line (BundleOrderlineKey) and returns a result row with 1 (executed) or 0 (rejected).

Key selection

BundleOrderlineKey = 0 is treated as NULL.
If both keys are missing, an informational message is raised and result = 0 is returned.
If BundleOrderlineKey is set, OrderlineKey is ignored.

Changeability check The line, or for a bundle every component order line, must fulfil all of the following:

its order state (OrderStates) is not a final state (FinalState is N or empty),
its status is not EIN,
it is not packed in a box (boxitems),
it is not on an invoice (Invlines).

If a single line fails the check, nothing is changed and result = 0 is returned.

Merging with current values Every parameter left out (NULL) keeps the value stored on the line. For ArtName, oItemSpecialNote and SerialNumber an empty string also keeps the stored value. For bundles the serial number is not processed. If the resulting Price is higher than FullPrice, FullPrice is raised to Price. The same rule applies to the net values.

Update The internal procedure Pixi_UpdateOrderline is then run with update user API. It does the following:

updates the order line, or the bundle order line, with quantity, gross/net price, confirmation date, name, note, serial number, full prices, discount percentage/value and DF_type;
for bundles, also sets DF_type on all component order lines;
writes the current header values (address remarks, gift message and, if a shipping instruction exists, shipping instruction, Verfahren, Product, Extras) back to OrderHeader;
synchronises the voucher of the order (see notes);
rebuilds the reservations of the whole order if any of its lines has a reservation.

Finally result = 1 is returned.

Notes

Non-existent key: if OrderlineKey or BundleOrderlineKey does not exist, the check finds no row and does not reject the call. Nothing is updated, but result = 1 is still returned.
Messages instead of errors: all RAISERROR calls use severity 0. They arrive only as SqlMessage, not as SQL errors.
Invoice check: if Pixi_UpdateOrderline finds an invoice line, it raises its message and changes nothing. result = 1 is still returned afterwards.
Net prices: the net price and net full price are initialised with the passed gross values (Price, FullPrice). The line price is then converted by dbo.fPixi_CalculatePrices (not attached) using tax rate and order type. FullPrice_Net is stored without conversion, so after passing FullPrice it holds the same value as FullPrice.
Types: DiscountPerc is passed as numeric(6,2) and is therefore rounded to two decimals. GiftMessage is passed as varchar(1000).
Values cannot be cleared: ArtName, oItemSpecialNote and SerialNumber cannot be cleared through this call.
Voucher handling (based on the voucher code of the line and OrderHeader.Discount):
- If the voucher exists with a different amount, its amount is set to the order discount.
- If that discount is 0, VoucherID is cleared on all lines and bundle lines of the order.
- If the voucher does not exist and the code is not NULL, a voucher is created (valid for about one year from the order date, single use, shop GRM) and assigned to all lines of the order.
Reservations: reservations are removed and recreated by Pixi_Res_RemoveReservationForOrder and Pixi_Res_CreateReservationForOrder. These procedures are not attached and may produce further output.
Transactions and errors: the update runs in a transaction, or a savepoint if a transaction is already open. On an exception it is rolled back, a row with the error message and the error count is returned (unnamed columns), the error is logged via log.InsertError, and result = 1 follows anyway.
Locking: the checks read with NOLOCK; updates use ROWLOCK.

Tables used

Orderlines · Write BundleOrderlines · Write OrderHeader · Write Voucher · Write OrderStates · Read boxitems · Read Invlines · Read Currency · Read Reservation · Read

Parameter	Type	Default	Description
`OrderlineKey`	int	NULL	Key of the order line to change. Ignored if `BundleOrderlineKey` is set. Example: `123456`
`ArtName`	varchar(120) string	NULL	New item name on the line. `NULL` or empty keeps the current name. Example: `T-Shirt Basic blau XL`
`Qty`	int	NULL	New quantity. `NULL` keeps the current quantity. Example: `2`
`Price`	money decimal	NULL	New unit price, also used as the input for the net price. `NULL` keeps the current price. Example: `19.95`
`FullPrice`	money decimal	NULL	New full (undiscounted) price, also stored as net full price. Raised to `Price` if lower. `NULL` keeps the current value. Example: `24.95`
`oItemSpecialNote`	varchar(8000) string	NULL	Special note for the line. `NULL` or empty keeps the current note. Example: `Bitte als Geschenk verpacken`
`DiscountValue`	money decimal	NULL	Discount amount of the line. `NULL` keeps the current value. Example: `5.00`
`DiscountPerc`	float decimal	NULL	Discount percentage of the line, stored with two decimals. `NULL` keeps the current value. Example: `20`
`DF_Type`	varchar(1) string	NULL	Direct-fulfillment type of the line (`DF_type`). For bundles also applied to all component lines. `NULL` keeps the current value. Example: `N`
`SerialNumber`	varchar(50) string	NULL	Serial number of the order line. `NULL` or empty keeps the current value. Not processed for bundle order lines. Example: `SN-2024-000815`
`BundleOrderlineKey`	int	NULL	Key of the bundle order line to change. `0` is treated as `NULL`. Takes precedence over `OrderlineKey`. Example: `0`

Result set 1 · If no key was sent or the line (or a bundle component) cannot be changed any more.

Status row signalling that nothing was changed.

Column	Type	Description
`result`	int	Always `0`.

Result set 2 · Only if an exception occurs inside the internal update procedure.

Error row of Pixi_UpdateOrderline with unnamed columns. Clients typically see them as Column1 and Column2. The changes are rolled back.

Column	Type	Description
`Column1` Nullable	nvarchar(4000) string	Error message (`ERROR_MESSAGE()`).
`Column2` Nullable	int	Accumulated error count.

Result set 3 · After the line passed the check and the internal update was run (also if it changed nothing or failed).

Status row signalling that the update was executed.

Column	Type	Description
`result`	int	Always `1`.

Response example

<SqlRowSet1>
  <row>
    <result>1</result>
  </row>
</SqlRowSet1>

Status	Message	Cause
RAISERROR	ERROR: No orderline or bundle key was sent!	Neither `OrderlineKey` nor a non-zero `BundleOrderlineKey` was passed. Informational message (severity 0), followed by `result = 0`.
RAISERROR	ERROR: Can't change orderline, since invoice is already created!	Raised by the internal procedure `Pixi_UpdateOrderline` when an invoice line exists for the line. Informational message (severity 0); nothing is changed.
ERROR	{ERROR_MESSAGE()}	Any SQL error during the update inside `Pixi_UpdateOrderline`. It is returned as a row with unnamed columns, and the transaction is rolled back.

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:pixiUpdateOrderline>
      <!-- <OrderlineKey>123456</OrderlineKey> -->
      <!-- <ArtName>T-Shirt Basic blau XL</ArtName> -->
      <!-- <Qty>2</Qty> -->
      <!-- <Price>19.95</Price> -->
      <!-- <FullPrice>24.95</FullPrice> -->
      <!-- <oItemSpecialNote>Bitte als Geschenk verpacken</oItemSpecialNote> -->
      <!-- <DiscountValue>5.00</DiscountValue> -->
      <!-- <DiscountPerc>20</DiscountPerc> -->
      <!-- <DF_Type>N</DF_Type> -->
      <!-- <SerialNumber>SN-2024-000815</SerialNumber> -->
      <!-- <BundleOrderlineKey>0</BundleOrderlineKey> -->
    </ns1:pixiUpdateOrderline>
  </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:pixiUpdateOrderline>
      <!-- <OrderlineKey>123456</OrderlineKey> -->
      <!-- <ArtName>T-Shirt Basic blau XL</ArtName> -->
      <!-- <Qty>2</Qty> -->
      <!-- <Price>19.95</Price> -->
      <!-- <FullPrice>24.95</FullPrice> -->
      <!-- <oItemSpecialNote>Bitte als Geschenk verpacken</oItemSpecialNote> -->
      <!-- <DiscountValue>5.00</DiscountValue> -->
      <!-- <DiscountPerc>20</DiscountPerc> -->
      <!-- <DF_Type>N</DF_Type> -->
      <!-- <SerialNumber>SN-2024-000815</SerialNumber> -->
      <!-- <BundleOrderlineKey>0</BundleOrderlineKey> -->
    </ns1:pixiUpdateOrderline>
  </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 = [
    // 'OrderlineKey' => '123456',
    // 'ArtName' => 'T-Shirt Basic blau XL',
    // 'Qty' => '2',
    // 'Price' => '19.95',
    // 'FullPrice' => '24.95',
    // 'oItemSpecialNote' => 'Bitte als Geschenk verpacken',
    // 'DiscountValue' => '5.00',
    // 'DiscountPerc' => '20',
    // 'DF_Type' => 'N',
    // 'SerialNumber' => 'SN-2024-000815',
    // 'BundleOrderlineKey' => '0',
];

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

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