Revisions and version history

List the revisions of an export template, read the content of a published revision, and see what a revision or the current draft changed.

Every publish creates a revision: an immutable copy of the whole export template. This guide shows how to read the revision history of an export template through the ETM API. To create a revision, see Publishing changes.

Prerequisites

You need a valid access token. See Authentication for how to obtain one with the Client Credentials flow.

You can only read the revision history of export templates you own. Being in the same account as the owner is not enough: for other export templates, the API returns 403 Forbidden.

Revision fields

Every revision endpoint returns the same summary fields:

Field	Description
`revisionId`	Public ID of the revision. Use it to address the revision in other requests.
`revisionNumber`	Sequential number within the export template, starting at `1`. `null` for legacy revisions.
`active`	`true` for the revision the platform and the analyzer use. Exactly one revision per export template is active.
`live`	`true` when the platform already runs this revision. A new revision is `active` immediately, and becomes `live` after the platform picks it up.
`createdAt`	When the revision was published.
`source`	Where the publish came from: `DEV_PORTAL`, `API`, or `SYSTEM`. `null` for legacy revisions.
`publishedBy`	`userId` and `displayName` of the publisher. `displayName` is `null` when it is not known.
`changeSummary`	How many items the revision added, removed, and changed per category, compared with the revision before it. `null` when there is nothing to compare against.

Legacy revisions were created by the V1 commit endpoint or published before version history was available. They record that a publish happened, but not what the export template contained.

List revisions

curl "https://export-template-api.productsup.com/V2/export-templates/{templateId}/revisions?firstResult=0&maxResults=50" \
  -H "Authorization: Bearer <token>"

The response lists revisions newest first, as metadata only, with a pagination object (firstResult, maxResults, count, total). maxResults defaults to 50 and is capped at 1000.

Read a revision

To get the active revision with its published content:

curl "https://export-template-api.productsup.com/V2/export-templates/{templateId}/revisions/latest" \
  -H "Authorization: Bearer <token>"

To get any revision with its published content:

curl "https://export-template-api.productsup.com/V2/export-templates/{templateId}/revisions/{revisionId}" \
  -H "Authorization: Bearer <token>"

Both responses contain the revision fields and a template object with the content published in that revision:

Template settings and export template tags

Attributes, with their conditions, tags, and analyzer tests

Marketing

Metadata

Custom form fields

template is null for legacy revisions.

/revisions/latest returns 404 Not Found when the export template has never been published.

See what changed

Two endpoints list what changed, item by item:

Endpoint	Compares
`GET /V2/export-templates/{templateId}/revisions/{revisionId}/changes`	A revision with the revision before it
`GET /V2/export-templates/{templateId}/draft/changes`	The current draft with the active revision, so you can see what a publish would change

curl "https://export-template-api.productsup.com/V2/export-templates/{templateId}/draft/changes" \
  -H "Authorization: Bearer <token>"

{
  "changeSummary": {
    "templateDetails": { "added": 0, "removed": 0, "changed": 0 },
    "attributes": { "added": 0, "removed": 0, "changed": 1 },
    "analyzerTests": { "added": 0, "removed": 0, "changed": 0 },
    "metadata": { "added": 0, "removed": 0, "changed": 0 }
  },
  "changes": {
    "templateDetails": [],
    "attributes": [
      {
        "type": "changed",
        "name": "example_attribute",
        "fields": [{ "field": "description", "from": null, "to": "Example description" }]
      }
    ],
    "analyzerTests": [],
    "metadata": []
  }
}

Changes are grouped into four categories:

Category	Items
`templateDetails`	Template settings by `field`, for example `encoding`, and tags and custom form fields by `name`
`attributes`	Attributes by `name`. Changed attributes list each changed field in `fields`.
`analyzerTests`	Analyzer tests by `attribute` and test `name`
`metadata`	Metadata fields by `field`

Each item has a type of added, removed, or changed. Attributes are matched by name, and internal IDs and timestamps are ignored, so only real content changes are listed. A draft without edits returns empty lists.

changes and changeSummary are null when there is nothing to compare against: the first revision of an export template, a revision whose previous revision is a legacy revision, a legacy revision itself, and a draft on an export template that has no active revision with content.

Revisions from before version history

When versioning was introduced, every export template that had already been published got its state at that time stored as its first revision, with source SYSTEM. Its earlier publishes are listed as legacy revisions: the history shows when they happened, but not what they contained. An export template that had never been published got no revision; its first publish creates revision 1.

Next steps

Publishing changes — create a revision and check when the platform uses it

View version history — the same history in the Developer Portal

List revisions — endpoint reference