Skip to main content

Send Finalize Transaction

POST 

/client/users/:correlation_id/activity/finalize/v2

This call sends a finalize activity associated with a user and returns the details regarding earning, redeeming, and offer rewards (point and/or non-point) the user has incurred with the purchase transaction.

Optional Parameter - The callId can be optionally included to further specify the request that was made to the ES Loyalty Platform which flows through to reporting. It should be just as unique as the correlationId. If not provided, a GUID is generated in its place.

In some cases, points can only be awarded after payment or fulfillment of the order have taken place, resulting in delayed transactions. Adding the following object to the end of the call supports a delayed transaction that requires confirmation.

"confirmation": {
"mode": "CART"
}

The response includes information about the confirmation status.

"ConfirmationDetails": {
"confirmed": true,
"mode": "CART"
}

The tender object contains details about payment tender(s). Within the tender object, the tender type and value can be presented as a key:value pair or, if more data is required as with a payment card, in an array. There can also be a mixture of both types within the tender object.

As a key:value pair:

"tender": {
"CASH": "200",
"LOYALTY": 100
}

As an array:

"tender": {
"VISA": [
{
"idType": "LAST_4",
"prefix": "12345",
"suffix": "1235",
"amount": "500"
}
}
}

Note: For a single members or in a household, if a redemption transaction begins, but one or more of the cards are subsequently set to a non-active state such as Suspended, Lost or Stolen, Fraud/Abuse, Cancelled, or Damaged before the redemption transaction is completed, then to prevent fraud, the redemption amount is still withdrawn from the single member or proportionally from all household members who had active cards before the redemption transaction began.

Request

Body

AttributeDescriptionFormatNotes
actionDescribes the action carried out by the Finalize request.StringRequired; for example, "PURCHASE" or "NON_POINT_REWARD"
channelIdentifies the channel through which the action takes place.Enum: "STORE", "POS", "WEBSITE", "APP", "PARTNER"Required. Default is "POS". The client can set this value, but it cannot be null or blank.
localeLocale of the member.String, values currently supported are: "en-CA", "en-US" and "fr-CA"; "EN" and "FR" can be used as well, but only for the member record (on the account level)Optional. Priority order: (1) value from the POS system; (2) locale set on the account; (3) environment locale. If locale is not provided or is not a valid value, system default ("en-CA") is used.
reservationTokenUses a token for API requests that include reserved points.StringOptional. See the Reserve for Redemption request.
transactionDateTimestamp for the transaction (date and time) in ISO-8601 format.StringRequired
retailBannerA store grouping or type. Transactions will default if a single BU or banner exists based on configuration. OAuth takes control of processing.StringOptional
storeNumberUnique identifier for the store where the purchase transaction took place.StringRequired. Used for targeting, analytics, and support.
tillNumberUnique identifier for the till in the store at which the purchase transaction took place.NumberOptional. Used for analytics and support.
employeeCodeUnique identifier for employee who carried out the transaction. CSR of the transaction.NumberThis attribute is optional for operations but required for analytics.
loyaltyIdUnique identifier for each member.NumberOptional. This can be captured in the Start Session request.
externalTransactionIDUnique identifier for transaction used by the client.StringOptional.
priceMatrixDesignates whether the transaction is retail or an employee purchase.Enum: "R" or "E"Required. "R" for retail, "E" for employee.
localeUsed to change the receipt message language response for this transaction. Defaults to the client's chosen language when not present.String, values currently supported are: "en-CA" and "fr-CA" as well as "EN" and "FR"Optional. "en-CA" for English.
"fr-CA" for French.
callIdUnique request identifier.StringOptional. Can be auto-generated if none provided. Supports tracking specific calls to be captured within a specific session for analytics. (Secondary Correlation ID).
cartObject containing array of saleLineItemsObjectRequired. JSON Object containing array of saleLineItems.
saleLineItemsContains details of one transaction item.ArrayRequired. JSON Object containing line items. See saleLineItems Details below this table
subCategorySame subcategory as in Product feed.NumberCan be blank to force system to grab subcategory from product data. This is an optional attribute.
skuThe product identifier scanned at POS.NumberRequired
quantityMeasure of product amount sold.Number; for some clients, may include values confirmed to be as low as 0.000001Required. Can be partial value for unit of measure calculations where there is no directly-applicable SKU (for instance, rope sold by the foot).
originalSaleAmountThe Manufacturer's Suggested Retail Price for a product.NumberRequired. Single-unit MSRP in pennies.
subCategoryIdentifier for the sub-category associated with the product.String
productNameUnique product name.String
saleAmountMSRP less the discount, the actual sale price.NumberRequired. MSRP minus item discount in pennies.
storeCouponStore-based coupon.NumberOptional. This is informational only, no active discounting occurs in ESL. This attribute is optional.
itemDiscountAmount discounted.NumberOptional. This attribute is optional. In pennies.
mnfCouponManufacturer Coupon.NumberOptional. This is informational only, no active discounting occurs in ESL. This attribute is optional.
promoCouponFlyer coupon.NumberOptional. This is informational only, no active discounting occurs in ESL. This attribute is optional.
itemTaxTax on the item.NumberRequired. Tax on the line item in pennies.
finalSaleAmountTotal sale amount for a specific product, the discounted price times the quantity purchased.NumberRequired. quantity * saleAmount
tagsTo provide additional informationStringRequired, but can be empty.
rewardTagsTo provide additional information about specified rewards.ObjectRequired, but can be empty. Contains offer name(s) and associated reward(s) as key:value pairs.
itemCostTotal cost for a specific product, the cost per unit times the quantity purchased.NumberOptional. cost per unit * quantity. This attribute is optional.
couponCodesPurchase-level coupons.StringOptional.
extendedDataClient keys needed for analytics of the transaction.Optional. Maximum 1KB, 1 level deep, 10 keys maximum.
totalSaleAmountTotal of all items sold on this transaction, including tax.NumberRequired. Summed up, tax included, total of all saleLineItems. In pennies.
tenderJSON Object containing transaction tender used.ObjectRequired. Contains one or more type of tender and details of each (as required).
{tender_type}Array containing one or more objects for a particular type of tender (such as "VISA" which replaces {tender_type}).String for tender type name, then array containing an object for each instance of that tender type.Contains idType to amount below. Possible values for {tender_type}: "CASH", "COUPON" (flyer coupon), "REWARDS" (non-points rewards), "AMEX", "MSTCARD", "VISA", "GWCOUP", "MCOUPON" (manufacturer's coupon), "LOYALTY" (points)
idTypeType of the card identifier being passed in.StringOptional. "TOKEN", "LAST_4", etc.
prefixPrefix of the card identifier.NumberOptional. Usually the BIN or first 6 digits of the card. Used for partner-based offers. This attribute is optional.
suffixSuffix of the card identifier.NumberOptional. Usually the last 4 digits. Used for partner-based offers.
amountTotal amount of the tender that was spent using this specific card/tender.Number or StringRequired. Total amount of the tender that was spent using this specific card/tender.
LOYALTYReserved key that denotes in cents the dollars spent by exchanging for loyalty points.NumberOptional. Used for redemption-based actions.
REWARDSContains data about non-points rewards.ObjectContains every non-points reward offer in this transaction. Contains {offer_name} to itemsAdjusted.
{offer_name}Contains details about one non-points reward offer.StringShows the quantity of the non-loyalty reward offer in dollars and whether it has been adjusted in the cart. Contains total and itemAdjusted below.
totalThe total amount of the non-points currency reward associated with the offer in cents.Number or String
itemsAdjustedGives the flexibility to the POS system to selectively choose to adjust the cart for some non-points offers and not for others.BooleanIf true, the cart/item sale amounts are already adjusted using the non-points rewards amount and no further adjustment is required. The point-based cart evaluation proceeds. If false, promo but did not adjust the cart for that at the time of sending the request. The promo-engine will adjust the cart first and then do further evaluation of the points-based offers.
saleLineItem Details
  • Original Sale Amount = Original price per Unit

  • Sale Amount = Discounted price per Unit

  • Final Sale Amount = Discounted Price per Unit * Quantity

  • itemCost = Cost per Unit * Quantity

Response

To view the hierarchy, see the example Response.

AttributeDefinitionFormatNotes
earnedContains points earned on all applicable programs.ObjectBesides "loyalty," there may be other programs such as a partner program (and related object) with additional points awarded. For instance, may contain "rewards" object.
loyaltyContains points earned on the loyalty program.Object
baseThe number of base rewards earned on the transaction.NumberBase points = points for any transaction based on spend.
bonusThe number of bonus rewards earned on the transaction.NumberBonus points = points for completing particular behaviour.
targetedThe number of points attributable to targeted offers.NumberTargeted points = points derived from targeted offer.
totalThe total of all points earned on the transaction.Number= base + bonus + targeted points
rewardsRewards awarded as non-loyalty points (for instance, in dollars).ObjectContains list of non-loyalty point rewards.
DOLLARDollar amount of reward.Number (in cents)Optional, can be 0
GAMEPLAYContains applicable game offers.ObjectIncludes {{gameOfferName}} field(s)
{{gameOfferName}}Name of one game offered.StringThere may be one or more of the game offers and associated game names
{{partnerName}}Contains partner points data.ObjectMay contain same attributes as "loyalty" above
loyaltyIDLoyalty Card number for the session.NumberIf loyaltyId was not provided in the request, then this is the primary card number on the account
pointsRedeemedThe number of points redeemed.NumberAlways 0 for this type of request. To redeem points, use Send Finalize Transaction (with Redemption).
pointsEarnedTotalThe total of points earned after redemptions.Numbertotal minus pointsRedeemed
offerRewardsContains details of one or more offer rewards.Array
offerDescriptionGeneral description of offer.StringFor instance, "Spend $20 and get 500 points."
offerDescription2Additional details of offer.StringFor instance, "Offer good through March 22."
promotionHeadlineHeadline under which offer is promoted.StringFor example: "Spend $20 and get 500 points."
offerCodeUnique code identifying offer.String
pointsEarnedPoints earned for this offer.Number
isTargetedFlags whether the transaction results from a targeted offer.Boolean
isDiscretionaryFlags whether the transaction is discretionary.Boolean
stackingUsed to provide data about reward groups and the winning group for rewards when one or more of the rewards are based on units.ObjectContains rewardGroups and winningGroup
rewardGroupsAll possible reward groups for this reward.ArrayContains one or more reward groups
winningGroupWinning reward group, the one used for this reward.StringContains one reward group from the array in rewardGroups
currencyCurrency used for this offer reward.StringFor instance, if the member is rewarded with game play, this will be "GAMEPLAY"
scopeContains details of one or more offer reward(s).ObjectContains type attribute and metadata object below
typeType of rewardStringFor instance, if the member is rewarded with game play, this will be "GAMEPLAY"
metadataContains details for the type of offer reward.ObjectFor example, for game play, contains gameID and gameProvider below for each game used as reward
gameIDUnique identifier for game.String
gameProviderName of vendor providing the game.String
partnerIDIdentification of a partner.StringUsed only with partner offerRewards, if relevant.
CartObject containing array of saleLineItems; used if configuration allows return of cart details in response.ObjectRequired. JSON Object containing array of saleLineItems.
saleLineItemsContains details of one transaction item.ArrayRequired. JSON Object containing line items. See saleLineItems Details below this table
subcategorySame subcategory as in Product feed.NumberOptional. Can be blank to force system to grab subcategory from product data.
skuThe product identifier scanned at POS.NumberRequired
quantityMeasure of product amount sold.Number; for some clients, may include values confirmed to be as low as 0.000001Required. Can be partial value for unit of measure calculations where there is no directly-applicable SKU (for instance, rope sold by the foot).
originalSaleAmountThe Manufacturer's Suggested Retail Price for a product.NumberRequired. Single-unit MSRP in pennies.
saleAmountMSRP less the discount, the actual sale price.NumberRequired. MSRP minus item discount in pennies.
subCategoryIdentifier for the sub-category associated with the product.String
productNameUnique product name.String
storeCouponStore-based coupon.NumberOptional. This is informational only, no active discounting occurs in ESL. This attribute is optional.
itemDiscountAmount discounted.NumberOptional. This attribute is optional. In pennies.
mnfCouponManufacturer Coupon.NumberOptional. This is informational only, no active discounting occurs in ESL. This attribute is optional.
promoCouponFlyer coupon.NumberOptional. This is informational only, no active discounting occurs in ESL. This attribute is optional.
itemTaxTax on the item.NumberRequired. Tax on the line item in pennies.
finalSaleAmountTotal sale amount for a specific product, the discounted price times the quantity purchased.NumberRequired. quantity* saleAmount
tagsTo provide additional informationStringRequired, but can be empty.
rewardTagsTo provide additional information about specified rewards.ObjectRequired, but can be empty. Contains offer name(s) and associated reward(s) as key:value pairs.
itemCostTotal cost for a specific product, the cost per unit times the quantity purchased.NumberOptional. cost per unit * quantity. This attribute is optional.
totalSaleAmountTotal of all items sold on this transaction, including tax.NumberRequired. Summed up, tax included, total of all saleLineItems. In pennies.
couponCodesPurchase-level coupons.StringOptional.
extendedDataClient keys needed for analytics of the transaction.Optional. Maximum 1KB, 1 level deep, 10 keys maximum.
tenderJSON Object containing transaction tender used.ObjectRequired. Contains one or more type of tender and details of each (as required).
{tender_type}Array containing one or more objects for a particular type of tender (such as "VISA" which replaces {tender_type}).String for tender type name, then array containing an object for each instance of that tender type.Contains idType to amount below. Possible values for {tender_type}: "CASH", "COUPON" (flyer coupon), "REWARDS" (non-points rewards), "AMEX", "MSTCARD", "VISA", "GWCOUP", "MCOUPON" (manufacturer's coupon), "LOYALTY" (points)
totalTotal of the sale transaction.ObjectContains subTotal, totalSaleAmount, and taxAmount within each sale object type
{transaction status type}Status of transaction.StringFor example, "final"; contains totalSaleAmount, subTotal, and taxAmount below
totalSaleAmountThe total amount of the sale including tax.String
subTotalThe total amount of the sale before tax.String
taxAmountThe tax generated on the sale.String
idTypeType of the card identifier being passed in.StringOptional. "TOKEN", "LAST_4", etc.
prefixPrefix of the card identifier.NumberOptional. Usually the BIN or first 6 digits of the card. Used for partner-based offers. This attribute is optional.
suffixSuffix of the card identifier.NumberOptional. Usually the last 4 digits. Used for partner-based offers.
amountTotal amount of the tender that was spent using this specific card/tender.Number or StringRequired. Total amount of the tender that was spent using this specific card/tender.
LOYALTYReserved key that denotes in cents the dollars spent by exchanging for loyalty points.NumberOptional. Used for redemption-based actions.
REWARDSContains data about non-points rewards.ObjectContains every non-points reward offer in this transaction. Contains {offer_name} to itemsAdjusted.
{offer_name}Contains details about one non-points reward offer.StringShows the quantity of the non-loyalty reward offer in dollars and whether it has been adjusted in the cart. Contains total and itemAdjusted below.
totalThe total amount of the non-points currency reward associated with the offer in cents.Number or String
itemsAdjustedGives the flexibility to the POS system to selectively choose to adjust the cart for some non-points offers and not for others.BooleanIf true, the cart/item sale amounts are already adjusted using the non-points rewards amount and no further adjustment is required. The point-based cart evaluation proceeds. If false, promo but did not adjust the cart for that at the time of sending the request. The promo-engine will adjust the cart first and then do further evaluation of the points-based offers.
stackingIdentification of a stacking group showing rewardsGroups associated with the transaction and the highest rewarding offer in that group (winningGroup).ObjectOptional. Contains information about the stacking group for the transaction.
rewardsGroupsIdentifies the rewards group(s) associated with the transaction.ArrayContains the name(s) of the rewards group(s).
winningGroupIdentifies the reward group that won the highest rewarding offer.StringContains the name of the winning group.
receiptMessageMessage to show on the receipt.StringThe message may differ depending on points earned, redeemed, both, or neither. It may also be a generic message or specific to the client depending on configuration.
messageDetails of transaction not shown to consumer.StringProvides information about the transaction and any redemptions.
pointsBalanceTotal number of points currently attributed to this account.NumberRewards balance in points.
redeemableBalanceMaximum balance quantity in currency that can currently be redeemedNumberAn increment of a standard redemption amount. For instance, with a pointsBalance of 120000 and currency rewards of $10 per 25000 points, this value would be 40, or four increments of 10.
redeemablePointBalanceMaximum number of points that can currently be redeemed.NumberAn increment of a standard redemption amount. For example, with a pointsBalance of 110000, the user may be able to redeem 100000, or four increments of 25000.
householdObject containing information about the household to which the member belongs.ObjectOnly returned if the member is a member of a household.
idUnique identifier for the household.String
roleThe member's role in the household.Enum: "PRIMARY" or "SECONDARY"
balanceObject containing data about the balances available to the household.Object
totalPointsBalanceThe total points balance of the household.NumberThe sum of all member balances.
totalDollarBalanceThe total dollar balance of the household.NumberThe sum of all member balances.
totalAvailablePointBalanceThe total points available to the household.Number
totalAvailableDollarBalanceThe total dollars available to the household.Number
totalRedeemablePointBalanceThe total number of points that can currently be redeemed by the household members.Number
totalRedeemableDollarBalanceThe total number of dollars that can currently be redeemed by the household members.Number
minRedeemPointsThe minimum number of points that can be redeemed by the household.Number
maxRedeemPointsThe maximum number of points that can be redeemed by the household.Number
minRedeemDollarsThe minimum number of dollars that can be redeemed by the household.Number
maxRedeemDollarsThe maximum number of dollars that can be redeemed by the household.Number

Error Responses

statusCodeerrorMessageerrorCodeDefinition
400 Bad RequestSession correlation ID does not exist--create it first.INVALID_REQUESTCreate session correlation ID before sending this request.
400 Bad RequestSession ClosedINVALID_REQUESTCannot process this request because the session is closed.
400 Bad RequestSession ExpiredINVALID_REQUESTCannot process this request because the session has expired.
400 Bad RequestCart cannot contain zero-quantity line itemsINVALID_REQUESTCannot process request when cart includes one or more line items with quantity of zero.
400 Bad RequestInvalid Extended data : Exceeded data size limit for extended data : {dataSize} BytesINVALID_REQUESTWhen extendedData size exceeds the size limit. See the limit on ConfigType = EXTENDED_DATA, on Platform.DataSizeLimitInKb.
400 Bad RequestInvalid Extended data : Exceeded root level key limit for extended data : {numberOfKeys} keysINVALID_REQUESTWhen extendData exceeds number of attributes/keys limit. See the limit on ConfigType = ‘EXTENDED_DATA’, on Platform.TopLevelKeysLimit.
400 Bad RequestAnonymous users cannot redeem.INVALID_REQUESTWhen session is anonymous and it’s a redemption transaction. Member must be registered for redemption.
400 Bad RequestInvalid confirmation mode.INVALID_REQUESTWhen confirmation is informed on request’s body, but confirmation.mode is different from ‘CART’.
400 Bad RequestThis card or user is not eligible for redemption.INVALID_REQUESTWhen it’s a redemption transaction and user is not eligible for redemption.
400 Bad RequestInvalid reservation Token provided.INVALID_REQUESTWhen it’s a redemption transaction and an invalid reservationToken is included in request body.
400 Bad RequestReservation token has expired.INVALID_REQUESTWhen it’s a redemption transaction and an expired reservationToken is included in request body.
400 Bad RequestProducts (or their quantities) do not match the Reservation request.INVALID_REQUESTProducts used in the reservation request must be the same ones redeemed for.
400 Bad RequestChannel should be a string value.INVALID_REQUESTCannot use data type other than string value for channel attribute. For example, channel attribute value cannot be a Boolean (rue, false, or null).
400 Bad RequeststoreNumber is mandatory and required to be non-empty.MISSING_REQUIRED_FIELDS_ERRORA required attribute is missing from the request, or a required attribute has an empty value.
409 ConflictToo many simultaneous requests for the same account.CONFLICT_REQUESTReduce number of simultaneous requests.
500 Unexpected ErrorAn unexpected error occured. Please report guid: {{GUID}}.UNKNOWNAn unexpected error has occured. Contact your Exchange Solutions representative with the GUID code above for more information.

Request

Responses

200 - Transaction Finalized

Response Headers
    Date
    Example: Fri, 02 Oct 2020 16:59:12 GMT
    Content-Length
    Example: 938
    Connection
    Example: keep-alive
    x-amzn-RequestId
    Example: 78159b02-6465-4e38-874c-3e65476ff414
    Referrer-Policy
    Example: no-referrer
    X-XSS-Protection
    Example: 1;mode=block
    Access-Control-Allow-Origin
    Example: *
    Expect-CT
    Example: max-age=86400
    Strict-Transport-Security
    Example: max-age=31536000
    Feature-Policy
    Example: vibrate 'none'; geolocation 'none'
    X-Frame-Options
    Example: sameorigin
    Content-Security-Policy
    Example: connect-src 'none';object-src https://*.cloudfront.net;script-src https://*.cloudfront.net
    x-amz-apigw-id
    Example: TytfBHRNoAMF99g=
    cache-control
    Example: no-cache, no-store, must-revalidate
    X-Content-Type-Options
    Example: nosniff
    X-Amzn-Trace-Id
    Example: Root=1-5f775c60-6d481fe94d4d3633480daa9c;Sampled=0