Promotions

Frequency:

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

Expected data:

Promotions on organization level:

• Promotion ID: the unique identifier of the promotion.
• Promotion type: the type of the promotion. Promotion types are configured in DSOrder during onboarding.

Promotions must be imported before their promotion articles.

Technical:

• If a promotion does not exist in DSOrder, it is created.
• If a promotion already exists, it is left unchanged; a different type_id is ignored. Contact DSOrder if the type of an existing promotion has to change.
• Resending the same request is safe.
• Processing stops at the first failing record; promotions before it stay saved (see Partial processing).

---

Import Promotions

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

Creates promotions that do not exist yet.

Request Body

The request body is a JSON array of objects.

Name	Type	Required	Description
external_id	string	Yes	Unique promotion identifier in the external system
type_id	string	Yes	Unique promotion type identifier in the external system; the type must be configured in DSOrder

Request Example

[
    {
        "external_id": "PROMO-00001",
        "type_id": "TV-PROMO"
    },
    {
        "external_id": "PROMO-00002",
        "type_id": "LEAFLET"
    }
]

Response

200: OK — Success

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

200: OK — Error

Unknown promotion type:

{
    "success": false,
    "message": "Promotion type not found by external ID TV-PROMO for client 42",
    "data": null,
    "warnings": []
}

A missing or empty external_id also returns "success": false.