Potential Points

Request Details

Item Value
Description CrowdTwist’s Potential Points API allows CrowdTwist clients to calculate the amount of points members could earn for the purchase of items or an entire basket/cart. Potential points are inclusive of base points for purchase, configured by client, as well as eligible and active bonus points campaigns.
Client Use:

  • Display potential points earned on ecommerce product pages
  • Communicate in-store (via POS or other method) potential points to perspective buyers
  • Display potential points earned for total transaction
Method POST
Endpoint https://[environment]pos[client_id].crowdtwist.com/receipt/points
HTTP Header X-CT-Authorization = CTApiKey [API Key]
Note: there is a space between CTApiKey and the API Key value
Content Type application/json

Request

Field Name Sample Value Required Format Description
URL PARAMETERS – none
QUERY PARAMETERS – none
Note: This request does not support URL or query parameters.


Request Body

Field Name Sample Vaue Required Format Description
date_purchased 2021-05-20T18:25:43.511-04:00 Yes String The local date & time the item is purchased. This date must be an ISO-8601 compliant date field with offset appended to it.
user_id 47111810 No Integer CrowdTwist user ID. If empty, we will store the receipt in the database. If found, we will try to award the user points.
user_attributes See the USER ATTRIBUTES OBJECT section. No Object Gives clients the ability to send user email address or phone number in place of user_id for awarding of points during purchase.
These user attributes are optional. If we don’t find a user based on the criteria given, then we continue processing the receipt and award no user. These user attributes are searched for in priority order. First, we check email, then phone, then third party id. If it matches with someone, then we stop right there.
tenders See the TENDERS ARRAY section. No Array (Tender Objects)  
channel_id 1 No Integer The channel this purchase was made through. If none provided, no multipliers will be applied to the channel type.
1 = In Store
2 = Online
Additional Channel IDs can be configured in Control Center.
items See the ITEMS ARRAY section. Yes Array (Item Objects)

 
USER ATTRIBUTES OBJECT
email_address test@crowdtwist.com No String This is the email associated with the member.
phone_number 1234567890 No String This is the phone number associated with the member.
third_party_id client_user_id123 No String This is the third party id associated with the member.
TENDERS ARRAY
type 1 Yes Integer Tender types used for this transaction. If none are provided, then no multipliers will be given for tender.
1 = Cash
2 = Personal Check
3 = Traveler’s Check
4 = Credit Card
5 = Gift Cards
6 = PIN Debit
7 = PLCC
8 = Vouchers
9 = Virtual Gift Card
10 = MCR – Merchandise Credit Receipt
11 = Other
12 = Mobile Payment
13 = PayPal
14 = Amazon Pay
15 = Credit Card (Amex)
16 = Credit Card (Diners Club)
17 = Credit Card (Discover)
18 = Credit Card (Mastercard)
19 = Credit Card (Visa)
20 = Deferred Payment
21 = EBT
22 = WIC
amount 4.44 Yes Decimal This represents corresponding purchase amount against the tender.
ITEMS ARRAY
sku sku1 Yes String This is the universal id around an item. This will be the main way to identify a particular item during a purchase, bonus campaigns, product catalogs, and other item-level actions.
price 21.22 Yes Decimal

The price of the item, quantity included. This is the value used to calculate points awarded. Any dollar off rewards/coupons will need to be prorated across the items in the order and deducted from the item price; reflecting the actual dollar amount used to purchase the item.
Total price for the full quantity of items. For example – for purchasing 2 of an item that costs $25, the price is $50 and the quantity is 2.

{ "items": [ { "sku": "sku001", "price": 50, "quantity": 2 } ] }
quantity 2 Yes Integer This is the number of items included in this item Array.
transaction_id 2 No Integer Transaction type used on an item. If transaction_id is not provided, then no multipliers or exemptions will be given for transaction types. Any item with a transaction_id associated with a 0x multiplier will not award points.
1 = Sale
2 = Tax Exempt Sale
3 = Employee Sale
4 = Payment on Account
5 = Stamp Sales
6 = Tender Exchange
7 = Gift Card Cash-Out
8 = MCR Cash-Out
9 = Corp Check Insurance
10 = Misc Income
11 = Pride Gift Card Issue
12 = Pride Purchase
13 = Non eligible item
14 = Commercial Sale
15 = Subscription Order

Response

Response Body

Field Name Sample Value Required Format Description
total_points_awarded 624 Yes Integer The total number of points awarded for the entire purchase transaction.
bonus_points_awarded 216 Yes Integer The bonus points awarded from bonus point campaigns.
points_awaiting_fulfilment 413 Yes Integer The number of points that are pending as item is awaiting fulfillment.
breakdown See the BREAKDOWN ARRAY section. Yes Array

The SKUs broken down by singular quantity and the points calculated for each singular quantity item.
BREAKDOWN ARRAY
sku SKU_1 Yes String The sku identifier that is the universal, unique identifier of the item.
is_awaiting_fulfillment true Yes Boolean Used to indicate an item that is awaiting fulfillment.
quantity 15 Yes Integer The number of items this item breakdown is for. Always singular.
item_price 26.11 Yes Decimal The price of the item. Used to calculate the points received for the purchase for the singular item.
points_to_dollar_conversion_rate 2 Yes Integer The conversion rate from dollar to points. This is configurable by the client.
points_to_currency_conversion_rate 2 Yes Integer The conversion rate from primary currency to points. This is configurable by the client.
converted_points 9.66 Yes Decimal Total points converted by multiplying points conversion rate with item price.
campaign See CAMPAIGN ARRAY section. No Array Present if and only if the item is associated with a bonus campaign.
transaction See TRANSACTION ARRAY section. No Array Present if a transaction_id was sent in with the request. If a transaction_id is present, the response will display what transaction type it is and the multiplier associated with it.
tenders See TENDER ARRAY section. No Array Shows the tenders used in this particular transaction. If no tenders are provided, then this array will not appear in the response.
points_awarded 312 Yes Integer The total number of points awarded for this item.
is_excluded false Yes Boolean If true, this item is excluded from receiving any points. This will only happen when a SKU is added to an exclusion list, and no points for that sku will ever be awarded while on the exclusion list.
CAMPAIGN ARRAY
title BONUS CAMPAIGN Yes String Title of the bonus campaign this item is a part of.
multiplier 2 Yes Decimal Multiplier for any item in this bonus campaign.
point_gift 50 Yes Integer Point value for any item in this bonus campaign.
Note: At a given time response can have either Point gift value or multiplier value. If you campaign is setup as points gift, then point_gift will have a value and multiplier will be null and vice versa.
TRANSACTION ARRAY
name MCR Cash-out Yes String Name of the transaction type for this item.
proportion 1 Yes Decimal Proportion of transaction associated with given transaction id.
multiplier 1 Yes Decimal Multiplier associated to this transaction type.
TENDER ARRAY
name Vouchers Yes String Name of the tender type for this item.
proportion 0.5 Yes Decimal Proportion of transaction associated with given tender type.
multiplier 0.25 Yes Decimal Multiplier associated to this tender type.


Error Responses

Field Name Sample Value Required Format Description
system PurchaseController Yes String Domain where the error occurred.
reason internal_error Yes String The identifier of the category of the error. This gives the client the ability to categorize errors and make assumptions based on the identifier of the error.
description Field value is empty. Yes String This is a short form description of the error.
message Value of field [\”receipt_id\”] must not be empty Yes String This is a detailed message around the error specifying, as specifically as possible, what the fields are that are missing or where exactly the error is.


Error Response Codes

Error Error Code Description Reason
Input Error 4xx Returned whenever the request is missing required fields, including situations in which the body is malformed (e.g. HTTP method not supported, receipt not found, etc.). – missing_data
– not_unique
– receipt_not_found
– invalid_amount
– invalid_currency
– invalid_date
– invalid_custom_field
– invalid
Server Error 5xx HTTP error status code is returned due to an error that occurred in the backend. – internal_error: unexpected error occurred in the CrowdTwist backend
– missing_field
– invalid_data
– not_configured: error occurs when an configuration has not been configured yet


Example Response Codes

Response Code System Reason Description Message
400 pos missing_data Required field is missing. Required field ["receipt_id"] is missing.
400 pos invalid Field value is empty. Value of field ["Receipt Image Id"] must not be empty.
400 pos invalid Receipt contains invalid data. Duplicate receipt_image_id for given client.
400 pos invalid_currency Invalid Currency Code. Invalid currency: ABC. Currency code must be ISO-4217 compliant.
400 pos currency_not_configured Currency Code [ABC] not configured for the program in commerce configuration. Currency not configured for the program.
400 pos user_not_found User Not Found. User with id [12345] can not be found.
400 pos invalid Unexpected Date Format. Date purchased is in incorrect format.

Samples

Sample Request Body

{ "date_purchased": "2012-04-23T18:25:43.511+00:00", "channel_id": 1, "currency": "USD", "items": [ { "sku": "sku_1", "price": 21.22, "quantity": 2, "transaction_id": 2 }, { "sku": "sku_2", "price": 3.22, "quantity": 1, "transaction_id": 1 } ], "tenders": [ { "type": 1, "amount": 20 }, { "type": 2, "amount": 4.44 } ] }

 
Sample Response Body
Whenever the request is successfully processed, a 200 HTTP status code will be returned. It is worthy to note that the returned “user_id” and “receipt_id” reflect the receipt and user records that are in the CrowdTwist system.

The breakdown returned details how the point total was calculated for each item on a single quantity basis.

{ "total_points_awarded": 55, "bonus_points_awarded": 7, "points_awaiting_fulfillment": 0, "breakdown": [ { "sku": "sku_1", "quantity": 1, "item_price": 10.61, "points_to_dollar_conversion_rate": 2, "points_to_currency_conversion_rate": 2, "converted_points": 21.22, "is_awaiting_fulfillment": false, "is_excluded": false, "campaigns": [], "transaction": [ { "name": "Tax Exempt Sale", "proportion": 1.0, "multiplier": 1.0 } ], "tender": [ { "name": "Personal Check", "proportion": 0.1817, "multiplier": 1 }, { "name": "Cash", "proportion": 0.8183, "multiplier": 1 } ], "points_awarded": 21 }, { "sku": "sku_1", "quantity": 1, "item_price": 10.61, "points_to_dollar_conversion_rate": 2, "points_to_currency_conversion_rate": 2, "converted_points": 21.22, "is_awaiting_fulfillment": false, "is_excluded": false, "campaigns": [], "transaction": [ { "name": "Tax Exempt Sale", "proportion": 1, "multiplier": 1 } ], "tender": [ { "name": "Cash", "proportion": 0.8183, "multiplier": 1 }, { "name": "Personal Check", "proportion": 0.1817, "multiplier": 1 } ], "points_awarded": 21 }, { "sku": "sku_2", "quantity": 1, "item_price": 3.22, "points_to_dollar_conversion_rate": 2, "points_to_currency_conversion_rate": 2, "converted_points": 6.44, "is_awaiting_fulfillment": false, "is_excluded": false, "campaigns": [], "transaction": [ { "name": "Sale", "proportion": 1, "multiplier": 2 } ], "tender": [ { "name": "Cash", "proportion": 0.8183, "multiplier": 1 }, { "name": "Personal Check", "proportion": 0.1817, "multiplier": 1 } ], "points_awarded": 13 } ] }

 
Sample Error Response

{ "system": "pos", "reason": "missing_data", "description": "Required field is missing.", "message": "Required field [\"receipt_id\"] is missing" }

Note:

• What if a member applies a coupon or other discount at time of purchase?
Potential points are calculated before any dollar off rewards/coupons are taken into consideration (or applied in cart or at POS). The client would prorate these discounts across the items at time of purchase which likely results in a lesser amount of points being awarded. This ensures points are only awarded for actual price paid.

• What if a bonus campaign is running against a category (i.e. Brand)?
If a campaign is running on a brand, we will take the “sku” and check to see if it matches the brand for that campaign.

• What happens when a sku matches multiple campaigns?
The campaign with the highest multiplier is chosen.

• What happens when the multipliers are the same?
The campaign created most recently is chosen.