Most of our content is Publicly accessible. However some content is Private and you will be asked to create an account the first time you try to access this content.
Private content is only available to our existing customers.

Integration core principles

  • Updated on Aug 18, 2026
  • Published on Jan 19, 2026
  • 3 minute(s) read
  • A
 Prev Next

This guide summarizes the core principles for integrating with the WAIR API.

Only POST Requests (Upsert by Primary ID)

  • All endpoints use POST.

  • WAIR uses an upsert pattern based on the primary ID:

    - If the ID already exists, the record is updated.

    - If the ID does not exist, the record is created.

  • To update a record, always send the complete object; partial updates are not supported.

Loose Coupling Between Endpoints

  • Endpoints are technically independent.

  • You can send stock for a SKU even if the item record has not yet been uploaded.

  • While items are commonly implemented first, you may build endpoints in any order, enabling multiple developers to work in parallel.

Identifiers: id vs code

All endpoints include both an id and a code. These serve different purposes:

  • id

    The unique identifier of the object. This is often a UUID or system-generated internal ID. It may not be visible to users in the source system. It is not mandatory to give the id in UUID format if you do not have this in the source system. As long as it is unique, it is basically a text-based identifier, like a name tag or reference code, that can contain letters, numbers, or other characters.

  • code

    A business key defined in the source system and familiar to end users. This value appears throughout the WAIR Customer Portal. It does not need to be unique. Avoid using the system-generated internal ID as this confuses the users of the portal.

To ensure performance and prevent time-outs, large datasets should be split into multiple API calls. Recommended maximums:

  • Purchase orders: 25.000 per call

  • Sales: 10.000 per call

  • Stock / stock mutations: 50.000 per call

  • Items: 25.000 per call

  • Prepacks: 25.000 per call

  • Transfers: 10.000 per call

  • Images: 1000 per call (for images/urls endpoint)

Example:

If you need to upload 50,000 sales records for an initial historical load, split them into 5 calls of 10,000 records each to POST /sales

Upload Frequency and Reliability

Minimum requirement:

Upload all datasets at least once per day.

Recommended approach:

For transactional data such as stock and sales, send data continuously or in frequent small batches.

Reasoning:

A single daily job is a single point of failure. If it fails, all data becomes outdated, which may lead to inaccurate replenishments or redistributions. Smaller and more frequent updates reduce this risk and keep data accurate.

Full Load Functionality

Some endpoints support the fullLoad query parameter. A full load is generally used for refreshing an entire dataset rather than for an initial load.

When performing a full load:

  1. Objects in your request that do not yet exist are created.

  2. Objects that already exist and are included in your request are updated.

  3. Objects that exist in WAIR but are not included in your request are deleted (soft delete).

Example outcome:

If your system originally has brands A and B, and you submit a full load containing brands B and C, the final result will contain B (updated) and C (created), and A will be removed.

There is an exception to this fullLoad functionality, in the POST /Stock endpoint there is also a fullLoad parameter available. When enabled the stock levels for all location/SKU’s not included in the API calls will be corrected to 0.

moreRecordsAvailable (for multi-call full loads)

For large datasets that require multiple full-load calls, you can use the moreRecordsAvailable parameter:

  • For all calls except the last:

    fullLoad = true

    moreRecordsAvailable = true

  • For the last call:

    fullLoad = true

    moreRecordsAvailable = false

This prevents records from being deleted prematurely while the full load is still in progress.

Summary

  • Use POST-only upserts based on full objects.

  • Endpoints are independent and can be implemented in any order.

  • Prioritize items, stock, sales, and locations for the backtest.

  • Large datasets must be split into multiple API calls.

  • Full load should be used for refreshing complete datasets, not for initial loads.

  • Upload data daily, and use continuous or frequent uploads for stock and sales.

Related articles