Manage sample requests

When to use this. A sample request asks a supplier to produce a physical sample of a style (a fit, proto, or pre-production sample) in specific sizes and colourways. Use these endpoints to read the sample requests raised on a style, move them through the sample workflow, record the fit measurements taken on each requested size, and read the requested sizes and per-colour quantities back for an overview or an ERP export. Raising and archiving sample requests is not yet part of the public API.

The workflow

Sample requests hang off a style. Each is raised against the style for a chosen sample type and size range, and runs through the sample workflow (request → sent → received → commented) as work progresses. The requested sizes and their per-colour quantities are read from a dedicated child collection so a list response never nests three arrays deep. Once the sample arrives, the designer records its fit measurements against each requested size.

Read requests and requested sizes

A sample request belongs to a style (GET /api/styles/{styleId}) and is raised for a sample type from the brand’s library (GET /api/sample-types). GET /api/styles/{styleId}/sample-requests lists a style’s requests; GET /api/sample-requests gives the org-wide, paginated overview, and GET /api/styles/{styleId}/sample-requests/{id} returns a single request. Fetch a request’s sizes and per-colour quantities from GET /api/styles/{styleId}/sample-requests/{sampleRequestId}/sizes.

Advance the sample workflow

PATCH /api/styles/{styleId}/sample-requests/{id} with a JSON Patch on /status moves one request along the workflow: the supplier marks it sent (with a trackingNumber), the designer marks it received when it arrives. See Move a request through the workflow.

Record fit measurements

Once the sample is in hand, read its measured grid with GET /api/styles/{styleId}/sample-requests/{sampleRequestId}/measurements and write the designer’s measured values, the wanted values for the next round, and a per-size fit comment back with PUT or PATCH on the same path. See Record fit measurements.

Walkthrough

List the sample requests on a style. Archived requests are left out unless you pass includeArchived=true.

curl "https://service.my.delogue.com/api/styles/4821/sample-requests" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: Bearer YOUR_API_KEY"

const res = await fetch("https://service.my.delogue.com/api/styles/4821/sample-requests", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "X-Auth-Token": "Bearer YOUR_API_KEY",
  },
});
const { data } = await res.json();

{
  "status": "success",
  "code": "sample_requests_retrieved",
  "data": [
    {
      "id": 90560,
      "styleId": 4821,
      "status": "requested",
      "deadline": "2026-04-10T00:00:00Z",
      "etd": "2026-03-25T00:00:00Z",
      "sendDate": null,
      "lastStateChange": "2026-02-01T11:15:00Z",
      "note": "First proto in Navy and Off White",
      "trackingNumber": null,
      "sampleType": {
        "id": 14,
        "name": "Fit sample",
        "state": "active",
        "commentDeadline": 7,
        "position": 1,
        "notifySettings": [
          "received"
        ],
        "properties": []
      },
      "properties": []
    }
  ]
}

The response wraps the requests in the standard envelope. Hold onto each id: the workflow PATCH, the measurements and the sizes child collection are keyed by it. The requested sizes are not embedded in the request representation; read them from the /sizes sub-resource.

Move a request through the workflow

PATCH /api/styles/{styleId}/sample-requests/{id} changes one request’s status. The body is an RFC 6902 JSON Patch document (Content-Type: application/json-patch+json) applied to the request’s current state, so only the paths you send change. Two paths are writable: /status, and /trackingNumber when the target status is sent.

curl -X PATCH "https://service.my.delogue.com/api/styles/4821/sample-requests/90560" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
  { "op": "replace", "path": "/status", "value": "sent" },
  { "op": "replace", "path": "/trackingNumber", "value": "TRK-SS26-004417" }
]'

const res = await fetch("https://service.my.delogue.com/api/styles/4821/sample-requests/90560", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "X-Auth-Token": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json-patch+json",
  },
  body: JSON.stringify([
    { op: "replace", path: "/status", value: "sent" },
    { op: "replace", path: "/trackingNumber", value: "TRK-SS26-004417" },
  ]),
});
const { data } = await res.json();

The response is the updated sample request (code: "sample_request_updated"), with lastStateChange stamped and, on a move to sent, sendDate and trackingNumber set.

The move must be allowed from the current status, and depends on who you are. The permitted moves mirror Delogue Classic. A supplier assigned to the style can, for example, confirm a requested sample or mark it sent; the designer side can also mark it received or commented, send it back to requested, or cancel it. A move the workflow does not allow returns 422 (unprocessable_error.invalid_state_transition).
trackingNumber belongs to sent only. Sending it with any other target status returns 400.
The status change is recorded in the request’s communication log. It sends no notifications.

Record fit measurements

When a sample arrives, the designer measures it and records the result on the sample request. Each request carries its own measured grid (one entry per requested size, one line per point of measure) separate from the style’s measurement chart. Each line’s target value, requestedMeasurement, is frozen from the style’s measurement chart when the request is raised. Read the grid for every requested size with GET /api/styles/{styleId}/sample-requests/{sampleRequestId}/measurements, or for one size with GET /api/styles/{styleId}/sample-requests/{sampleRequestId}/measurements/{sizeRangeSizeId}:

{
  "status": "success",
  "code": "sample_request_measurement_retrieved",
  "data": {
    "sizeRangeSizeId": 331,
    "sizeRangeSizeName": "M",
    "unit": "Centimeters",
    "designerComment": null,
    "properties": [],
    "lines": [
      {
        "lineId": 5012,
        "name": "A - Back body length",
        "requestedMeasurement": 68.0,
        "companyMeasurement": null,
        "supplierMeasurement": 68.5,
        "newMeasurement": null,
        "tolerance": 1.0
      },
      {
        "lineId": 5013,
        "name": "B - Chest width",
        "requestedMeasurement": 52.0,
        "companyMeasurement": null,
        "supplierMeasurement": 51.0,
        "newMeasurement": null,
        "tolerance": 0.5
      },
      {
        "lineId": null,
        "name": "C - Hem width",
        "requestedMeasurement": 50.0,
        "companyMeasurement": null,
        "supplierMeasurement": null,
        "newMeasurement": null,
        "tolerance": null
      }
    ]
  }
}

A line with a null lineId is deactivated: it is returned for display and cannot be written. The response carries no discrepancy: compare requestedMeasurement with the measured values yourself. A sizeRangeSizeId that is not a requested size on the request returns 404. Only three values are writable per size: companyMeasurement and newMeasurement on each active line, and the size’s designerComment. The read-only fields (name, requestedMeasurement, supplierMeasurement and tolerance) are rejected in a write body with 400. Pick the call by how much you are writing:

Call	Writes	Semantics
`PUT /api/styles/{styleId}/sample-requests/{sampleRequestId}/measurements`	Every requested size	Full replace. The body is an array with one entry per requested size (`sizeRangeSizeId`, `designerComment`, `lines`), covering every requested size and every active line exactly once.
`PUT /api/styles/{styleId}/sample-requests/{sampleRequestId}/measurements/{sizeRangeSizeId}`	One size	Full replace of that size. The body is a single object (`designerComment`, `lines`) covering every active line of the size exactly once; other sizes are untouched. The route names the size, so a `sizeRangeSizeId` in the body returns 400.
`PATCH /api/styles/{styleId}/sample-requests/{sampleRequestId}/measurements`	Only the paths you send	JSON Patch addressed by array index, e.g. `/0/lines/1/companyMeasurement` or `/0/designerComment`. Omitted values are preserved.
`PATCH /api/styles/{styleId}/sample-requests/{sampleRequestId}/measurements/{sizeRangeSizeId}`	Only the paths you send, within one size	JSON Patch within the size, e.g. `/lines/1/companyMeasurement` or `/designerComment`. Omitted values are preserved.

Record the designer’s measurements for size M and ask for a wider chest in the next round:

cURL

curl -X PATCH "https://service.my.delogue.com/api/styles/4821/sample-requests/90560/measurements/331" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
  { "op": "replace", "path": "/lines/0/companyMeasurement", "value": 68.4 },
  { "op": "replace", "path": "/lines/1/companyMeasurement", "value": 51.2 },
  { "op": "replace", "path": "/lines/1/newMeasurement", "value": 52.5 },
  { "op": "replace", "path": "/designerComment", "value": "Chest runs narrow - widen for the next round." }
]'

The response is the updated size (code: "sample_request_measurement_updated").

Full-replace PUT clears what you leave out. designerComment is written verbatim, so omitting it or sending null clears the fit comment, and a null measured value clears that value. To build the body from the GET response, keep sizeRangeSizeId (grid-wide PUT only), designerComment, and each active line’s lineId, companyMeasurement and newMeasurement; drop the read-only fields and every deactivated line (lineId: null), both of which return 400. Then change only what you mean to. Use PATCH when you only want to touch a few values.

Patch indexes count active lines only, in line-position order (and, on the grid-wide PATCH, requested sizes in size order). A deactivated line is not in the patch document, so do not index by its position in the GET response.
A changed newMeasurement updates the style’s measurement chart. The wanted value is written back to that line of the style’s chart, which is re-graded in the same transaction; if the chart rejects the change, the whole write fails with 422 and nothing is saved.
The write is recorded in the request’s measurement change history, and does not change the sample request’s status or dates.
A request in the commented status does not accept measurement writes (422). A size or line that is not on the request, or a full-replace body that misses a requested size or an active line, also returns 422.

Field reference

The fields that matter most when reading a request back:

Field	What it means at Delogue
`deadline`	Date by which the sample is due. Null when no deadline is set.
`etd`	Estimated time of departure (ETD) for the sample shipment. Null when not set.
`lastStateChange`	When the request’s status or archive state last changed.
`note`	Free-text note on the sample request. Null when none was entered.
`properties`	Extensibility flags. `is_archived` is emitted when the request has been archived.
`sampleType`	The sample type the request was raised for, such as a fit or proto sample. Null when no sample type is set.
`sendDate`	Date the supplier dispatched the sample. Null until the sample is sent.
`status`	Where the request is in the sample workflow, for example `requested`, `sent`, `received` or `commented`.
`trackingNumber`	Carrier tracking number for the dispatched sample. Null until one is recorded.

Measured values

The writable fields of a measurement write. Each measured value is a number in the size’s unit, and null clears it.

Field	What it means at Delogue
`sizeRangeSizeId`	The requested size the entry writes, matching `sizeRangeSizeId` from the read. Grid-wide `PUT` only: the per-size `PUT` takes the size from the route.
`designerComment`	The designer’s fit comment for the size, text only. Written verbatim on a full replace; `null` or empty clears it. While the request is `received`, a changed comment is visible to the designer side only (the size carries the `designerVisibleOnly` marker); in any other status it is visible to the supplier.
`lines[].lineId`	The measurement line (point of measure) to write. Must be an active line on the size.
`lines[].companyMeasurement`	The designer’s measured actual for the line.
`lines[].newMeasurement`	The wanted value for the next sample round. A change is written back to the style’s measurement chart.

Roles & permissions

Sample requests are a style collaboration surface, so access follows the parent style. Designer (brand) accounts (typically CompanyAdmin or CompanyUser) work on the requests of their own styles. Suppliers assigned to the style collaborate on its sample requests: a supplier can read the style’s requests and change their status with PATCH /api/styles/{styleId}/sample-requests/{id}, within the moves the workflow allows the supplier side. Changing status needs styles write access on either side. Measurements are designer-only: reading them requires your organisation to own the style, and writing them also needs styles write access on a brand account (CompanyAdmin or CompanyUser). A supplier caller receives 403 from the measurement endpoints. A style ID belonging to another organisation returns 403; a style ID that exists nowhere returns 404, as does a sample request that is not on the given style.

When things go wrong

Errors use the standard envelope (status: "error", a code, and error.details[]). The PATCH endpoints return 409 when a JSON Patch test operation fails and 422 for any other operation that cannot be applied; a status change or measurement write that collides with a concurrent change also returns 409: re-read and retry. See Errors & responses for the full list of codes and how to resolve them.

What to call next

Styles

Sample requests hang off a style: create and manage the parent style first.

Sample types

Manage the fit / proto / pre-production sample types a request is raised for.

Requested sizes

Read a request’s sizes and per-colour quantities: GET /api/styles/{styleId}/sample-requests/{sampleRequestId}/sizes.

Measurement charts

The style’s graded chart that a request’s target values are frozen from.

Authentication

How to get and send your X-Auth-Token API key.

Getting Started

Concepts

Guides

The workflow

Walkthrough

Move a request through the workflow

Record fit measurements

Field reference

Measured values

Roles & permissions

When things go wrong

What to call next

Styles

Sample types

Requested sizes

Measurement charts

Authentication

​The workflow

​Walkthrough

​Move a request through the workflow

​Record fit measurements

​Field reference

​Measured values

​Roles & permissions

​When things go wrong

​What to call next

Styles

Sample types

Requested sizes

Measurement charts

Authentication

The workflow

Walkthrough

Move a request through the workflow

Record fit measurements

Field reference

Measured values

Roles & permissions

When things go wrong

What to call next