Use traceability records when you need a per-batch audit trail without modeling a full product journey. See the Traceability concept page for the difference between the two models.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/traceability | List records, optionally filtered by productId |
GET | /api/v1/traceability/{id} | Get a single record |
POST | /api/v1/traceability | Create a batch traceability record |
PATCH | /api/v1/traceability/{id} | Partially update a record |
DELETE | /api/v1/traceability/{id} | Delete a record |
GET /api/v1/traceability
| Query parameter | Type | Required |
|---|---|---|
productId | string | — |
Shell
curl "{{BASE_URL}}/api/v1/traceability?productId=SKU-001"
Response 200 OK — JSON array of TraceabilityRecordDto.
POST /api/v1/traceability
Request body (CreateTraceabilityRecordDto)
| Field | Type | Required | Description |
|---|---|---|---|
productId | string | ✅ | Any product identifier (SKU, UUID, or external ref) |
batchNumber | string | ✅ | Your batch reference |
origin | string | ✅ | Where the batch comes from |
destination | string | — | Where the batch is going |
supplierId | uuid | — | Linked supplier (if any) |
processingFacility | string | — | Facility name / description |
certifications | string | — | Free-form list of certifications |
isCompliant | boolean | — | Your QA compliance flag (default false) |
userId | uuid | — | Owning user (optional) |
companyId | uuid | — | Owning company (optional) |
notes | string | — | Free-form notes |
metadata | object | — | Arbitrary JSON |
Shell
curl -X POST {{BASE_URL}}/api/v1/traceability \-H "Content-Type: application/json" \-d '{"productId": "SKU-001","batchNumber": "B-2026-042","origin": "Gujarat, India","destination": "Milano warehouse","supplierId": "3f2b9a1c-…","processingFacility": "Ahmedabad spinning mill","certifications": "GOTS, OEKO-TEX","isCompliant": true}'
Response 201 Created — TraceabilityRecordDto.
GET /api/v1/traceability/{id}
200 OK—TraceabilityRecordDto.404 Not Found— record does not exist in your tenant.
PATCH /api/v1/traceability/{id}
Partial update over any of the documented fields.
DELETE /api/v1/traceability/{id}
204 No Content— deleted.404 Not Found— record does not exist in your tenant.
Record schema
TraceabilityRecordDto:
JSON
{"id": "rec-uuid…","productId": "SKU-001","batchNumber": "B-2026-042","origin": "Gujarat, India","destination": "Milano warehouse","supplierId": "3f2b9a1c-…","processingFacility": "Ahmedabad spinning mill","certifications": "GOTS, OEKO-TEX","isCompliant": true,"userId": null,"companyId": null,"notes": null,"metadata": null,"createdAt": "2026-04-21T10:00:00.000Z","updatedAt": "2026-04-21T10:00:00.000Z"}