Skip to main content

Resync

The change feed brings only changes. To load everything the WMS already holds — when you connect a new system, or to recover after your data went out of step — read a full snapshot with a resync session, then continue with the change feed from the point where the snapshot was taken.

A resync needs the Change feed read capability. Not every data type can be resynced; see the Reading line of each type in Integration data types.

Steps​

  1. Start a session for the data types you need:

    POST /api/v1/integrations/resync-sessions
    {"externalSystemCode": "ERP_MAIN", "entityTypes": ["PARTY", "PRODUCT"], "warehouseScope": []}

    warehouseScope limits warehouse-bound data to the listed warehouses (WMS identifiers); an empty list means the warehouses your external system may work with. The answer:

    {"sessionId": 1, "status": "CREATED", "snapshotWatermarkEventId": 5, "expiresAt": "2026-10-28T09:54:29.190Z"}

  2. Read the pages until hasMore is false:

    GET /api/v1/integrations/resync-sessions/1/page?limit=100&cursor=<nextCursor of the previous page>

    limit is required, from 1 to 500. Leave out cursor for the first page. Every item carries the full current state of one record, with identifiers as {int, ext} pairs (see Building the payload):

    {
      "sessionId": 1,
      "status": "IN_PROGRESS",
      "items": [
        {
          "entityType": "PARTY",
          "scopeType": "GLOBAL",
          "internalEntityId": "01a16373-d1c6-77c5-8fe9-71c359d09e0e",
          "payload": {
            "id": {"int": "01a16373-d1c6-77c5-8fe9-71c359d09e0e", "ext": null},
            "name": "Contoso Foods",
            "supplier": true,
            "deleted": false
          }
        }
      ],
      "nextCursor": "eyJ2ZXJzaW9uIjoxLCJlbnRpdHlUeXBlIjoiUEFSVFkiLCJ…",
      "hasMore": true
    }

  3. Complete the session after the last page:

    POST /api/v1/integrations/resync-sessions/1/complete
    {"expectedStatus": "SNAPSHOT_COMPLETED"}

  4. Continue with the change feed after the session's snapshotWatermarkEventId. Completing the session does not move your checkpoint, so confirm that event yourself when the checkpoint is behind it (POST /api/v1/integrations/checkpoints/acknowledge, see Change feed); the reading loop then starts right after the snapshot. Everything changed after the snapshot was taken comes through the feed; nothing is lost between the two.

    Your system has one checkpoint for all data types. Move it to the snapshot only when the resync covered every type your system reads from the feed; otherwise the changes of the other types before the snapshot would be skipped.

A session must be completed within 24 hours of its start. GET /api/v1/integrations/resync-sessions/{sessionId} shows its current state; the statuses are listed in Resync session statuses.

Code​

The function runs the whole session and returns the event id to continue the change feed from; pass it to the startChangeFeedAt function from Change feed. It uses the client from API basics.

// Reads a full snapshot of the given data types page by page and hands every
// record to `handleItem`. Returns the event id to continue the change feed from.
async function runResync(entityTypes, handleItem, {warehouseScope = [], pageSize = 100} = {}) {
  const base = '/api/v1/integrations/resync-sessions';
  const {body: session} = await wmsRequest('POST', base, {
    body: {externalSystemCode: config.externalSystem, entityTypes, warehouseScope},
  });

  let cursor;
  for (;;) {
    const query = {limit: pageSize};
    if (cursor) query.cursor = cursor;
    const {body: page} = await wmsRequest('GET', `${base}/${session.sessionId}/page`, {query});
    for (const item of page.items) await handleItem(item); // {entityType, internalEntityId, payload}
    if (!page.hasMore) break;
    cursor = page.nextCursor;
  }

  const {body: done} = await wmsRequest('POST', `${base}/${session.sessionId}/complete`, {
    body: {expectedStatus: 'SNAPSHOT_COMPLETED'},
  });
  // Read the change feed with fromEventId = this value: nothing before it is missed.
  return done.snapshotWatermarkEventId;
}