VAT return status (690)

Browse code 690 (BrowseCode::VatReturnStatus, “Btw-aangifte status”): the VAT and ICT returns of a year with their period, status and when they were sent. The returns themselves are in Declarations.

Twinfield documentation: Browse data.

• equal('fin.vat.declyear', $year): the returns of one year. equal('fin.vat.statusname', 'sent') selects on the status.
• fin.vat.decltype: vat, ict, taxgroup, yearlysuppletion or taxgroupyearlysuppletion; fin.vat.timeframe the period of the return, e.g. quarter1.
• fin.vat.statusname is the status (created, authorised, sent, approved, rejected, …); fin.vat.status the status code.
• fin.vat.sent is a Datetime, empty when the return is not sent yet.

Criteria: year and status. See browse-definitions/690.xml and the browse data guide.

Fields

All fields of the browse definition (browse-definitions/690.xml), with the label for a Dutch user, the data type and the values of a field with a fixed list (browsefields.xml). A field that is not visible is meant as criterion: asking for it as column can give a server error. Twinfield does not apply the proposed values: send every criterion you need.

Field	Label	Type	Visible	Criterion
fin.trs.head.office	Administratie	string	yes
fin.trs.head.officename	Adm.naam	string	yes
fin.vat.decltype	Aangifte type	special: ict, vat, taxgroup, yearlysuppletion, taxgroupyearlysuppletion	yes
fin.vat.declyear	Jaar	long	yes	equal
fin.vat.timeframe	Tijdvak	special: year, halfyear1, halfyear7, fourmonth1, fourmonth5, fourmonth9, quarter1, quarter2, quarter3, quarter4, quarter5, quarter6, quarter7, quarter8, quarter9, quarter10, quarter11, quarter12, bimonth1, bimonth3, bimonth5, bimonth7, bimonth9, bimonth11, month1, month2, month3, month4, month5, month6, month7, month8, month9, month10, month11, month12	yes
fin.vat.status	Btw-statuscode	long	yes
fin.vat.statusname	Btw-status	special: created, authorised, modified, sent, approved, sendtimeout, rejected	yes	equal
fin.vat.sent	Verzonden	datetime	yes
fin.vat.gateway	Poort	string	yes

Code

$twinfield = Example::twinfield();

$year = (int) ($argv[1] ?? date('Y'));

$query = $twinfield->browse(BrowseCode::VatReturnStatus)
    ->columns(
        'fin.vat.decltype',
        'fin.vat.declyear',
        'fin.vat.timeframe',
        'fin.vat.statusname',
        'fin.vat.sent',
    )
    ->equal('fin.vat.declyear', $year);

$result = $query->get();

echo count($result), ' return(s) in ', $year, PHP_EOL;

foreach ($result as $index => $row) {
    $sent = $row->nullableString('fin.vat.sent') === null ? null : $row->dateTime('fin.vat.sent');

    echo sprintf(
        '[%d/%d] %s %d %s: %s%s',
        $index + 1,
        count($result),
        $row->string('fin.vat.decltype'),
        $row->int('fin.vat.declyear'),
        $row->displayName('fin.vat.timeframe') ?? $row->string('fin.vat.timeframe'),
        $row->string('fin.vat.statusname'),
        $sent === null ? '' : ', sent ' . $sent->format('Y-m-d H:i'),
    ), PHP_EOL;
}

Run

php examples/browse-data/690-vat-return-status/example.php        # this year
php examples/browse-data/690-vat-return-status/example.php 2025   # 2025

Add TWINFIELD_DEBUG=1 to see the SOAP requests and responses.

2 return(s) in 2026
[1/2] vat 2026 Per kwartaal jan tot en met mrt: approved, sent 2026-04-21 09:30
[2/2] vat 2026 Per kwartaal apr tot en met jun: created

XML

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.

Compose the browse request and send it

Twinfield documentation: Browse data: Compose the browse request and send it.

$twinfield->browse(BrowseCode::VatReturnStatus)
    ->columns(
        'fin.vat.decltype',
        'fin.vat.declyear',
        'fin.vat.timeframe',
        'fin.vat.statusname',
        'fin.vat.sent',
    )
    ->equal('fin.vat.declyear', 2026)
    ->get();

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

<columns code="690" optimize="true">
  <column>
    <field>fin.vat.decltype</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.vat.declyear</field>
    <visible>true</visible>
    <operator>equal</operator>
    <from>2026</from>
  </column>
  <column>
    <field>fin.vat.timeframe</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.vat.statusname</field>
    <visible>true</visible>
  </column>
  <column>
    <field>fin.vat.sent</field>
    <visible>true</visible>
  </column>
</columns>

Twinfield answers with this XML in ProcessXmlStringResult:

<browse result="1" first="1" last="2" total="2">
  <th>
    <td label="" hideforuser="false" type="String">fin.vat.decltype</td>
    <td label="" hideforuser="false" type="Number">fin.vat.declyear</td>
    <td label="" hideforuser="false" type="String">fin.vat.timeframe</td>
    <td label="" hideforuser="false" type="String">fin.vat.statusname</td>
    <td label="" hideforuser="false" type="Datetime">fin.vat.sent</td>
  </th>
  <tr>
    <td name="Btw">vat</td>
    <td>2026</td>
    <td name="Per kwartaal jan tot en met mrt">quarter1</td>
    <td name="Goedgekeurd">approved</td>
    <td name="21/04/2026 09:30:00">20260421093000</td>
    <key>
      <office>1000</office>
    </key>
  </tr>
  <tr>
    <td name="Btw">vat</td>
    <td>2026</td>
    <td name="Per kwartaal apr tot en met jun">quarter4</td>
    <td name="Aangemaakt">created</td>
    <td/>
    <key>
      <office>1000</office>
    </key>
  </tr>
</browse>

Source

View examples/browse-data/690-vat-return-status/example.php on GitHub.