Commerce – Usable Coupons


Request Details

Item Value
Description This document describes the Usable Coupons endpoint in the REST v2 Users API. This endpoint returns a list of reward coupons which are available for use by a given program member. A coupon is considered usable if it has been assigned to the user through reward redemption, it has not yet itself been redeemed, and its expiration date (if it has one) has not yet passed.

The correct operation of this endpoint depends on the client providing us with the information that a given coupon has been used. Currently this is only possible via the Commerce Purchase API. If we are not told that a coupon has been used, it will continue to show as usable even when it has already been used.

Method GET
Endpoint https://api.crowdtwist.com/v2/users/[userId]/usable_coupons?api_key=[api_key]&id_type=[id_type]


Request

Field Name Sample Value Required Format Notes
URL PARAMETERS      
user_id alice@crowdtwist.com Yes String Unique ID of the user for whom activities will be returned:
Options:
– Email Address
– Facebook User ID
– Twitter User ID
– CrowdTwist ID
– Third Party ID
– Username
QUERY STRING PARAMETERS      
api_key QWERTYUIOP Yes String  
id_type email No String Type of ID being Sent:
Options:
– email
– facebook_user_id
– twitter_user_id
– id (CrowdTwist ID) – default ID if id_type is not specified
– third_party_id
– username


Successful Response

Field Name Sample Value Required Format Description
reward_id     Numeric The ID of the original reward record that was redeemed to receive the coupon
redeem_order_id     Numeric The ID of the redemption order record that resulted in the coupon assignment
redeem_order_coupon_id     Numeric The ID of the redemption order coupon record that resulted in the coupon assignment
total_points_redeemed     Numeric The number of points redeemed in the redemption order that resulted in the coupon assignment
ending_balance     Numeric The program member’s redeemable points balance after the redemption order that resulted in the coupon assignment
quantity     Numeric The quantity from the redemption order that assigned the coupon
code     String[1000] The coupon code
reward_title     String[100] The title of the reward redeemed to receive the coupon, at the time it was redeemed
coupon_category_id     Numeric The ID of the coupon’s category
coupon_category_name     String[50] The name of the coupon’s category at the time the coupon was assigned via reward redemption
coupon_category_expiration_days     Numeric The coupon category’s setting for the number of days after which coupons assigned by it expire (null if expiration is not performed)
batch_num     Numeric The batch number of the coupon (a serial number incrementing each time a batch of coupons is generated)
date_to_expire     Numeric / null If the coupon will expire, the Unix timestamp when it will expire (otherwise null)
order_date_created     Numeric The Unix timestamp of when the reward redemption order that assigned the coupon took place
coupon_date_created     Numeric The Unix timestamp of when the coupon was originally generated (coupons are generated before they’re assigned to a program member via reward redemption)


Error Response

Field Name Sample Value Required Format Description
error param_error Yes String A machine readable code that describes the error.
message Missing the user_id parameter Yes String A short, descriptive sentence detailing the error.


Error Response Codes

Error Message
input_error The input provided in invalid or formatted incorrectly.
internal_error Something went wrong on our end.
page_not_found The requested page does not exist or has been removed.
param_error A missing or invalid parameter is included in the request.
no_activities There are no rewards available to this user.


Sample Request

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


Sample Successful Response: Status Code 200

{
  {
  "reward_id":127819,
  "reward_order_id":28184278,
  "reward_order_coupon_id":17298195,
  "total_points_redeemed":200,
  "ending_balance":22,
  "quantity":1,
  "code":"ACC58191285",
  "reward_title":"$20 Sunshine Rewards Coupon",
  "coupon_category_id":218,
  "coupon_category_name":"Sunshine Rewards",
  "coupon_category_expiration_days":90,
  "batch_num":82,
  "date_to_expire":1479450627,
  "order_date_created":1478820760,
  "coupon_date_created":1478706211
  },
  {
  "reward_id":127817,
  "reward_order_id":28184282,
  "reward_order_coupon_id":17298198,
  "total_points_redeemed":50,
  "ending_balance":37,
  "quantity":1,
  "code":"ACC58111301",
  "reward_title":"$5 Sunshine Rewards Coupon",
  "coupon_category_id":218,
  "coupon_category_name":"Sunshine Rewards",
  "coupon_category_expiration_days":90,
  "batch_num":65,
  "date_to_expire":1479441218,
  "order_date_created":1478823150,
  "coupon_date_created":1478721025
  }
}
{
	{
	"reward_id":127819,
	"reward_order_id":28184278,
	"reward_order_coupon_id":17298195,
	"total_points_redeemed":200,
	"ending_balance":22,
	"quantity":1,
	"code":"ACC58191285",
	"reward_title":"$20 Sunshine Rewards Coupon",
	"coupon_category_id":218,
	"coupon_category_name":"Sunshine Rewards",
	"coupon_category_expiration_days":90,
	"batch_num":82,
	"date_to_expire":1479450627,
	"order_date_created":1478820760,
	"coupon_date_created":1478706211
	},
	{
	"reward_id":127817,
	"reward_order_id":28184282,
	"reward_order_coupon_id":17298198,
	"total_points_redeemed":50,
	"ending_balance":37,
	"quantity":1,
	"code":"ACC58111301",
	"reward_title":"$5 Sunshine Rewards Coupon",
	"coupon_category_id":218,
	"coupon_category_name":"Sunshine Rewards",
	"coupon_category_expiration_days":90,
	"batch_num":65,
	"date_to_expire":1479441218,
	"order_date_created":1478823150,
	"coupon_date_created":1478721025
	}
}

Sample Error Response: Status Code 400

{
   "error": "page_not_found",
   "message": "User does not exist."
}
{
	 "error": "page_not_found",
	 "message": "User does not exist."
}