User Redemption History v2.2

Request Details

Item Value
Description User redemption history returns the list of rewards the the loyalty member has redeemed.
Method GET
Endpoint https://[environment]api[client_id].crowdtwist.com/v2.2/users/[user_id]/redemption_history?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 QWERTYP Yes String
id_type email No String

Type of ID being sent, defaults will be Crowdtwist ID if not specified.
The type of ID can be:

  • email
  • facebook_user_id
  • twitter_user_id
  • id (CrowdTwist ID, default if not specified)
  • third_party_id
  • username
  • mobile_phone_number
date_start YYYY-MM-DD No Date Start date of the date range for history in UTC timezone. There is a limit of one year for date_start to date_end. A longer range will return an error stating date range should not exceed more than a year.
date_end YYYY-MM-DD No Date End date of the date range for history in UTC timezone. Date_end must be greater than date_start.
page 1 No Integer
  • Clients have the option to send request for a specific page number.
  • If no page number is requested we will return the first page.
  • If page requested is not a valid value we will return the first page.
  • If page is out of range – Eg if page number is 0 or lesser, we will return empty rewards array and next page will have a link to page 1. If page number is exceeding the length of pages available we will return empty rewards array and return a link to the previous available page.
  • Max entries per page is 10.
page_size 10 No Integer The size of page that is returned in the response (max of 10). If no page_size is specified, we default with 10 rewards in the response.

Response

Response Body

Field Name Sample Value Required Format Description
paging

See the PAGING ARRAY section.

 Yes Array (Paging objects) Array that stores information on the specified page of purchases.
rewards

See the REDEMPTIONS ARRAY section.

 Yes Array (Redemption objects) Array of redemption information.
PAGING ARRAY
total 203 Yes Integer This is the total number of rewards.
pages 10 Yes Integer This is the total page numbers.
next_page http://example.ct.com/v2.1/rewards?page=3 No String This is the URL of the next page.
prev_page http://example.ct.com/v2.1/rewards?page=1 No String This is the URL of the previous page.
REDEMPTIONS ARRAY
reward_id 64256446 Yes Integer The is the variation ID of the reward.
date_created 2020-04-14T20:32:03Z Yes String Date user redeemed reward. ISO-8601 compliant date field with offset appended to it.
date_fulfilled 2021-04-14T20:32:03Z No String This value will always be set to null and instead fulfillment_data at the tracking_info object level will hold the value for date when the item will be fulfilled.
total_points_redeemed 100 Yes Integer Total points redeemed by user for reward.
ending_balance 15687 Yes Integer Total points remaining after redemption.
category_id 3352 Yes String This is the category ID of the reward.
description Customer Fan Favorite Baseball Cap Reward Yes String This is the description of the reward.
group_id 123456 Yes String This is the group the reward is in. When a reward has multiple sizes/colors, they will all share the same group_id.
reward_title Fan Favorite Cap Yes String This is the title of the reward redeemed.
order_id 63827426 Yes Integer This is the unique ID of the redemption.
image http://www.imagestorage.com/image Yes String The reward image.
digital_download http://www.imagestorage.com/image No String This is the URL for download if digital download reward was redeemed.
extra_data See the EXTRA DATA OBJECT section. No Object This is client defined additional data, max limit of 20.
codes See the CODE ARRAY section. No Array If code reward – array of codes distributed for redemption.
redemption items See the REDEMPTION ITEMS ARRAY section. No Array Array of redeemed items, only required if client has integration for reward redemption with a third party, or else this field will return an empty array.
shipping_info 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 Oracle-CrowdTwist representative.
tracking_info See the SHIPPING INFO OBJECT section. Yes Object Shipping information will be returned depending on if collected for redemptions.
codes See the TRACKING INFO ARRAY section. No Array Stores tracking information for the redemption if available.
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.
CODE ARRAY
code TESTCODE123 No URL Code issued to the member.
date_used 2018-01-01T11:00:18Z No Date ISO-8601 compliant date field with offset appended to it.
REDEMPTION ITEMS ARRAY
item_id 890479 Yes String Third party Item ID sent by the vendor.
item_points 100 Yes String Points spent per item.
item_name Partner Baseball Cap Yes String Name of the item.
item_quantity 1 Yes Integer Item quantity.
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.
SHIPPING INFO OBJECT
first_name John No String If required by reward – first name to whom the reward will be shipped.
last_name Doe No String If required by reward – last name to whom the reward will be shipped.
street_address_1 25 1st Avenue No String If required by reward – street address of destination the reward will be shipped.
street_address_2 Apt 1C No String If required by reward – additional address info of destination the reward will be shipped.
country USA No String If required by reward – country of destination the reward will be shipped.
state NY No String If required by reward – state of destination the reward will be shipped.
city New York No String If required by reward – city of destination the reward will be shipped.
zip 10001 No String If required by reward – zip code of destination the reward will be shipped.
phone_number 2125551234 No String If required by reward – phone number of user redeeming reward.
TRACKING INFO ARRAY
fulfillment_id 46445665 Yes Integer Identifier which uniquely identifies a fulfillment record.
tracking_number ABFTGDB34352 Yes String Shipment tracking number.
vendor_name UPS Yes String Shipment vendor.
fulfillment_date "2012-04-23T18:25:43Z" Yes String Date when item was fulfilled.
quantity 3 Yes Integer This is the quantity of rewards fulfilled.



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 param_error Param category has invalid value.
403 invalid_auth Invalid access credentials.
404 page_not_found Unable to find user.

Samples

Sample Request Body

curl -X GET https://api.crowdtwist.com/v2.1/users/alice@crowdtwist.com/redemption_history?api_key=QWERTYUIOP&id_type=email



Sample Response Body

{ "paging": { "total": 133, "pages": 14, "next_page": "https://api[client_id].ct.com/v2.1/rewards?page=2&api_key=", "prev_page": "https://api[client_id].ct.com/v2.1/rewards?page=21&api_key=" }, "redemptions": [ { "reward_id": "555401", "date_created": "2018-01-01T11:00:18Z", "total_points_redeemed": 0, "ending_balance": 136, "category_id": "2865", "description": null, "group_id": "39045", "reward_title": "Exclusive Gold Member Reward", "order_id": "22132", "date_fulfilled": null, "image": null, "quantity": 1, "extra_data": { "city": "New York" }, "custom_data": null, "codes": [ { "code": "BIRTHDAY21", "date_used": "2018-01-01T11:00:18Z" } ], "redemptionItems": [ { "item_id": "AB3543C", "item_name": "T-Shirt", "item_points": 100, "item_quantity": 2, "custom_data": null }, { "item_id": "24A34", "item_name": "Shoes", "item_points": 5000, "item_quantity": 1, "custom_data": null } ], "shipping_info": { "first_name": "John", "last_name": "Smith", "street_address_1": "251 Ave C", "street_address_2": null, "country": "Canada", "state": "Ontario", "city": "Toronto", "zip": "M1R 0E9", "phone_number": "3455554444" }, "tracking_info": [ { "tracking_number": "A564FG16756757", "vendor_name": "Fedex", "fulfillment_id": 4689568, "fulfillment_date": "2018-04-23T18:25:43.511+00:00", "quantity": 1 }, { "tracking_number": "4967834537", "vendor_name": "Fedex", "fulfillment_id": 5689568, "fulfillment_date": "2019-04-23T18:25:43.511+00:00", "quantity": 2 } ] } ] }



Sample Error Response

{ "error": "invalid_auth", "message": "Invalid access credentials." }