Stock Write

pixiSetStockMultiple_AH

Sets, adds or removes stock for several items and bins (Lagerplätze) in one call, based on an XML document with stock levels per bin.

Processes an XML document with one or more items and their bins and books the stock changes as stock movements.

Input

If ParameterXML is not empty, it replaces XML.
The whole XML text is converted to upper case before parsing. This applies to element names and to all values, including bin names and batch numbers.
Rows are read from /ITEMSTOCK/ITEM/INVBINS/INVBIN. Each INVBIN becomes one row. The item fields ITEMNRINT, ITEMKEY, EANUPC and OVERWRITESTOCK are read from the parent ITEM.
Empty SMTREF, SMOREF, BATCHNUMBER and BESTBEFOREDATE are treated as NULL.

Item lookup The item is resolved in this order:

by ITEMKEY
by ITEMNRINT, if no key was found
by EANUPC, if still no key was found

Item key, item number and EAN are then taken from the item master.

Overwrite mode If OVERWRITESTOCK = 1 for an item, the call adds a row with target stock 0 for every other bin of that item that currently holds stock (sum of quantities > 0) and is not listed in the XML. These bins are emptied.

Processing per row Only rows with a resolved item and an existing bin name are processed, one by one:

If the item has the batch number tag but the row has no BATCHNUMBER, the row is skipped without any message. If the item has no batch tag, a given batch number is ignored. The same rule applies to the best-before-date tag and BESTBEFOREDATE.
If STOCK is given, the difference to the current quantity in the bin is calculated. A positive difference becomes StockAdd, a negative one becomes StockRemove. With no difference, a row with status 1 and No stock change needed is recorded.
If SMOREF or SMTREF is missing, defaults are used:
- for additions: operation API/PutToStock and movement type 0201
- for removals: operation API/TakeOut and movement type 0301
The stock movement operation must belong to application API, and the operation/type pair must exist in the stock movement matching table. Otherwise the row is not booked.
For StockAdd > 0 the stock is booked in with Pixi_InvBinScanIn. Otherwise, for StockRemove > 0, it is taken out with Pixi_InvBinTakeOut. The location is the BinLocID of the first bin with that name.

Result and follow-up

The final result set lists the processed rows with their status and message.
Rows whose item or bin could not be found are added with status 0.
All resolved items are inserted into pixi.ItemRecalculateStockQueue for stock recalculation and export.

Notes

Extra result sets: for every processed row the code runs an unaliased SELECT of the current SMTREF value. Each of these is returned as its own result set. The actual status result set therefore comes last, after one extra result set per processed row. Read the last SqlRowSetN.
Upper case: because the XML is upper-cased, batch numbers are booked in upper case.
STOCK element: an empty <STOCK/> is converted to 0 and empties the bin. Leave the element out if no absolute value is intended.
Combining fields: when STOCK is given, the computed difference overwrites only one of StockAdd/StockRemove. A STOCKADD sent in the XML can therefore still trigger a scan-in when the difference is negative or zero. Do not combine STOCK with STOCKADD/STOCKREMOVE.
Variable @delta is not reset per row: for rows without STOCK, the validation checks use the difference of the previous row. For the first such row the value is NULL, so the SMO check is skipped.
Rows missing from the result: rows skipped because of a missing batch number or best-before date, and rows failing the "SMO not assigned to API" check, produce no result row.
What is ignored: NEUTRALINVENTORY is read but not used. The setting FilterStockOperationsWithLocation is read but not passed on.
Current quantity: the difference is calculated over all bins with the same name and over all batches. The location is taken with TOP 1 without ordering, so duplicate bin names across locations can lead to unexpected bookings.
Transactions: there is no overall transaction. Each booking runs in its own transaction inside Pixi_InvBinScanIn/Pixi_InvBinTakeOut. A failing row does not roll back earlier rows.
Called procedures: Pixi_InvBinScanIn_Base and Pixi_InvBinTakeOut_Base are not attached, so their exact checks and messages are unknown. The quantity limit MaxStockOperationLimit applies.
Master data reads use NOLOCK.

Parameters

Parameter Type Default Description

Parameter	Type	Default	Description
`XML`	varchar(max) xml	NULL	XML document with items and their bins and stock values. Ignored if `ParameterXML` is not empty. Example: `<ITEMSTOCK> <ITEM> <ITEMNRINT>A-1001</ITEMNRINT> <ITEMKEY>12345</ITEMKEY> <EANUPC>4006381333931</EANUPC> <OVERWRITESTOCK>0</OVERWRITESTOCK> <INVBINS> <INVBIN> <BINNAME>A-01-01</BINNAME> <STOCK>25</STOCK> <STOCKADD>0</STOCKADD> <STOCKREMOVE>0</STOCKREMOVE> <NEUTRALINVENTORY>0</NEUTRALINVENTORY> <SMTREF/> <SMOREF/> <BATCHNUMBER>CH-2024-001</BATCHNUMBER> <BESTBEFOREDATE>2025-12-31T00:00:00</BESTBEFOREDATE> </INVBIN> </INVBINS> </ITEM> </ITEMSTOCK>`
`ParameterXML`	varchar(max) xml	NULL	Alternative input with the same structure as `XML`. Takes precedence over `XML` if not empty. Example: `<ITEMSTOCK> <ITEM> <ITEMNRINT>A-1001</ITEMNRINT> <ITEMKEY>12345</ITEMKEY> <EANUPC>4006381333931</EANUPC> <OVERWRITESTOCK>1</OVERWRITESTOCK> <INVBINS> <INVBIN> <BINNAME>A-01-01</BINNAME> <STOCK>10</STOCK> <STOCKADD>0</STOCKADD> <STOCKREMOVE>0</STOCKREMOVE> <NEUTRALINVENTORY>0</NEUTRALINVENTORY> <SMTREF/> <SMOREF/> <BATCHNUMBER/> <BESTBEFOREDATE/> </INVBIN> </INVBINS> </ITEM> </ITEMSTOCK>`
`Username`	varchar(50) string	pipiSetStockMultiple	User name recorded for the stock movements. Example: `ShopImport`

XML

varchar(max)
xml

NULL

XML document with items and their bins and stock values. Ignored if ParameterXML is not empty.

Example:

<ITEMSTOCK>
  <ITEM>
    <ITEMNRINT>A-1001</ITEMNRINT>
    <ITEMKEY>12345</ITEMKEY>
    <EANUPC>4006381333931</EANUPC>
    <OVERWRITESTOCK>0</OVERWRITESTOCK>
    <INVBINS>
      <INVBIN>
        <BINNAME>A-01-01</BINNAME>
        <STOCK>25</STOCK>
        <STOCKADD>0</STOCKADD>
        <STOCKREMOVE>0</STOCKREMOVE>
        <NEUTRALINVENTORY>0</NEUTRALINVENTORY>
        <SMTREF/>
        <SMOREF/>
        <BATCHNUMBER>CH-2024-001</BATCHNUMBER>
        <BESTBEFOREDATE>2025-12-31T00:00:00</BESTBEFOREDATE>
      </INVBIN>
    </INVBINS>
  </ITEM>
</ITEMSTOCK>

ParameterXML

varchar(max)
xml

NULL

Alternative input with the same structure as XML. Takes precedence over XML if not empty.

Example:

<ITEMSTOCK>
  <ITEM>
    <ITEMNRINT>A-1001</ITEMNRINT>
    <ITEMKEY>12345</ITEMKEY>
    <EANUPC>4006381333931</EANUPC>
    <OVERWRITESTOCK>1</OVERWRITESTOCK>
    <INVBINS>
      <INVBIN>
        <BINNAME>A-01-01</BINNAME>
        <STOCK>10</STOCK>
        <STOCKADD>0</STOCKADD>
        <STOCKREMOVE>0</STOCKREMOVE>
        <NEUTRALINVENTORY>0</NEUTRALINVENTORY>
        <SMTREF/>
        <SMOREF/>
        <BATCHNUMBER/>
        <BESTBEFOREDATE/>
      </INVBIN>
    </INVBINS>
  </ITEM>
</ITEMSTOCK>

Username

varchar(50)
string

pipiSetStockMultiple

User name recorded for the stock movements.

Example: ShopImport

Response

Result set 1 · Once per processed row, i.e. a row with a resolved item and existing bin that was not skipped by the batch/best-before check.

Unintended debug output: the SMTREF value of the current row before defaults are applied. The column has no name in SQL; the client assigns a generic name.

Column	Type	Description
`Column1` Nullable	int	Stock movement type reference of the current row, NULL if not given.

Result set 2 · Always, as the last result set.

Status per item/bin. The first part contains processed rows with their recorded message. The second part contains rows whose item or bin was not found, with status 0.

Column	Type	Description
`ItemNrInt` Nullable	varchar(50) string	Internal item number.
`ItemKey` Nullable	int	Item key, NULL if the item was not found.
`Ean` Nullable	varchar(13) string	EAN/UPC of the item.
`BinName` Nullable	varchar(50) string	Bin name (upper case).
`Stock` Nullable	int	Target stock as sent in the XML, or 0 for bins added by overwrite mode.
`StockAdd` Nullable	int	Quantity to add as sent in the XML, not the computed difference.
`StockRemove` Nullable	int	Quantity to remove as sent in the XML, not the computed difference.
`Error` Nullable	varchar(8000) string	Message of the booking or validation, e.g. `No stock change needed`, `Item not found`.
`Reason` Nullable	varchar(50) string	Empty for XML rows; for rows added by overwrite mode the reason stored on the bin item.
`SmoRef` Nullable	int	Stock movement operation reference as sent in the XML.
`SmtRef` Nullable	int	Stock movement type reference as sent in the XML.
`status` Nullable	int	Success flag: 1 = success, 0 = error; for bookings the return value of the scan-in/take-out procedure.
`BatchNumber` Nullable	varchar(50) string	Batch number (Charge) as sent in the XML.
`BestBeforeDate` Nullable	datetime dateTime	Best-before date as sent in the XML.

Response example

<SqlRowSet1>
  <row>
    <Column1>12</Column1>
  </row>
</SqlRowSet1>

Error messages

Status	Message	Cause
RAISERROR	Error Message: API pipiSetStockMultiple: SMO is not assigned to API!	The stock movement operation in `SMOREF` (or the default) does not belong to application `API`. Raised with severity 10 (informational); the row is not booked and does not appear in the result. Use an SMO of application `API`.
0	Error Message: API pipiSetStockMultiple: SMT is not matched to SMO - please check Control Center - Stock Movements matching table! ItemKey = {ItemKey}, BinName = {BinName}	The combination of `SMOREF` and `SMTREF` is not in the stock movement matching table. The message is also written to `LogTable` and raised with severity 1. Maintain the matching in the Control Center.
0	Item and Bin not found	Neither the item (by key, number or EAN) nor the bin name could be found.
0	Item not found	The item could not be resolved by `ITEMKEY`, `ITEMNRINT` or `EANUPC`.
0	Bin not found	No bin with the given `BINNAME` exists.
RAISERROR	Stock can not be set, scan in stock quantity is greater than limit of setting: MaxStockOperationLimit!	Raised by the called `Pixi_InvBinScanIn` when the quantity to add exceeds the setting `MaxStockOperationLimit`.
RAISERROR	Stock can not be set, take out stock quantity is greater than limit of setting: MaxStockOperationLimit!	Raised by the called `Pixi_InvBinTakeOut` when the quantity to remove exceeds the setting `MaxStockOperationLimit`.

Examples

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:pixiSetStockMultiple_AH>
      <!-- <XML><![CDATA[<ITEMSTOCK><ITEM><ITEMNRINT>A-1001</ITEMNRINT><ITEMKEY>12345</ITEMKEY><EANUPC>4006381333931</EANUPC><OVERWRITESTOCK>0</OVERWRITESTOCK><INVBINS><INVBIN><BINNAME>A-01-01</BINNAME><STOCK>25</STOCK><STOCKADD>0</STOCKADD><STOCKREMOVE>0</STOCKREMOVE><NEUTRALINVENTORY>0</NEUTRALINVENTORY><SMTREF></SMTREF><SMOREF></SMOREF><BATCHNUMBER>CH-2024-001</BATCHNUMBER><BESTBEFOREDATE>2025-12-31T00:00:00</BESTBEFOREDATE></INVBIN></INVBINS></ITEM></ITEMSTOCK>]]></XML> -->
      <!-- <ParameterXML><![CDATA[<ITEMSTOCK><ITEM><ITEMNRINT>A-1001</ITEMNRINT><ITEMKEY>12345</ITEMKEY><EANUPC>4006381333931</EANUPC><OVERWRITESTOCK>1</OVERWRITESTOCK><INVBINS><INVBIN><BINNAME>A-01-01</BINNAME><STOCK>10</STOCK><STOCKADD>0</STOCKADD><STOCKREMOVE>0</STOCKREMOVE><NEUTRALINVENTORY>0</NEUTRALINVENTORY><SMTREF></SMTREF><SMOREF></SMOREF><BATCHNUMBER></BATCHNUMBER><BESTBEFOREDATE></BESTBEFOREDATE></INVBIN></INVBINS></ITEM></ITEMSTOCK>]]></ParameterXML> -->
      <!-- <Username>ShopImport</Username> -->
    </ns1:pixiSetStockMultiple_AH>
  </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:pixiSetStockMultiple_AH>
      <!-- <XML><![CDATA[<ITEMSTOCK><ITEM><ITEMNRINT>A-1001</ITEMNRINT><ITEMKEY>12345</ITEMKEY><EANUPC>4006381333931</EANUPC><OVERWRITESTOCK>0</OVERWRITESTOCK><INVBINS><INVBIN><BINNAME>A-01-01</BINNAME><STOCK>25</STOCK><STOCKADD>0</STOCKADD><STOCKREMOVE>0</STOCKREMOVE><NEUTRALINVENTORY>0</NEUTRALINVENTORY><SMTREF></SMTREF><SMOREF></SMOREF><BATCHNUMBER>CH-2024-001</BATCHNUMBER><BESTBEFOREDATE>2025-12-31T00:00:00</BESTBEFOREDATE></INVBIN></INVBINS></ITEM></ITEMSTOCK>]]></XML> -->
      <!-- <ParameterXML><![CDATA[<ITEMSTOCK><ITEM><ITEMNRINT>A-1001</ITEMNRINT><ITEMKEY>12345</ITEMKEY><EANUPC>4006381333931</EANUPC><OVERWRITESTOCK>1</OVERWRITESTOCK><INVBINS><INVBIN><BINNAME>A-01-01</BINNAME><STOCK>10</STOCK><STOCKADD>0</STOCKADD><STOCKREMOVE>0</STOCKREMOVE><NEUTRALINVENTORY>0</NEUTRALINVENTORY><SMTREF></SMTREF><SMOREF></SMOREF><BATCHNUMBER></BATCHNUMBER><BESTBEFOREDATE></BESTBEFOREDATE></INVBIN></INVBINS></ITEM></ITEMSTOCK>]]></ParameterXML> -->
      <!-- <Username>ShopImport</Username> -->
    </ns1:pixiSetStockMultiple_AH>
  </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 = [
    // 'XML' => '<ITEMSTOCK><ITEM><ITEMNRINT>A-1001</ITEMNRINT><ITEMKEY>12345</ITEMKEY><EANUPC>4006381333931</EANUPC><OVERWRITESTOCK>0</OVERWRITESTOCK><INVBINS><INVBIN><BINNAME>A-01-01</BINNAME><STOCK>25</STOCK><STOCKADD>0</STOCKADD><STOCKREMOVE>0</STOCKREMOVE><NEUTRALINVENTORY>0</NEUTRALINVENTORY><SMTREF></SMTREF><SMOREF></SMOREF><BATCHNUMBER>CH-2024-001</BATCHNUMBER><BESTBEFOREDATE>2025-12-31T00:00:00</BESTBEFOREDATE></INVBIN></INVBINS></ITEM></ITEMSTOCK>',
    // 'ParameterXML' => '<ITEMSTOCK><ITEM><ITEMNRINT>A-1001</ITEMNRINT><ITEMKEY>12345</ITEMKEY><EANUPC>4006381333931</EANUPC><OVERWRITESTOCK>1</OVERWRITESTOCK><INVBINS><INVBIN><BINNAME>A-01-01</BINNAME><STOCK>10</STOCK><STOCKADD>0</STOCKADD><STOCKREMOVE>0</STOCKREMOVE><NEUTRALINVENTORY>0</NEUTRALINVENTORY><SMTREF></SMTREF><SMOREF></SMOREF><BATCHNUMBER></BATCHNUMBER><BESTBEFOREDATE></BESTBEFOREDATE></INVBIN></INVBINS></ITEM></ITEMSTOCK>',
    // 'Username' => 'ShopImport',
];

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

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

pixiSetStockMultiple

Tables used

items · Read InvBin · Read InvBinItem · Read StockMovementOperations · Read StockMovementTypes · Read StockMovementMatching · Read Settings · Read TagMatch · Read LogTable · Write ItemRecalculateStockQueue · Write

SQL object:: dbo.pipiSetStockMultiple_AH