CMS Draft & Publish Workflow

Some CMS collections gate their items behind a draft/publish workflow instead of writing straight to the live site. Such a collection has the Draft Items plugin installed. Each item is in one of three states — DRAFT, PUBLISHED, or CHANGED (a published item with a pending draft edit) — and edits are staged as drafts until explicitly published.

This reference is for an agent that must detect whether a collection uses this workflow, read the right version of an item, and drive item state transitions (publish, unpublish, revert, delete) through the public Wix Data REST API.

Prerequisites

1. Wix CMS enabled on the site.
2. The collection already exists (see CMS Schema Management).
3. API access with write permission on the collection's data items (reading, authoring drafts, and publishing all go through the Data Items API), plus collection-management permission to add or remove the Draft Items plugin.

Required APIs

• Data Items API: REST — includes Publish Data Item Draft and Unpublish Data Item.
• Data Collections API: REST — Add/Delete Data Collection Plugin.

Mental model — where drafts live

A collection with the Draft Items plugin has two paired surfaces:

Read the drafts collection id from the plugin — do not assume the __drafts suffix. The published collection's Draft Items plugin exposes draftItemsPluginOptions.draftsCollectionId; the drafts collection's plugin exposes draftItemsPluginOptions.publishedCollectionId. Resolve the pairing from those fields.

Item state is derived from where the item exists:

1. Detect the workflow on a collection

Read the collection and inspect its plugins. A collection with the Draft Items plugin uses the draft/publish workflow.

• Draft Items plugin present → the collection gates items behind draft/publish. Its draftItemsPluginOptions.draftsCollectionId gives the paired drafts collection to author and edit drafts against.
• Draft Items plugin absent → plain collection; every insert/update goes straight live. No draft surface exists.

2. Read items

Reads target a specific surface — there is no merged view:

• Published items: query the published collection (articles).
• Drafts: query the drafts collection resolved from draftItemsPluginOptions.draftsCollectionId (e.g. articles__drafts).

Endpoint: POST /wix-data/v2/items/query

• To read only published items, query with dataCollectionId: "articles".
• To read drafts, query with dataCollectionId set to the paired drafts collection id.
• Compute CHANGED by checking whether an item id exists in both the published and drafts surfaces.

3. Write & transition items

Author a brand-new draft

Insert into the drafts collection. The item starts as DRAFT.

Endpoint: POST /wix-data/v2/items

Edit a draft

Update or patch against the drafts collection (articles__drafts). See CMS Data Items CRUD for Update/Patch shapes.

Edit a PUBLISHED item → produces CHANGED

Editing a live item does not overwrite the live copy — it stages a pending draft, leaving the published version untouched until published. The live item then has a pending draft (state CHANGED).

Create the draft first, then edit it. To edit a published item, explicitly create the draft via the create-draft flow (createDataItemDraft) rather than relying on an implicit draft-on-update. Create-draft seeds a full draft copy of the currently-published item into the drafts collection under the same item id; you then apply your edits to that draft. This is the more reliable path — a bare partial update straight to the drafts collection risks producing a draft that is missing the fields you didn't touch. So: create-draft for the published item id, then Update/Patch that draft on the drafts collection (articles__drafts).

Publish a pending draft (DRAFT/CHANGED → PUBLISHED)

Replaces the published item's data with the draft's content; the draft is then deleted. Pass the published collection id.

Endpoint: POST /wix-data/v2/items/publish-draft

Response — the newly-published item (the draft is gone):

• Returns NOT_FOUND if no pending draft exists for that id.

Unpublish a live item (PUBLISHED/CHANGED → DRAFT)

Retracts a published item back to draft state. Pass the published collection id.

Endpoint: POST /wix-data/v2/items/unpublish

copyToDraft controls the two "keep vs discard" variants:

• Response (copyToDraft: true) carries the new draft, not the removed live item.
• Returns NOT_FOUND if no published item exists with that id.

Revert to live version (CHANGED → PUBLISHED, discard the pending edit)

Discard the pending draft while keeping the live version as-is: delete the item from the drafts collection.

Delete an item entirely (removes both versions)

Deleting must remove both the live item and any pending draft.

4. Enable / disable the workflow on a collection

Enable — add the Draft Items plugin (requires collection-management permission). Use the dedicated endpoint; the Draft Items plugin cannot be added through the generic add-plugin call.

Endpoint: POST /wix-data/v2/collections/add-draft-items-plugin

publishPluginConflictAction controls what happens if the legacy Publish plugin is already installed:

Disable — remove the plugin:

Endpoint: POST /wix-data/v2/collections/delete-draft-items-plugin

draftItemsRemovalAction decides the fate of existing drafts:

Permissions

At the REST level, every read/author/publish/unpublish call here goes through the Data Items API and requires write access to the collection's data items. Beyond that, individual draft and publish actions may be further permission-restricted per caller on the collection, and there's no way to introspect those permissions ahead of time — so attempt the action and handle authorization errors gracefully if the write is rejected.

Decision table — collection + desired action → API + permission

Agent gotchas

• Resolve the drafts collection from the plugin. Read draftItemsPluginOptions.draftsCollectionId off the published collection's Draft Items plugin rather than assuming a __drafts suffix.
• Status is server-authoritative. Derive DRAFT/PUBLISHED/CHANGED from the published + drafts surfaces (or the value the API returns). Never compute it locally, and never render an optimistic status before the write confirms (confirm-then-render).
• Pass the published collection id to publish-draft and unpublish — not the drafts collection id. Author and edit drafts against the drafts collection id.
• Publishing deletes the draft. After publish-draft, the pending draft no longer exists; the returned item is the live one.
• Unpublish overwrites an existing draft when copyToDraft: true — any pending edit for that id is replaced with the previously-published data.
• Refetch after publish/unpublish. State changes across the published/draft surfaces are not guaranteed atomic; re-query rather than assuming local state. Wix Data is eventually consistent — use consistentRead: true if you must read immediately after a write.

Related Documentation

• Publish Data Item Draft
• Unpublish Data Item
• Data Collections API — plugin management
• CMS Data Items CRUD — insert/update/patch/delete/query shapes
• CMS Schema Management — creating and modifying collections
• Wix Data and Eventual Consistency