Promotion Article Placements

Frequency:

Near real-time: a new promotion article placement in the external system should trigger the interface.

Expected data:

Placement quantities and types of promotion articles in specific stores (for example, the number of pallets placed in the store for the promotion).

Placement types are configured in DSOrder during onboarding.

Technical:

• The promotion and the promotion article must be imported first. The placement is attached to the promotion article of the store; if there is none, to the organization-wide promotion article.
• A placement is identified by the promotion article, store_id and placement_type_id.
• If the placement does not exist in DSOrder, it is created.
• If the placement already exists, it is left unchanged; a different placement_quantity is ignored. Contact DSOrder if the quantity of an existing placement has to change.
• The following records are skipped without an error:
  • placement_type_id is not configured in DSOrder;
  • the article is not part of the promotion (no matching promotion article).
• An unknown promotion, article or store fails the request. Processing stops at the failing record; records before it stay saved (see Partial processing).
• Resending the same request is safe.

---

Import Promotion Article Placements

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

Creates promotion article placements that do not exist yet.

Request Body

The request body is a JSON array of objects.

Name	Type	Required	Description
promotion_id	string	Yes	Unique promotion identifier in the external system
article_id	string	Yes	Unique article identifier in the external system
store_id	string	Yes	Unique store identifier in the external system
placement_quantity	number	Yes	Placement quantity
placement_type_id	string	Yes	Unique placement type identifier in the external system; the type must be configured in DSOrder

Request Example

[
    {
        "promotion_id": "PROMO-00001",
        "article_id": "ART-00001",
        "store_id": "STORE-0001",
        "placement_quantity": 120,
        "placement_type_id": "EUR"
    },
    {
        "promotion_id": "PROMO-00001",
        "article_id": "ART-00002",
        "store_id": "STORE-0002",
        "placement_quantity": 100,
        "placement_type_id": "EUR"
    }
]

Response

200: OK — Success

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

200: OK — Error

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