Promotions

This API allows to retrieve the promotions applicable to the provided search criteria. #### Request URI #### Request Parameters

API field	Type	Description	Mandatory	Technical Details
`customerCode`	String	Customer code used to identify the promotion scope.	Y	SAP Kunnr.
`invoiceDate`	String	Invoice reference date used to identify applicable promotions.	Y	Recommended format: YYYY-MM-DD.
`materialCode`	String	Material code to be included in the promotion search.	Y	Can be repeated to search for multiple materials.

#### Request Example

GET /promotions/v1?customerCode=<CUSTOMER_CODE>&invoiceDate=<INVOICE_DATE>&materialCode=<MATERIAL_CODE>

#### Request Example with multiple materials

GET /promotions/v1?customerCode=<CUSTOMER_CODE>&invoiceDate=<INVOICE_DATE>&materialCode=<MATERIAL_CODE_1>&materialCode=<MATERIAL_CODE_2>

#### Response Structure

API field	Type	Mandatory	Description
`promotions (0..∞)`
`promotionCode`	String	N	Promotion identifier.
`customerCode`	String	N	Customer code associated with the promotion.
`customerName`	String	N	Customer name associated with the promotion.
`salesOrganizationCode`	String	N	Sales organization code.
`promotionDescription`	String	N	Promotion description.
`promotionTypeCode`	String	N	Promotion type code.
`comment`	String	N	Promotion comment.
`sellInStartDate`	String	N	Sell-in start date.
`sellInEndDate`	String	N	Sell-in end date.
`sellOutStartDate`	String	N	Sell-out start date.
`sellOutEndDate`	String	N	Sell-out end date.
`deliveryStartDate`	String	N	Delivery start date.
`deliveryEndDate`	String	N	Delivery end date.
`promotionStatus`	String	N	Promotion status.
`financialReferencePromotion`	String	N	Financial reference promotion.
`groupOperation`	String	N	Group operation code.
`depotCode`	String	N	Depot code.
`operationClosed`	Boolean	N	Indicates whether the operation is closed.
`orderReceived`	Boolean	N	Indicates whether the order has been received.
`creationDate`	String	N	Promotion creation date.
`modificationTime`	String	N	Promotion last modification time.
`modificationDate`	String	N	Promotion last modification date.
`modifiedBy`	String	N	User who last modified the promotion.
`accrualCurrencyCode`	String	N	Accrual currency code.
`accrualAmount`	Decimal	N	Accrual amount.

#### Response Example

{
  "promotions": [
    {
      "promotionCode": "0000060023",
      "customerCode": "ZCNTFR0012",
      "customerName": "Customer name",
      "salesOrganizationCode": "FR60",
      "promotionDescription": "Promotion description",
      "promotionTypeCode": "Z001",
      "comment": "Promotion comment",
      "sellInStartDate": "2026-07-01",
      "sellInEndDate": "2026-07-31",
      "sellOutStartDate": "2026-07-01",
      "sellOutEndDate": "2026-08-15",
      "deliveryStartDate": "2026-06-25",
      "deliveryEndDate": "2026-07-20",
      "promotionStatus": "ACTIVE",
      "financialReferencePromotion": "FRPROMO20260023",
      "groupOperation": "SUMMER2026",
      "depotCode": "FR01",
      "operationClosed": false,
      "orderReceived": true,
      "creationDate": "2026-06-10",
      "modificationTime": "10:30:00",
      "modificationDate": "2026-06-18",
      "modifiedBy": "PROMOTOOL_USER",
      "accrualCurrencyCode": "EUR",
      "accrualAmount": 1500.00
    }
  ]
}

#### Empty Response Example

{
  "promotions": []
}

#### Error Response Structure

API field	Type	Mandatory	Description
`status`	String	Y	Response status. Returned as Error in case of failed processing.
`message`	String	Y	Error message describing the reason of the failure.

#### Error Response Examples

Validation error

{
  "status": "Error",
  "message": "Invalid or missing request parameters."
}

SAP / backend processing error

{
  "status": "Error",
  "message": "Unable to retrieve promotion information. SAP returned a processing error."
}

version 2 as of 5 days ago by Daniele.Urciuoli

0 Comments

Please sign in to post a comment.

Promotions

0 Comments

Docs Navigation