API best practices

Twinfield has a series of articles with best practices for building an API integration. This introduction lists all articles in the series: what to know before you start, how to connect, common integrations, importing and retrieving data, and the API limits.

The article

Source: API Best Practices - Introduction, Twinfield community (Wolters Kluwer). Quoted on 9 November 2026.

This series guides you through the process of building your API integration with Twinfield. The purpose of these articles is to share best practices, help you understand key concepts, and highlight important considerations and potential pitfalls. We also explore common integration scenarios to provide practical examples and help you get started with popular use cases.

Things to know before you start

• What does the certification process for Twinfield’s API look like?
• Why is the office code an important identifier?
• How does matching work in Twinfield?
• How to determine the period table?

Setting up a connection to Twinfield

• Setting up a connection using OAuth2
• Retrieving a list of offices that you can access

Common API connections

• API Best Practices - POS (Point of Sale) system
• Webshop
• Medical professionals

Importing data into Twinfield

• Importing sales transactions including customers
• Importing purchase transactions including suppliers
• Importing cash transactions
• Importing journal transactions

Retrieving data from Twinfield

• Keeping a shadow database with customers/suppliers
• Keeping a shadow database with transactions from Twinfield
• Downloading open invoices from Twinfield

API Rate Limits

• Information about Twinfield API Rate Limits
• How to adjust my Twinfield API connection to match the API limit on number of transaction lines?
• How to adjust my API connection to fit Twinfield API limits?

Getting more help

• How do I create an API-related support-case?
• Link to the Support Portal (for Twinfield, Basecone, Alure Online)

The links in the article are relative links on the community site; they are written out in full here.

With this SDK

Where to find each topic of the series in this SDK:

Topic	With this SDK
The office code as identifier	Organisations: every model knows its company and organisation, and Keys for a shadow database lists the key for each kind of data. Twinfield now calls an office a company.
Matching	Matching and receive() and pay() in the transactions guide; example: Split payment over invoices
The period table	List periods and Rename period
OAuth2	OAuth2; examples: Authentication and Token info
Offices you can access	Offices; examples: List offices and Switch company
POS system	Daily cash register
Webshop	Sales invoice or sales transaction?, Create customer and Create sales transaction
Sales transactions including customers	Sales transactions and Customers
Purchase transactions including suppliers	Purchase transactions and Suppliers
Cash transactions	Daily cash register and Read cash transaction
Journal transactions	Journal transactions; examples: Create journal transaction and Opening balance
Shadow database with customers/suppliers	Searching in the master data guide; examples: List customers, List suppliers and Paginate
Shadow database with transactions	Keeping a shadow database with transactions and Browse data; examples: Initial load, Incremental load and Validate balances
Open invoices	Open sales invoices and Open purchase invoices
Rate limits	Rate limits, and see below
Many transaction lines	Saving many transactions; example: Bulk import with errors

Rate limits

When Twinfield answers HTTP 429 Too Many Requests, the SDK throws a RateLimitExceededException. It does not retry by itself: your integration decides when to try again. retryAfterSeconds has the value of the Retry-After header, or null when Twinfield did not send one. concurrencyLimitExceeded says whether the concurrency limit was exceeded instead of the rate limit. See Rate limits for the other properties and exponential backoff.

use SolveBeam\Twinfield\Soap\RateLimitExceededException;

try {
    $customer = $twinfield->customers()->get('1000');
} catch (RateLimitExceededException $e) {
    sleep($e->retryAfterSeconds ?? 60);

    $customer = $twinfield->customers()->get('1000');
}

See also Error handling.