Guides
Builder API
Processor API
Getting Started
Overview
Account Setup
Creating your first discount
API Intro
Overview
Coupon Codes
Loyalty Schemes
Discount Types
Discount Interaction
Publishing Model
Tiered Actions
Currencies
Properties
Example Loyalty Scheme
Management Tooling
Discounts
Discount Conditions
Discount Actions
Discount Priorities
Expressions
Coupon Codes
Loyalty Schemes
Files
Properties
Currencies
Audit
Builder API
Discount Types
Coupon Code Generation
Loyalty Schemes
Loyalty Discount Types
File Uploads
Expressions
Dates and Times
Discount Priorities
Discount Examples
Processor API
Request
Response
Commits
Dates and Times
Loyalty APIs
Line Item Apportioning

Response Format

This page gives details on the response format from the /evaluate endpoint. See Processor API Definitions for API contracts.

Actions

The actions array will contain any actions from discounts that have been applied.

Each action has an id and type. The types are:

  • CouponCodeAccepted
  • CouponCodeRejected
  • AmountOffLineItem
  • AmountOffBasket
  • AmountOffCost
  • Content
  • AccrueLoyaltyPoints
  • RedeemLoyaltyPoints

CouponCodeAccepted

This will be returned if a coupon code was provided in the request and there is a matching valid coupon code.

Note, this doesn't mean a discount has applied using the code. If a discount has applied, another action will be included with a qualifiedCouponCode property matching the code.

Below is an example response for a valid coupon code.

{
  "actions": [
    {
      "type": "CouponCodeAccepted",
      "id": "05efc804-4018-41da-8989-b65e19a32ed7",
      "code": "TotalUsageLimitCode"
    }
  ]
}

CouponCodeRejected

This will be returned if a coupon code was provided in the request, but it is not valid for use. The reason property gives details for why it isn't valid. Valid values are:

  • NotRecognised - code doesn't exist in the system
  • IncorrectUser - code is restricted to a specific email, but a different customer email was provided in the request.
  • UserRequired - code is restricted to a specific email, but no customer email was provided in the request.
  • NotStarted - code has a start date and the start date is in the future.
  • Expired - code has a end date and the end date is in the past.
  • UsageLimitReached - the usage limit set on the code has been reached and therefore cannot be used.

The JSON below shows the response for two coupon codes that don't exist.

{
  "actions": [
    {
      "type": "CouponCodeRejected",
      "id": "84f02ebe-ac60-41b3-a689-c257a6da69f0",
      "code": "InvalidCode1",
      "reason": "NotRecognised"
    },
    {
      "type": "CouponCodeRejected",
      "id": "efc6cc0a-49b4-477d-9b79-4af90ba4afda",
      "code": "InvalidCode2",
      "reason": "NotRecognised"
    }
  ]
}

Amount off Actions

Actions with a currency amount off share the following properties:

  • amountOffType - the amount off type of the action: PercentOff, AmountOff or FixedPrice
  • value - the value of the action. If amountOffType is is PercentOff then this is the percentage value of the discount action. Otherwise it is the currency amount on the discount action.
  • amountOff - the currency amount of the discount.

AmountOffLineItem

Below is an example of an AmountOffLineItem action for a 20% off a single line item discount.

The basket provided has one line item with a quantity of 2 and another with a quantity of 1.

Request JSON

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

Response JSON

{
  "actions": [
    {
      "id": "10774d95-e71a-4279-b013-65e1072cdd67",
      "discountId": "284d21a9-a3b3-4cf7-973c-099db0e801c6",
      "type": "AmountOffLineItem",
      "qualifiedCouponCode": null,
      "amountOffType": "PercentOff",
      "value": 20,
      "amountOff": 1.2,
      "displayMessages": [
        {
          "locale": "en-GB",
          "value": "Great Discount"
        }
      ]
    }
  ],
  "basket": {
    "total": 122.77,
    "totalAmountOff": 1.2,
    "items": [
      {
        "total": 117.98,
        "totalAmountOff": 0,
        "actions": []
      },
      {
        "total": 4.79,
        "totalAmountOff": 1.2,
        "actions": [
          {
            "id": "10774d95-e71a-4279-b013-65e1072cdd67",
            "subItemId": 1,
            "amountOff": 1.2
          }
        ]
      }
    ]
  },
  "aggregates": {
    "total": 122.77,
    "totalAmountOff": 1.2
  },
  "costs": [],
  "commitId": null,
  "evaluationLog": null
}

See the Basket section below for more details on the basket format.

AmountOffBasket

Below is an example of a AmountOffBasket action for a 10 GBP off the basket total discount.

The basket provided has one line item with a quantity of 2 and another with a quantity of 1.

Request JSON

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

Response JSON

{
  "actions": [
    {
      "id": "32d3c3df-fad0-43fc-91b8-dbd319013aab",
      "discountId": "284d21a9-a3b3-4cf7-973c-099db0e801c6",
      "type": "AmountOffBasket",
      "qualifiedCouponCode": null,
      "amountOffType": "AmountOff",
      "value": 10,
      "amountOff": 10,
      "displayMessages": [
        {
          "locale": "en-GB",
          "value": "Great Discount"
        }
      ]
    }
  ],
  "basket": {
    "total": 113.97,
    "totalAmountOff": 10,
    "items": [
      {
        "total": 108.46,
        "totalAmountOff": 9.52,
        "actions": [
          {
            "id": "32d3c3df-fad0-43fc-91b8-dbd319013aab",
            "subItemId": 1,
            "amountOff": 4.76
          },
          {
            "id": "32d3c3df-fad0-43fc-91b8-dbd319013aab",
            "subItemId": 2,
            "amountOff": 4.76
          }
        ]
      },
      {
        "total": 5.51,
        "totalAmountOff": 0.48,
        "actions": [
          {
            "id": "32d3c3df-fad0-43fc-91b8-dbd319013aab",
            "subItemId": 1,
            "amountOff": 0.48
          }
        ]
      }
    ]
  },
  "aggregates": {
    "total": 113.97,
    "totalAmountOff": 10
  },
  "costs": [],
  "commitId": null,
  "evaluationLog": null
}

From this response you can see how the 10 GBP off the basket is allocated across the line items.

See the Basket section below for more details on the basket format.

AmountOffCost

Below is an example of a AmountOffCost action. The request will have included a Shipping cost.

{
  "actions": [
    {
      "id": "ad37eeac-c66c-42c4-baae-1a76ef671d8d",
      "discountId": "a3a7762b-f296-4257-a12e-4c59cb988ac9",
      "type": "AmountOffCost",
      "qualifiedCouponCode": null,
      "amountOffType": "AmountOff",
      "value": 10,
      "amountOff": 10,
      "displayMessages": [
        {
          "locale": "en-GB",
          "value": "Great Discount"
        }
      ]
    }
  ]
}

When costs are provided in the request, a costs array is returned in the response. Below is an example when a discount has applied:

{
  "costs": [
    {
      "name": "Shipping",
      "value": 0,
      "totalAmountOff": 10,
      "actions": [
        {
          "id": "40ae5ef7-4c99-4eb8-bbc1-1ed734961e26",
          "amountOff": 10
        }
      ]
    }
  ]
}
  • value is the value of the cost after applying a discount. In this case a 100% off discount has applied, so the cost value is 0.
  • totalAmountOff is the total discount amount.

The actions array contains items with the following fields:

  • id - this is a reference to the matching action in the top level actions array.
  • amountOff - this is the amount the cost was reduced by.

If no cost discounts apply, the actions on the costs array will be empty and the value will be the same as the value provided in the request. E.g.

{
  "costs": [
    {
      "name": "Shipping",
      "value": 10,
      "totalAmountOff": 0,
      "actions": []
    }
  ]
}

Content

Below is an example of a Content action.

{
  "actions": [
    {
      "id": "1918b4b6-b021-4a27-b86b-3f59bafc3181",
      "discountId": "a3a7762b-f296-4257-a12e-4c59cb988ac9",
      "type": "Content",
      "qualifiedCouponCode": null,
      "value": [
        {
          "locale": "en-GB",
          "value": "Welcome, VIP customer!"
        },
        {
          "locale": "fr-FR",
          "value": "Bienvenue, client VIP !"
        }
      ]
    }
  ]
}

AccrueLoyaltyPoints

Below is an example of the AccrueLoyaltyPoints action.

{
  "id": "f316b8fa-a868-4020-90dc-d48c576021b8",
  "discountId": "eaa7edfc-79cb-4e4f-864c-ec9ebf80c546",
  "type": "AccrueLoyaltyPoints",
  "loyaltySchemeId": "05a35e84-8e55-409f-9f87-76d55cbd0e6c",
  "qualifiedCouponCode": null,
  "pointsAccrued": 1,
  "startDate": null,
  "expiryDate": "2024-09-11T07:53:55.569055",
  "displayMessages": []
}

The action provides the number of points accrued and any start/expiry dates for the points. The ID of the loyalty scheme is also returned.

RedeemLoyaltyPoints

Below is an example of the RedeemLoyaltyPoints action.

{
  "id": "2c6ec5fa-5eb9-43c5-8951-3ec66fa2e684",
  "discountId": "a16434cd-e1d2-4ff3-917c-b654b540a14f",
  "type": "RedeemLoyaltyPoints",
  "loyaltySchemeId": "05a35e84-8e55-409f-9f87-76d55cbd0e6c",
  "qualifiedCouponCode": null,
  "pointsRedeemed": 101,
  "displayMessages": []
}

The action provides the number of points redeemed as well as the ID of the loyalty scheme.

Basket

If a basket is provided in the request, a basket object is returned in the response.

Basket provided in the request:

{
  "basket": {
    "items": [
      {
        "quantity": 2,
        "price": 58.99
      },
      {
        "quantity": 1,
        "price": 5
      }
    ]
  }
}

basket in the response when a 10 GBP AmountOffBasket has applied:

{
  "basket": {
    "total": 112.98,
    "totalAmountOff": 10,
    "items": [
      {
        "total": 108.38,
        "totalAmountOff": 9.6,
        "actions": [
          {
            "id": "f3eaf140-acac-4ee9-81c2-f13ed209b2f5",
            "subItemId": 1,
            "amountOff": 4.8
          },
          {
            "id": "f3eaf140-acac-4ee9-81c2-f13ed209b2f5",
            "subItemId": 2,
            "amountOff": 4.8
          }
        ]
      },
      {
        "total": 4.6,
        "totalAmountOff": 0.4,
        "actions": [
          {
            "id": "f3eaf140-acac-4ee9-81c2-f13ed209b2f5",
            "subItemId": 1,
            "amountOff": 0.4
          }
        ]
      }
    ]
  }
}

The 10 GBP off is allocated over the line items.

The items are returned in the same order as they are provided in the request. Each item has the following properties:

  • total - the line item total after discount
  • totalAmountOff - the amount the line item total was reduced by
  • actions - has an entry for each action applied to the line item.

Item Actions

Each entry in the actions array on basket items has the following properties:

  • id - this is a reference to the matching action in the top level actions array.
  • subItemId - this is an id for multiple quantities of a line item. E.g. if the line item has a quantity of 3 and an action has applied to all 3, there will be subItemId 1, 2, 3.
  • amountOff - the amount the line item total was reduced by for this sub item.

If no discounts apply to the basket, the actions on the items array will be empty.

{
  "basket": {
    "total": 122.98,
    "totalAmountOff": 0,
    "items": [
      {
        "total": 117.98,
        "totalAmountOff": 0,
        "actions": []
      },
      {
        "total": 5,
        "totalAmountOff": 0,
        "actions": []
      }
    ]
  }
}

Costs

This array has the list of costs provided in the request with any actions applied. See the AmountOffCost section above for more details.

Aggregates

The aggregates object gives you the following totals:

  • total - this is the overall total (basket + costs) with discounts applied
  • totalAmountOff the total amount taken off by discounts

CommitId

Unique ID of the commit if the request had settings.commit set to true. This ID should be recorded after the response has been returned. It uniquely identifies the commit. It can also be used to rollback the commit.

See the Commits page for more details.

Evaluation Log

This object will be present if the request had settings.explain set to true (note this should only be used for diagnostics, not for every request).

The messages array will have general messages and the discountEvaluationResults will have an entry per-discount (in the order they are evaluated). This will give you give you details on why a discount did or did not apply.

If a discount doesn't appear in this list, check settings.dataInstance in the request. If it is Live, try the request again with a value of Staging. If the discount hasn't been published to live it won't be available on the Live data instance.

Another option for a discount not appearing in the log is that it failed to be loaded. The most common cause of this is when a discount on the Live data instance references an expression that hasn't been published to Live. Review the discount to see if this is the case. Publish any referenced expressions.