Product Traceability API

A product traceability is a header (the journey) plus an ordered list of processing stages. See the Traceability concept page for the model.

Endpoints

Traceability header

Processing stages

GET /api/v1/product/traceability

curl "{{BASE_URL}}/api/v1/product/traceability?page=1&limit=20&search=t-shirt"

Response 200 OK — ProductTraceabilityListResponseDto with data, meta and facets.

GET /api/v1/product/traceability/stage-types

Lists available stage types for traceability canvas configuration.

Response 200 OK — array of StageTypeDto with id, code, label and icon.

GET /api/v1/product/traceability/{id}

Returns the full traceability including all its processing stages sorted by sequenceOrder.

• 200 OK — ProductTraceabilityDto with processingStages[].
• 404 Not Found — journey does not exist in your tenant.

POST /api/v1/product/traceability

Request body (CreateProductTraceabilityDto)

1curl -X POST {{BASE_URL}}/api/v1/product/traceability \
2  -H "Content-Type: application/json" \
3  -d '{
4    "productId": "product-uuid…",
5    "traceabilityName": "T-Shirt SS26 — Supply Chain",
6    "description": "Full cotton-to-garment journey"
7  }'

Response 201 Created — ProductTraceabilityDto.

PATCH /api/v1/product/traceability/{id}

Partial update of pfcrCalculationId, traceabilityName, description, metadata and other fields exposed by UpdateProductTraceabilityDto.

DELETE /api/v1/product/traceability/{id}

Removes the journey and all its processing stages.

• 204 No Content — deleted.
• 404 Not Found — journey does not exist in your tenant.

POST /api/v1/product/traceability/{id}/stages

Appends a processing stage to the journey identified by {id}.

Request body (CreateProcessingStageDto)

1curl -X POST {{BASE_URL}}/api/v1/product/traceability/{tracId}/stages \
2  -H "Content-Type: application/json" \
3  -d '{
4    "sequenceOrder": 1,
5    "stageName": "Cotton cultivation",
6    "companyType": "SUPPLIER",
7    "supplierId": "3f2b9a1c-…",
8    "transportMode": "TRUCK",
9    "startsFromCompany": false,
10    "distanceKm": 120,
11    "co2Emissions": 15.4,
12    "certificationsSnapshot": "GOTS"
13  }'

Response 201 Created — ProcessingStageDto.

PATCH /api/v1/product/traceability/stages/{stageId}

Partially updates a single stage. Any of the fields documented above can be changed.

DELETE /api/v1/product/traceability/stages/{stageId}

Removes the stage. The parent journey's aggregate totalCo2PerKg and totalDistanceKm are recomputed server-side.

• 204 No Content — deleted.
• 404 Not Found — stage does not exist in your tenant.

Traceability schema

ProductTraceabilityDto:

1{
2  "id": "trac-uuid…",
3  "userId": "user-uuid…",
4  "productId": "product-uuid…",
5  "pfcrCalculationId": null,
6  "traceabilityName": "T-Shirt SS26 — Supply Chain",
7  "description": "Full cotton-to-garment journey",
8  "totalCo2PerKg": 2.85,
9  "totalDistanceKm": 11230,
10  "metadata": null,
11  "processingStages": [
12    {
13      "id": "stg-uuid…",
14      "traceabilityId": "trac-uuid…",
15      "userId": "user-uuid…",
16      "sequenceOrder": 1,
17      "stageName": "Cotton cultivation",
18      "companyType": "SUPPLIER",
19      "supplierId": "3f2b9a1c-…",
20      "companyId": null,
21      "internalProcess": null,
22      "transportMode": "TRUCK",
23      "startsFromCompany": false,
24      "distanceKm": 120,
25      "co2Emissions": 15.4,
26      "certificationsSnapshot": "GOTS",
27      "createdAt": "2026-04-21T10:00:00.000Z",
28      "updatedAt": "2026-04-21T10:00:00.000Z"
29    }
30  ],
31  "createdAt": "2026-04-21T10:00:00.000Z",
32  "updatedAt": "2026-04-21T10:00:00.000Z"
33}

Stage schema

ProcessingStageDto matches the embedded stage structure shown above.