---
title: "Import tracked changes from DOCX"
description: "Import Word insertions and deletions as reviewable suggestions, or apply or discard them during the import."
canonical_url: "https://tiptap.dev/docs/conversion/import/docx/tracked-changes"
---

# Import tracked changes from DOCX

Import Word insertions and deletions as reviewable suggestions, or apply or discard them during the import.

> **Tracked Changes add-on:**
>
> Tracked Changes is a paid add-on that isn't included in any plan. Test it during the free trial
> or purchase it in [your dashboard](https://cloud.tiptap.dev/v2/billing). Once [integrated in
> your editor](https://tiptap.dev/docs/tracked-changes/getting-started/install.md), it works with Conversion to round-trip
> reviews between Word and Tiptap.

- **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start
  plan](https://cloud.tiptap.dev/v2/billing) in your account.
- **2. Get the Tracked Changes add-on**

  Tracked Changes is a paid add-on that isn't included in any plan. Test it during the free
  trial or purchase it separately in [your dashboard](https://cloud.tiptap.dev/v2/billing).
- **3. Set up your integration path**

  For the editor extension, authenticate to Tiptap's private npm registry by following the [setup
  guide](https://tiptap.dev/docs/guides/pro-extensions.md). For the REST API, authenticate calls with a signed token
  carrying `aud: "Convert"`. See [Authentication](https://tiptap.dev/docs/authentication.md).

A Word document that has been reviewed carries a record of who inserted and removed what. On import you decide what happens to that record: keep it as suggestions you can review in the editor, apply it, or discard it.

## Choosing a mode

| Mode       | What happens                                                                      |
| ---------- | --------------------------------------------------------------------------------- |
| `preserve` | Insertions and deletions become suggestions, with their original author and date  |
| `accept`   | Insertions become ordinary text and deletions are removed                         |
| `reject`   | Deletions are restored as ordinary text and insertions are removed                |
| `auto`     | Editor extension only. Picks `preserve` or `accept` based on your editor's schema |

## With the editor extension

`ImportDocx` takes a `trackedChanges` option, and defaults to `auto`:

```ts
import { ImportDocx } from '@tiptap-pro/extension-import-docx'

const editor = new Editor({
  extensions: [
    ImportDocx.configure({
      token: 'your-jwt',
      trackedChanges: 'auto',
    }),
  ],
})
```

You can also decide per import, which wins over the configured value:

```ts
editor.commands.importDocx({ file, trackedChanges: 'preserve' })
```

### What `auto` does

`auto` looks for the tracked changes `suggestion` mark in your editor's schema. If it is there, the mode becomes `preserve`. If it is not, the mode becomes `accept`. If you renamed that mark through `prosemirrorMarks`, `auto` looks for the name you gave it.

This matters because the editor drops marks its schema does not know while keeping the text they were on. Asking for `preserve` in an editor that cannot render suggestions would therefore turn every deletion back into ordinary content, which silently reverses the reviewer's edit. `auto` avoids that, so leave it alone unless you know which mode you want.

> **Preserving suggestions needs the tracked changes extension:**
>
> Register [`@tiptap-pro/extension-tracked-changes`](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) to
> keep imported redlines. Without it, use `accept` or `reject` so the document arrives as ordinary
> text.

## With the REST API

Send `trackedChanges` as a form field. It accepts `preserve`, `accept` and `reject`, and defaults to `accept`.

```bash
curl -X POST https://api.tiptap.dev/v2/convert/import/docx \
  -H "Authorization: Bearer <your-jwt>" \
  -F "file=@reviewed.docx" \
  -F "trackedChanges=preserve"
```

The default is `accept` rather than `preserve` so that callers who send nothing keep receiving plain content, and never receive suggestion marks their editor cannot render.

## What preserved suggestions look like

Text carrying a change gets a `suggestion` mark:

```json
{
  "type": "text",
  "text": "brave ",
  "marks": [
    {
      "type": "suggestion",
      "attrs": {
        "id": "docx-suggestion-1",
        "type": "add",
        "userId": "ada lovelace",
        "createdAt": "2026-07-27T10:00:00Z",
        "updatedAt": "2026-07-27T10:00:00Z",
        "userMetadata": { "name": "Ada Lovelace" }
      }
    }
  ]
}
```

`type` is `add` for an insertion and `delete` for a deletion. A replacement, where the reviewer swapped one piece of text for another, arrives as a deletion followed by an insertion.

Word identifies reviewers by display name only, so `userMetadata.name` holds that name and `userId` is derived from it: trimmed, whitespace collapsed, lower cased. Reviewers who share a display name therefore share a `userId`. A change with no author gets `anonymous` as its `userId` and `null` as its `userMetadata`.

Word writes one record per run of text, so a single edit is often split into several. Neighbouring records from the same author with the same type are merged into one suggestion, which keeps a change that spans different formatting as one reviewable unit rather than several.

Inserted or deleted images and other standalone content carry the same information as node attributes instead of a mark: `suggestionId`, `suggestionType`, `suggestionUserId`, `suggestionCreatedAt`, `suggestionUpdatedAt` and `suggestionUserMetadata`.

## Where suggestions are kept

Suggestions are preserved in the body of the document, including inside table cells.

Headers, footers, comments and footnotes are edited separately from the main document, and `preserve` does not reach them. Their changes are applied on the way in instead, so a deletion in a header arrives as removed text rather than as a suggestion. Their content is never lost.

This is deliberate. Those parts usually run on a schema with no `suggestion` mark, and preserving there would strip the mark while leaving the text behind, turning a deletion into real content. Configuring the header and footer editors with the tracked changes extension does not change the import behaviour today.

## What is not imported yet (work in progress)

For these two the text arrives in full, and only the record of the change is missing:

- **Paragraph splits and joins.** Word records these on the paragraph mark rather than on the text, and they are common in reviewed documents. The paragraphs import correctly, but the fact that the split itself was a tracked change is not kept.
- **Formatting changes**, such as a word made bold with tracking on. The formatting is imported, the record of it being a change is not.

Moves are the exception, and worth checking on your own documents:

- **Moves**, where a reviewer relocated a block of text. Word writes a move as two halves, a source and a destination, and neither is recognised yet. Check a moved passage before relying on it.

## Round-trip

Exporting a document whose suggestions came from Word writes them back as Word insertions and deletions, with the author and date intact. See [export tracked changes](https://tiptap.dev/docs/conversion/export/docx/tracked-changes.md).

Accepting everything in Tiptap gives the same result as accepting everything in Word, and rejecting matches too. The exceptions are the cases the export cannot write, including suggestions on images and other standalone content, which come in as node attributes and go back out as ordinary content. See [what is not exported](https://tiptap.dev/docs/conversion/export/docx/tracked-changes.md#what-is-not-exported-work-in-progress).