How-to Guide - Rest API - Promotions

Introduction

The purpose of this guide is to provide an understanding of the REST Promotions APIs provided by Enactor for use with external Web Sites and for Customer integration. It is separated out into functional areas, with each section related to a specific service. Note that the final URL used to access the service will be determined based on how the Enactor REST Promotions API is deployed.

Following are Enactor REST Promotions APIs areas covered in this document:

• Promotions API

  • Health Check

  • List Promotions

  • Promotion Calculation

Promotions API

Following is the list of Promotions APIs covered in this section:

• Health Check.

• List Promotions.

• Promotion Calculation.

Health Check

This API is used to check if the promotions service is ready to use. The response body is simply a summary of the checks performed where the HTTP status code is the important information.

Request

Request Service URL

GET /promotions/healthcheck

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

There is no request body.

Response

Response Headers

There are no response headers.

Response Body

IHealthCheckResponse

Element	Type	Description
serviceStatus	String	The status of the service – READY or ERROR.
databaseStatus	String	The status of the database – OK or FAIL.
deploymentStatus	String	The status of the deployment – OK or FAIL.

Request & Response Examples

Request:

GET: http://[SWARM_LEADER_IP]/WebRestApi/rest/promotions/healthcheck
Content-Type: application/json

Response:

Status: 200 OK

{ "serviceStatus": "READY", "databaseStatus": "OK", "deploymentStatus": "OK" }

List Promotions

This lists all the possible promotions when given the list of items and basket details. If the request is empty, then all promotions will be returned.

Request

Request Service URL

POST /promotions/list

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

IPromotionCalculationRequest

Element	Required / Optional	Type	Description
items	Required	List<IPromotionCalculationRequestItem>	A list of items to be requested.

Response

Response Headers

There are no response headers.

Response Body

IListPromotionsResponse

Element	Type	Description
promotions	List<IPromotionResponse>	The promotions relevant to the request.

IPromotionDescriptionResponse

Element	Type	Description
promotionKey	List<IPromotionDescriptionResponse>	The promotion related information such as promotion ID and group that it belongs to.
description	String	The description of the promotion.

Request & Response Examples

Request:

POST http://[SWARM_LEADER_IP]/WebRestApi/rest/promotions/list
Content-Type: application/json

{
  "creationDate": {
    "calendar": 1521129992000
  },
  "honourDate": {},
  "currency": {
    "id": "GBP"
  },
  "employeeSale": false,
  "employeeStartingBalance": 0,
  "fascia": {
    "id": ""
  },
  "items": [
    {
      "promotionCalculationRequestProductItem": {
        "product": {
          "id": "DF517XM-1"
        },
        "parentProduct": {
          "id": "DF517XM"
        },
        "mmGroup": {
          "groupHierarchyId": "FASHION",
          "groupTypeId": "mmGroup",
          "id": "MENS_SHIRTS",
          "variantGroupHierarchyId": "All",
          "variantGroupId": "UK",
          "variantGroupTypeId": "region"
        },
        "brand": {
          "groupHierarchyId": "FASHION",
          "groupTypeId": "brand",
          "id": "INTERNAL",
          "variantGroupHierarchyId": "All",
          "variantGroupId": "UK",
          "variantGroupTypeId": "region"
        },
        "priceType": {
          "id": "R"
        },
        "loyaltyPoints": 0,
        "lineNumber": 1,
        "quantity": 1.0,
        "unitValue": 2595,
        "lineNetValue": 2595,
        "isReturn": false,
        "honourPromotionItem": false,
        "manuallyTargetedPromotionId": []
      }
    }
  ],
  "itemQuantity": 1.0,
  "merchandiseItemQuantity": 1.0,
  "merchandiseItemValue": 2595,
  "enableReturns": false,
  "location": {
    "id": "0001"
  },
  "loyaltyPointsBalance": 0,
  "loyaltyPointsTotal": 0,
  "loyaltyPointsRate": 0,
  "loyaltyTransaction": false,
  "priceGroup": {
    "@entity": "core:groupKey",
    "groupHierarchyId": "ALL",
    "groupTypeId": "priceGroup",
    "id": "UK",
    "variantGroupHierarchyId": "All",
    "variantGroupId": "All",
    "variantGroupTypeId": "region"
  },
  "region": {
    "groupHierarchyId": "All",
    "groupTypeId": "region",
    "id": "UK"
  },
  "total": 2595,
  "ignoreCrossTransactionLimits": false
}

Response:

Status: 200 OK

{
  "promotions": [
    {
      "promotionKey": {
        "promotionId": "C543210",
        "groupKey": {
          "id": "UK",
          "groupTypeId": "region",
          "groupHierarchyId": "All"
        }
      }
    },
    {
      "promotionKey": {
        "promotionId": "Gift Card001",
        "groupKey": {
          "id": "UK",
          "groupTypeId": "region",
          "groupHierarchyId": "All"
        }
      }
    },
    {
      "promotionKey": {
        "promotionId": "VoucherPromo",
        "groupKey": {
          "id": "All",
          "groupTypeId": "region",
          "groupHierarchyId": "All"
        }
      }
    },
    {
      "promotionKey": {
        "promotionId": "GiftVUK Promo",
        "groupKey": {
          "id": "All",
          "groupTypeId": "region",
          "groupHierarchyId": "All"
        }
      }
    },
    {
      "promotionKey": {
        "promotionId": "3",
        "groupKey": {
          "id": "All",
          "groupTypeId": "region",
          "groupHierarchyId": "All"
        }
      }
    },
    {
      "promotionKey": {
        "promotionId": "1",
        "groupKey": {
          "id": "All",
          "groupTypeId": "region",
          "groupHierarchyId": "All"
        }
      }
    }
  ]
}

Promotion Calculation

This service calculates the amount of savings and the total amount of points for the given request.

Request

Request Service URL

POST /promotions/calculate

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

IPromotionCalculationRequest

Element	Required / Optional	Type	Description
items	Required	List<IPromotionCalculationRequestItem>	A list of items to be requested.

Response

Response Headers

There are no response headers.

Response Body

IPromotionCalculationResponse

Element	Type	Description
promotionCalculation	IPromotionCalculation	The result of the promotion calculation.

Request & Response Examples

Request:

POST http://[SWARM_LEADER_IP]/WebRestApi/rest/promotions/calculate
Content-Type: application/json

{
  "creationDate": {
    "calendar": 1521129992000
  },
  "honourDate": {},
  "currency": {
    "id": "GBP"
  },
  "employeeSale": false,
  "employeeStartingBalance": 0,
  "fascia": {
    "id": ""
  },
  "items": [
    {
      "promotionCalculationRequestProductItem": {
        "product": {
          "id": "DF517XM-1"
        },
        "parentProduct": {
          "id": "DF517XM"
        },
        "mmGroup": {
          "groupHierarchyId": "FASHION",
          "groupTypeId": "mmGroup",
          "id": "MENS_SHIRTS",
          "variantGroupHierarchyId": "All",
          "variantGroupId": "UK",
          "variantGroupTypeId": "region"
        },
        "brand": {
          "groupHierarchyId": "FASHION",
          "groupTypeId": "brand",
          "id": "INTERNAL",
          "variantGroupHierarchyId": "All",
          "variantGroupId": "UK",
          "variantGroupTypeId": "region"
        },
        "priceType": {
          "id": "R"
        },
        "loyaltyPoints": 0,
        "lineNumber": 1,
        "quantity": 1.0,
        "unitValue": 2595,
        "lineNetValue": 2595,
        "isReturn": false,
        "honourPromotionItem": false,
        "manuallyTargetedPromotionId": []
      }
    }
  ],
  "itemQuantity": 1.0,
  "merchandiseItemQuantity": 1.0,
  "merchandiseItemValue": 2595,
  "enableReturns": false,
  "location": {
    "id": "0001"
  },
  "loyaltyPointsBalance": 0,
  "loyaltyPointsTotal": 0,
  "loyaltyPointsRate": 0,
  "loyaltyTransaction": false,
  "priceGroup": {
    "@entity": "core:groupKey",
    "groupHierarchyId": "ALL",
    "groupTypeId": "priceGroup",
    "id": "UK",
    "variantGroupHierarchyId": "All",
    "variantGroupId": "All",
    "variantGroupTypeId": "region"
  },
  "region": {
    "groupHierarchyId": "All",
    "groupTypeId": "region",
    "id": "UK"
  },
  "total": 2595,
  "ignoreCrossTransactionLimits": false
}

Response:

Status: 200 OK

{
  "promotionCalculation": {
    "totalSaving": 2595,
    "totalPoints": 0,
    "itemsArray": [
      {
        "promotionSavingItem": {
          "saving": 2595,
          "savingAdjustment": 0,
          "distributedSavings": [
            {
              "distributedPromotionSavingItem": {
                "lineNumber": 1,
                "distributedSaving": 2595,
                "promotionKey": {
                  "promotionId": "1",
                  "groupKey": {
                    "id": "All",
                    "groupTypeId": "region",
                    "groupHierarchyId": "All"
                  }
                },
                "modifierType": "PROMOTION",
                "effectiveValue": -2595
              }
            }
          ],
          "adjustEmployeeBalance": false,
          "promotionDescription": "£10000, 10% off",
          "promotionQuantity": 1,
          "operationWithDiscounts": "APPLIES_AFTER_ON_GROSS",
          "promotionKey": {
            "promotionId": "1",
            "groupKey": {
              "id": "All",
              "groupTypeId": "region",
              "groupHierarchyId": "All"
            }
          },
          "triggers": [
            {
              "rewardValue": 259500000,
              "lineRewardValue": 2595,
              "distributeSaving": true,
              "lineNumber": 1,
              "quantity": 1,
              "unitValue": 2595,
              "triggerCount": 1
            }
          ]
        }
      }
    ]
  }
}