Skip to main content
Products are independently versioned: one draft (editable) and zero or more published versions (immutable). Publishing uses Change Requests to choose which draft changes go into the new version. This page focuses on how the API handles versioning, stable IDs, and the fields you use for matching.

​
Draft ID: The Stable Reference

The draft ID of an item or property never changes. It is the stable reference for the logical entity. The API exposes this as optional draft_item_id and draft_property_id on item and property responses. Use these for matching the same logical item or property across versions (e.g. “this item in v1” = “this item in v2”).

​
Item IDs and Property IDs

When a version is published, the system creates a snapshot for that version. Each item or property in the snapshot is assigned a new id, and its draft_item_id / draft_property_id is set to the original draft ID. When you request the draft, you always get the same draft item.
  • Draft entity → Maintains its stable id.
  • Published entity → A copy is stored for that version with a new id; draft_item_id / draft_property_id is set to the draft ID. Use these fields to match the same logical entity across versions.
Previously, unchanged entities shared the same id across versions. As of June 2026, all entities get new IDs per version. You must use the draft IDs for correlation across versions.

​
Summary

Use stable IDs and draft_item_id / draft_property_id to correlate entities across versions. The draft ID never changes and is the reference for matching.