Discount Priorities

Discounts are evaluated in priority order. The order is from lowest to highest. E.g. a discount with a priority of 1 will be evaluated before a discount with a priority of 2.

When a discount is created it is created with a higher priority than the existing discounts. This means it will be evaluated last unless the priority is updated.

Getting Discount Priorities

The /discounts Builder API endpoint returns the priority of discounts (discounts are also returned in priority order).

Below is an example response showing the priority property.

{
  "discounts": [
    {
      "id": "e80c622f-4c97-4c34-9e54-e8847e925066",
      "name": "Discount 1",
      "start": null,
      "end": null,
      "status": "ModifiedOnStaging",
      "priority": 1,
      "createdUtc": "2023-06-27T15:36:44.060492Z",
      "lastModifiedUtc": "2023-07-11T11:47:21.579007Z",
      "tags": []
    },
    {
      "id": "52201609-cb84-43a3-aa85-5fbff6febb91",
      "name": "Discount 2",
      "start": null,
      "end": null,
      "status": "Staged",
      "priority": 2,
      "createdUtc": "2023-07-03T10:51:13.977169Z",
      "lastModifiedUtc": "2023-07-26T08:14:37.412505Z",
      "tags": []
    }
  ]
}

Updating Discount Priorities

To update the priority of discounts, use the /discountpriorities Builder API endpoint. Only the IDs of the discounts being updated need to be provided.

An example request to update two discount priorities is below.

{
  "priorities": [
    {
      "id": "e80c622f-4c97-4c34-9e54-e8847e925066",
      "priority": 2
    },
    {
      "id": "52201609-cb84-43a3-aa85-5fbff6febb91",
      "priority": 1
    }
  ]
}

Discounts can have the same priority. However, the evaluation order for discounts with the same priority is not deterministic.

Publishing Updated Priorities to Live

When discount priorities are updated they only impact the Staging instance. To update them on the Live instance, they must be published using the /discountpriorities/status endpoint.

Evaluation Log

You can use the evaluation log diagnostic information to review the order discounts are being evaluated in. This is done using the explain flag in the settings property.

For example, the following request to the /evaluate endpoint has explain set to true:

{
  "basket": {
    "items": [
      {
        "quantity": 2,
        "price": 58.99
      }
    ]
  },
  "context": {
    "currencyCode": "GBP"
  },
  "settings": {
    "dataInstance": "Staging",
    "commit": false,
    "explain": true
  }
}

This means the response contains the evaluationLog property. Below is an example response.

{
  "evaluationLog": {
    "messages": ["No coupon codes matched"],
    "discountEvaluationResults": [
      {
        "id": "e80c622f-4c97-4c34-9e54-e8847e925066",
        "name": "Discount 1",
        "messages": [
          "Didn't meet quantity condition",
          "Basket cannot possibly meet the required discount conditions",
          "Conditions not matched"
        ]
      },
      {
        "id": "52201609-cb84-43a3-aa85-5fbff6febb91",
        "name": "Discount 2",
        "messages": [
          "No conditions on discount, so conditions considered met",
          "Conditions matched",
          "Award condition matched",
          "Added as a winner"
        ]
      }
    ]
  }
}

Note. the evaluation log is purely for diagnostic information and should not be used for functionality.