Article Placements

Frequency:

Near real-time: any change of an article placement in the external system should trigger the interface.

Expected data:

Placement quantities and types of articles in specific stores for a period, independent of promotions (for example, a display pallet placed in the store).

Placement types are configured in DSOrder during onboarding.

Technical:

• A placement is identified by article_id, store_id, type_id, placement_start and placement_end. Changing the period of a placement creates a new placement; delete the old one explicitly.
• Records that reference an unknown store, article or placement type are skipped without an error, and the response still reports "success": true. Use Get Article Placements to verify an import if needed.

---

Import Article Placements

Method: POST
URL: https://{url}/articles/placement

Creates or updates article placements. If the placement exists, its quantity is overwritten; otherwise it is created. Resending the same request is safe.

Request Body

The request body is a JSON array of objects.

Name	Type	Required	Description
article_id	string	Yes	Unique article identifier in the external system
store_id	string	Yes	Unique store identifier in the external system
quantity	number	Yes	Placement quantity
type_id	string	Yes	Unique placement type identifier in the external system; the type must be configured in DSOrder
placement_start	date	Yes	First day of the placement
placement_end	date	Yes	Last day of the placement

Request Example

[
    {
        "article_id": "ART-00001",
        "store_id": "STORE-0001",
        "quantity": 120,
        "type_id": "EUR",
        "placement_start": "2026-10-15",
        "placement_end": "2026-10-31"
    },
    {
        "article_id": "ART-00002",
        "store_id": "STORE-0001",
        "quantity": 120,
        "type_id": "EUR",
        "placement_start": "2026-10-01",
        "placement_end": "2026-10-31"
    }
]

Response

200: OK — Success

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

200: OK — Error

Returned only when the request body cannot be read — for example, it is not a JSON array, contains undocumented fields, or a date is not in yyyy-mm-dd format. Nothing is saved in that case, and message describes the parsing problem.

{
    "success": false,
    "message": "Unrecognized field \"placement_type_id\" ...",
    "data": null,
    "warnings": []
}

---

Delete Article Placements

Method: DELETE
URL: https://{url}/articles/placement

Deletes article placements. The placement must match all identifying fields exactly, including placement_start and placement_end. Deleting a placement that does not exist succeeds and changes nothing.

Request Body

The request body is a JSON array of objects. Do not include quantity.

Name	Type	Required	Description
article_id	string	Yes	Unique article identifier in the external system
store_id	string	Yes	Unique store identifier in the external system
type_id	string	Yes	Unique placement type identifier in the external system
placement_start	date	Yes	First day of the placement
placement_end	date	Yes	Last day of the placement

Request Example

[
    {
        "article_id": "ART-00001",
        "store_id": "STORE-0001",
        "type_id": "EUR",
        "placement_start": "2026-10-15",
        "placement_end": "2026-10-31"
    },
    {
        "article_id": "ART-00002",
        "store_id": "STORE-0001",
        "type_id": "EUR",
        "placement_start": "2026-10-01",
        "placement_end": "2026-10-31"
    }
]

Response

200: OK — Success

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

200: OK — Error

Returned only when the request body cannot be read, as for Import Article Placements. Nothing is deleted in that case.

{
    "success": false,
    "message": "Unrecognized field \"quantity\" ...",
    "data": null,
    "warnings": []
}

---

Get Article Placements

Method: GET
URL: https://{url}/articles/placement/{date}/{store_id}

Returns the article placements of a store that have not ended on the given date — placements that are active on that date or start later. A placement is included when placement_end is on or after date.

Path Parameters

Name	Type	Required	Description
date	date	Yes	Reference date in yyyy-mm-dd format
store_id	string	Yes	Unique store identifier in the external system

Response Body

A JSON array of objects; empty if the store has no such placements.

Name	Type	Required	Description
article_id	string	Yes	Unique article identifier in the external system
quantity	number	Yes	Placement quantity
type_id	string	Yes	Unique placement type identifier in the external system
placement_start	date	Yes	First day of the placement
placement_end	date	Yes	Last day of the placement

Response

200: OK

[
    {
        "article_id": "ART-00001",
        "quantity": 120,
        "type_id": "EUR",
        "placement_start": "2026-10-15",
        "placement_end": "2026-10-31"
    },
    {
        "article_id": "ART-00002",
        "quantity": 120,
        "type_id": "EUR",
        "placement_start": "2026-10-01",
        "placement_end": "2026-10-31"
    }
]

200: OK — Error

Unknown store:

{
    "success": false,
    "message": "Store with external ID 'STORE-9999' was not found for organization '7'",
    "data": null,
    "warnings": []
}

409: Conflict

date is not in yyyy-mm-dd format. Empty body.