Resume observed changes from a durable publication checkpoint

curl --request GET \
  --url http://127.0.0.1:5185/v1/changes/sync

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "product_first_observed",
      "product": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "utah_dabs_sku": "347210"
        },
        "name": "<string>",
        "brand": "<string>"
      },
      "store": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "inventory_store_code": "0002"
        },
        "name": "<string>"
      },
      "change": {},
      "semantics": "first_observed_by_nektir",
      "times": {
        "source_updated_at": "2023-11-07T05:31:56Z",
        "retrieved_at": "2023-11-07T05:31:56Z",
        "published_at": "2023-11-07T05:31:56Z"
      },
      "upstream_age_known": true
    }
  ],
  "meta": {
    "page": {
      "has_more": true,
      "next_cursor": "<string>",
      "cursor_expires_at": "2023-11-07T05:31:56Z"
    },
    "sync": {
      "checkpoint": "<string>",
      "scope": "observed_product_changes",
      "order": "publication_then_event"
    },
    "warnings": [
      {
        "code": "INVENTORY_COVERAGE_PARTIAL"
      }
    ]
  },
  "links": {
    "self": "<string>",
    "next": "<string>"
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

Resume observed changes from a durable publication checkpoint

With neither token, returns no events and a checkpoint covering the current publication. Capture that checkpoint BEFORE requesting a baseline export, then poll with checkpoint. Events are ordered oldest-first by publication and event within (completed checkpoint, frozen publication]. Retrieval time is not used as a synchronization watermark. If has_more is true, follow next_cursor alone with the same filters. Only the final page returns a new checkpoint; commit it atomically with processing that page. Retried pages may repeat event UUIDs. Empty filtered windows still advance the checkpoint. Checkpoints are signed, filter-bound and independent of page-cursor and version-history TTLs. History deletion/reset can return 410 CHECKPOINT_EXPIRED: import a new baseline. 410 CURSOR_EXPIRED instead means retry from the last completed checkpoint and deduplicate. This is observed-product-change invalidation, not every successful retrieval or store-directory CDC. No source requests are triggered. Family and observed-time filters are not supported here.

curl --request GET \
  --url http://127.0.0.1:5185/v1/changes/sync

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "product_first_observed",
      "product": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "utah_dabs_sku": "347210"
        },
        "name": "<string>",
        "brand": "<string>"
      },
      "store": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "source_ids": {
          "inventory_store_code": "0002"
        },
        "name": "<string>"
      },
      "change": {},
      "semantics": "first_observed_by_nektir",
      "times": {
        "source_updated_at": "2023-11-07T05:31:56Z",
        "retrieved_at": "2023-11-07T05:31:56Z",
        "published_at": "2023-11-07T05:31:56Z"
      },
      "upstream_age_known": true
    }
  ],
  "meta": {
    "page": {
      "has_more": true,
      "next_cursor": "<string>",
      "cursor_expires_at": "2023-11-07T05:31:56Z"
    },
    "sync": {
      "checkpoint": "<string>",
      "scope": "observed_product_changes",
      "order": "publication_then_event"
    },
    "warnings": [
      {
        "code": "INVENTORY_COVERAGE_PARTIAL"
      }
    ]
  },
  "links": {
    "self": "<string>",
    "next": "<string>"
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "detail": "<string>",
  "instance": "<string>",
  "code": "<string>",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>"
    }
  ]
}

Headers

If-None-Match

string

Strong entity tag from an earlier response.

If-Modified-Since

string

HTTP-date fallback validator. ETag takes precedence.

Query Parameters

product_id

string<uuid>

Stable API-owned product UUID. Mutually exclusive with sku.

sku

string

Exact six-character Utah DABS SKU. Mutually exclusive with product_id.

Pattern: ^[0-9]{6}$

Examples:

"347210"

"004190"

store_id

string<uuid>

Restrict store-level inventory events to one stable API-owned store UUID.

types

enum<string>[]

Comma-separated observed event types with OR semantics.

Maximum array length: 8

Available options:

product_first_observed,

price_changed,

status_changed,

product_presentation_changed,

aggregate_inventory_changed,

store_inventory_first_observed,

store_inventory_changed,

catalog_presence_changed

checkpoint

string

Opaque completed-window token. Mutually exclusive with cursor. Omit both only when starting a new baseline.

Required string length: 1 - 4096

cursor

string

Signed opaque keyset cursor, valid for 15 minutes and only with the original resource endpoint, query, and sort. Reuse on another endpoint or with changed filters returns CURSOR_QUERY_MISMATCH. Follow links.next unchanged.

Maximum string length: 2048

limit

integer

default:25

Required range: 1 <= x <= 100

Response

Frozen ascending event page, or initial checkpoint. New completed checkpoint is null until the last page.

data

object[]

required

Maximum array length: 100

Show child attributes

Exports

Changes

Availability

Products

Search

Brands

Product families

Stores

Metadata

Resume observed changes from a durable publication checkpoint

Headers

Query Parameters

Response