User Purchase History

Request Details

Item Value
Description The user purchase history endpoint allows clients to request a member’s purchase history at a high level. Clients can then request details about each purchase through the Purchase Detail endpoint.
Method GET
Endpoint https://[environment]pos[client_id].crowdtwist.com/users/[user_id]/purchases?id_type=[id_type]&page=1&date_start=[date_start]&date_end=[date_end]
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:
Options:

  • email
  • id (CrowdTwist ID)
  • third_party_id
  • mobile_phone_number
QUERY PARAMETERS
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
  • mobile_phone_number
page 5 No Integer Page number for which the history details needs to be returned.
  • If no page number is requested history of first page will be returned.
  • If page requested is not a valid value history of first page will be returned.
  • If page is out of range – Eg if page number is 0 or lesser, empty purchases array will be returned and next page will have a link to page 1. If page number is exceeding the length of pages available empty purchases array will be returned with a link to the previous available page.
  • Max entries per page is 10.
date_start YYYY-MM-DD No Date
  • This will be the start of the queried range.
  • The response set will include purchases on this date.
  • If only date_start is specified then transactions will be returned from date_start to current date.
date_end YYYY-MM-DD No Date
  • This will be the end of the queried range.
  • The response set will include purchases on this date.
  • If date_start and date_end is present then date_end cannot be before the date_start.
  • If only date_end is present then all transaction will be returned until date_end.

Response

Response Body

Field Name Sample Value Required Format Description
purchases See the PURCHASE ARRAY section. Yes Array (Purchases Objects) It stores purchase information for a member.
paging See the PAGING OBJECT section. Yes Object It stores information on the specified page of the purchases.
PURCHASE ARRAY
last_date_purchased 2018-01-01T11:00:18Z Yes String Purchases can contain more than one receipt. This is the most recent receipt’s purchase date.
ISO 8601 format
This date is returned in UTC.
purchase_id order_100 Yes String The order id or the third party receipt id of this purchase.
purchase_id_type order_id
receipt_id		 Yes String The type of purchase ID.
purchase_total 400 Yes Integer The total of all receipts in this purchase.
total_points_awarded 500 Yes Integer The total number of points awarded for this purchase.
total_points_earned 500 Yes Integer The total number of points that were earned for this purchase. A member may not be awarded all of the points they earned if a point cap is in place.
points_awaiting_fulfillment 200 Yes Integer The total points that are awaiting fulfillment for this purchase. A member may not be awarded all of the points they earned if a point cap is in place.
PAGING OBJECT
total 203 Yes Integer Total number of orders.
pages 10 Yes Integer Total number of pages.
next_page

https://pos12.crowdtwist.com/users/332170040/

purchases?id_type=id&page=2

 Yes String URL of the next page.
prev_page

https://pos12.crowdtwist.com/users/332170040/

purchases?id_type=id&page=1

 Yes String URL of the previous page.


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
404 not_found User ID not found.
400 invalid_parameter ID type is invalid.

Samples


Sample Request

GET https://pos12.crowdtwist.com/users/332170040/purchases?id_type=id&page=1&date_start=2022-01-01&date_end=2022-01-12

 

Sample Response Body

{ "purchases": [ { "last_date_purchased": "2018-01-01T11:00:18Z", "purchase_id": "order_100", "purchase_id_type": "receipt_id", "purchase_total": 400, "total_points_awarded": 400, "total_points_earned": 400 }, { "last_date_purchased": "2018-01-01T11:00:18Z", "purchase_id": "order_200", "purchase_id_type": "receipt_id", "purchase_total": 500, "total_points_awarded": 500, "total_points_earned": 500 } ], "paging": { "total": 2, "pages": 1, "next_page": "Link to next page", "prev_page": "Link to previous page" } }

 

Sample Error Response

{ "error": { "code": 404, "message": "Not found", "errors": [ { "reason": "user_not_found", "message": "User does not exist" } ] } }