Request Details

Item	Value
Description	This document describes the Usable Coupons endpoint in the REST v2 Users API. This endpoint returns a list of reward coupons which are available for use by a given program member. A coupon is considered usable if it has been assigned to the user through reward redemption, it has not yet itself been redeemed, and its expiration date (if it has one) has not yet passed. The correct operation of this endpoint depends on the client providing us with the information that a given coupon has been used. Currently this is only possible via the Commerce Purchase API. If we are not told that a coupon has been used, it will continue to show as usable even when it has already been used.
Method	GET
Endpoint	https://[environment]api[client_id].crowdtwist.com/v2/users/[userId]/usable_coupons?api_key=[api_key]&id_type=[id_type]
HTTP Header	X-CT-Authorization = CTApiKey [API Key] Note: there is a space between CTApiKey and the API Key value

Request

Field Name	Sample Value	Required	Format	Description
URL PARAMETERS
user_id	alice@crowdtwist.com	Yes	String	Unique ID of the user for whom activities will be returned. User ID that can be sent are: – email – id (CrowdTwist ID) – third_party_id – mobile_phone_number
QUERY PARAMETERS
api_key	QWERTY	Yes	String
id_type	email	No	String	Type of ID being Sent. – email – id (CrowdTwist ID) – default ID if id_type is not specified – third_party_id – username
expired	false	No	String	Either true or false. If attribute is not provided, default is true (expired, unused coupons are included).

Response

Response Body

Field Name	Sample Value	Required	Format	Description
reward_id	58239	Yes	String	The ID of the original reward record that was redeemed to receive the coupon.
reward_category_id	1057	Yes	String	The ID of the reward category.
redeem_order_id	205501233	Yes	String	The ID of the redemption order record that resulted in the coupon assignment.
redeem_order_coupon_id	279272719	Yes	String	The ID of the redemption order coupon record that resulted in the coupon assignment.
total_points_redeemed	10	Yes	Integer	The number of points redeemed in the redemption order that resulted in the coupon assignment.
ending_balance	1000	Yes	Integer	The program member’s redeemable points balance after the redemption order that resulted in the coupon assignment.
quantity	1	Yes	String	The quantity from the redemption order that assigned the coupon.
code	new name	Yes	String	The coupon code.
reward_title	Reach Gold Tier	Yes	String	The title of the reward redeemed to receive the coupon, at the time it was redeemed.
coupon_category_id	1057	Yes	String	The ID of the coupon’s category.
coupon_category_name	Tier Goal	Yes	String	The name of the coupon’s category at the time the coupon was assigned via reward redemption.
coupon_category_expiration_days		Yes	String	The coupon category’s setting for the number of days after which coupons assigned by it expire (null if expiration is not performed).
batch_num	5	Yes	String	The batch number of the coupon (a serial number incrementing each time a batch of coupons is generated).
date_to_expire	1641990827	Yes	String	If the coupon will expire, the Unix timestamp when it will expire (otherwise null).
order_date_created	1641990827	Yes	String	The Unix timestamp of when the reward redemption order that assigned the coupon took place.
coupon_date_created	16074741453	Yes	String	The Unix timestamp of when the coupon was originally generated (coupons are generated before they’re assigned to a program member via reward redemption).

Error Responses

Field Name	Sample Value	Required	Format	Description
error	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.
message	User could not be found	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.).	– receipt_not_found – 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 – not_configured: error occurs when an configuration has not been configured yet

Example Response Codes

Response Code	Reason	Message
403	invalid_auth	Invalid access credentials.
404	page_not_found	User does not exist

Samples

Sample Request

 

Sample Response Body

 

Sample Error Response