pixiCancelOrderline · Pixi API documentation

Sets the status of an orderline, or of a bundle orderline together with all of its orderlines, to STO (cancelled) or NLB (not available).

Status defaults to STO; an empty value or NULL is also treated as STO.
A value of 0 for OrderlineKey or BundleOrderlineKey counts as not sent. If neither key is sent, an error row is returned.
If only OrderlineKey is sent and this orderline belongs to an existing bundle orderline (BundleOrderlineRef), the call switches to that bundle. The whole bundle is then processed, not just the single line.
If a bundle key is known (sent or looked up), OrderlineKey is ignored. All orderlines with this BundleOrderlineRef are processed.
Only orderlines that meet all of these conditions are updated:
- their current status is not a final state in OrderStates (FinalState = 'Y')
- they are not packed in a box (boxitems)
- they are not on an invoice line (Invlines)
The selected orderlines get the new Status, UpdateEmp = 'API' and the current date as UpdateDate. The related bundle orderlines are updated in the same way.
On success, a row with SuccessfulMessage is returned. The text depends on whether a single orderline or a bundle was cancelled.

If Status is not STO or NLB, or if no orderline meets the conditions, a row with ErrorMessage is returned.

Notes

The message ONLY Status STO or NLB Allowed is also returned when the status is valid but no orderline qualifies. This happens when the key does not exist, or when all lines are in a final state, boxed or invoiced. The text is therefore misleading in this case.
For bundles, only the qualifying orderlines are updated. The bundle orderline itself still gets the new status as soon as at least one of its lines qualifies. Lines that are boxed, invoiced or final keep their old status.
The success or error message is returned in a column whose name differs (ErrorMessage vs. SuccessfulMessage). Clients should check which column is present.
The checks read with NOLOCK. The two updates do not run in an explicit transaction.
The procedure's return value (0/1) is not part of the result rows.
The status value is written as sent. Its comparison with STO/NLB depends on the database collation.

Tables used

Orderlines · Write BundleOrderlines · Write OrderStates · Read boxitems · Read Invlines · Read

Parameter Type Default Description

Parameter	Type	Default	Description
`OrderlineKey`	int	NULL	Key of the orderline to cancel. `0` is treated as not sent. If the line belongs to a bundle, the whole bundle is processed. Example: `123456`
`Status`	varchar(3) string	STO	New status for the orderlines. Empty or NULL means `STO`. Allowed values `STO` – Cancelled `NLB` – Not available Example: `STO`
`BundleOrderlineKey`	int	NULL	Key of the bundle orderline whose orderlines are cancelled. If set, `OrderlineKey` is ignored. `0` is treated as not sent. Example: `7890`

OrderlineKey

int

NULL

Key of the orderline to cancel. 0 is treated as not sent. If the line belongs to a bundle, the whole bundle is processed.

Example: 123456

Status

varchar(3)
string

STO

New status for the orderlines. Empty or NULL means STO.

Allowed values

STO – Cancelled
NLB – Not available

Example: STO

BundleOrderlineKey

int

NULL

Key of the bundle orderline whose orderlines are cancelled. If set, OrderlineKey is ignored. 0 is treated as not sent.

Example: 7890

Result set 1 · On error: no key sent, invalid status, or no qualifying orderline

Single row with the error text.

Column	Type	Description
`ErrorMessage`	varchar(43) string	Error message.

Result set 2 · On success (at least one orderline updated)

Single row with the confirmation text.

Column	Type	Description
`SuccessfulMessage`	varchar(70) string	`Orderline was successfully canceled` for a single orderline, or `Bundleorderline and all belonging Orderlines was successfully canceled` for a bundle.

Response example

<SqlRowSet1>
  <row>
    <SuccessfulMessage>Orderline was successfully canceled</SuccessfulMessage>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	ERROR: No orderline or bundle key was sent!	Neither `OrderlineKey` nor `BundleOrderlineKey` was sent (or both are 0). Send at least one key.
ERROR	ONLY Status STO or NLB Allowed	`Status` is not `STO` or `NLB`. The same message also appears when no orderline qualifies: the key does not exist, or the lines are in a final state, packed in a box or already invoiced.

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:pixiCancelOrderline>
      <!-- <OrderlineKey>123456</OrderlineKey> -->
      <!-- <Status>STO</Status> -->
      <!-- <BundleOrderlineKey>7890</BundleOrderlineKey> -->
    </ns1:pixiCancelOrderline>
  </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:pixiCancelOrderline>
      <!-- <OrderlineKey>123456</OrderlineKey> -->
      <!-- <Status>STO</Status> -->
      <!-- <BundleOrderlineKey>7890</BundleOrderlineKey> -->
    </ns1:pixiCancelOrderline>
  </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',
    // 'Status' => 'STO',
    // 'BundleOrderlineKey' => '7890',
];

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

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