Commerce – Potential Points


Request Details

Item Value
Description CrowdTwist’s Potential Points API allows CrowdTwist clients to calculate the amount of points members could earn for the purchase of items or an entire basket/cart. Potential points are inclusive of base points for purchase, configured by client, as well as eligible and active bonus points campaigns.
Client Use:
• Display potential points earned on ecommerce product pages
• Communicate in-store (via POS or other method) potential points to perspective buyers
• Display potential points earned for total transaction
Method POST
Endpoint https://pos.crowdtwist.com/receipt/points
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


Successful Response – Request Body

Field Name Sample Vaue Required Format Notes
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.
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
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
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.
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
Field Name Sample Value Required Format Description
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

{
  "date_purchased": "2012-04-23T18:25:43.511+00:00",
  "channel_id": 1,
  "currency": "USD",
  "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
    }
  ]
}
{
  "date_purchased": "2012-04-23T18:25:43.511+00:00",
  "channel_id": 1,
  "currency": "USD",
  "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
    }
  ]
}

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.

{
  "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
    }
  ]
}
{
  "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 [“date_purchased"] is missing."
  }
}
{
  "error": {
    "system": "PurchaseController",
    "reason": "missing_data",
    "description": "Missing Data From Request",
    "message": "Required field [“date_purchased"] is missing."
  }
}

Sample Error Response: Status Code 500

{
  "error": {
    "system": "PurchaseController",
    "reason": "internal_error",
    "description": "Unexpected Error.",
    "message": "An unexpected error occurred in the CrowdTwist backend.”
  }
}
{
  "error": {
    "system": "PurchaseController",
    "reason": "internal_error",
    "description": "Unexpected Error.",
    "message": "An unexpected error occurred in the CrowdTwist backend.”
  }
}

Notes on usage of the Potential Points API:

 What if a member applies a coupon or other discount at time of purchase?
  – Potential points are calculated before any dollar off rewards/coupons are taken into consideration (or applied in cart or at POS). The client would prorate these discounts across the items at time of purchase which likely results in a lesser amount of points being awarded. This ensures points are only awarded for actual price paid.

 What if a bonus campaign is running against a category (i.e. Brand)?
  – If a campaign is running on a brand, we will take the “sku” and check to see if it matches the brand for that campaign.

 What happens when a sku matches multiple campaigns?
  – The campaign with the highest multiplier is chosen.

 What happens when the multipliers are the same?
  – The campaign created most recently is chosen.