User Redemption
Request Details
Item | Value |
Description | The User Redemption API redeems a reward for a user. |
Method | POST |
Endpoint | https://[environment]api[client_id].crowdtwist.com/v2/users/[user_id]/redemption?api_key=[api_key]&id_type=[id_type] |
Content Type | application/json |
Request
Field Name | Sample Value | Required | Format | Description |
URL PARAMETERS | ||||
user_id | alice@crowdtwist.com | Yes | String | User ID of the user for whom the reward will be redeemed. The user ID can be:: – Email address – Facebook user ID – Twitter User ID – CrowdTwist ID – Third party ID – Username – Mobile Phone Number |
QUERY PARAMETERS | ||||
api_key | QWERTYUIOP | Yes | String | |
id_type | No | String | Type of ID being sent, defaults to ID if not specified. The type of ID can be: – facebook_user_id – twitter_user_id – id (CrowdTwist ID, default if not specified) – third_party_id – username – mobile_phone_number |
Request Body
Field Name | Sample Value | Required | Format | Description |
reward_id | 64 | Yes | String | The reward variation ID to be redeemed. |
quantity | 1 | Yes | Integer | The quantity of the reward to be redeemed. |
shipping_phone_number | 2125551234 | No | String | If required by reward – phone number of user redeeming reward. |
shipping_first_name | John | No | String | If required by reward – first name to whom the reward will be shipped. |
shipping_last_name | Doe | No | String | If required by reward – last name to whom the reward will be shipped. |
shipping_street_address_1 | 25 1st Avenue | No | String | If required by reward – street address of destination the reward will be shipped. |
shipping_street_address_2 | Apt 7C | No | String | If required by reward – additional address info of destination the reward will be shipped. |
shipping_country | USA | No | String | If required by reward – country of destination the reward will be shipped. |
shipping_state | NY | No | String | If required by reward – state of destination the reward will be shipped. |
shipping_city | New York | No | String | If required by reward – city of destination the reward will be shipped. |
shipping_postal_code | 10001 | No | String | If required by reward – postal code of destination the reward will be shipped. |
custom_data | See the CUSTOM DATA OBJECT section. | No | Object | Client-defined attributes can be sent via the custom_data request object. For a list of configured attributes, please work with your CrowdTwist representative. |
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. |
Response
Response Body
Field Name | Sample Value | Required | Format | Description |
ending_balance | 6000 | Yes | Integer | Number of points remaining available to user. |
codes | See the CODE ARRAY section. | No | Array (String) | If code reward – array of code(s) or url(s) for code(s). |
digital_download | http://programurl.com/download | No | String | If digital download – url to download. |
CODE ARRAY | ||||
codes |
[
"123456",
"123789"
]
|
No | Array (Strings) | This is the list of codes available. |
Error Responses
Field Name | Sample Value | Required | Format | Description |
error | Field value is empty. | Yes | String | This is a short form of the error. |
message | Value of field [fieldname] 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 | Error | Message |
404 | page_not_found | User does not exist. |
403 | insufficient_points | User does not have enough points to redeem reward. |
403 | access_denied | User is not in the right segment to access this reward. |
404 | invalid_reward | Reward does not exist, is expired or inactive. |
403 | over_redeem_limit | User can only redeem x of this reward. |
403 | sweep_entry_over | This sweepstakes is either over or entries are no longer being accepted. |
403 | forbidden | User does not meet the minimum age requirement. User's age is. Minimum age is x. |
403 | forbidden | Redemption exceed current quantity of rewards. |
Samples
Sample Request
Sample Request Body
Sample Response Body
Sample Error Response