pixiReturnCaseUpdate · Pixi API documentation

Updates the return cost of one return case in pixi.Return.

Steps:

UserName is trimmed. An empty value becomes API.
Both ReturnId and ReturnCost must be provided.
The return case must exist.
The return case must be in status StatusId = 2 (Received).
ReturnCost must not be negative. A value of 0 is accepted.
The upper limit is computed from the return case and its invoice (Invoices.InvoiceKey = Return.InvoiceId). It is the returned items amount plus the shipping cost refund minus the voucher amount:
- for B2B orders: TotalToRefundNet + ShippingCostRefundNet - VoucherAmountNet
- for B2C orders: TotalToRefundGross + ShippingCostRefundGross - VoucherAmountGross
If ReturnCost is above this limit, an error row is returned.
The cost is written to the return case:
- B2C: the value goes to ReturnCostGross.
- any other order type: the value goes to ReturnCostNet.
RecordModifiedByUserId and RecordModifiedOn are set as well.

The user ID is resolved from UserName. If that user does not exist, the user pixiAdministration is used.

The call returns exactly one row with Status and Message, both on success and on error.

Notes

Validation reads use NOLOCK; the update uses ROWLOCK. No explicit transaction is used.
Pitfall: the limit check is skipped in three cases:
- no matching invoice is found in Invoices, so the order type stays NULL;
- the order type is neither B2B nor B2C;
- one of the amount columns is NULL.
In the first two cases the value is written to ReturnCostNet without any limit check.
The error text 'must be greater than 0' is misleading: only negative values are rejected, so 0 is accepted.
On error the procedure also returns the return code 1. The status row is the relevant signal for SOAP clients.

Tables used

Return · Write Invoices · Read UCS_USERS · Read

Parameter	Type	Default	Description
`ReturnId`	int	NULL	ID of the return case (`pixi.Return.id`). Effectively required. Example: `1542`
`ReturnCost`	money decimal	NULL	Return cost to store. It is stored as net for B2B and as gross for B2C. It must not be negative or exceed the refundable amount. Effectively required. Example: `5.95`
`UserName`	varchar(50) string	API	Name of the user recorded as modifier. An empty value becomes `API`. An unknown user falls back to `pixiAdministration`. Example: `API`

Result set 1 · Always (one row, on success or error)

Status row of the update.

Column	Type	Description
`Status`	varchar(7) string	`Success` or `Error`.
`Message`	varchar string	Success or error message.

Response example

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>Return Case updated successfully.</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	Return id and return costs needs to be provided	`ReturnId` or `ReturnCost` was not provided. Send both parameters.
Error	No return found for return Id: {ReturnId}	No return case with this ID exists. Check the ID.
Error	Return id {ReturnId} is not in received status.	The return case does not have `StatusId = 2` (Received). The cost can only be set for received returns.
Error	Return cost must be greater than 0.	`ReturnCost` is negative. A value of 0 is accepted.
Error	Return cost must be less then Returned items amount + Shipping costs - Discount voucher.	`ReturnCost` exceeds the refundable amount: net for B2B, gross for B2C.

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:pixiReturnCaseUpdate>
      <!-- <ReturnId>1542</ReturnId> -->
      <!-- <ReturnCost>5.95</ReturnCost> -->
      <!-- <UserName>API</UserName> -->
    </ns1:pixiReturnCaseUpdate>
  </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:pixiReturnCaseUpdate>
      <!-- <ReturnId>1542</ReturnId> -->
      <!-- <ReturnCost>5.95</ReturnCost> -->
      <!-- <UserName>API</UserName> -->
    </ns1:pixiReturnCaseUpdate>
  </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 = [
    // 'ReturnId' => '1542',
    // 'ReturnCost' => '5.95',
    // 'UserName' => 'API',
];

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

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