Request Details

Item	Value
Description	The purchase API is used to send purchase data to the CrowdTwist system. Purchases associated with a program member will award points.
Method	POST
Endpoint	https://[environment]pos[client_id].crowdtwist.com/purchase
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
receipt_id	receipt123	Yes	String	For each purchase transaction, this should be the id on the receipt. This must be a unique identifier of this request.
order_id	order123	No	String	This is for clients to capture multiple receipts (or transactions) under one order number. This won’t be used for any validation or calculations, but is only stored for reporting purposes.
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.
total	119.64	Yes	Decimal	This field is only recorded and is not used for any calculations.
subtotal	110.78	No	Decimal	This field is only recorded and is not used for any calculations.
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.
custom_data	See the CUSTOM DATA OBJECT section.	No	Object	Fields added to this will be stored in the database, but these fields must be known by CrowdTwist. If the fields sent in are not known by CrowdTwist, there will be a response of a 400 error. Refer to Custom Data Requirements below for additional details. For a list of configured attributes, please work with your CrowdTwist representative.
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.
coupons	See the COUPONS ARRAY section.	No	Array (String)	The coupons used in this purchase.
currency	USD	No	String	This is the currency of all the amounts and prices included in this API. If no currency is provided the default is USD. See Additional details.
receipt_image_id	7f84123c14c4569c105789 a34c71423ed71d7ff	No	String	CrowdTwist generated file id. Required if channel_id=10.
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.
COUPONS ARRAY
coupon	[ "coupon123456", "coupon123789" ]	Yes	Array (Strings)	This is the list of coupons that are used in this transaction. This field marks the coupon(s) as used in the CrowdTwist platform, but will not error-out if a previously used code is sent through again. No coupon dollar amounts are factored into the calculations of bonus points or the total of the transaction.
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
is_awaiting_fulfillment	true	No	Boolean	Used to indicate an item that is awaiting fulfillment.
custom_data		No	Object	Fields added to this will be stored in the database, but these fields must be known by CrowdTwist. If the fields sent in are not known by CrowdTwist, there will be a response of a 400 error. Refer to Custom Data Requirements for additional details. Attribute names (item level custom_data): color size
CUSTOM DATA OBJECT
store_loc	store1	No	String	Store location associated with purchase.
cashier_id	cashier1	No	String	ID of cashier that helped with purchase.

Note:
The custom_data field will contain a list of key-value data pairs that are specified by the client.
• The value needs to be a string.
• The value needs to have less than a max character length of 512.
• Any attributes to be sent need to be known by CrowdTwist prior to integration.
• If there are key(s) that were not identified by the client to CrowdTwist, then the unknown key(s).
• “error”: “input_error”, “message”: “No custom attributes setup for client 12.”}.
• “error”: “input_error”, “message”: “Unrecognized attribute name bar for client 12.”}.

Response

Response Body

Field Name	Sample Value	Required	Format	Description
receipt_id	15	Yes	String	The id of the receipt record found in CrowdTwist’s system that correlates to the sent in “receipt_id” in the request.
user_id	12	Yes	String	The id of the user record found in CrowdTwist’s system that correlates to the sent in CrowdTwist user id or to the sent in third party member identifying attributes within the user attributes object in the request.
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.
campaigns	See CAMPAIGNS 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.
CAMPAIGNS 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

 

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.

 

Sample Error Response