curl --request PATCH \
  --url https://api.comstruct.com/v1/supplier-orders/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "change_type": "CONFIRM_ORDER",
  "comment": "Bestellung wird wie geplant ausgeliefert."
}
'

{
  "message": "Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet.",
  "error": null
}

Orders (Supplier)

Update supplier order

Erforderliche Berechtigungen: orders:write

Ermöglicht es einem Lieferanten, eine ihm zugeordnete Bestellung zu aktualisieren — Bestätigen, Ablehnen, Bearbeiten, Stornierung bestätigen, Abruf bestätigen oder Eingang bestätigen.

Der API-Schlüssel muss mit einem Lieferanten verknüpft sein (SUPPLIER_AND_OPTIONAL_CUSTOMER). Lieferanten können ausschließlich Bestellungen aktualisieren, die ihrem Lieferantenkonto zugeordnet sind.

Verhalten der change_type-State-Machine:

CONFIRM_ORDER — Setzt den Status auf CONFIRMED.
DECLINE_ORDER — Setzt den Status auf DECLINED.
EDIT_ORDER — Wendet die in changes übergebenen Felder an, ohne den Status zu ändern.
CONFIRM_CANCEL_ORDER — Setzt den Status auf CANCEL_CONFIRMED (nur möglich, wenn die Bestellung im Status CANCELLED ist).
CONFIRM_ON_DEMAND — Setzt den Status auf ON_DEMAND_CONFIRMED.
RECEIVE_ORDER — Setzt den Status auf RECEIVED.

Das Feld changes wird nur für EDIT_ORDER ausgewertet — bei den übrigen Änderungstypen wird es ignoriert. So können ERP-Systeme bei Bestätigungen risikofrei den vollständigen Bestelldatensatz mitschicken, ohne ihn versehentlich zu mutieren.

Optional kann pdf_base64 ein base64-kodiertes PDF (z. B. Auftragsbestätigung) mitschicken. Identische PDFs werden per Content-Hash dedupliziert.

Werden keine tatsächlichen Änderungen erkannt (z. B. weil die übergebenen Werte mit dem aktuellen Stand übereinstimmen), liefert der Endpunkt Keine Änderungen zurück und führt keinen Schreibvorgang aus.

PATCH

supplier-orders

{id}

curl --request PATCH \
  --url https://api.comstruct.com/v1/supplier-orders/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "change_type": "CONFIRM_ORDER",
  "comment": "Bestellung wird wie geplant ausgeliefert."
}
'

{
  "message": "Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet.",
  "error": null
}

Overview

This endpoint lets a supplier update one of their assigned orders through the comstruct API. Confirming, declining, editing, confirming a cancellation, confirming an on-demand call-off, and acknowledging receipt are all handled through a single PATCH call. The actual status transition is derived server-side from the change_type field — status is intentionally not part of the request body so the state machine stays on the server.

If the submitted fields match the current state of the order, the endpoint replies with Keine Änderungen (“No changes”) and skips the write. ERP systems can therefore safely include the full order payload on confirmations without risking accidental mutations.

Permissions

Scope	Tenant type
`orders:write`	Supplier API key (`SUPPLIER_AND_OPTIONAL_CUSTOMER`)

The API key must be linked to a supplier. Customer-only API keys cannot use this endpoint. Suppliers can only update orders that are assigned to their own supplier account.

Headers

Header	Required	Description
`x-api-key`	Yes	API key with scope `orders:write`
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Description
`id`	`uuid`	Unique ID of the order to update

Change types (`change_type`)

Value	Effect	Precondition
`CONFIRM_ORDER`	Sets status to `CONFIRMED`	—
`DECLINE_ORDER`	Sets status to `DECLINED`	—
`EDIT_ORDER`	Applies the fields in `changes`; status stays the same	—
`CONFIRM_CANCEL_ORDER`	Sets status to `CANCEL_CONFIRMED`	Order must be in status `CANCELLED`
`CONFIRM_ON_DEMAND`	Sets status to `ON_DEMAND_CONFIRMED`	—
`RECEIVE_ORDER`	Sets status to `RECEIVED`	—

changes is only consumed for EDIT_ORDER. For every other change type the body of changes is ignored.

Supplier Comment Field

The comment field is an optional top-level string field (max 2000 characters) that can be sent with any change_type. It is used by suppliers to:

Add notes when confirming an order (e.g., ‘Confirmed, delivery scheduled for next week’)
Explain reasons when declining (e.g., ‘Material unavailable until Q2’)
Provide context during edits (e.g., ‘Increased quantity per customer request’)

The comment field is always included in the change notification email sent to the customer, regardless of which change_type was used. This makes it ideal for supplier-to-customer communication.

The comment field is separate from the editable changes.comment field used in EDIT_ORDER. The top-level comment is for this specific action, while changes.comment permanently updates the order’s stored comment.

Examples

Confirming with a comment:

{
  "change_type": "CONFIRM_ORDER",
  "comment": "Order confirmed, estimated delivery Monday"
}

Declining with an explanation:

{
  "change_type": "DECLINE_ORDER",
  "comment": "Cannot fulfill - requested material discontinued"
}

Editing with a comment:

{
  "change_type": "EDIT_ORDER",
  "comment": "Updated delivery date per customer phone call",
  "changes": {
    "planned_delivery_time": "2026-09-20T08:00:00Z"
  }
}

Optional PDF (`pdf_base64`)

Field	Type	Required	Description
`pdf_base64`	`string`	No	Base64-encoded PDF (max. 10 MB decoded)
`pdf_file_name`	`string`	No	Optional filename for the stored document title

The PDF can be sent with any change_type — for example confirm an order and attach the order confirmation in one request. Identical PDFs are deduplicated by content hash.

Editable fields (only on `EDIT_ORDER`)

Field	Type	Description
`supplier_order_number`	`string`	Supplier-side order number
`planned_delivery_time`	`string` (ISO 8601)	Planned delivery date / time
`comment`	`string`	Supplier comment on the order
`properties`	`object`	Free-form additional metadata (shallow-merged with existing `properties`)
`items`	`array`	Order line items — replaces the existing item list

Item fields (`items[]`)

Field	Type	Description
`title`	`string`	Line item title
`quantity`	`number` (≥ 0)	Quantity
`unit`	`string`	Unit of measure (`m3`, `t`, `kg`, `stk`, `h`, `pau`, …)
`description`	`string`	Optional long description
`product_number`	`string`	Supplier product number
`type`	`string`	Line item type
`marked`	`boolean`	Flag the line item as verified

Behavior

Only fields that actually differ from the current state are written.
If EDIT_ORDER produces no real diff, the endpoint replies with Keine Änderungen and writes nothing.
properties is shallow-merged with the existing payload — keys you don’t send keep their previous value.
items is fully replaced when present in changes.
Every successful mutation triggers a change notification email to the customer; the comment is forwarded in that email.

Response codes

Code	Description
`200`	Order updated successfully or no changes detected
`400`	Invalid input — validation failed
`401`	Unauthorized — API key is not linked to a supplier
`403`	Forbidden — missing `orders:write` scope, or order belongs to another supplier
`404`	Order not found / invalid `id`
`500`	Internal server error

Authorizations

X-API-Key

string

header

required

API-Schlüssel zur Authentifizierung. Kontaktieren Sie Ihren Customer Success Manager, um einen API-Schlüssel zu erhalten.

Jeder Endpunkt erfordert spezifische Berechtigungen (Scopes); die erforderlichen Scopes werden pro Endpunkt angezeigt.

Scopes

orders:write

Path Parameters

string<uuid>

required

Bestellungs-ID (UUID)

Body

application/json

change_type

enum<string>

required

Treibt die Statusübergänge der Bestellung:

CONFIRM_ORDER → Status CONFIRMED
DECLINE_ORDER → Status DECLINED
EDIT_ORDER → Status unverändert; changes werden angewendet
CONFIRM_CANCEL_ORDER → Status CANCEL_CONFIRMED (Bestellung muss vorher CANCELLED sein)
CONFIRM_ON_DEMAND → Status ON_DEMAND_CONFIRMED
RECEIVE_ORDER → Status RECEIVED

Available options:

CONFIRM_ORDER,

DECLINE_ORDER,

EDIT_ORDER,

CONFIRM_CANCEL_ORDER,

CONFIRM_ON_DEMAND,

RECEIVE_ORDER

comment

string

Optionaler Kommentar des Lieferanten zu dieser Änderung. Wird in der Benachrichtigung an das Bauunternehmen mitgesendet.

Maximum string length: 2000

changes

object

Konkrete Feldänderungen. Wird nur für change_type: EDIT_ORDER ausgewertet — bei allen anderen Änderungstypen wird der Inhalt ignoriert, sodass ERP-Systeme den vollständigen Bestelldatensatz risikofrei mitschicken können.

Show child attributes

pdf_base64

string

Optionales base64-kodiertes PDF (roh oder mit data-URI-Präfix, max. 10 MB dekodiert)

pdf_file_name

string

Optionaler Dateiname für den Dokumenttitel bei pdf_base64

Response

Bestellung erfolgreich aktualisiert oder keine Änderungen erkannt

message

string

Menschenlesbare Statusmeldung; Keine Änderungen signalisiert, dass keine Mutation durchgeführt wurde.

Example:

"Die aktualisierte Bestellung wurde an das Bauunternehmen gesendet."

error

string | null

Fehlermeldung, sofern aufgetreten (sonst null)

Example:

null

Overview

Projects

Deliveries

Invoices

Invoice dimensions

Suppliers

Purchase orders

Orders (Supplier)

Master data

Q-Point Integration

Workflows

Calendar

IDS Orders

Update supplier order

Overview

Permissions

Headers

Path parameters

Change types (`change_type`)

Supplier Comment Field

Examples

Optional PDF (`pdf_base64`)

Editable fields (only on `EDIT_ORDER`)

Item fields (`items[]`)

Behavior

Response codes

Authorizations

Scopes

Path Parameters

Body

Response

​Overview

​Permissions

​Headers

​Path parameters

​Change types (change_type)

​Supplier Comment Field

​Examples

​Optional PDF (pdf_base64)

​Editable fields (only on EDIT_ORDER)

​Item fields (items[])

​Behavior

​Response codes

Authorizations

Scopes

Path Parameters

Body

Response

Overview

Permissions

Headers

Path parameters

Change types (`change_type`)

Supplier Comment Field

Examples

Optional PDF (`pdf_base64`)

Editable fields (only on `EDIT_ORDER`)

Item fields (`items[]`)

Behavior

Response codes