Commerce – Return


Request Details

Item Value
Description The Return API is called to request purchase returns to the CrowdTwist system. To request a purchase return, you must perform an HTTP Post request with a JSON object
Method POST
Endpoint https://pos.crowdtwist.com/return
HTTP Header X-CT-Authorization = CTApiKey [ClientSecretKey]
Note: there is a space between CTAPIKey and the Secret Key value


Request

Field Name Sample Value Required Format Notes
URL PARAMETERSnone
QUERY STRING PARAMETERSnone
HTTP HEADER
ClientSecretKey QWERTYUIOP Yes String  


Request Body

Field Name Validation Required Format Notes
return_id Not null Yes String This is the ID of the return request. This field should be unique and not empty.
original_receipt_id Not null No String This is the client’s receipt id of the original purchase. If receipt id is not included, then at least one user_attribute field is required.
return_type Not null, matches valid return type value Yes Integer Return types:
1. Return With Receipt
2. Return With Gift Receipt
3. Ecommerce Return
4. Return without Receipt
5. Manager’s Return without Receipt
6. Return for Exchange
7. Cancellation
8. Void
9. Return For Exchange Without Receipt

Non member returns are not accepted for return_type 4 & 9. These return_type values require data in the user_attributes field.

date_returned Not null, ISO-8601 compliant Yes String This field will be the local date-time that the return was made. This date must be an ISO-8601 compliant date field with offset appended to it.
items Not null Yes Array This is the array of items to be returned.
user_attributes If return_type is 4 or 9, one value is required. No JSON Array Gives clients the ability to send user email address or phone number in place of user_id for awarding of points during purchase.
These user attributes are optional. If we don’t find a user based on the criteria given, then we continue processing the receipt and award no user.
These user attributes are searched for in priority order.  First we check email, then phone, then third party id. If it matches with someone, then we stop right there.

{
  "email_address": "test@crowdtwist.com",
  "phone_number": "1234567890",
  "third_party_id": "client_user_id123"
}
{
  "email_address": "test@crowdtwist.com",
  "phone_number": "1234567890",
  "third_party_id": "client_user_id123"
}
custom_data Attributes are predefined at CrowdTwist No JSON Object Fields added to this will be stored in the database, but these fields must be known by CrowdTwist. If the fields sent in are not known by CrowdTwist, there will be a response of a 400 error. Refer to Custom_Data Instructions below for additional details.
ITEMS ARRAY
sku Not null Yes String The SKU string identifier of the item that is being returned.
quantity Not null; greater than zero Yes Interger The number of this item with this SKU is being returned.


Custom Data Requirements
The custom_data field will contain a list of key-value data pairs that are specified by the client.
 • The value needs to be a string.
 • The value needs to have less than a max character length of 512.
 • Any attributes to be sent need to be known by CrowdTwist prior to integration.
  • If there are key(s) that were not identified by the client to CrowdTwist, then the unknown key(s)
  • “error”: “input_error”, “message”: “No custom attributes setup for client 12.”}
  • “error”: “input_error”, “message”: “Unrecognized attribute name bar for client 12.”}


Successful Response Field Definitions

FIELD NAME DATA TYPE NOTES
receipt_id Long This is the ID of the receipt record found in the CrowdTwist database that matches the “original_receipt_id” found in the return request.
total_points_deducted Long The total number of points deducted after the return is complete.
user_id Long If user_id is found with the original receipt, then it will be returned in the success response. If user_id is not found, then success response will return a null value in the user_id field.
is_excluded Boolean If the flag is true, the return is excluded from deducted points and the “points_deducted” field will be 0 for each item. This occurs if/when there is an exclusion rule to the return type that was sent in. For example, if “return without a receipt” is excluded, the flag will be true and all “points_deducted” will be 0 for every item in the return.
breakdown Array The array containing all the sku’s in one quantity and how many points were deducted in each.
sku String SKU identifier sent in the request.
points_deducted Long The number of points taken from the client for this one sku with one quantity.
date_points_awarded String ISO-8601 compliant date of when the user was awarded for this sku purchase.
points_awarded Long The number of points that were awarded to the user for this sku during time of purchase.


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
– quantity_too_large
– sku_not_found
– not_supported (if an endpoint is not supported, a status HTTP code of 405 will be returned)
– 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


Error Response Field Definitions

Field Name Data Type Notes
system String Domain where the error occurred.
reason String This identifier is the category of the error which gives the client the ability to categorize errors and make assumptions based on the identifier of the error.
description String This is a short form description of the error.
message String Detailed message that specifies what fields are missing or where the error occurred.


Sample Request

  {
  "return_id”: "return1”,
  "return_type”: 1,
   "original_receipt_id”: "originalreceiptId1”
   "date_returned”: "2012-04-23T18:25:43.511+00:00”,
    "custom_data”: { 
            employee_data: "employee1”,
            store_loc: "store1” 
     },
     "items”: [
         {
            "sku”: "sku1”,
            "quantity”: 2
          },
          {
             "sku”: "sku2”
             "quantity”: 1
           }
      ]
}
  {
  "return_id”: "return1”,
  "return_type”: 1,
   "original_receipt_id”: "originalreceiptId1”
   "date_returned”: "2012-04-23T18:25:43.511+00:00”,
    "custom_data”: { 
            employee_data: "employee1”,
            store_loc: "store1” 
     },
     "items”: [
         {
            "sku”: "sku1”,
            "quantity”: 2
          },
          {
             "sku”: "sku2”
             "quantity”: 1
           }
      ]
}

Sample Successful Response: Status Code 200

A return request containing 1 item (“sku1”) with quantity 2 and when there is no exclusion on the return type

{
"receipt_id": 12345,
"total_points_deducted": 1000,
 "user_id: 123,
  "is_excluded:: false
 "breakdown": [
    {
      "sku": "sku1",
      "points_deducted": 500,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    },
    {
"sku": "sku1",
      "points_deducted": 500,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    }
  ]
}
{
"receipt_id": 12345,
"total_points_deducted": 1000,
 "user_id: 123,
  "is_excluded:”: false
 "breakdown": [
    {
      "sku": "sku1",
      "points_deducted": 500,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    },
    {
"sku": "sku1",
      "points_deducted": 500,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    }
  ]
}

Sample Successful Response: Status Code 200

A return request containing 1 item (“sku1”) with quantity 2 and when there is an exclusion on the return type

{
   "receipt_id": 12345,
   "total_points_deducted": 0,
    "user_id”: 123, 
    "is_excluded:: true
    "breakdown": [
    {
      "sku": "sku1",
      "points_deducted": 0,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    },
    {
      "sku": "sku1",
      "points_deducted": 0,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    }
  ]
}
{
   "receipt_id": 12345,
   "total_points_deducted": 0,
    "user_id”: 123, 
    "is_excluded:”: true
    "breakdown": [
    {
      "sku": "sku1",
      "points_deducted": 0,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    },
    {
      "sku": "sku1",
      "points_deducted": 0,
      "date_points_awarded": "2012-04-23T18:25:43.511+00:00”,
      "points_awarded":500
    }
  ]
}

Sample Successful Response: Status Code 200 – Return without receipt

{
“receipt_id”: null,
“total_points_deducted”: 0,
“user_id”:123,
“is_excluded”: false,
“breakdown”: [
{
“sku”: “sku1”,
“points_deducted”: 500,
“date_points_awarded”:”2012-04-23T18:25:43.511+00:00″,
“points_awarded”:500
},
{
“sku”: “sku1”,
“points_deducted”: 500,
“date_points_awarded”:”2012-04-23T18:25:43.511+00:00″,
“points_awarded”:500
}
]
}

Sample Error Response: Status Code 400

{
"error”: {
"system”: "ReturnController”,
"reason”: "missingData”,
 "description”: "Missing Data From Request”,
 "message”: "Required field ["return_id”] is missing.”
}
}
{
"error”: {
"system”: "ReturnController”,
"reason”: "missingData”,
 "description”: "Missing Data From Request”,
 "message”: "Required field ["return_id”] is missing.”
}
}

Sample Error Response: Status Code 500

{
 "error”: {
"system”: "ReturnController”,
 "reason”: "internal_error”,
 "description”: "Return Request Missing Fields.”,
 "message”: "Return id is null when trying to make a database query.”
 }
}
}
{
 "error”: {
"system”: "ReturnController”,
 "reason”: "internal_error”,
 "description”: "Return Request Missing Fields.”,
 "message”: "Return id is null when trying to make a database query.”
 }
}
}

Additional Details:
 • What happens when someone returns an item whereby the original receipt has multiple entries for that one item?
 – This scenario can occur if, during purchase, the client sends in multiple receipt items with the same sku but different prices associated with them.
 – If the purchase was sent in with the same-sku items but different price amounts, the return API will choose the item with the higher point value to deduct from the user during a return.

 • What happens when there are returns without an original receipt?
 – The system will not support this scenario. The client must find the original receipt for the user in order to successfully process the return.

 • Can special fields (e.g. ‘order #’) be stored?
 – The custom_data field allows any field that is sent in to be saved in the CrowdTwist database as long as they were identified to CrowdTwist by the client in advance.