> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poelis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> How Poelis handles versioning and what Item/Property IDs mean in the API

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.

<Note>
  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.
</Note>

## Summary

| Scenario            | `id`                     | `draft_item_id` / `draft_property_id` |
| ------------------- | ------------------------ | ------------------------------------- |
| Draft item/property | Fixed, stable            | N/A (this is the draft entity)        |
| Published copy      | **New** `id` per version | Set to draft ID—use for matching      |

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.