Reward Create
Request Details
Item | Value |
Description | The Create Reward API allows clients to create rewards in their loyalty program. The create reward API supports standard, sweepstake, code and download rewards types. |
Method | POST |
Endpoint | https://[environment]api[client_id].crowdtwist.com/v2/reward?api_key=[api_key] |
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 |
title | Free Cap | Yes | String | The title of reward. |
description | Free Accessories | Yes | String | The description of reward. |
type | STANDARD | Yes | String |
Reward types that can be created:
|
category_id | 4536 | Yes | Integer | Reward category id. |
points_to_redeem | 100 | Yes | Integer | The number of points required to redeem this reward. |
total_quantity | 25 | No | Integer | Total quantity of the reward which is set. Updating the quantity does not add to initial quantity, but will set the quantity to the new value.
This will not be required when reward has variations as each variation will have its own quantity. This attribute is not present for Sweepstake. This will not be required when reward has variations as each variation will have its own quantity This field is not present for Sweepstake |
reference_id | First software-rewards | No | String | Reference ID used for matching external reward fields. |
max_lifetime_redemptions | 1 | No | Integer | If set, then the value is the maximum allowed. If not set, then unlimited. |
is_shipping_required | true | Yes | Boolean | If shipping information is required for redemption |
is_phone_number_required | true | Yes | Boolean | If phone number is required for redemption |
date_start | 2012-04-23T18:25:43z | Yes | Date | Start date of the reward. This date must be an ISO-8601 compliant date field with offset appended to it. |
date_end | 2018-04-23T18:25:43z | No | Date | End date of the reward. This date must be an ISO-8601 compliant date field with offset appended to it. It is mandatory if reward type is sweepstake. |
freq_cap | 2 | No | Integer | Check is going to be made for fan center client/s who do not have the feature enabled for them. The API will not support frequency capping for Fan center clients how many times a reward can be redeemed within a given time period. |
freq_period_id | 1 | No | Integer |
Given time period for reward. Below periods can be chosen:
|
code_expiration | Null | No | Integer |
The offset of number of days of expiration for the reward. Note: Only present for CODE reward type. |
segment_link_id | 123 | No | Integer | ID of the segment or segment group linked to the reward . This is the same ID returned in the User Profile API. |
segment_link_type | include | No | String |
"include" or "exclude", required if segment_link_id is provided.
|
variations | See the VARIATION ARRAY section. | No | Array | |
extra_data | See the EXTRA DATA OBJECT section. | No | Object | This is client defined additional data, max limit of 20. |
date_until_entries_accepted | 2012-04-23T18:25:43z | No | Date | Date/Time until which a user can enter a sweepstake. It is mandatory if reward type is sweepstake. |
num_winners | 3 | No | Integer | Number of winners assigned for the Sweepstake reward. It is mandatory if reward type is sweepstake. |
min_age | 18 | No | Integer | Minimum age required to enter the sweepstake. |
VARIATION ARRAY | ||||
display_order | 1 | Yes | Integer | Order in which the reward variations will appear. |
quantity | 64256446 | Yes | Integer | Quantity of the variation. |
reference_id | ABFTGDB34352 | No | String | Reference ID of the reward. |
color | Red | Yes | String | The color of the shirt. |
size | Small | Yes | String | Size of the shirt. |
EXTRA DATA OBJECT | ||||
city | New York | No | String | City information. |
state | New York | No | String | State information. |
country | USA | No | String | Country information. |
postal code | 10010 | No | String | Postal code information. |
Response
Response Body
Field Name | Sample Value | Required | Format | Description |
reward_ids | [5089, 694568] | Yes | Array (Strings) | This is the Array of Internal CrowdTwist reward id(s). |
reward_group_id | 64256446 | Yes | Integer | This is the group ID of the reward. |
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 |
400 | reward_title_taken | Reward with the same name exists. |
400 | required_property_missing | Missing [fieldname] required field. |
400 | exceeds_max_size | Property [filename] cannot exceed [max]. |
400 | below_min_size | Property [filename] cannot be less than [min]. |
400 | end_date_before_start_date | End date/time cannot be before start date/time. |
400 | invalid_date | Invalid data format, [field] should be [data_type] but entered [data_type]. |
400 | non_unique_variation | Color and size combination have to be unique. |
400 | invalid_category_id | Category ID is invalid |
400 | invalid_reward_type | Only type STANDARD/SWEEPSTAKE is allowed in type field. |
400 | entry_dead_line_date_before_start_date_or_after_end_date | Entry deadline date/time cannot be before start date of after end date. |
400 | reward_property_type_not_allowed | Property [propertyName}] is not allowed for supported for [RewardType] reward. |
Samples
Sample Request Body - Standard Rewards
Sample Request Body - Sweepstakes
Sample Response Body
Sample Error Response