> ## Documentation Index
> Fetch the complete documentation index at: https://integration.delogue.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage sample requests
> Request physical samples against a style, track them through the request → sent → received → commented workflow, and read back the requested sizes and per-colour quantities.
**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 raise sample requests on a style, move them through their lifecycle (cancel,
archive, reactivate), and read the requested sizes and per-colour quantities back for an
overview or an ERP export.
## The workflow
Sample requests hang off a style. You raise one (or several) against the style for a chosen
sample type and size range, the request runs through the sample workflow
(request → sent → received → commented), and you can transition it — cancel, archive, or
reactivate — 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.
A sample request is created on a style (`GET /api/styles/{styleId}`) for a sample type from
the brand's library (`GET /api/sample-types`). Have both IDs ready.
`POST /api/styles/{styleId}/sample-requests` with an array of requests. Each carries a
`sampleTypeId`, the `sizeRangeId`, and `requestedSampleSizes` — the sizes and the per-colour
quantity for each.
`PUT /api/styles/{styleId}/sample-requests` (per style) or `PUT /api/sample-requests`
(across styles) with `{ id, state, comment }` rows to `cancelled`, `archived`, or back to
`requested` (reactivate a cancelled request).
`GET /api/styles/{styleId}/sample-requests` lists a style's requests;
`GET /api/sample-requests` gives the org-wide, paginated overview. Fetch a request's sizes
and per-colour quantities from `GET /api/styles/{styleId}/sample-requests/{sampleRequestId}/sizes`.
```mermaid theme={"dark"}
sequenceDiagram
participant D as Designer
participant API as Delogue API
participant S as Supplier
D->>API: POST /api/styles/{styleId}/sample-requests
API-->>D: sample request id (status "requested")
S->>API: (sample dispatched → status "sent")
D->>API: GET /api/styles/{styleId}/sample-requests/{id}/sizes
API-->>D: requested sizes + per-colour quantities
D->>API: PUT /api/styles/{styleId}/sample-requests (state "cancelled")
API-->>D: updated sample request
```
## Walkthrough
Create a sample request on a style, then read it back. The body is an array — one or many
requests are created in a single all-or-nothing transaction.
```bash cURL theme={"dark"}
curl -X POST "https://service.my.delogue.com/api/styles/{styleId}/sample-requests" \
-H "Accept: application/json" \
-H "X-Auth-Token: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"sampleTypeId": 14,
"sizeRangeId": 208,
"sizeRangeName": "Womenswear Tops",
"deadline": "2026-04-10T00:00:00Z",
"etd": "2026-03-25T00:00:00Z",
"locationId": 55,
"note": "First proto in Navy and Off White",
"allowHalfSample": false,
"requestedSampleSizes": [
{
"sizeRangeSizeId": 331,
"sizeRangeSizeName": "M",
"sizeRangeSizeStatus": true,
"specs": [
{
"styleColorId": 7781,
"styleColorName": "Navy",
"styleColorCustomId2": "NVY",
"quantity": 2,
"available": false
},
{
"styleColorId": 7782,
"styleColorName": "Off White",
"styleColorCustomId2": "OWH",
"quantity": 1,
"available": false
}
]
}
]
}
]'
```
```js JavaScript theme={"dark"}
const res = await fetch("https://service.my.delogue.com/api/styles/{styleId}/sample-requests", {
method: "POST",
headers: {
"Accept": "application/json",
"X-Auth-Token": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify([
{
"sampleTypeId": 14,
"sizeRangeId": 208,
"sizeRangeName": "Womenswear Tops",
"deadline": "2026-04-10T00:00:00Z",
"etd": "2026-03-25T00:00:00Z",
"locationId": 55,
"note": "First proto in Navy and Off White",
"allowHalfSample": false,
"requestedSampleSizes": [
{
"sizeRangeSizeId": 331,
"sizeRangeSizeName": "M",
"sizeRangeSizeStatus": true,
"specs": [
{
"styleColorId": 7781,
"styleColorName": "Navy",
"styleColorCustomId2": "NVY",
"quantity": 2,
"available": false
},
{
"styleColorId": 7782,
"styleColorName": "Off White",
"styleColorCustomId2": "OWH",
"quantity": 1,
"available": false
}
]
}
]
}
]),
});
const { data } = await res.json();
```
```json theme={"dark"}
{
"status": "success",
"code": "sample_requests_created",
"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 created requests in the standard envelope. Hold onto each `id` — the
lifecycle `PUT`s 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.
## Field reference
The fields that matter most when creating a request or reading one back:
| Field | What it means at Delogue |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowHalfSample` | Whether half-size samples are permitted for this request. |
| `deadline` | Date by which the sample is due. Null when no deadline is set. |
| `etd` | Estimated time of departure (ETD) for the sample. Null when not set. |
| `locationId` | Identifier of the delivery location for the sample. Null when no location is set. |
| `note` | Free-text note to attach to the sample request. Null when none. |
| `requestedSampleSizes` | The sizes to request, each with its per-colour quantities. Unless the request is a planned request, at least one size must carry a positive quantity. |
| `sampleTypeId` | Identifier of the sample type to raise the request for. Required. |
| `sizeRangeId` | Identifier of the style's size range the requested sizes are drawn from. Required. |
| `sizeRangeName` | Name of the size range, stored on the request as a snapshot so a cancelled request keeps its size range even if the range is later deleted. |
## Roles & permissions
Sample requests are a **style** collaboration surface, so access follows the parent style.
Raising and transitioning requests requires write access to the style on a **designer (brand)**
account — typically `CompanyAdmin` or `CompanyUser`. Suppliers assigned to the style collaborate
on its sample requests. A style ID belonging to another organisation returns **403**; a style ID
that exists nowhere returns **404**.
## When things go wrong
Errors use the standard envelope (`status: "error"`, a `code`, and `error.details[]`). Bulk
create and bulk lifecycle updates are all-or-nothing and report per-item failures with `[i].field`
paths. See [Errors & responses](/concepts/errors) for the full list of codes and how to resolve
them.
## What to call next
Sample requests hang off a style — create and manage the parent style first.
Manage the fit / proto / pre-production sample types a request is raised for.
Read a request's sizes and per-colour quantities: `GET /api/styles/{styleId}/sample-requests/{sampleRequestId}/sizes`.
How to get and send your `X-Auth-Token` API key.