Skip to main content

Import

Your system sends reference data and documents to the WMS with one endpoint. A single request can carry items of different types, in different import modes:

POST /api/v1/integrations/import
WMS-Idempotency-Key: 6f1c2b7e-3d4a-4c1b-9a8e-2f5d7c9b1e04
{
  "externalSystemCode": "ERP_MAIN",
  "items": [
    {
      "entityType": "PARTY",
      "importMode": "UPSERT",
      "payload": {"id": "sup-0001", "name": "Northwind Supplies"}
    },
    {
      "entityType": "PRODUCT",
      "importMode": "UPSERT",
      "payload": {"id": "prod-0017", "name": "Cement M400", "uomId": "uom-bag"}
    }
  ]
}
  • externalSystemCode — the code of your external system.
  • entityType — the data type of the item.
  • importMode — what to do with it; required for every item.
  • payload — the data, built as described in Building the payload.

The system needs the Reference import capability to send reference data and Document import to send documents.

How items are processed​

  • In order. Items are applied one after another, in the order of the array. Put a record before the items that refer to it: a product before a receipt that receives it. A reference to a record sent earlier in the same request works.
  • One by one. Each item is saved on its own. When one item fails, the others are still saved; nothing is rolled back.
  • Any mix. One request may mix data types, reference data and documents, and import modes. Keep requests to a few hundred items.

The answer​

The answer is 200 even when some items fail. It reports every item:

{
  "externalSystemId": "01a17a5d-5148-71bf-8935-79c3016fbf5c",
  "summary": {
    "PARTY": {"created": 1, "updated": 0, "skipped": 0, "deleted": 0, "restored": 0},
    "PRODUCT": {"created": 0, "updated": 0, "skipped": 1, "deleted": 0, "restored": 0}
  },
  "results": [
    {
      "itemIndex": 0,
      "entityType": "PARTY",
      "status": "CREATED",
      "internalEntityId": "01a17a69-a738-732f-9880-39fe2ce9783a",
      "errors": []
    },
    {
      "itemIndex": 1,
      "entityType": "PRODUCT",
      "status": "SKIPPED",
      "errors": [
        {
          "path": "uomId",
          "message": "External reference was not found for UNIT_OF_MEASURE with external id `uom-bag`"
        }
      ]
    }
  ],
  "processedAt": "2026-10-27T09:51:46.985Z"
}
  • results[].itemIndex — the position of the item in your items array.
  • status — what happened; see Import item statuses.
  • internalEntityId — the WMS identifier of the record. You do not need to keep it: the WMS already knows your id.
  • errors — empty when the item went through. Otherwise each error has a path inside the item's payload (for example uomId or lines[0].productId) and a message. An item with errors changed nothing; fix it and send it again.

Repeating a request​

Every import request carries a WMS-Idempotency-Key header: a unique string such as a UUID. If you do not know whether a request reached the server — a timeout, a broken connection, a 5xx answer — send the same request with the same key again:

  • if the first request was processed, the server does not apply it again; it returns the saved answer with the header WMS-Idempotency-Replayed: true;
  • if it was not, the server processes it now.

The server remembers a key for about 10 minutes. Use a new key for every new request: the same key with different items returns the answer of the first request.

Deleting​

To delete a record, send it with the Delete mode; the payload needs only id. Reference data can also be deleted or restored with "deleted": true or false in an Create or update item. Only the system that sent a record may delete it.

Code​

The function sends one request and lists the failed items. It uses the client from API basics.

import {randomUUID} from 'node:crypto';

// Sends one import request. `items` is an array of
// {entityType, importMode, payload}; items are applied in this order.
// Returns the whole answer and the items that failed, with their errors.
async function importItems(items, idempotencyKey = randomUUID()) {
  // Keep the key if you may need to repeat this exact request (e.g. after a timeout).
  const {body} = await wmsRequest('POST', '/api/v1/integrations/import', {
    body: {externalSystemCode: config.externalSystem, items},
    idempotencyKey,
  });
  const failed = body.results
    .filter((result) => result.errors.length > 0)
    .map((result) => ({item: items[result.itemIndex], result}));
  for (const {item, result} of failed) {
    const reasons = result.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
    console.warn(`${item.entityType} ${item.payload.id} was not imported — ${reasons}`);
  }
  return {response: body, failed};
}