Suppliers Write

pixiCreateDeliveryItem

Adds a new item line to an open supplier delivery, identified by delivery key or number, and returns the created delivery line.

Creates one new line (SDelDetail) in a supplier delivery (SDelHeader).

Normalisation: empty values are treated as not given. For the numeric parameters this means that 0 counts as empty: SDelHKey = 0 and SDelHNr = 0 become NULL. Quantities and prices that are not given become 0.
Mandatory input: either SDelHKey or SDelHNr, and either EANUPC or ItemNrInternal, must be set.
Item lookup: the item is searched with COALESCE(EANUPC, ItemNrInternal) among the scannable item codes (pixi.ItemCode joined with ItemCodeType, Scannable = 1). If EANUPC is set, ItemNrInternal is ignored.
Delivery lookup: if SDelHKey is empty, the key is taken from the first delivery with SDelHNr. If both are given, SDelHKey wins.
Checks:
- The delivery must exist and must not have the status CLS (closed) or INV (invoiced).
- The delivery must not be locked by Picco (LockedByPicco = 'Y').
- LocID must be empty, or at least one supplier delivery with SDelHLocationID = LocID must exist.
Insert: the item name is taken from items and the supplier from the delivery header. A new line is always inserted, with the ordered and delivered quantities, purchase price, final price, batch number and best-before date. There is no order line reference. Discounts and the mid price are set to 0.
Price fallback: if SupplPrice is 0 or not given and the delivery has a supplier, the purchase price is taken from the supplier item record (AddItems.SupplPrice). This value is used for the price, the mid price and the final price. In this case a given SupplFinalPrice is overwritten as well.
Result: the newly created delivery line is returned with additional information:
- quantity matched to supplier order lines
- open customers, open orders and open quantity for the item in the delivery's location
- supplier item number and internal item number from the supplier item record

All errors are raised with RAISERROR (severity 16). No line is created in that case.

Notes

SDelHSupplNr and PiccoUser are accepted but not used; SDelHSupplNr is marked as unused in the code (DEV-4203). The supplier always comes from the delivery header.
Location check: the LocID check does not compare against the location of the target delivery. It only checks whether any supplier delivery with this location ID exists.
Duplicate lines: calling the procedure again for the same item creates an additional line. Existing lines are never updated; the error text points to pixiUpdateDeliveryItem for updates.
Supplier item creation: if the setting InsertAddItemOnSOrdersDragDrop is 1 and no supplier item record (AddItems) exists for the delivery's supplier and the item, the internal procedure Pixi_InsertAddItemOnDelivery is called. That procedure is not attached, so its exact effects are not documented here; it presumably creates such a record.
Price may be NULL: with the price fallback, the price becomes NULL if the supplier has no supplier item record for the item.
Duplicated error text: if only the delivery reference is missing, the validation logic concatenates the message twice, so the error text appears twice.
User name: if UserName is sent as an empty string, it becomes NULL and is stored as NULL creator/updater.
Reads use NOLOCK. No explicit transaction is used.

pixiUpdateDeliveryItem

Tables used

SDelHeader · Read SDelDetail · Write items · Read ItemCode · Read ItemCodeType · Read AddItems · Read BuyingMatch · Read Customers · Read Orderlines · Read OrderStates · Read OrderHeader · Read Suppliers · Read

Parameter	Type	Default	Description
`SDelHKey`	int	NULL	Internal key of the supplier delivery. Takes precedence over `SDelHNr`; `0` counts as not given. Example: `5321`
`SDelHNr`	int	NULL	Delivery number. Used only if `SDelHKey` is empty. Either this parameter or `SDelHKey` is required. Example: `10452`
`UserName`	varchar(50) string	API	User name stored as creator and last editor of the line. Example: `API`
`ItemNrInternal`	varchar(50) string	NULL	Item code used for the lookup if `EANUPC` is empty. It is matched against the scannable item codes. Example: `ART-10045`
`EANUPC`	varchar(13) string	NULL	EAN/UPC of the item, looked up among the scannable item codes. Takes precedence over `ItemNrInternal`. Example: `4006381333931`
`SupplPrice`	money decimal	NULL	Purchase price of the line. If `0` or not given, the price is taken from the supplier item record. Example: `12.50`
`SupplFinalPrice`	money decimal	NULL	Final purchase price. It is overwritten by the fallback price if `SupplPrice` is `0`. Example: `12.50`
`SDelHSupplNr`	varchar(4) string	NULL	Not used (DEV-4203). The supplier is taken from the delivery header.
`OrderdQty`	money decimal	0	Ordered quantity of the line. Example: `10`
`DeliverdQty`	money decimal	0	Delivered quantity of the line. Example: `10`
`LocID`	varchar(255) string	NULL	Optional location ID. If set, at least one supplier delivery with this location ID must exist, otherwise an error is raised. Example: `001`
`PiccoUser`	varchar(59) string	NULL	Not used by the code.
`BatchNumber`	varchar(50) string	NULL	Batch number stored on the delivery line. Example: `CH-2024-0815`
`BestBeforeDate`	datetime dateTime	NULL	Best-before date stored on the delivery line. Example: `2025-12-31T00:00:00`

Result set 1 · On success (all checks passed, line inserted)

The newly created supplier delivery line with additional information.

Column	Type	Description
`SDelDkey`	int	Key of the new delivery line.
`SDelDHref`	int	Key of the supplier delivery.
`SDelDItemRef`	int	Item key.
`SDelDItemName` Nullable	string	Item name taken from the item master.
`SDelDqtyDelivered` Nullable	money decimal	Delivered quantity.
`SDelDqtyOrdered` Nullable	money decimal	Ordered quantity.
`SDelDsorderlineRef` Nullable	int	Reference to a supplier order line; always `NULL` for lines created by this call.
`SDelDsPrice` Nullable	money decimal	Purchase price.
`SDelDsDiscount` Nullable	money decimal	Discount (always 0).
`SDelDsFinalPrice` Nullable	money decimal	Final purchase price.
`SDelDcreateDate` Nullable	datetime dateTime	Creation date.
`SDelDcreateEmp` Nullable	varchar(50) string	Creating user.
`SDelDupdateDate` Nullable	datetime dateTime	Date of last change.
`SDelDupdateEmp` Nullable	varchar(50) string	User of last change.
`SDelDsAddDiscount` Nullable	money decimal	Additional discount (always 0).
`SDelDsMidPrice` Nullable	money decimal	Mid price: 0, or the supplier item price when the price fallback applies.
`BatchNumber` Nullable	varchar(50) string	Batch number.
`BestBeforeDate` Nullable	datetime dateTime	Best-before date.
`BuyingMatchQty`	decimal	Sum of quantities of this line matched to supplier order lines (`BuyingMatch`), 0 if none.
`OpenCustomersCountForItem`	int	Number of customers with active order lines for the item in the delivery's location.
`OpenOrdersCountForItem`	int	Number of orders with active order lines for the item in the delivery's location.
`OpenQTYSforItem` Nullable	decimal	Total quantity of active order lines for the item in the delivery's location; `NULL` if there are none.
`ItemNrSuppl` Nullable	string	Supplier item number from `AddItems` for the delivery's supplier (`MGS` if the delivery has no supplier).
`ItemNrInt` Nullable	string	Internal item number from `AddItems` for the delivery's supplier (`MGS` if the delivery has no supplier).
`EANUPC` Nullable	string	EAN/UPC from the supplier item record of the delivery's supplier, matched via `IntLinkNR1`.

Response example

<SqlRowSet1>
  <row>
    <SDelDkey>88412</SDelDkey>
    <SDelDHref>5321</SDelDHref>
    <SDelDItemRef>10045</SDelDItemRef>
    <SDelDItemName>Kaffeebecher Steingut 300ml</SDelDItemName>
    <SDelDqtyDelivered>10.0000</SDelDqtyDelivered>
    <SDelDqtyOrdered>10.0000</SDelDqtyOrdered>
    <SDelDsPrice>12.5000</SDelDsPrice>
    <SDelDsDiscount>0.0000</SDelDsDiscount>
    <SDelDsFinalPrice>12.5000</SDelDsFinalPrice>
    <SDelDcreateDate>2024-05-14T09:32:11.237</SDelDcreateDate>
    <SDelDcreateEmp>API</SDelDcreateEmp>
    <SDelDupdateDate>2024-05-14T09:32:11.237</SDelDupdateDate>
    <SDelDupdateEmp>API</SDelDupdateEmp>
    <SDelDsAddDiscount>0.0000</SDelDsAddDiscount>
    <SDelDsMidPrice>0.0000</SDelDsMidPrice>
    <BatchNumber>CH-2024-0815</BatchNumber>
    <BestBeforeDate>2025-12-31T00:00:00</BestBeforeDate>
    <BuyingMatchQty>0.0000</BuyingMatchQty>
    <OpenCustomersCountForItem>3</OpenCustomersCountForItem>
    <OpenOrdersCountForItem>3</OpenOrdersCountForItem>
    <OpenQTYSforItem>5.0000</OpenQTYSforItem>
    <ItemNrSuppl>LF-77812</ItemNrSuppl>
    <ItemNrInt>ART-10045</ItemNrInt>
    <EANUPC>4006381333931</EANUPC>
  </row>
</SqlRowSet1>

Status	Message	Cause
RAISERROR	You must provide Delivery reference or Delivery number.	Neither `SDelHKey` nor `SDelHNr` is given (or both are 0/empty). Provide one of them. The text may appear twice because of the message concatenation.
RAISERROR	You must provide item EAN or ItemNrInternal.	Neither `EANUPC` nor `ItemNrInternal` is given. Provide one of them.
RAISERROR	Item with EANUPC {EANUPC} does not exist.	No scannable item code matches the given `EANUPC`.
RAISERROR	Item with ItemNrInternal {ItemNrInternal} does not exist.	`EANUPC` is empty and no scannable item code matches `ItemNrInternal`.
RAISERROR	You cant add items to closed or invoiced deliveries.	The delivery does not exist (for example an unknown `SDelHNr`) or has the status `CLS` or `INV`.
RAISERROR	Delivery is locked!	The delivery is locked by Picco (`LockedByPicco = 'Y'`). Retry after the lock is released.
RAISERROR	Error: You cant add the item to the delivery, you have enter an invalid Location ID. For Updating use pixiUpdateDeliveryItem.	`LocID` is set, but no supplier delivery with this location ID exists. Leave `LocID` empty or pass a valid location ID.

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:pixiCreateDeliveryItem>
      <!-- <SDelHKey>5321</SDelHKey> -->
      <!-- <SDelHNr>10452</SDelHNr> -->
      <!-- <UserName>API</UserName> -->
      <!-- <ItemNrInternal>ART-10045</ItemNrInternal> -->
      <!-- <EANUPC>4006381333931</EANUPC> -->
      <!-- <SupplPrice>12.50</SupplPrice> -->
      <!-- <SupplFinalPrice>12.50</SupplFinalPrice> -->
      <!-- <SDelHSupplNr>?</SDelHSupplNr> -->
      <!-- <OrderdQty>10</OrderdQty> -->
      <!-- <DeliverdQty>10</DeliverdQty> -->
      <!-- <LocID>001</LocID> -->
      <!-- <PiccoUser>?</PiccoUser> -->
      <!-- <BatchNumber>CH-2024-0815</BatchNumber> -->
      <!-- <BestBeforeDate>2025-12-31T00:00:00</BestBeforeDate> -->
    </ns1:pixiCreateDeliveryItem>
  </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:pixiCreateDeliveryItem>
      <!-- <SDelHKey>5321</SDelHKey> -->
      <!-- <SDelHNr>10452</SDelHNr> -->
      <!-- <UserName>API</UserName> -->
      <!-- <ItemNrInternal>ART-10045</ItemNrInternal> -->
      <!-- <EANUPC>4006381333931</EANUPC> -->
      <!-- <SupplPrice>12.50</SupplPrice> -->
      <!-- <SupplFinalPrice>12.50</SupplFinalPrice> -->
      <!-- <SDelHSupplNr>?</SDelHSupplNr> -->
      <!-- <OrderdQty>10</OrderdQty> -->
      <!-- <DeliverdQty>10</DeliverdQty> -->
      <!-- <LocID>001</LocID> -->
      <!-- <PiccoUser>?</PiccoUser> -->
      <!-- <BatchNumber>CH-2024-0815</BatchNumber> -->
      <!-- <BestBeforeDate>2025-12-31T00:00:00</BestBeforeDate> -->
    </ns1:pixiCreateDeliveryItem>
  </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 = [
    // 'SDelHKey' => '5321',
    // 'SDelHNr' => '10452',
    // 'UserName' => 'API',
    // 'ItemNrInternal' => 'ART-10045',
    // 'EANUPC' => '4006381333931',
    // 'SupplPrice' => '12.50',
    // 'SupplFinalPrice' => '12.50',
    // 'SDelHSupplNr' => '?',
    // 'OrderdQty' => '10',
    // 'DeliverdQty' => '10',
    // 'LocID' => '001',
    // 'PiccoUser' => '?',
    // 'BatchNumber' => 'CH-2024-0815',
    // 'BestBeforeDate' => '2025-12-31T00:00:00',
];

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

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

SQL object:: dbo.pipiCreateDeliveryItem

pixiCreateDeliveryItem

Notes

Related calls

Tables used

Result set 1 · On success (all checks passed, line inserted)

Response example