Invoices Write

pixiCreateInvoice

Creates an invoice for a packed box (BoxNr at a location) and returns the new invoice ID and number together with a status row.

Creates the invoice for the contents of one box and always returns exactly one status row.

If BoxNr or LocId is NULL, an error row is returned. An empty UserName is replaced by API.
The box is checked for invoice eligibility with the internal procedure GOS_BoxesRange (range BoxNr..BoxNr at LocId). The box is eligible if all of the following apply:
- it is not yet marked as sent (WaitForSend <> Y), or it is physically full and contains items without invoice lines;
- the customer has no ship lock (SLocked not Y/1);
- no ship address of the order lines in the box has a ship lock (ASlocked);
- the box number is not the location's own box number (LocBoxNumber);
- if order lines in the box have a confirmation date (ConfDate), at least one of them is today.
If the box is not eligible, the call tries to find the reason and returns an error row: box not found at this location, box empty, invoice already exists, ship lock on an order address, ship lock on the customer; otherwise a generic "Invoice creation failed." (this also covers the ConfDate and location box number rules).
If eligible, the internal procedure Pixi_CreateInv creates the invoice with creation mode API and language ID 1. It:
- marks the box as sent (WaitForSend = 'Y') and locks it against double invoicing;
- inserts the invoice header (Invoices) and one invoice line (Invlines) per box item; additionally, not yet invoiced order lines of the same order with status MIN or a status listed in the setting PutThisStatusesOnInvoice;
- sets Orderlines.InvRef, assigns the final invoice number per shop, the gross weight, a return tracking ID and an InvoicePackage record;
- optionally scans the box out, cancels open partial deliveries, books the invoice on the customer account and publishes the InvoiceCreated event. If the box already has a draft invoice (InvoiceStatusId = 0), that draft is finalized instead (creation mode MobileShipOut).
Result: on success a row with InvoiceId, InvoiceNr and Status = 'SUCCESS'; on failure InvoiceId/InvoiceNr are NULL and Status/Message contain the error.

Notes

Invoice creation runs in its own transaction (or a savepoint if the caller already has one). On deadlock (1205) or duplicate key (2601) it is retried up to 5 times; retries and errors are written to LogTable and the error log.
Pre-checks use NOLOCK; the final protection against double invoices is the UPDLOCK on the box inside Pixi_CreateInv.
The status value differs in case: pre-check errors return Error, errors from the invoice creation return ERROR (taken from the internal result).
Pitfall: some internal errors (e.g. "ERROR CREATING INVOICE Invoice Total empty", foreign key errors such as orders of different customers in one box) are caught inside Pixi_CreateInv without setting its error message. In that case this call returns Status = 'SUCCESS' with InvoiceId/InvoiceNr = NULL. Always check that InvoiceId is not NULL.
Behaviour depends on settings read at runtime: PutThisStatusesOnInvoice, Enforce_CheckKuhlung (shipping cost adjustment for chilled items), DefaultShippingWeight, CalculateWeightFromItems, Invoice_CancelPartialDelivery (open lines with status ANG, HAL, BOR are set to STO).
Scan-out happens automatically if the ship vendor (DoScanOutOnInvoiceCreate) or payment method (AutoScanOutInvoice) requests it.
The draft finalization path (Pixi_CreateInvoiceFromDraft) is not attached; its exact behaviour and messages are not documented here.
The error text for missing parameters mentions the user name, but only BoxNr and LocId are checked.

Parameters

Parameter	Type	Default	Description
`BoxNr` Required	int	–	Number of the packed box to invoice. Example: `1042`
`LocId` Required	varchar(3) string	–	Location (warehouse) ID the box belongs to. Example: `001`
`UserName`	varchar(50) string	API	User name stored as creator of the invoice and its lines. Empty or NULL is replaced by `API`. Example: `shopconnector`

Response

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

Status row with the created invoice or the error.

Column	Type	Description
`InvoiceId` Nullable	int	Internal key of the created invoice (`InvoiceKey`); NULL on error.
`InvoiceNr` Nullable	varchar(20) string	Invoice number assigned to the new invoice; NULL on error.
`Status` Nullable	varchar(50) string	`SUCCESS` on success, `Error` for pre-check errors, `ERROR` (internal result) for errors during invoice creation.
`Message` Nullable	varchar(200) string	Empty on success, otherwise the error message.

Response example

<SqlRowSet1>
  <row>
    <InvoiceId>184532</InvoiceId>
    <InvoiceNr>RE2024104871</InvoiceNr>
    <Status>SUCCESS</Status>
    <Message/>
  </row>
</SqlRowSet1>

Error messages

Status	Message	Cause
Error	Parameters Box number, Location Id and User Name must be specified.	`BoxNr` or `LocId` was not passed or is NULL.
Error	Box could not be found.	No box with this `BoxNr` exists at location `LocId`.
Error	Box is empty - no items.	The box has no box items; pack items before invoicing.
Error	Invoice creation failed. Invoice already exists.	The box is already marked as sent (`WaitForSend = 'Y'`) and has no uninvoiced items in a physically full box.
Error	Invoice creation failed. There is a "Ship lock" set for order in box {BoxNr}.	A ship address of an order line in the box has a ship lock (`ASlocked`). Remove the lock first.
Error	Invoice creation failed. There is a "Ship lock" set for customer in box {BoxNr}.	The customer of the box has a ship lock (`SLocked`). Remove the lock first.
Error	Invoice creation failed.	The box is not eligible for another reason, e.g. order lines with a confirmation date not today, or the box number is the location's own box number.
Error	{ERROR_MESSAGE()}	An SQL error escaped the internal invoice creation; the original SQL error text is returned.
ERROR	INVOICE ALREADY EXISTS	During creation the box was found to be already invoiced (e.g. concurrent call).
ERROR	URGENT: Double invlines; BoxKey={BoxKey} currentLocation={LocId} User={UserName}	Duplicate invoice lines were detected for the order lines; the invoice is rolled back.
ERROR	ERROR CREATING INVOICE; please check related addresses, country code could be missing	The invoice header could not be inserted, typically because the ship address has no valid country code.
ERROR	ERROR CREATING INVOICE BoxItems <> Invlines	The number of invoice lines does not match the number of box items; the invoice is rolled back.

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:pixiCreateInvoice>
      <BoxNr>1042</BoxNr>
      <LocId>001</LocId>
      <!-- <UserName>shopconnector</UserName> -->
    </ns1:pixiCreateInvoice>
  </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:pixiCreateInvoice>
      <BoxNr>1042</BoxNr>
      <LocId>001</LocId>
      <!-- <UserName>shopconnector</UserName> -->
    </ns1:pixiCreateInvoice>
  </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 = [
    'BoxNr' => '1042',
    'LocId' => '001',
    // 'UserName' => 'shopconnector',
];

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

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

Tables used

boxes · Read boxitems · Read Invlines · Read Orderlines · Read Addresses · Read Customers · Read

SQL object:: dbo.pipiCreateInvoice