Skip to content

Spread purchase transaction

Spreads the costs of a purchase transaction over a number of periods, e.g. a yearly subscription over twelve months.

Twinfield documentation: Spread transactions.

This example changes data in Twinfield. Only run it on a test administration. The spread transactions of a final transaction are final too: they cannot be changed or deleted.

Twinfield makes the spread transactions itself. You give the intermediate account (a balance sheet account, e.g. prepaid expenses) and the first and last period:

  • postFinal() spreads a final transaction, postProvisional() a provisional one. The example reads the transaction first and picks the right one.
  • postFinalByLines() and postProvisionalByLines() take the periods per detail line, as SpreadLine objects with DetailLine::$id of the transaction: new SpreadLine($transaction->details[0]->id, Period::of(2026, 1), Period::of(2026, 12)). Lines you leave out are not spread.
  • undo() removes the spread of a provisional transaction again.

All of them return a Spread, with the settings and the spread transactions; see Read spread.

$twinfield = Example::twinfield();
// E.g. `INK 202600021 2500 2026/01 2026/12`: a purchase transaction, the intermediate account
// and the first and last period of the spread.
[, $dayBook, $number, $intermediateAccount, $start, $end] = array_pad($argv ?? [], 6, null);
if ($dayBook === null || $number === null || $intermediateAccount === null || $start === null || $end === null) {
echo 'Usage: php example.php <day book> <transaction number> <intermediate account> ',
'<start period> <end period>', PHP_EOL;
exit(0);
}
$spreads = $twinfield->spreadTransactions();
try {
$transaction = $twinfield->purchaseTransactions()->get($dayBook, (int) $number);
$existing = $spreads->get($dayBook, (int) $number);
if ($existing->isSpread()) {
echo 'Already spread in ', count($existing->spreadTransactions), ' transactions.', PHP_EOL;
exit(0);
}
$from = Period::fromString($start);
$to = Period::fromString($end);
// A final transaction is spread with postFinal(), a provisional one with postProvisional().
$spread = $transaction->header->status === TransactionStatus::Final
? $spreads->postFinal($dayBook, (int) $number, $intermediateAccount, $from, $to)
: $spreads->postProvisional($dayBook, (int) $number, $intermediateAccount, $from, $to);
} catch (TransactionNotFoundException $exception) {
echo 'Not found: ', $exception->reason, PHP_EOL;
exit(1);
} catch (ProcessXmlException $exception) {
echo 'Refused: ', $exception->getMessage(), PHP_EOL;
exit(1);
}
echo 'Spread ', $dayBook, ' ', $number, ' (', $transaction->value(), ' ', $transaction->header->currency, ') over ',
$start, ' to ', $end, ' through ', $intermediateAccount, PHP_EOL;
foreach ($spread->spreadTransactions as $spreadTransaction) {
echo 'Spread transaction: ', $spreadTransaction->dayBook, ' ', $spreadTransaction->number, PHP_EOL;
}

The write guard of the examples blocks changes unless you allow them for a company in TWINFIELD_WRITE_COMPANIES:

Terminal window
TWINFIELD_COMPANY=1002_3 TWINFIELD_ALLOW_WRITES=1002_3 php examples/spread-transactions/spread-purchase-transaction/example.php INK 202600021 2500 2026/01 2026/02

The output below follows the documentation; it was not run live yet.

Spread INK 202600021 (121.00 EUR) over 2026/01 to 2026/02 through 2500
Spread transaction: KOSTENVERDELING 202600002
Spread transaction: KOSTENVERDELING 202600003
Spread transaction: KOSTENVERDELING 202600004

What the SDK sends to Twinfield and what Twinfield sends back, for a call like the one in this example. The responses come from the tests, with example data.

Twinfield documentation: Spread transactions: Post final.

$twinfield->spreadTransactions()->postFinal('INK', 202600001, '2500', Period::of(2026, 1), Period::of(2026, 2));

The SDK sends this XML as xmlRequest of ProcessXmlString to processxml.asmx:

<spread action="postfinal">
<original>
<office>1000</office>
<code>INK</code>
<number>202600001</number>
</original>
<settings>
<dim1>2500</dim1>
<startperiod>2026/01</startperiod>
<endperiod>2026/02</endperiod>
</settings>
</spread>

Twinfield answers with this XML in ProcessXmlStringResult:

<spread result="1" action="postfinal">
<original>
<office>1000</office>
<code>INK</code>
<number>202600001</number>
</original>
<settings>
<dim1>2500</dim1>
<startperiod>2026/01</startperiod>
<endperiod>2026/02</endperiod>
</settings>
<spreadtransactions>
<spreadtransaction>
<office>1000</office>
<code>KOSTENVERDELING</code>
<number>202600002</number>
</spreadtransaction>
<spreadtransaction>
<office>1000</office>
<code>KOSTENVERDELING</code>
<number>202600003</number>
</spreadtransaction>
<spreadtransaction>
<office>1000</office>
<code>KOSTENVERDELING</code>
<number>202600004</number>
</spreadtransaction>
</spreadtransactions>
</spread>

Twinfield documentation: Spread transactions: Post provisional by lines.

$twinfield->spreadTransactions()->postProvisionalByLines(
'INK',
202600001,
'2500',
new SpreadLine(2, Period::of(2026, 1), Period::of(2026, 2)),
new SpreadLine(4, Period::of(2026, 3), Period::of(2026, 5)),
);

The SDK sends this XML as xmlRequest of ProcessXmlString to processxml.asmx:

<spread action="postprovisionalbylines">
<original>
<office>1000</office>
<code>INK</code>
<number>202600001</number>
</original>
<settings>
<dim1>2500</dim1>
<linessettings>
<linesettings>
<lineid>2</lineid>
<startperiod>2026/01</startperiod>
<endperiod>2026/02</endperiod>
</linesettings>
<linesettings>
<lineid>4</lineid>
<startperiod>2026/03</startperiod>
<endperiod>2026/05</endperiod>
</linesettings>
</linessettings>
</settings>
</spread>

Twinfield answers with this XML in ProcessXmlStringResult:

<spread result="1" action="postprovisionalbylines">
<original>
<office>1000</office>
<code>INK</code>
<number>202600001</number>
</original>
<settings>
<dim1>2500</dim1>
<linessettings>
<linesettings>
<lineid>2</lineid>
<startperiod>2026/01</startperiod>
<endperiod>2026/02</endperiod>
</linesettings>
<linesettings>
<lineid>4</lineid>
<startperiod>2026/03</startperiod>
<endperiod>2026/05</endperiod>
</linesettings>
</linessettings>
</settings>
<spreadtransactions>
<spreadtransaction>
<office>1000</office>
<code>KOSTENVERDELING</code>
<number>202600002</number>
</spreadtransaction>
<spreadtransaction>
<office>1000</office>
<code>KOSTENVERDELING</code>
<number>202600003</number>
</spreadtransaction>
<spreadtransaction>
<office>1000</office>
<code>KOSTENVERDELING</code>
<number>202600004</number>
</spreadtransaction>
</spreadtransactions>
</spread>

Twinfield documentation: Spread transactions: Delete.

$twinfield->spreadTransactions()->undo('INK', 202600001);

The SDK sends this XML as xmlRequest of ProcessXmlString to processxml.asmx:

<spread action="undo">
<original>
<office>1000</office>
<code>INK</code>
<number>202600001</number>
</original>
</spread>

Twinfield answers with this XML in ProcessXmlStringResult:

<spread action="undo" result="1">
<original>
<office>1000</office>
<code>INK</code>
<number>202600001</number>
</original>
</spread>

View examples/spread-transactions/spread-purchase-transaction/example.php on GitHub.

Made by SolveBeam

Twinfield and Wolters Kluwer are trademarks of Wolters Kluwer. Their names and logos are used only to refer to their products.