Orders

Purchase orders are created and submitted in DSOrder. The ERP polls for submitted orders, reports what was delivered for each order line and closes the order once receiving is complete.

---

Get Submitted Orders

Method: GET
URL: https://{url}/orders/submitted

Returns the orders created today (UTC calendar day) that are in Submitted status.

Frequency:

Controlled by the ERP, for example every 5 minutes.

Technical:

• The same order is returned by every poll for the rest of the day while it stays in Submitted status. The ERP must de-duplicate by order_id. Reporting fulfillment does not remove an order from the list; closing it does.
• Orders created on previous days are not returned, even if they are still submitted.
• Only order lines with a quantity greater than zero are included in details.

Response Body

The orders are returned in the data field of the response envelope.

Order object:

Name	Type	Required	Description
order_id	string	Yes	Unique order identifier in DSOrder
supplier_id	string	Yes	Unique supplier identifier in the external system
store_id	string	Yes	Unique store identifier in the external system
order_date	timestamp	Yes	Date and time the order was created
delivery_date	timestamp	Yes	Delivery date (midnight UTC)
xdock_delivery_date	timestamp	No	Cross-dock delivery date (midnight UTC); null if the order is not delivered through a cross-dock
supplier_schedule_title	string	No	Title of the supplier schedule the order was created from; null if none
details	array	Yes	Order lines, see below; may be empty

Order line object (inside details):

Name	Type	Required	Description
line_number	number	Yes	Order line number, unique within the order. Use it when reporting fulfillment
article_id	string	Yes	Unique article identifier in the external system
quantity	number	Yes	Ordered quantity. If the article has an order unit coefficient configured in DSOrder, the quantity is in order units (base quantity divided by the coefficient, rounded to a whole number); otherwise it is in base units
min_purchase_shelf_life	timestamp	Yes	Earliest acceptable expiry date of the delivered goods

Response

200: OK

{
    "success": true,
    "message": null,
    "data": [
        {
            "order_id": "100034",
            "supplier_id": "SU-000002",
            "store_id": "ST-0000001",
            "order_date": 1758096912000,
            "delivery_date": 1758240000000,
            "xdock_delivery_date": null,
            "supplier_schedule_title": "JIT 1-3+3-5+5-1 3x",
            "details": [
                {
                    "line_number": 1000,
                    "article_id": "ART-000003",
                    "quantity": 100,
                    "min_purchase_shelf_life": 1758844800000
                },
                {
                    "line_number": 2000,
                    "article_id": "ART-000004",
                    "quantity": 100.5,
                    "min_purchase_shelf_life": 1758844800000
                }
            ]
        }
    ],
    "warnings": []
}

If no orders were submitted today, data is an empty array.

---

Report Order Fulfillment

Method: POST
URL: https://{url}/orders/{order_id}/fulfill

Reports received quantities per order line. Fulfillment can be reported several times, until the line is finished or the order is closed.

Frequency:

Near real-time, as goods are received.

Technical:

• quantity is added to the quantity already received for the line. Send only the quantity received since the previous report, not the running total. Resending the same report counts the quantity twice.
• A line reported with "finished": true is locked. Later reports for that line are skipped and returned as a warning; the rest of the request is still processed.
• A line is identified by the combination of line_number and article_id; both must match the order.
• The request is atomic: if any line fails (unknown article, line not found in the order), nothing from the request is saved.
• The order can be in any status except Closed.

Path Parameters

Name	Type	Required	Description
order_id	string	Yes	Unique order identifier in DSOrder

Request Body

The request body is a JSON array of objects.

Name	Type	Required	Description
line_number	number	Yes	Order line number, as returned by Get Submitted Orders
article_id	string	Yes	Unique article identifier in the external system
quantity	number	Yes	Quantity in base units received since the previous report for this line
finished	boolean	Yes	true if no more deliveries are expected for this line

Request Example

[
    {
        "line_number": 1000,
        "article_id": "ART-000003",
        "quantity": 12,
        "finished": true
    },
    {
        "line_number": 2000,
        "article_id": "ART-000004",
        "quantity": 36,
        "finished": false
    }
]

Response

200: OK — Success

{
    "success": true,
    "message": null,
    "data": null,
    "warnings": []
}

200: OK — Success with warnings

{
    "success": true,
    "message": null,
    "data": null,
    "warnings": [
        "Order line 1000 has already been marked as finished, skipping"
    ]
}

200: OK — Error

Order not found:

{
    "success": false,
    "message": "Purchase order with externalId '100123' was not found for organization '42'",
    "data": null,
    "warnings": []
}

Order already closed:

{
    "success": false,
    "message": "Order 100123 has been closed already",
    "data": null,
    "warnings": []
}

---

Close Order

Method: POST
URL: https://{url}/orders/{order_id}/close

Closes the order once receiving is complete. A closed order is read-only: it no longer accepts fulfillment reports and is no longer returned by Get Submitted Orders.

Frequency:

Near real-time, when receiving of the order is complete.

Technical:

• Only orders in Submitted or In receiving status can be closed.
• Closing an order that is already closed returns an error; it is safe to treat that error as success when retrying.

Path Parameters

Name	Type	Required	Description
order_id	string	Yes	Unique order identifier in DSOrder

Request Body

None.

Response

200: OK — Success

{
    "success": true,
    "message": null,
    "data": null,
    "warnings": []
}

200: OK — Error

Order not found:

{
    "success": false,
    "message": "Purchase order with externalId '100123' was not found for organization '42'",
    "data": null,
    "warnings": []
}

Order already closed:

{
    "success": false,
    "message": "Order 5512 has been closed already",
    "data": null,
    "warnings": []
}

Order in a status that cannot be closed:

{
    "success": false,
    "message": "Order 5512 can not be closed, because it is in 'CANCELLED' status",
    "data": null,
    "warnings": []
}