Send Trial Activity
POST/client/users/:correlation_id/activity/trial/v2
Description
Used to send the current Purchase transaction to ES Loyalty to retrieve a point estimate. This API works in conjunction with the Near-Miss Prompt feature to advise consumers making purchases at Point-of-Sale or e-Commerce channels about a bonus offer or earning threshold that they are close to achieving. It also works with Anonymous Prompt to advise consumers when they have missed a reward because they have not swiped their loyalty card.
In more detail:
-
This request sends a "non-finalized" activity (a transaction detail) associated with a user.
-
The system returns detail about what the customer would have earned if this was sent as a real activity.
-
The difference in dollars between the amount spent and the amount that would have triggered a bonus offer or achieved an earning threshold is returned rounded off to two decimal places.
-
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.
Request
Body
| Attribute | Definition | Format | Notes |
|---|---|---|---|
| action | Identifies purchase transaction | String | Required; for example, "PURCHASE" or "NON_POINT_REWARD" |
| channel | Identifies through which channel the transaction was invoked | Enum: "STORE", "POS", "WEBSITE", "APP", "PARTNER" | |
| locale | The locale of the member from the POS system. | String | Optional. Currently "en-CA" or "fr-CA". If locale is set by the POS system in the Start Session request, this overrides locale set in the member provide and as the system default. |
| reservationToken | Used for purchases that include redemption. | String | This attribute is optional. |
| transactionDate | Full date and time of the transaction. | String | Date of the Transaction (Full Date and Time) must be in an ISO-8601-compliant format, for example: 2022-01-17T13:48:59-04:00. |
| retailBanner | A store grouping or type. | String | Transactions will default if a single BU or banner exists (configuration). OAuth token controls how we process. This attribute is optional. |
| storeNumber | Used for targeting, analytics and support. | String | |
| tillNumber | Use for analytics and support. | Number | This attribute is optional. |
| employeeCode | CSR of the transaction. | Number | This attribute is optional for operations, but required for analytics. |
| loyaltyId | Unique member identifier. | Number | This can be captured in the Start Session. This attribute is optional. |
| externalTransactionID | Unique identifier for transaction used by the client. | String | Optional. |
| priceMatrix | Designates whether the transaction is retail or an employee purchase. | Enum: "R" or "E" | R = Retail E = Employee |
| locale | Used to change the receipt message language response for this transaction. Defaults to the client's chosen language when not present | String | "en-CA" for English. "fr-CA" for French. Optional. |
| callId | Request identifier. | String | Can be auto-generated if none provided. Supports tracking specific calls to be captured within a specific session for analytics. (Secondary Correlation ID). This attribute is optional. |
| cart | Containing array of saleLineItems. | Object | JSON Object containing array of saleLineItems. |
| saleLineItems | Descriptors for item in the cart. | Array | Array of JSON Objects. |
| subCategory | Same subcategory as in Product feed. | Number | Can be blank to force system to grab subcategory from product data. This is an optional attribute. |
| sku | The product identifier. | Number | For instance, may be scanned at Point of Sale. |
| quantity | Measure of product amount sold. | Number | Can be partial value for unit of measure calculations where there is no directly-applicable SKU (for instance, rope sold by the foot). |
| originalSaleAmount | The Manufacturer's Suggested Retail Price for a product. | Number | Single-unit MSRP in pennies. |
| saleAmount | MSRP less the discount, the actual sale price. | Number | MSRP minus item discount in pennies. |
| storeCoupon | Store-based coupon. | Number | This is informational only, no active discounting occurs in ESL. This attribute is optional. |
| itemDiscount | Amount discounted. | Number | This attribute is optional. In pennies. |
| mnfCoupon | Manufacturer Coupon. | Number | This is informational only, no active discounting occurs in ESL. This attribute is optional. |
| promoCoupon | Flyer coupon. | Number | This is informational only, no active discounting occurs in ESL. This attribute is optional. |
| itemTax | Tax on the item. | Number | Tax on the line item in pennies. |
| finalSaleAmount | Total sale amount for a specific product, the discounted price times the quantity purchased. | Number | quantity * saleAmount |
| tags | Additional information about the transaction. | String | Required, but can be empty. |
| itemCost | Total cost for a specific product, the cost per unit times the quantity purchased. | Number | cost per unit * quantity. This attribute is optional. |
| totalSaleAmount | Total of all items sold on this transaction, including tax. | Number | Summed up, tax included, total of all saleLineItems. In pennies. |
| couponCodes | Purchase-level coupons. | String | This attribute is optional. |
| extendedData | Client keys needed for analytics of the transaction. | Object | Maximum 1KB, 1 level deep, 10 keys maximum. This is an optional attribute. |
| tender | JSON Object containing transaction tender used. | Object | Contains one or more type of tender and details of each (as required). |
| {name} | Name of type of tender. | String."VISA", "LOYALTY", etc. | |
| prefix | Prefix of the card identifier. | Number | Usually the IIN / First 6 numbers of the card. Used for partner-based offers. This attribute is optional. |
| idType | Type of the card identifier being passed in. | String | "TOKEN". This attribute is optional. |
| suffix | Suffix of the card identifier. | Number | Usually the last 4 digits. Used for partner-based offers. This attribute is optional. |
| amount | Total amount of the tender. | Number | Total amount of the tender that was spent using this specific card/tender. |
| LOYALTY | Reserved key that denotes in cents the dollars spent by exchanging for loyalty points. | Number | Used for redemption-based actions. This attribute is optional. |
| REWARDS | Reserved key that contains description of one or more non-loyalty points reward(s). | Object | Contains total and items adjusted for each non-loyalty points reward |
| total | The total amount of the reward in cents. | Number | |
| itemsAdjusted | Whether or not the items have been adjusted in the reward points. | Boolean |
Response
To view the hierarchy, see the example Response.
| Attribute | Definition | Format | Notes |
|---|---|---|---|
| earned | Contains points earned on all applicable programs. | Object | Besides "loyalty," there may be other programs such as a partner program (and related object) with additional points awarded. |
| loyalty | Contains points earned on the loyalty program. | Object | The attributes would be the same for other programs (if any). |
| base | The number of base rewards earned on the transaction. | Number | Base points = points for any transaction based on spend. |
| bonus | The number of bonus rewards earned on the transaction. | Number | Bonus points = points for completing particular behaviour. |
| targeted | The number of points attributable to targeted offers. | Number | Targeted points = points derived from targeted offer. |
| total | The total of all points earned on the transaction. | Number | = base + bonus + targeted points |
| rewards | Rewards awarded as non-loyalty points (for instance, in dollars). | Object | Contains list of non-loyalty point rewards. |
| DOLLAR | Dollar amount of reward. | Number (in cents) | Optional, can be 0 |
| GAMEPLAY | Contains applicable game offers. | Object | Includes {{gameOfferName}} field(s) |
| {{gameOfferName}} | Name of one game offered. | String | There may be one or more of the game offers and associated game names |
| loyaltyID | Loyalty Card number for the session. | Number | If loyaltyId was not provided in the request, then this is the primary card number on the account |
| pointsRedeemed | The number of points redeemed. | Number | Always 0 for this type of request. To redeem points, use Send Finalize Transaction (with Redemption). |
| pointsEarnedTotal | The total of points earned after redemptions. | Number | total minus pointsRedeemed |
| offerRewards | Contains details of one or more offer rewards. | Array containing an object for each offer reward. | |
| offerDescription | General description of offer. | String | For instance, "Spend $20 and get 500 points." Optional. |
| offerDescription2 | Additional details of offer. | String | For instance, "Offer good through March 22." |
| promotionHeadline | Headline under which offer is promoted. | String | For example: "Spend $20 and get 500 points." Optional. |
| offerCode | Unique code identifying offer. | String | |
| pointsEarned | Points earned for this offer. | Number | Used only if points are earned as the reward |
| isTargeted | Flags whether the transaction results from a targeted offer. | Boolean: true or false | |
| isDiscretionary | Flags whether the transaction is discretionary. | Boolean: true or false | |
| currency | Currency used for this offer reward. | String | For instance, if the member is rewarded with game play, this will be "GAMEPLAY" |
| scope | Contains details of one or more offer reward(s). | Object | Contains type attribute and metadata object below |
| type | Type of reward | String | For instance, if the member is rewarded with game play, this will be "GAMEPLAY" |
| metadata | Contains details for the type of offer reward. | Object | For example, for game play, contains gameID and gameProvider below for each game used as a reward |
| gameID | Unique identifier for game. | String | |
| gameIdentifier | Name of vendor providing the game. | String | |
| type | Type of offer. | String | For example, "FLAT" or "PERCENTAGE" per qualifying item. Optional. |
| currency | The currency for the reward. | String | For instance, "DOLLAR" required for dollar rewards. |
| rewardsEarned | Total number of dollars earned for this offer. | Number | |
| amount | Number of dollars earned for each item in this offer. | Number | |
| scope | Details about non-loyalty points reward. | Object | Contains type, metadata, applyTo, and items attributes. |
| type | The type of reward, either on the entire cart or on specific items within the cart. | String | "ITEM" or "CART" |
| metadata | Contains additional information about the dollar reward. | Object | |
| applyTo | Sets whether to apply non-loyalty point reward to all items in cart. | String | If all items, set to "ALL". If only one item, set to "ONE". |
| items | Contains the SKUs for the items rewarded. | Array | Each in double quotation marks separated by commas. |
| disposition | Disposition of the non-loyalty points reward, whether it is awarded right away. | String | "INSTANT" or "BANKED". |
| appliedBy | Determines whether the reward is applied by the loyalty system or the POS system. | String | "POS" or "LOYALTY". |
| partnerID | Identification of a partner. | String | Used only with partner offerRewards, if relevant. Optional. |
| receiptMessage | Message to show on the receipt. | String | The message may differ depending on points earned, redeemed, both, or neither. |
| message | Details of transaction not shown to consumer. | String | Provides information about the transaction and any redemptions. |
| pointsBalance | Total number of points currently attributed to this account. | Number | Rewards balance in points. |
| redeemableBalance | The number of points that can currently be redeemed. | Number | |
| redeemablePointBalance | Maximum number of points that can currently be redeemed. | Number | An 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. |
| household | Object containing information about the household to which the member belongs. | Object | Only returned if the member is a member of a household. |
| id | Unique identifier for the household. | String | |
| role | The member's role in the household. | Enum: "PRIMARY" or "SECONDARY" | |
| balance | Object containing data about the balances available to the household. | Object | |
| totalPointsBalance | The total points balance of the household. | Number | The sum of all member balances. |
| totalDollarBalance | The total dollar balance of the household. | Number | The sum of all member balances. |
| totalAvailablePointBalance | The total points available to the household. | Number | |
| totalAvailableDollarBalance | The total dollars available to the household. | Number | |
| totalRedeemablePointBalance | The total number of points that can currently be redeemed by the household members. | Number | |
| totalRedeemableDollarBalance | The total number of dollars that can currently be redeemed by the household members. | Number | |
| minRedeemPoints | The minimum number of points that can be redeemed by the household. | Number | |
| maxRedeemPoints | The maximum number of points that can be redeemed by the household. | Number | |
| minRedeemDollars | The minimum number of dollars that can be redeemed by the household. | Number | |
| maxRedeemDollars | The maximum number of dollars that can be redeemed by the household. | Number | |
| promptMessageID | Contains unique identifier for prompt message (such as near-miss). | Array | Contains string with identifier value for prompt message |
| promptMessage | Contents of prompt message. Used, for instance, as near-miss prompt. | String | For example, "Customer is $4 short of qualifying for Spend 20 and get 500 points offer." |
| prompt | Type of prompt message. Used, for instance, as near-miss prompt. | String | For instance, "REQUEST_ADD_PURCHASE" for a prompt indicating that the member can get rewards by spending more. |
| promptMessages | Contains unique identifier(s) for prompt category. Used with "ANONYMOUS" prompt. | Object | Contains an array that holds details for an anonymous prompt |
| {promptType} | Contains unique identifier(s) for prompt(s) used for this prompt type. | Object | For instance, "ANONYMOUS" array contains unique identifier(s) for anonymous prompt(s) |
| promptMessageID | Within the "ANONYMOUS" object, unique identifier for the anonymous prompt message. | String | |
| promptMessage | Within the "ANONYMOUS" object, contents of prompt message. If locale is included in the request and set to "fr-CA", then the message is rendered in French. Points or dollars are calculated in back end, then displayed in message. | String | For instance, "You may be missing out on 500 points. Please present your loyalty card so that you can earn these points." The points or dollars shown are the accumulation of all rewards available on the transaction. This message may be slightly different for specific clients. |
| prompt | Within the "ANONYMOUS" object, the type of prompt. | String | For example, "REQUEST_LOYALTY_SWIPE" |
Error Responses
| statusCode | errorMessage | errorCode | Definition |
|---|---|---|---|
| 400 Bad Request | Session CallId has already been used | INVALID_REQUEST | Cannot reuse the same CallId that has been used before |
| 400 Bad Request | Cart cannot contain zero-quantity line items | INVALID_REQUEST | Line items in the cart must have a quantity of 1 or more |
| 400 Bad Request | Invalid confirmation mode | INVALID_REQUEST | When confirmation is informed on request’s body, but confirmation.mode is different from ‘CART’ |
| 400 Bad Request | Invalid extended data: Exceeded data size limit for extended data: {dataSize} Bytes | INVALID_REQUEST | When extendedData size exceeds the size limit. See the limit on ConfigType = EXTENDED_DATA, on Platform.DataSizeLimitInKb. |
| 400 Bad Request | Invalid Extended data : Exceeded root level key limit for extended data : {numberOfKeys} keys | INVALID_REQUEST | When extendData exceeds number of attributes/keys limit. See the limit on ConfigType = ‘EXTENDED_DATA’, on Platform.TopLevelKeysLimit. |
Request
Responses
- 200
- 400
200 - Trial Activity Sent
Response Headers
Date
Example:
Fri, 02 Oct 2020 16:15:42 GMTContent-Length
Example:
949Connection
Example:
keep-alivex-amzn-RequestId
Example:
c0271966-bcde-4b83-905d-7491793d0edbReferrer-Policy
Example:
no-referrerX-XSS-Protection
Example:
1;mode=blockAccess-Control-Allow-Origin
Example:
*Expect-CT
Example:
max-age=86400Strict-Transport-Security
Example:
max-age=31536000Feature-Policy
Example:
vibrate 'none'; geolocation 'none'X-Frame-Options
Example:
sameoriginContent-Security-Policy
Example:
connect-src 'none';object-src https://*.cloudfront.net;script-src https://*.cloudfront.netx-amz-apigw-id
Example:
TynHPF42IAMF57w=cache-control
Example:
no-cache, no-store, must-revalidateX-Content-Type-Options
Example:
nosniffX-Amzn-Trace-Id
Example:
Root=1-5f77522e-57272eb82698fe096dec3346;Sampled=0400 - Cannot Reuse Same callId Within a Single Session
Response Headers
Date
Example:
Thu, 10 Jun 2021 16:08:33 GMTContent-Length
Example:
103Connection
Example:
keep-alivex-amzn-RequestId
Example:
2a834b44-790b-4d1c-b311-cdf5cb759927Referrer-Policy
Example:
no-referrerX-XSS-Protection
Example:
1;mode=blockAccess-Control-Allow-Origin
Example:
*Expect-CT
Example:
max-age=86400Strict-Transport-Security
Example:
max-age=31536000Feature-Policy
Example:
vibrate 'none'; geolocation 'none'X-Frame-Options
Example:
sameoriginContent-Security-Policy
Example:
connect-src 'none';object-src https://*.cloudfront.net;script-src https://*.cloudfront.netx-amz-apigw-id
Example:
At3YTFHtIAMF-_g=cache-control
Example:
no-cache, no-store, must-revalidateX-Content-Type-Options
Example:
nosniffX-Amzn-Trace-Id
Example:
Root=1-60c23901-53ab345741dcebcc16c79faa;Sampled=0