Transferring a catalogue as a file — with review notes before it is taken over

A dealer exports their item stock from the ERP as CSV once a month. An API integration is not planned, and for that rhythm it would be overkill. The risk lies elsewhere: one shifted column in a file with ten thousand rows turns prices into item numbers.

The catalogue transfer therefore treats the file like a sync run: first a preview with counts and review notes is produced, then a decision is made against exactly that preview. According to the contract, the transfer is created in the canonical Commerce model; whether the review differs by format is not specified by the contract.

What this case requires

• An uploaded file with a token. The transfer references the file via artifactToken; the token is only written, never returned.
• The right format. serialization knows csv, xml and json.
• Optionally a connection. connectionId is optional and references a connection; the contract does not describe what effect it has on the transfer.
• Someone who reads the notes. Approval is only as good as the review before it.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. Create the transfer. POST /commerce/v1/catalog-transfers takes direction with import or export, serialization and artifactToken. The response carries transferId, state and the first counts — nothing is taken over yet.
2. Read the state. GET /commerce/v1/catalog-transfers/{transferId} returns state and counts with read, changed, rejected and conflicted. The four figures are the first sanity check: ten thousand read and ten thousand changed is rarely right for a monthly file.
3. Read the review notes. GET /commerce/v1/catalog-transfers/{transferId}/issues lists per note severity, code, message, pointer and, where present, recordNumber. With recordNumber you find the row in your own file instead of interpreting an error message.
4. Decide. POST /commerce/v1/catalog-transfers/{transferId}/approval takes decision with approve or reject, plus previewRevision and expectedRevision. What is approved is the reviewed preview — if the state has changed in the meantime, the revision no longer matches.
5. Collect the result file. GET /commerce/v1/catalog-transfers/{transferId}/artifact returns artifactToken, checksum and expiresAt. checksum is a string of 64 hexadecimal characters; the contract does not specify the algorithm or what it is computed over. expiresAt gives the expiry time.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: katalog-import-2026-09' \
  -d '{"direction":"import","serialization":"csv","artifactToken":"<artifactToken>","connectionId":"<connectionId>"}' \
  'https://commerce-preview.invalid/commerce/v1/catalog-transfers'

What you end up with

What remains is a catalogue taken over only after approval against the reviewed preview, and a result file with a checksum. The contract does not enforce that anyone has read the counts and review notes before approval; it requires previewRevision and expectedRevision — which is why someone who reads the notes is among the prerequisites. A shifted column can be noticed before approval if the preview’s counts or review notes show it.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-commerce). All use cases arranged by surface and role: overview of the use cases.