Request Details

Item	Value
Description	The Return API is called to request purchase returns to the CrowdTwist system. To request a purchase return, you must perform an HTTP Post request with a JSON object. The Return API deducts points from the member’s account for the item(s) returned.
Method	POST
Endpoint	https://[environment]pos[client_id].crowdtwist.com/return
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 Value	Required	Format	Description
return_id	RT031942	Yes	String	This is the ID of the return request. This field should be unique and not empty.
original_receipt_id	33-1302-1202	No	String	This is the client’s receipt id of the original purchase. If receipt id is not included, then at least one user_attribute field is required.
return_type	1	Yes	Integer	Return types: 1. Return With Receipt 2. Return With Gift Receipt 3. Ecommerce Return 4. Return without Receipt 5. Manager’s Return without Receipt 6. Return for Exchange 7. Cancellation 8. Void 9. Return For Exchange Without Receipt Non-member returns are not accepted for return_type 4, 5, and 9. These return_type values require data in the user_attributes field.
date_returned	2021-05-20T18:25:43.511-04:00	Yes	String	This field will be the local date-time that the return was made. This date must be an ISO-8601 compliant date field with offset appended to it.
user_id	8694859	No	Integer	CrowdTwist unique identifier for user. Matching on User ID will take precedence over user_attributes. If return_type is 4, 5, or 9, either user id or user attribute is required.
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. If return_type is 4, 5, or 9, one value is required.
custom_data	Attributes are predefined at CrowdTwist	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 Instructions for additional details.
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.
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.
quantity	2	Yes	Integer	This is the number of items included in this item Array.
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	This is the ID of the receipt record found in the CrowdTwist database that matches the “original_receipt_id” found in the return request.
is_excluded	false	Yes	Boolean	If the flag is true, the return is excluded from deducted points and the “points_deducted” field will be 0 for each item. This occurs if/when there is an exclusion rule to the return type that was sent in. For example, if “return without a receipt” is excluded, the flag will be true and all “points_deducted” will be 0 for every item in the return.
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_deducted	624	Yes	Integer	The total number of points deducted after the return is complete.
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.
points_deducted	true	Yes	Boolean	The number of points taken from the client for this one sku with one quantity.
date_points_awarded	2021-05-20T18:25:43.511-04:00	Yes	String	ISO-8601 compliant date of when the user was awarded for this sku purchase.
points_awarded	20	Yes	Integer	The number of points that were awarded to the user for this sku during time of purchase.

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.	Return must include valid user attributes.
400	pos	quantity_too_large	Return request Invalid Fields	User is trying to return more items than the number that were bought and awarded for during purchase.
400	pos	item_not_available	Return request Invalid Fields	SKU being processed for return but isn't available for return.
400	pos	invalid	Return request Invalid Fields	Return ID is empty.

Samples

Sample Request Body

 

Sample Response Body

 

Sample Response Body - Exclusion on return type

 

Sample Response Body – Return without receipt

 

Sample Error Response

Note:

• What happens when someone returns an item whereby the original receipt has multiple entries for that one item?
This scenario can occur if, during purchase, the client sends in multiple receipt items with the same sku but different prices associated with them.
If the purchase was sent in with the same-sku items but different price amounts, the return API will choose the item with the higher point value to deduct from the user during a return.

• What happens when there are returns without an original receipt?
When processing a return the original return must be located either by providing the original_receipt_id or via lookup by using the user_attributes option. If no purchase can be located, the the return will not be processed.

• Can special fields (e.g. ‘order #’) be stored?
The custom_data field allows any field that is sent in to be saved in the CrowdTwist database as long as they were identified to CrowdTwist by the client in advance.