Retrieve Earned Reward

Action: GET
Endpoint: /rewards/{user_token}/earned/{token}

To retrieve an earned reward for a user, send a GET request to the /rewards/{user_token}/earned/{token} endpoint. Include the reward token and the user_token as path parameters to identify the reward and the user.

URL Path Parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user who owns the earned reward. Existing user token.

Issue a GET to /users to retrieve user tokens.
token string Yes Identifies the earned reward. Existing earned reward token.

Issue a GET to /rewards/{user_token}/earned to retrieve earned reward tokens for a user.

Response Body Field Details

Name Type Description
purchases array An array of purchases that led to the reward.
excess_from_token string The amount in excess of the reward threshold.
burn_reference_token string The unique identifier of the instance of reward expenditure.
created_time string The date and time of the transaction.
deleted_time string The date and time of reward deletion.
transaction_token string The unique identifier of the transaction.
reward_program object Defines the characteristics of the campaign.
memo string Additional descriptive text.
reward object Defines the characteristics of the reward.
tags string Metadata about the reward program.
token string Unique identifier of the reward.
status Possible values are: UNKNOWN | PENDING | SETTLED | REVERSED | CANCELLED | DECLINED

purchases

Name Type Description
token string The unique identifier of the earn condition.
amount decimal The purchase amount.
status The possible values are: UNKNOWN | PENDING | SETTLED | REVERSED | CANCELLED | DECLINED
created_time string The date and time of the transaction.
transaction_token string The unique identifier of the transaction.
excess_from_token string The amount in excess of the reward threshold.
expiration_time string The date and time the reward expires.

reward_program

Name Type Description
created_time string The date and time of the transaction.
token string Unique identifier of the reward program or campaign.
last_modified_time string The date and time of the last modification to the reward program or campaign.
start_date string The date and time the reward program or campaign is scheduled to take effect.
end_date string The date and time the reward program or campaign is scheduled to become inactive.
active boolean Indicates whether the reward program is active or not.
reward object Defines the characteristics of the reward.
earn_conditions array Defines the conditions under which rewards can be earned.
burn_conditions array Defines the conditions under which rewards can be spent.
tags string Metadata about the reward program.
name string The name of the reward program.
actions array Defines the action or event to occur when earn or burn conditions are met.
priority integer Determines the priority of the reward conditions when multiple rewards conditions exist.

reward_program.earn_conditions

Name Type Description
name string The name ascribed to a specific set of reward-earning conditions. Possible values are: PURCHASE_THRESHOLD | PURCHASE_STACK | BASE_REWARD | REWARD_EXPIRATION_TIME | PURCHASE_EXPIRATION_TIME
argument object Defines the parameters under which the earn conditions are met.

reward_program.argument

Name Type Description
constraint Defines a monetary threshold for reward earning or burning eligibility. The possible values are: MIN | MAX | EQUAL
value string The value attributed to the defined constraint.
descriptor The value descriptor. The possible values are: CENTS_PER_GALLON | CASH_AMOUNT | TRANSACTION_EVENT | BOOLEAN | GALLONS | NUMBER | DAYS | MONTHS | END_OF_MONTH | PERCENT

reward_program.burn_conditions

Name Type Description
name string The name ascribed to a specific set of reward-burning conditions. The possible values are: PURCHASE_THRESHOLD | REWARD_ROLLOVER | NUM_PURCHASES | EXCESS_DISCOUNT | REWARD_THRESHOLD
argument object Defines the parameters under which the earn conditions are met.

reward_program.actions

Name Type Description
name string The name of the event that is to occur when earn or burn conditions are met.
argument object Defines the parameters under which the earn conditions are met.

reward

Name Type Description
value decimal The reward amount.
descriptor string The type of reward applied.

Sample Response Body

{
"purchases": [
{
"token": "",
"amount": "decimal",
"status": "TransactionStatus",
"created_time": "",
"transaction_token": "",
"excess_from_token": "",
"expiration_time": ""
}
],
"excess_from_token": "",
"burn_reference_token": "",
"expiration_time": "",
"created_time": "",
"deleted_time": "",
"transaction_token": "",
"reward_program": {
"created_time": "",
"token": "",
"last_modified_time": "",
"start_date": "",
"end_date": "",
"active": false,
"reward": {
"value": "",
"descriptor": ""
},
"earn_conditions": [
{
"name": "",
"argument": {
"constraint": "argument_constraint",
"value": "",
"descriptor": "value_descriptor"
}
}
],
"burn_conditions": [
{
"name": "",
"argument": {
"constraint": "argument_constraint",
"value": "",
"descriptor": "value_descriptor"
}
}
],
"tags": "",
"name": "",
"actions": [
{
"name": "",
"argument": {
"constraint": "argument_constraint",
"value": "",
"descriptor": "value_descriptor"
}
}
],
"priority": 0
},
"memo": "",
"reward": {
"value": "",
"descriptor": ""
},
"tags": "",
"token": "",
"status": "TransactionStatus"
}


List All Earned Rewards

Action: GET
Endpoint: /rewards/{user_token}/earned

To list all earned rewards for a user, send a GET request to the /rewards/{user_token}/earned endpoint. Include the user_token as a path parameter to identify the user.

This endpoint supports field filtering and pagination.

URL Path Parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user who owns the earned rewards. Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample Response Body

{
"count" : 1,
"start_index" : 0,
"end_index" : 0,
"is_more" : false,
"data" : [ {
"token" : "my_gas_reward",
"reward" : {
"value" : "0.10",
"descriptor" : "CENTS_PER_GALLON"
},
"status" : "SETTLED",
"purchases" : [ {
"token" : 1820,
"amount" : 50.00,
"status" : "SETTLED",
"transaction_token" : 24648,
"expiration_time" : "2015-07-18T23:59:59Z",
"created_time" : "2015-06-18T21:18:59Z"
} ],
"transaction_token" : 24648,
"created_time" : "2015-06-18T21:18:59Z",
"reward_program" : {
"type" : "CAMPAIGN",
"name" : "my_campaign",
"priority" : 0,
"active" : true,
"reward" : {
"value" : "0.10",
"descriptor" : "CENTS_PER_GALLON"
},
"actions" : [ {
"name" : "EarnRewardAction",
"argument" : {
"value" : "AUTH,CLEAR,SALE",
"descriptor" : "TRANSACTION_EVENT"
}
} ],
"token" : "my_cashback_reward",
"earn_conditions" : [ {
"name" : "PURCHASE_THRESHOLD",
"argument" : {
"value" : "50.00",
"descriptor" : "CASH_AMOUNT"
}
}, {
"name" : "REWARD_EXPIRATION_TIME",
"argument" : {
"value" : "30",
"descriptor" : "DAYS"
}
}, {
"name" : "PURCHASE_EXPIRATION_TIME",
"argument" : {
"value" : "30",
"descriptor" : "DAYS"
}
} ],
"burn_conditions" : [ {
"name" : "PURCHASE_THRESHOLD",
"argument" : {
"value" : "20",
"descriptor" : "GALLONS",
"constraint" : "MAX"
}
} ],
"created_time" : "2015-02-11T01:48:54Z",
"last_modified_time" : "2015-02-24T23:22:04Z",
"campaign" : {
"active" : true,
"name" : "my_campaign",
"token" : "my_campaign_token",
"start_date" : "2014-11-21",
"end_date" : "2043-11-21"
}
},
"burn_reference_token" : "my_burn_reference_token",
"expiration_time" : "2015-07-18T23:59:59Z"
} ]
}


Retrieve Burned Reward

Action: GET
Endpoint: /rewards/{user_token}/burned/{token}

To retrieve a burned reward for a user, send a GET request to the /rewards/{user_token}/burned/{token} endpoint. Include the reward token and the user_token as path parameters to identify the reward and the user.

This endpoint supports field filtering.

URL Path Parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user who owns the burned reward. Existing user token.

Issue a GET to /users to retrieve user tokens.
token string Yes Identifies the burned reward to retrieve. Existing burned reward token.

Issue a GET to /rewards/{user_token}/burned to retrieve burned reward tokens for a user.

Sample Response Body

{
"token" : "my_gas_reward_token",
"reward" : {
"value" : "0.40",
"descriptor" : "CENTS_PER_GALLON"
},
"status" : "SETTLED",
"transaction_token" : 24640,
"created_time" : "2015-06-18T21:18:44Z",
"reward_program" : {
"type" : "CAMPAIGN",
"name" : "my_campaign",
"priority" : 1,
"active" : true,
"reward" : {
"value" : "0.35",
"descriptor" : "CENTS_PER_GALLON"
},
"actions" : [ {
"name" : "BurnRewardAction",
"argument" : {
"value" : "AUTH,CAPTURE,CLEAR,SALE",
"descriptor" : "TRANSACTION_EVENT"
}
} ],
"token" : "my_base_reward_token",
"earn_conditions" : [ {
"name" : "BASE_REWARD",
"argument" : {
"value" : "true",
"descriptor" : "BOOLEAN"
}
} ],
"burn_conditions" : [ {
"name" : "PURCHASE_THRESHOLD",
"argument" : {
"value" : "20",
"descriptor" : "GALLONS",
"constraint" : "MAX"
}
}, {
"name" : "NUM_PURCHASES",
"argument" : {
"value" : "0",
"descriptor" : "NUMBER",
"constraint" : "EQUAL"
}
}, {
"name" : "EXCESS_DISCOUNT",
"argument" : {
"value" : "0.05",
"descriptor" : "CENTS_PER_GALLON"
}
} ],
"created_time" : "2015-02-11T00:18:17Z",
"last_modified_time" : "2015-02-24T19:37:40Z",
"campaign" : {
"active" : true,
"name" : "my_campaign",
"token" : "my_campaign_token",
"start_date" : "2014-11-21",
"end_date" : "2043-11-21"
}
},
"burned_rewards" : [ ]
}


List All Burned Rewards

Action: GET
Endpoint: /rewards/{user_token}/burned

To list all burned rewards for a user, send a GET request to the /rewards/{user_token}/burned endpoint. Include the user_token as a path parameter to identify the user.

This endpoint supports field filtering and pagination.

URL Path Parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user who owns the burned rewards. Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample Response Body

{
"count" : 2,
"start_index" : 0,
"end_index" : 1,
"is_more" : false,
"data" : [ {
"token" : "my_gas_reward_token",
"reward" : {
"value" : "0.05",
"descriptor" : "CENTS_PER_GALLON"
},
"status" : "SETTLED",
"transaction_token" : 24643,
"created_time" : "2015-06-18T21:18:50Z",
"reward_program" : {
"type" : "CAMPAIGN",
"name" : "Marqeta QA Clover Reward 1",
"priority" : 0,
"active" : true,
"reward" : {
"value" : "0.05",
"descriptor" : "CENTS_PER_GALLON"
},
"actions" : [ {
"name" : "BurnRewardAction",
"argument" : {
"value" : "AUTH,CAPTURE,CLEAR,SALE",
"descriptor" : "TRANSACTION_EVENT"
}
} ],
"token" : "my_base_reward_token",
"earn_conditions" : [ {
"name" : "BASE_REWARD",
"argument" : {
"value" : "true",
"descriptor" : "BOOLEAN"
}
} ],
"created_time" : "2015-02-09T23:12:37Z",
"last_modified_time" : "2015-02-09T23:12:37Z",
"campaign" : {
"active" : true,
"name" : "my_campaign",
"token" : "my_campaign_token",
"start_date" : "2014-11-21",
"end_date" : "2043-11-21"
}
},
"burned_rewards" : [ ]
}, {
"token" : "my_gas_reward_token",
"reward" : {
"value" : "0.40",
"descriptor" : "CENTS_PER_GALLON"
},
"status" : "SETTLED",
"transaction_token" : 24640,
"created_time" : "2015-06-18T21:18:44Z",
"reward_program" : {
"type" : "CAMPAIGN",
"name" : "my_campaign",
"priority" : 1,
"active" : true,
"reward" : {
"value" : "0.35",
"descriptor" : "CENTS_PER_GALLON"
},
"actions" : [ {
"name" : "BurnRewardAction",
"argument" : {
"value" : "AUTH,CAPTURE,CLEAR,SALE",
"descriptor" : "TRANSACTION_EVENT"
}
} ],
"token" : "my_base_reward",
"earn_conditions" : [ {
"name" : "BASE_REWARD",
"argument" : {
"value" : "true",
"descriptor" : "BOOLEAN"
}
} ],
"burn_conditions" : [ {
"name" : "PURCHASE_THRESHOLD",
"argument" : {
"value" : "20",
"descriptor" : "GALLONS",
"constraint" : "MAX"
}
}, {
"name" : "NUM_PURCHASES",
"argument" : {
"value" : "0",
"descriptor" : "NUMBER",
"constraint" : "EQUAL"
}
}, {
"name" : "EXCESS_DISCOUNT",
"argument" : {
"value" : "0.05",
"descriptor" : "CENTS_PER_GALLON"
}
} ],
"created_time" : "2015-02-11T00:18:17Z",
"last_modified_time" : "2015-02-24T19:37:40Z",
"campaign" : {
"active" : true,
"name" : "my_campaign",
"token" : "my_campaign_token",
"start_date" : "2014-11-21",
"end_date" : "2043-11-21"
}
},
"burned_rewards" : [ ]
} ]
}


List Pending Rewards

Action: GET
Endpoint: /rewards/{user_token}/pending

To list all pending rewards for a user, send a GET request to the /rewards/{user_token}/pending endpoint. Include the user_token as a path parameter to identify the user.

This endpoint supports field filtering and pagination.

URL Path Parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user who owns the pending rewards. Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample Response Body

{
"purchases": [
{
"token": 51,
"amount": "10.00",
"status": "SETTLED",
"created_time": "2015-02-24T01:08:27Z",
"transaction_token": 14,
"excess_from_token": 12,
"expiration_time": "2015-08-24T06:59:59Z"
}
],
"excess_from_token": "12",
"burn_reference_token": "my_burn_reference_token",
"expiration_time": "2015-08-24T06:59:59Z",
"created_time": "2015-02-24T01:08:27Z",
"transaction_token": 10,
"reward_program": {
"created_time": "2015-02-24T01:08:27Z",
"last_modified_time": "2015-02-24T01:08:09Z",
"token": "10",
"active": false,
"start_date": "2013-11-20",
"end_date": "2043-11-20",
"reward": {
"value": "0.10",
"descriptor": "CENTS_PER_GALLON"
},
"earn_conditions": [
{
"name": "PURCHASE_THRESHOLD",
"argument": {
"value": "75.00",
"descriptor": "CASH_AMOUNT"
}
}
],
"burn_conditions": [
{
"name": "PURCHASE_THRESHOLD",
"argument": {
"value": "20",
"descriptor": "GALLONS"
}
}
],
"name": "BurnRewardAction",
"actions": [
{
"name": "PURCHASE_EXPIRATION_TIME",
"argument": {
"value": "30",
"descriptor": "DAYS"
}
}
],
"priority": 0,
"tags": ""
},
"transaction_token": 84,
"reward": {
"value": "0.10",
"descriptor": "CENTS_PER_GALLON"
},
"status": "SETTLED",
"token": "45"
}


Retrieve Rewards Summary

Action: GET
Endpoint: /rewards/{user_token}/summary

To retrieve the rewards summary for a user, send a GET request to the /rewards/{user_token}/summary endpoint. Include the user_token as a path parameter to identify the user.

This endpoint supports field filtering.

URL Path Parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user whose reward summary you want to retrieve. Existing user token.

Issue a GET to /users to retrieve user tokens.

Sample Response Body

{
"reward_programs": [
{
"reward_program": {
"type": "CAMPAIGN",
"name": "my_campaign",
"priority": 0,
"active": true,
"reward": {
"value": "0.05",
"descriptor": "CENTS_PER_GALLON"
},
"actions": [
{
"name": "BurnRewardAction",
"argument": {
"value": "AUTH,CAPTURE,CLEAR,SALE",
"descriptor": "TRANSACTION_EVENT"
}
}
],
"token": "my_base_reward",
"earn_conditions": [
{
"name": "BASE_REWARD",
"argument": {
"value": "true",
"descriptor": "BOOLEAN"
}
}
],
"created_time": "2015-02-09T23:12:37Z",
"last_modified_time": "2015-02-09T23:12:37Z",
"campaign": {
"active": true,
"name": "my_campaign",
"token": "my_campaign_token",
"start_date": "2014-11-21",
"end_date": "2043-11-21"
}
}
},
{
"reward_program": {
"type": "CAMPAIGN",
"name": "my_campaign",
"priority": 0,
"active": true,
"reward": {
"value": "0.10",
"descriptor": "CENTS_PER_GALLON"
},
"actions": [
{
"name": "EarnRewardAction",
"argument": {
"value": "AUTH,CLEAR,SALE",
"descriptor": "TRANSACTION_EVENT"
}
}
],
"token": "my_cashback_reward",
"earn_conditions": [
{
"name": "PURCHASE_THRESHOLD",
"argument": {
"value": "50.00",
"descriptor": "CASH_AMOUNT"
}
},
{
"name": "REWARD_EXPIRATION_TIME",
"argument": {
"value": "30",
"descriptor": "DAYS"
}
},
{
"name": "PURCHASE_EXPIRATION_TIME",
"argument": {
"value": "30",
"descriptor": "DAYS"
}
}
],
"burn_conditions": [
{
"name": "PURCHASE_THRESHOLD",
"argument": {
"value": "20",
"descriptor": "GALLONS",
"constraint": "MAX"
}
}
],
"created_time": "2015-02-11T01:48:54Z",
"last_modified_time": "2015-02-24T23:22:04Z",
"campaign": {
"active": true,
"name": "my_campaign",
"token": "my_campaign_token",
"start_date": "2014-11-21",
"end_date": "2043-11-21"
}
}
}
]
}