Commerce – Purchase


Request Details

Item Value
Description The purchase API is used to send purchase data to the CrowdTwist system. To send purchase data, you must perform an HTTP POST request with a JSON object.

The purchase API awards points for purchase.

Method POST
Endpoint https://pos.crowdtwist.com/purchase
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 Sample Vaue Required Format Notes
receipt_id receipt123 Yes String For each purchase transaction, this should be the id on the receipt. This must be a unique identifier of this request
order_id order123 No String This is for clients to capture multiple receipts (or transactions) under one order number. This won’t be used for any validation or calculations, but is only stored for reporting purposes.
user_id 47111810 No Number CrowdTwist user ID. If empty, we will store the receipt in the database. If found, we will try to award the user points.
user_attributes
{
  "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"
}
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.
total 119.64 Yes Decimal This field is only recorded and is not used for any calculations.
subtotal 110.78 No Decimal This field is only recorded and is not used for any calculations.
date_purchased 2012-04-23T18:25:43.511z Yes String The date the item is purchased. This date must be an ISO-8601 compliant date field with offset appended to it.
custom_data
{
  "store_loc": "store1",
  "register_id": "register1",
  "cashier_id": "cashier1",
  "employee_id": "employee_123"
}
{
  "store_loc": "store1",
  "register_id": "register1",
  "cashier_id": "cashier1",
  "employee_id": "employee_123"
}
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.
is_awaiting_fulfillment true No Boolean Used to indicate an item that is awaiting fulfillment.
tenders
[
  {
    "type": 1,
    "amount": 20
  },
  {
    "type": 2,
    "amount": 4.44
  }
]
[
  {
    "type": 1,
    "amount": 20
  },
  {
    "type": 2,
    "amount": 4.44
  }
]
No Array Tender types used for this transaction. If none are provided, then no multipliers will be given for tender.
1 = Cash
2 = Personal Check
3 = Traveler’s Check
4 = Major Credit (MC, Visa, Disc, AmEx)
5 = Gift Cards
6 = PIN Debit
7 = PLCC
8 = Vouchers
9 = Virtual Gift Card
10 = MCR – Merchandise Credit Receipt
11 = Other
12 = Mobile Payment
13 = PayPal
14 = Amazon Pay
channel_id 1 No Integer The channel this purchase was made through. If none provided, no multipliers will be applied to the channel type.
1 = In Store
2 = Online
3 = Kiosk / In Store Other
4 = Call Center
5 = Mobile App
6 = Other
7 = Receipt Scan
8 = Affiliate
9 = Outlet
coupons coupon123456 No String The coupons used in this purchase. This is the list of coupons that are used in this transaction. This field invalidates the coupons used from future use. No coupon dollar amounts are factored into the calculations of bonus points or the total of the transaction.
currency USD This is the currency of all the amounts and prices included in this API. If no currency is provided the default is ‘USD. Additional details
ITEMS ARRAY
sku sku1 Yes String This is the universal id around an item. This will be the main way to identify a particular item during a purchase, bonus campaigns, product catalogs, and other item-level actions.
price 21.22 Yes Decimal The price of the item, quantity included. This is the value used to calculate points awarded. Any dollar off rewards/coupons will need to be prorated across the items in the order and deducted from the item price; reflecting the actual dollar amount used to purchase the item.

Total price for the full quantity of items. For example – for purchasing 2 of an item that costs $25, the price is $50 and the quantity is 2.

"items": [
    {
      "sku": "sku001",
      "price": 50,
      "quantity": 2
    }
  ],
"items": [
    {
      "sku": "sku001",
      "price": 50,
      "quantity": 2
    }
  ],
quantity 2 Yes Integer This is the number of items included in this item JSON object.
transaction_id 2 No Integer Transaction type used on an item. If transaction_id is not provided, then no multipliers or exemptions will be given for transaction types. Any item with a transaction_id associated with a 0x multiplier will not award points.
1 = Sale
2 = Tax Exempt Sale
3 = Employee Sale
4 = Payment on Account
5 = Stamp Sales
6 = Tender Exchange
7 = Gift Card Cash-Out
8 = MCR Cash-Out
9 = Corp Check Insurance
10 = Misc Income
11 = Pride Gift Card Issue
12 = Pride Purchase
13 = Non eligible item
custom_data 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.


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 – Request Body

Field Name Sample Value Required Format Description
receipt_id 15 Yes String The id of the receipt record found in CrowdTwist’s system that correlates to the sent in “receipt_id” in the request.
user_id 12 Yes String The id of the user record found in CrowdTwist’s system that correlates to the sent in CrowdTwist user id or to the sent in third party member identifying attributes within the user attributes object in the request.
total_points_awarded 624 Yes Array The total number of points awarded for the entire purchase transaction.
breakdown Yes Arry The SKUs broken down by singular quantity and the points calculated for each singular quantity item.
BREAKDOWN ARRAY
sku SKU_1 String The sku identifier that is the universal, unique identifier of the item.
is_awaiting_fulfillment true Boolean Used to indicate an item that is awaiting fulfillment.
quantity hi Integer The number of items this item breakdown is for. Always singular.
item_price 26.11 Decimal The price of the item. Used to calculate the points received for the purchase for the singular item.
points_to_dollar_conversion_rate 2 Integer The conversion rate from dollar to points. This is configurable by the client.
campaign JSON Object Present if and only if the item is associated with a bonus campaign. See Campaign Level below.
transaction JSON Object Present if a transaction_id was sent in with the request. If a transaction_id is present, the response will display what transaction type it is and the multiplier associated with it. See Transaction Level below.
tenders Array Shows the tenders used in this particular transaction. If no tenders are provided, then this array will not appear in the response. See Tender Level below.
channel JSON Object Shows the channel by which this item was purchased. If no channel_id is sent in with the request, then this will not appear. See Channel Level below.
points_awarded 312 Yes Integer The total number of points awarded for this item.
is_excluded Yes Boolean If true, this item is excluded from receiving any points. This will only happen when a SKU is added to an exclusion list, and no points for that sku will ever be awarded while on the exclusion list.
CAMPAIGN ARRAY
title BONUS CAMPAIGN Yes String Title of the bonus campaign this item is a part of.
multiplier 2 Yes Integer Multiplier for any item in this bonus campaign.
TRANSACTION ARRAY
name MCR Cash-out Yes String Name of the transaction type for this item.
multiplier 1 Yes Integer Multiplier associated to this transaction type.
TENDER ARRAY
name Vouchers 100 String Name of the tender type for this item.
multiplier 1 Yes Integer Multiplier associated to this tender type.
CHANNEL ARRAY
name In Store 100 String Name of the channel this item was purchased.
multiplier 1 Yes Integer TMultiplier associated with this channel.


Error Response

Field Name Sample Value Required Format Description
system PurchaseController Yes String Domain where the error occurred.
reason 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.
description Return Request Missing Fields Yes String This is a short form description of the error.
message Return id is null when trying to make a database query.” 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


Sample Request

{
  "receipt_id": "receipt123",
  "order_id": "order123",
  "user_id": 47111810,
  "total": 119.64,
  "subtotal": 110.78,
  "date_purchased": "2012-04-23T18:25:43.511+00:00",
  "channel_id": 1,
  "currency": "USD",
  "custom_data": {
    "store_loc": "store1",
    "register_id": "register1",
    "cashier_id": "cashier1",
    "employee_id": "employee_123"
  },
  "items": [
    {
      "sku": "sku_1",
      "price": 21.22,
      "quantity": 2,
      "transaction_id": 2,
      "custom_data": {
        "color": "blue",
        "size": "Medium"
      }
    },
    {
      "sku": "sku_2",
      "price": 3.22,
      "quantity": 1,
      "transaction_id": 1,
      "custom_data": {
        "color": "blue",
        "size": "Medium"
      }
    }
  ],
  "tenders": [
    {
      "type": 1,
      "amount": 20
    },
    {
      "type": 2,
      "amount": 4.44
    }
  ],
  "coupons": [
    "coupon123456",
    "coupon123789"
  ]
}
{
  "receipt_id": "receipt123",
  "order_id": "order123",
  "user_id": 47111810,
  "total": 119.64,
  "subtotal": 110.78,
  "date_purchased": "2012-04-23T18:25:43.511+00:00",
  "channel_id": 1,
  "currency": "USD",
  "custom_data": {
    "store_loc": "store1",
    "register_id": "register1",
    "cashier_id": "cashier1",
    "employee_id": "employee_123"
  },
  "items": [
    {
      "sku": "sku_1",
      "price": 21.22,
      "quantity": 2,
      "transaction_id": 2,
      "custom_data": {
        "color": "blue",
        "size": "Medium"
      }
    },
    {
      "sku": "sku_2",
      "price": 3.22,
      "quantity": 1,
      "transaction_id": 1,
      "custom_data": {
        "color": "blue",
        "size": "Medium"
      }
    }
  ],
  "tenders": [
    {
      "type": 1,
      "amount": 20
    },
    {
      "type": 2,
      "amount": 4.44
    }
  ],
  "coupons": [
    "coupon123456",
    "coupon123789"
  ]
}

Sample Successful Response: Status Code 200
Whenever the request is successfully processed, a 200 HTTP status code will be returned. It is worthy to note that the returned “user_id” and “receipt_id” reflect the receipt and user records that are in the CrowdTwist system.

The breakdown returned details how the point total was calculated for each item on a single quantity basis.

{
  "receipt_id": 15,
  "user_id": 12,
  "total_points_awarded": 624,
  "breakdown": [
    {
      "sku": "SKU_1",
      "is_awaiting_fulfillment": true,
      "quantity": 1,
      "item_price": 26.11,
      "points_to_dollar_conversion_rate": 2,
      "converted_points": 52,
      "is_excluded": false,
      "campaigns": [
        {
          "type": "SKU",
          "title": "BONUS CAMPAIGN",
          "multiplier": 2
        },
        {
          "type": "DAY-TIME",
          "title": "TUESDAY MORNING SPECIAL",
          "multiplier": 1
        }
      ],
      "transaction": {
        "name": "MCR Cash-out",
        "multiplier": 1
      },
      "tenders": [
        {
          "name": "Vouchers",
          "proportion": 0.3333333333333333,
          "multiplier": 1
        },
        {
          "name": "PLCC",
          "proportion": 0.6666666666666666,
          "multiplier": 4
        }
      ],
      "channel": {
        "name": "In Store",
        "multiplier": 1
      },
      "points_awarded": 312
    },
    {
      "sku": "SKU_1",
      "quantity": 1,
      "item_price": 26.11,
      "points_to_dollar_conversion_rate": 2,
      "converted_points": 52,
      "is_excluded": false,
      "campaigns": [
        {
          "type": "SKU",
          "title": "BONUS CAMPAIGN",
          "multiplier": 2
        },
        {
          "type": "DAY-TIME",
          "title": "TUESDAY MORNING SPECIAL",
          "multiplier": 1
        }
      ],
      "transaction": {
        "name": "MCR Cash-out",
        "multiplier": 1
      },
      "tenders": [
        {
          "name": "Vouchers",
          "proportion": 0.3333333333333333,
          "multiplier": 1
        },
        {
          "name": "PLCC",
          "proportion": 0.6666666666666666,
          "multiplier": 4
        }
      ],
      "channel": {
        "name": "In Store",
        "multiplier": 1
      },
      "points_awarded": 312
    }
  ]
}
{
  "receipt_id": 15,
  "user_id": 12,
  "total_points_awarded": 624,
  "breakdown": [
    {
      "sku": "SKU_1",
      "is_awaiting_fulfillment": true,
      "quantity": 1,
      "item_price": 26.11,
      "points_to_dollar_conversion_rate": 2,
      "converted_points": 52,
      "is_excluded": false,
      "campaigns": [
        {
          "type": "SKU",
          "title": "BONUS CAMPAIGN",
          "multiplier": 2
        },
        {
          "type": "DAY-TIME",
          "title": "TUESDAY MORNING SPECIAL",
          "multiplier": 1
        }
      ],
      "transaction": {
        "name": "MCR Cash-out",
        "multiplier": 1
      },
      "tenders": [
        {
          "name": "Vouchers",
          "proportion": 0.3333333333333333,
          "multiplier": 1
        },
        {
          "name": "PLCC",
          "proportion": 0.6666666666666666,
          "multiplier": 4
        }
      ],
      "channel": {
        "name": "In Store",
        "multiplier": 1
      },
      "points_awarded": 312
    },
    {
      "sku": "SKU_1",
      "quantity": 1,
      "item_price": 26.11,
      "points_to_dollar_conversion_rate": 2,
      "converted_points": 52,
      "is_excluded": false,
      "campaigns": [
        {
          "type": "SKU",
          "title": "BONUS CAMPAIGN",
          "multiplier": 2
        },
        {
          "type": "DAY-TIME",
          "title": "TUESDAY MORNING SPECIAL",
          "multiplier": 1
        }
      ],
      "transaction": {
        "name": "MCR Cash-out",
        "multiplier": 1
      },
      "tenders": [
        {
          "name": "Vouchers",
          "proportion": 0.3333333333333333,
          "multiplier": 1
        },
        {
          "name": "PLCC",
          "proportion": 0.6666666666666666,
          "multiplier": 4
        }
      ],
      "channel": {
        "name": "In Store",
        "multiplier": 1
      },
      "points_awarded": 312
    }
  ]
}

Sample Error Response: Status Code 400

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

Sample Error Response: Status Code 500

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