> ## 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 sub-suppliers
> Build and maintain a supplier's sub-supplier library for supply chain transparency — the companies a supplier works with for production.
**When to use this.** A sub-supplier is any external company a supplier works with as part of
their production network — fabric mills, trim suppliers, printing houses, embroidery workshops,
and similar partners. Suppliers maintain their own library, which brand customers can then view
to gain supply chain visibility. Use these endpoints to create, update, and query that library
on behalf of a supplier organization, or to read sub-suppliers across organizations your
account has access to.
## The workflow
Sub-suppliers belong to a supplier organization. The typical path is to create the sub-supplier
with location and contact details, optionally update or archive it as the relationship evolves,
and soft-delete it when it is no longer part of the supply chain.
`POST /api/organizations/{organizationId}/sub-suppliers` to add one or more sub-suppliers
to a specific supplier org, including the primary contact and relation type. Alternatively,
use `POST /api/sub-suppliers` if your token is already scoped to the supplier org.
`GET /api/sub-suppliers/{id}` to fetch a single sub-supplier, or `GET /api/sub-suppliers`
to list them with filters (country, relation type, custom ID, free-text search).
`PUT /api/sub-suppliers/{id}` for a full replace, or `PATCH /api/sub-suppliers/{id}` for
partial JSON Patch updates (e.g. updating only the website or archiving). Use
`PUT /api/sub-suppliers` to update multiple sub-suppliers in a single request.
Set `state` to `archived` via `PUT` or `PATCH` to hide a sub-supplier from active lists
without removing history. Call `DELETE /api/sub-suppliers/{id}` to soft-delete it and
cascade to its contacts and associated facilities.
```mermaid theme={"dark"}
sequenceDiagram
participant S as Supplier
participant API as Delogue API
S->>API: POST /api/organizations/{organizationId}/sub-suppliers
API-->>S: sub-supplier id (UUID)
S->>API: GET /api/sub-suppliers/{id}
API-->>S: sub-supplier details + contacts
S->>API: PATCH /api/sub-suppliers/{id} (update website or archive)
API-->>S: updated sub-supplier
S->>API: DELETE /api/sub-suppliers/{id} (soft-delete)
API-->>S: sub-supplier with state=deleted
```
## Walkthrough
Create a sub-supplier under a specific supplier organization. The body is an array — one or
many sub-suppliers are created in a single all-or-nothing transaction.
```bash cURL theme={"dark"}
curl -X POST "https://service.my.delogue.com/api/sub-suppliers" \
-H "Accept: application/json" \
-H "X-Auth-Token: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"name": "Foshan Brightweave Textiles Co., Ltd",
"customId": "10004",
"relationType": "styleSupplier",
"address": "Unit 12, Building 3, No. 88 Chunhui Road, Chancheng District",
"zipCode": "528000",
"city": "Foshan City",
"stateOrRegion": "Guangdong Province",
"countryCode": "CN",
"latitude": null,
"longitude": null,
"webSite": null,
"vatNumber": null,
"mid": "CNFOSBRI88CHA",
"avatarColor": "7486FF",
"contacts": [
{
"firstName": "Alex",
"lastName": "Kim",
"email": "alex.kim@example.com",
"phone": "+86 000 0000 0000",
"role": "Production Manager",
"faxNumber": null,
"properties": [
"primaryContact"
],
"countryCode": "CN"
}
]
}
]'
```
```js JavaScript theme={"dark"}
const res = await fetch("https://service.my.delogue.com/api/sub-suppliers", {
method: "POST",
headers: {
"Accept": "application/json",
"X-Auth-Token": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify([
{
"name": "Foshan Brightweave Textiles Co., Ltd",
"customId": "10004",
"relationType": "styleSupplier",
"address": "Unit 12, Building 3, No. 88 Chunhui Road, Chancheng District",
"zipCode": "528000",
"city": "Foshan City",
"stateOrRegion": "Guangdong Province",
"countryCode": "CN",
"latitude": null,
"longitude": null,
"webSite": null,
"vatNumber": null,
"mid": "CNFOSBRI88CHA",
"avatarColor": "7486FF",
"contacts": [
{
"firstName": "Alex",
"lastName": "Kim",
"email": "alex.kim@example.com",
"phone": "+86 000 0000 0000",
"role": "Production Manager",
"faxNumber": null,
"properties": [
"primaryContact"
],
"countryCode": "CN"
}
]
}
]),
});
const { data } = await res.json();
```
```json theme={"dark"}
{
"status": "success",
"code": "sub_suppliers_created",
"data": [
{
"id": "6AE876DD-547D-4202-B004-AC8617E3744A",
"organizationId": 18931,
"name": "Foshan Brightweave Textiles Co., Ltd",
"customId": "10004",
"relationType": "styleSupplier",
"relationTypeName": "Style Supplier",
"address": "Unit 12, Building 3, No. 88 Chunhui Road, Chancheng District",
"zipCode": "528000",
"city": "Foshan City",
"stateOrRegion": "Guangdong Province",
"countryCode": "CN",
"countryName": "China",
"latitude": null,
"longitude": null,
"webSite": null,
"vatNumber": null,
"mid": "CNFOSBRI88CHA",
"avatarColor": "7486FF",
"processingTypes": null,
"facilityCount": 0,
"state": "active",
"createdAt": "2026-06-29T06:52:20.767Z",
"contacts": [
{
"id": 101,
"firstName": "Alex",
"lastName": "Kim",
"email": "alex.kim@example.com",
"phone": "+86 000 0000 0000",
"role": "Production Manager",
"faxNumber": null,
"properties": [
"primaryContact"
],
"countryCode": "CN"
}
]
}
]
}
```
The response wraps the created sub-suppliers in the standard envelope. Hold onto each `id`
(UUID) — you use it for single-record reads, updates, and deletes.
## Field reference
The fields that matter most when creating or updating a sub-supplier:
| Field | What it means at Delogue |
| --------------- | ------------------------------------------------------------------------------------------ |
| `address` | Street address of the sub-supplier. |
| `avatarColor` | Hex color code for the avatar, e.g. 7486FF. |
| `city` | City. |
| `contacts` | Initial list of contact persons to create with the sub-supplier. |
| `countryCode` | ISO 3166-1 alpha-2 country code. Required. |
| `customId` | Customer-defined identifier for the sub-supplier. |
| `latitude` | Geographic latitude in decimal degrees. |
| `longitude` | Geographic longitude in decimal degrees. |
| `mid` | Manufacturer Identification (MID) number. |
| `name` | Display name of the sub-supplier company. Required. |
| `relationType` | Commercial relationship type: distributor, itemSupplier, sourcingAgency, or styleSupplier. |
| `stateOrRegion` | State, province, or region. |
| `vatNumber` | VAT registration number. |
| `webSite` | Website URL. |
| `zipCode` | Postal or ZIP code. |
## Roles & permissions
Managing a sub-supplier library requires the **`suppliers`** permission on a **supplier**
account — `SupplierAdmin` or `SupplierUser`. Brand (designer) accounts with access to the
Supplier Module can read sub-supplier data via the org-scoped endpoints
(`GET /api/organizations/{organizationId}/sub-suppliers`) but cannot create or modify sub-suppliers
on behalf of a supplier organization without an active brand relationship.
## When things go wrong
Errors use the standard envelope (`status: "error"`, a `code`, and `error.details[]`). See
[Errors & responses](/concepts/errors) for the full list of codes and how to resolve them.
Common cases:
* **404** — the sub-supplier UUID does not exist or belongs to a different organization.
* **403** — your account does not have an active brand relationship with the supplier org, or lacks the `suppliers` permission.
* **400** — a required field (`name`, `countryCode`) is missing, or an enum value (`relationType`, `state`) is invalid.
## What to call next
Register production facility locations for a sub-supplier to build out the supply chain map.
Manage the brand's reusable colour library that styles and items reference.
Create the seasons that styles are filed under — the top-level collection structure.
Look up the supplier and contact people assigned to a style.
Full parameter and response schemas for all sub-supplier endpoints.