Schema Objects
Earned Reward
The EarnedReward object represents the calculated reward details for a single transaction.
JSON Schema
{
"transactionId": "67890",
"transactionAmount": 250.75,
"transactionDate": "2023-10-02",
"merchant": "Walmart",
"cardName": "American Express Blue Cash EveryDay",
"rewardValue": 0.01,
"rewardMultiplier": 1,
"rewardAmount": 2.5075
}Fields
| Field | Type | Description |
| transactionId | string | Unique identifier/reference for the transaction. |
| transactionAmount | number | Dollar amount spent in the transaction. |
| transactionDate | string | Date of the transaction (format: YYYY-MM-DD). |
| merchant | string | Name of the merchant or store. |
| cardName | string | Name of the credit card used for the purchase. |
| rewardValue | number | Monetary value (in USD) per reward point/mile for this card. |
| rewardMultiplier | number | Multiplier based on how the purchase category aligns with the card’s program. |
| rewardAmount | number | Total dollar value of the reward earned for this transaction. |
Example
{
"transactionId": "67890",
"transactionAmount": 250.75,
"transactionDate": "2023-10-02",
"merchant": "Walmart",
"cardName": "American Express Blue Cash EveryDay",
"rewardValue": 0.01,
"rewardMultiplier": 1,
"rewardAmount": 2.5075
}EarnedRewardsResponse
The response wrapper for Reward calculation requests.
{
"data": {
"earnedRewards": [
{ /* EarnedReward object */ }
],
"totalEarnedReward": 3.814
},
"message": "Success"
}
| Field | Type | Description |
| data.earnedRewards | array | Array of EarnedReward |
| data.totalEarnedReward | number | Total rewards earned across all listed transactions |
| message | string | Human-readable status or info message |
MissedReward
Represents the missed reward opportunity for a specific card for a given transaction.
{
"cardId": 43,
"cardName": "Capital One QuickSilver",
"transactionId": "12345",
"rewardValue": 0.01,
"rewardMultiplier": 1.5,
"missedReward": 0.201
}
| Field | Type | Description |
| cardId | integer | Uthrive-internal numeric ID for the card |
| cardName | string | Name of the card |
| transactionId | string | Related transaction |
| rewardValue | number | Dollar value per point/mile on this card |
| rewardMultiplier | number | Card’s multiplier for category/merchant |
| missedReward | number | Missed dollar value if this card had been used |
MissedRewardDetail
Per-transaction analysis of missed rewards and the best alternative card scenario.
{
"transactionId": "12345",
"transactionAmount": 100.5,
"transactionDate": "2023-10-01",
"merchant": "Amazon",
"cardName": "Chase Sapphire Preferred",
"rewardAmount": 1.3065,
"missedRewardYourCards": [ /* array of MissedReward */ ],
"missedRewardNewCards": [ /* array of MissedReward */ ],
"bestCard": { /* MissedReward object */ }
}
| Field | Type | Description |
| transactionId | string | Associated transaction ID |
| transactionAmount | number | Amount spent |
| transactionDate | string | Date of the transaction |
| merchant | string | Merchant name |
| cardName | string | Card used for original purchase |
| rewardAmount | number | Rewards earned with the actual card used |
| missedRewardYourCards | array | Missed rewards with other cards user owns |
| missedRewardNewCards | array | Missed rewards with alternative/new cards |
| bestCard | object (MissedReward) | Card with maximum possible reward for this transaction |
MissedRewardResponse
Response wrapper for /reward/missed.
{
"data": {
"missedRewards": [ /* array of MissedRewardDetail */ ],
"overallMissedRewardsExisting": 1.45475,
"overallMissedRewardsNew": 3.211
},
"message": "Success"
}| Field | Type | Description |
| data.missedRewards | array | Array of MissedRewardDetail |
| data.overallMissedRewardsExisting | number | Total missed value with cards you own |
| data.overallMissedRewardsNew | number | Total missed value if you had all recommended cards |
| message | string | Human-readable status message |
AdviceInput
Input for /recommend/advice.
{
"merchant": "Amazon",
"yourCards": [
"American Express Platinum",
"Chase Sapphire Preferred"
],
"spendAmount": 300
}| Field | Type | Description |
| merchant | string | Target merchant |
| yourCards | array | Cards the user currently owns |
| spendAmount | number | Intended spend in US dollars |
CardReward
Reward information for a given card under a given scenario.
{
"cardName": "Chase Sapphire Preferred",
"rewardValue": 0.013,
"rewardMultiplier": 1,
"rewardAmount": 3.9,
"bonus": 0.013
}| Field | Type | Description |
| cardName | string | Name of the card |
| rewardValue | number | $ value per point/mile |
| rewardMultiplier | number | Category/merchant multiplier |
| rewardAmount | number | Total estimated reward for the spend |
| bonus | number | Bonus value, if applicable |
RewardInfo
Returned in data for card advice.
{
"bestCard": { /* CardReward */ },
"otherCards": [ /* array of CardReward */ ]
}| Field | Type | Description |
| bestCard | object | The best card for this scenario |
| otherCards | array | Alternative cards in the wallet |
AdviceResponse
Response for /recommend/advice.
{
"data": {
"bestCard": { /* CardReward object */ },
"otherCards": [ /* CardReward objects */ ]
},
"message": "Success"
}| Field | Type | Description |
| data | object | RewardInfo object |
| message | string | Status or informational message |
