Skip to main content

Promotion Articles

Frequency:

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

Expected data:

Articles taking part in a promotion, with the purchase and sales periods of the promotion, either for the whole organization or for a specific store.

Technical:

  • The promotion must be imported first.
  • A promotion article is identified by promotion_id, article_id and store_id. A record without store_id (organization-wide) and a record for a specific store are separate promotion articles.
  • If the promotion article does not exist in DSOrder, it is created. If it exists, its periods and is_not_ordered_after_promo are overwritten with the new values.

Import Promotion Articles​

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

Creates or updates promotion articles. Resending the same request is safe.

Processing stops at the first failing record; records before it stay saved (see Partial processing).

Request Body​

The request body is a JSON array of objects.

NameTypeRequiredDescription
promotion_idstringYesUnique promotion identifier in the external system
article_idstringYesUnique article identifier in the external system
store_idstringNoUnique store identifier in the external system; null or omitted if the promotion applies to all stores
purchase_startdateYesFirst day of the purchase period of the promotion
purchase_enddateYesLast day of the purchase period of the promotion
sales_startdateYesFirst day of the sales period of the promotion
sales_enddateYesLast day of the sales period of the promotion
is_not_ordered_after_promobooleanNotrue if the article must not be ordered for delivery after the promotion ends. Default: false

Request Example​

[
    {
        "promotion_id": "PROMO-00001",
        "article_id": "ART-00001",
        "store_id": null,
        "purchase_start": "2026-07-26",
        "purchase_end": "2026-08-30",
        "sales_start": "2026-08-01",
        "sales_end": "2026-08-30",
        "is_not_ordered_after_promo": false
    },
    {
        "promotion_id": "PROMO-00001",
        "article_id": "ART-00002",
        "store_id": "STORE-0001",
        "purchase_start": "2026-07-26",
        "purchase_end": "2026-08-30",
        "sales_start": "2026-08-01",
        "sales_end": "2026-08-30",
        "is_not_ordered_after_promo": true
    }
]

Response​

200: OK — Success​

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

200: OK — Error​

Unknown promotion:

{
    "success": false,
    "message": "Promotion not found by external ID PROMO-00001 and organization ID 7",
    "data": null,
    "warnings": []
}

Unknown article:

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

Unknown stores are reported the same way. A missing promotion_id, article_id or date also returns "success": false, and in that case nothing from the request is saved.

Delete Promotion Articles​

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

Removes articles from promotions.

Technical:

  • All promotion articles of the article in the promotion are deleted — the organization-wide record and the records for every store.
  • Deleting an article that is not in the promotion succeeds and changes nothing.
  • The promotion and the article must exist in DSOrder, otherwise the request fails. Processing stops at the first failing record; records before it stay deleted.

Request Body​

The request body is a JSON array of objects.

NameTypeRequiredDescription
promotion_idstringYesUnique promotion identifier in the external system
article_idstringYesUnique article identifier in the external system

Request Example​

[
    {
        "promotion_id": "PROMO-00001",
        "article_id": "ART-00001"
    },
    {
        "promotion_id": "PROMO-00001",
        "article_id": "ART-00002"
    }
]

Response​

200: OK — Success​

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

200: OK — Error​

{
    "success": false,
    "message": "Promotion not found by external ID PROMO-00001 and organization ID 7",
    "data": null,
    "warnings": []
}

Get Promotion Articles​

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

Returns the promotion articles of a store whose sales period has not ended on the given date — promotions that are running on that date or start later.

Technical:

  • Only store-specific promotion articles are returned. Organization-wide promotion articles (imported without store_id) are not included.
  • A promotion article is included when sales_end is on or after date.

Path Parameters​

NameTypeRequiredDescription
datedateYesReference date in yyyy-mm-dd format
store_idstringYesUnique store identifier in the external system

Response Body​

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

NameTypeRequiredDescription
promotion_idstringYesUnique promotion identifier in the external system
article_idstringYesUnique article identifier in the external system
purchase_startdateYesFirst day of the purchase period of the promotion
purchase_enddateYesLast day of the purchase period of the promotion
sales_startdateYesFirst day of the sales period of the promotion
sales_enddateYesLast day of the sales period of the promotion
is_not_ordered_after_promobooleanYestrue if the article must not be ordered for delivery after the promotion ends

Response​

200: OK​

[
    {
        "promotion_id": "PROMO-00001",
        "article_id": "ART-00002",
        "purchase_start": "2026-07-26",
        "purchase_end": "2026-08-30",
        "sales_start": "2026-08-01",
        "sales_end": "2026-08-30",
        "is_not_ordered_after_promo": true
    }
]

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.