Note
This feature is currently in beta and subject to change. To learn more about the Beta program for this feature, contact your Marqeta representative.
This feature is currently in beta and subject to change. To learn more about the Beta program for this feature, contact your Marqeta representative.
/credit/rewards/accounts/{token} endpoint to manage reward accounts and track rewards balances, accruals, and entries on a credit account. The configurations for a reward account are defined in the reward policy on the account’s associated bundle. To receive webhook notifications when reward accounts and reward entry events occur, see Credit reward entry events in Event Types.
List reward accounts
Action:GETEndpoint:
/credit/rewards/accounts
Retrieve a list of reward accounts.
URL query parameters
| Fields | Description |
|---|---|
| credit_account_token string Optional | Unique identifier of the credit account for which you want to retrieve reward accounts. Allowable Values: Existing credit account token |
| is_active boolean Optional | A value of true returns active resources. A value of false returns inactive resources.Allowable Values: true, false |
| count integer Optional | Number of resources to retrieve. Allowable Values: 1–100 |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: 0 min |
| sort_by_updated string Optional | Field on which to sort. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.NOTE: You must sort using system field names, such as updatedTime. Do not sort by field names that appear in response bodies, such as updated_time.Allowable Values: updatedTime, -updatedTime |
Response body
| Fields | Description |
|---|---|
| count integer Returned | Number of resources returned. Allowable Values: 1–100 |
| start_index integer Returned | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| end_index integer Returned | Sort order index of the last resource in the returned array. Allowable Values: Any integer |
| is_more boolean Returned | A value of true indicates that more unreturned resources exist.Allowable Values: true, false |
| data array of objects Returned | List of reward account objects. Allowable Values: Valid array of one or more reward account objects |
| data[].token string Returned | Unique identifier of the reward account. Allowable Values: 36 char max |
| data[].credit_account_token string Returned | Unique identifier of the associated credit account. Allowable Values: 36 char max |
| data[].bundle_token string Conditionally returned | Unique identifier of the associated bundle that contains the reward policy on which the reward account is based. Allowable Values: 36 char max |
| data[].is_active boolean Returned | A value of true indicates that the reward account is active.Allowable Values: true, false |
| data[].global_rules array of objects Conditionally returned | List of global rules. Allowable Values: Valid array of one or more global rules |
| data[].global_rules[].rule_token string Conditionally returned | Unique identifier of the rule. Allowable Values: 36 char max |
| data[].global_rules[].description string Conditionally returned | Description of the rule, pulled from the rule entry. Allowable Values: 255 char max |
| data[].created_time datetime Returned | Date and time when the reward account was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| data[].updated_time datetime Returned | Date and time when the reward account was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "4829608d-97e4-4a8c-bdab-20b26e7f243d",
"credit_account_token": "bbf6c086-4286-4a1c-a3dd-2f54bf6fd799",
"bundle_token": "f0cf97cb-76f7-47a5-83e7-188b9e741cf9",
"is_active": true,
"created_time": "2024-01-05T20:37:11Z",
"updated_time": "2024-01-05T20:37:11Z"
}
]
}
Retrieve reward account
Action:GETEndpoint:
/credit/rewards/accounts/{token}
Retrieve a specific reward account.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
URL query parameters
| Fields | Description |
|---|---|
| expand array of strings Optional | Embeds the specified object into the response GLOBAL_RULES.Allowable Values: RULES |
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the reward account. Allowable Values: 36 char max |
| credit_account_token string Returned | Unique identifier of the associated credit account. Allowable Values: 36 char max |
| bundle_token string Conditionally returned | Unique identifier of the associated bundle that contains the reward policy on which the reward account is based. Allowable Values: 36 char max |
| is_active boolean Returned | A value of true indicates that the reward account is active.Allowable Values: true, false |
| global_rules array of objects Conditionally returned | List of global rules. Allowable Values: Valid array of one or more global rules |
| global_rules[].rule_token string Conditionally returned | Unique identifier of the rule. Allowable Values: 36 char max |
| global_rules[].description string Conditionally returned | Description of the rule, pulled from the rule entry. Allowable Values: 255 char max |
| created_time datetime Returned | Date and time when the reward account was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| updated_time datetime Returned | Date and time when the reward account was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"token": "4829608d-97e4-4a8c-bdab-20b26e7f243d",
"credit_account_token": "bbf6c086-4286-4a1c-a3dd-2f54bf6fd799",
"bundle_token": "f0cf97cb-76f7-47a5-83e7-188b9e741cf9",
"is_active": true,
"global_rules": [
{
"rule_token": "00fb5637-2dab-4833-aa12-0463e7cf8cbb",
"description": "Earn 3x on agricultural services, contracted services, and purchases at Target."
}
],
"created_time": "2024-01-05T20:37:11Z",
"updated_time": "2024-01-05T20:37:11Z"
}
Update active state
Action:PUTEndpoint:
/credit/rewards/accounts/{token}
Update a reward account’s active state.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
Request body
| Fields | Description |
|---|---|
| is_active boolean Optional | A value of true indicates that the reward account is active and rewards can be accrued for the associated account.Allowable Values: true, false |
Sample request body
JSON
{
"is_active": false
}
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the reward account. Allowable Values: 36 char max |
| credit_account_token string Returned | Unique identifier of the associated credit account. Allowable Values: 36 char max |
| bundle_token string Conditionally returned | Unique identifier of the associated bundle that contains the reward policy on which the reward account is based. Allowable Values: 36 char max |
| is_active boolean Returned | A value of true indicates that the reward account is active.Allowable Values: true, false |
| global_rules array of objects Conditionally returned | List of global rules. Allowable Values: Valid array of one or more global rules |
| global_rules[].rule_token string Conditionally returned | Unique identifier of the rule. Allowable Values: 36 char max |
| global_rules[].description string Conditionally returned | Description of the rule, pulled from the rule entry. Allowable Values: 255 char max |
| created_time datetime Returned | Date and time when the reward account was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| updated_time datetime Returned | Date and time when the reward account was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"token": "4829608d-97e4-4a8c-bdab-20b26e7f243d",
"credit_account_token": "bbf6c086-4286-4a1c-a3dd-2f54bf6fd799",
"bundle_token": "f0cf97cb-76f7-47a5-83e7-188b9e741cf9",
"is_active": true,
"created_time": "2024-01-05T20:37:11Z",
"updated_time": "2024-01-05T20:37:11Z"
}
Retrieve reward account balances
Action:GETEndpoint:
/credit/rewards/accounts/{token}/balances
Retrieve rewards balances for a specific reward account.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
URL query parameters
| Fields | Description |
|---|---|
| start_date datetime Optional | Starting date and time of a date range from which to return resources, in UTC. Allowable Values: format: yyyy-MM-ddThh:mm:ssZ |
| end_date datetime Optional | Ending date and time of a date range from which to return resources, in UTC. Allowable Values: format: yyyy-MM-ddThh:mm:ssZ |
Response body
| Fields | Description |
|---|---|
| billing_cycle_opening_date datetime Returned | Opening date of the billing cycle for which rewards were accrued, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| billing_cycle_closing_date datetime Returned | Closing date of the billing cycle for which rewards were accrued, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| total_spend_this_cycle decimal Returned | Total amount spent during a given billing cycle, minus any refunds or disputes, even if transactions did not result in a reward. Used to determine reward accrual. Allowable Values: Format: 0.00 |
| points_balance object Returned | Pending and total accrual balance (in points) for the reward account. Allowable Values: accrued_this_cycle, total_reward_balance |
| points_balance.accrued_this_cycle decimal Returned | Pending balance (in points) for a reward account. Allowable Values: Any integer |
| points_balance.total_reward_balance decimal Returned | Total reward balance (in points) for a reward account. Allowable Values: Any integer |
| reward_values array of objects Returned | List of possible reward conversion values. Allowable Values: Valid array of one or more reward_values objects |
| reward_values[].redemption_type string Conditionally returned | Type of redemption. - EXTERNAL - You issue the redemption on your external platform; Marqeta adjusts the reward account balance on the system of record.- STATEMENT_CREDIT - Marqeta issues the redemption as a statement credit on the associated account.NOTE: This creates a new journal entry on the account and cannot be undone. Allowable Values: EXTERNAL, STATEMENT_CREDIT |
| reward_values[].conversion_rate decimal Returned | Conversion rate of the reward account’s points, if they were used for this redemption type. Allowable Values: 0.001 min Format: 0.000 |
| reward_values[].conversion_increment decimal Returned | Allowed point increments that the reward account must have to use this redemption type. Allowable Values: Any integer |
| retrieved_time datetime Conditionally returned | Retrieval date of the reward account’s accrual balance, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"billing_cycle_opening_date": "2023-12-25T20:37:11Z",
"billing_cycle_closing_date": "2024-01-24T20:37:11Z",
"total_spend_this_cycle": 5832,
"points_balance": {
"accrued_this_cycle": 10000,
"total_reward_balance": 25000
},
"reward_values": [
{
"redemption_type": "STATEMENT_CREDIT",
"conversion_rate": 0.001,
"conversion_increment": 10
}
],
"retrieved_time": "2024-01-05T20:37:11Z"
}
Retrieve reward account accruals
Action:GETEndpoint:
/credit/rewards/accounts/{token}/accruals
Use this endpoint to retrieve the reward accounts rewards accrual by rule for a specified time frame. If you do not specify a time frame in your query parameters, the query defaults to the current billing cycle.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
Response body
| Fields | Description |
|---|---|
| start_date datetime Conditionally returned | Start date of rewards accrual retrieval, in UTC. Defaults to the billing cycle closing date. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| end_date datetime Conditionally returned | End date of rewards accrual retrieval, in UTC. Defaults to the billing cycle closing date. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| rules array of objects Conditionally returned | List of accrual information by rule. Allowable Values: Valid array of one or more rule accrual objects |
| rules[].description string Conditionally returned | Description of the rule, pulled from the rule entry. Allowable Values: 255 char max |
| rules[].total_spend decimal Conditionally returned | Total spend contributed to the reward accrual for this rule. Allowable Values: Any integer |
| rules[].total_rewards_earned decimal Conditionally returned | Total settled rewards accrued against the rule. Allowable Values: Any integer |
| retrieved_time datetime Conditionally returned | Retrieval date of the reward account’s accruals, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"start_date": "2023-12-25T20:37:11Z",
"end_date": "2024-01-24T20:37:11Z",
"rules": [
{
"description": "Earn 3x on agricultural services, contracted services, and purchases at Target.",
"total_spend": 12300,
"total_rewards_earned": 30000
},
{
"description": "Earn 5x on Lyft, up to $500.",
"total_spend": 600,
"total_rewards_earned": 2500
},
{
"description": "Earn 50 points by spending $50 at Target.",
"total_spend": 2500,
"total_rewards_earned": 50
},
{
"description": "Earn one point on all transactions.",
"total_spend": 5863,
"total_rewards_earned": 5000
}
],
"retrieved_time": "2024-01-05T20:37:11Z"
}
Create reward entry
Action:POSTEndpoint:
/credit/rewards/accounts/{token}/entries
Create a reward entry for a specific reward account.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
Request body
| Fields | Description |
|---|---|
| token string Optional | Unique identifier of the reward entry. Allowable Values: 36 char max |
| value decimal Required | Value of the reward granted to the account. Allowable Values: 0.001 min Format: 0.000 |
| note string Required | Note explaining why the reward entry is being created. Allowable Values: 255 char max |
| created_time datetime Optional | Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample request body
JSON
{
"value": 5000,
"note": "Account awarded 5000 bonus points for completing customer feedback survey."
}
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the reward entry. Allowable Values: 36 char max |
| reward_account_token string Returned | Unique identifier of the reward account for which to return reward entries. Allowable Values: 36 char max |
| rule_token string Conditionally returned | Unique identifier of the rule used to determine the value of the reward entry. Allowable Values: 36 char max |
| transaction_amount decimal Conditionally returned | Transaction amount to which the rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00 |
| value decimal Returned | Value of the reward entry. Allowable Values: Format: 0.00 |
| related_journal_entry_token string Conditionally returned | Unique identifier of the related journal entry to which the rule was applied that triggered the reward entry. Allowable Values: 36 char max Existing journal entry token |
| related_redemption_token string Conditionally returned | Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
| related_entry_token string Conditionally returned | Unique identifier of the related reward entry token for a given dispute. Allowable Values: 36 char max |
| note string Returned | Note providing information on the reward entry. Allowable Values: 255 char max |
| created_time datetime Conditionally returned | Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"token": "948d82d0-2f6f-46e9-bfa2-68e0f2e1192a",
"reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
"value": 5000,
"note": "Account completed customer feedback survey for 5000 bonus points.",
"created_time": "2024-01-04T20:37:11Z"
}
List reward entries for a reward account
Action:GETEndpoint:
/credit/rewards/accounts/{token}/entries
Retrieve an array of reward entries for a specific reward account.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
URL query parameters
| Fields | Description |
|---|---|
| start_date datetime Optional | Starting date and time of a date range from which to return resources, in UTC. Allowable Values: format: yyyy-MM-ddThh:mm:ssZ |
| end_date datetime Optional | Ending date and time of a date range from which to return resources, in UTC. Allowable Values: format: yyyy-MM-ddThh:mm:ssZ |
| count integer Optional | Number of resources to retrieve. Allowable Values: 1–100 |
| start_index integer Optional | Sort order index of the first resource in the returned array. Allowable Values: 0 min |
| sort_by_created string Optional | Field on which to sort. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.NOTE: You must sort using system field names, such as createdTime. Do not sort by field names that appear in response bodies, such as created_time.Allowable Values: createdTime, -createdTime |
| status string Required | Status of the reward entries in the returned array. Allowable Values: PENDING, POSTED |
Response body
| Fields | Description |
|---|---|
| count integer Returned | Number of resources returned. Allowable Values: 1–100 |
| start_index integer Returned | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| end_index integer Returned | Sort order index of the last resource in the returned array. Allowable Values: Any integer |
| is_more boolean Returned | A value of true indicates that more unreturned resources exist.Allowable Values: true, false |
| data array of objects Returned | List of reward entry objects. Allowable Values: Valid array of one or more reward entry objects |
| data[].token string Returned | Unique identifier of the reward entry. Allowable Values: 36 char max |
| data[].reward_account_token string Returned | Unique identifier of the reward account for which to return reward entries. Allowable Values: 36 char max |
| data[].rule_token string Conditionally returned | Unique identifier of the rule used to determine the value of the reward entry. Allowable Values: 36 char max |
| data[].transaction_amount decimal Conditionally returned | Transaction amount to which the rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00 |
| data[].value decimal Returned | Value of the reward entry. Allowable Values: Format: 0.00 |
| data[].related_journal_entry_token string Conditionally returned | Unique identifier of the related journal entry to which the rule was applied that triggered the reward entry. Allowable Values: 36 char max Existing journal entry token |
| data[].related_redemption_token string Conditionally returned | Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
| data[].related_entry_token string Conditionally returned | Unique identifier of the related reward entry token for a given dispute. Allowable Values: 36 char max |
| data[].note string Returned | Note providing information on the reward entry. Allowable Values: 255 char max |
| data[].created_time datetime Conditionally returned | Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"count": 5,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "12959312-675e-44e9-b6be-9dc7a0d996bd",
"reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
"rule_token": "b125a2ea-477d-410f-b6a1-283b8eddb3cd",
"transaction_amount": 100,
"value": 200,
"note": "Account awarded 5000 bonus points for completing customer feedback survey.",
"related_journal_entry_token": "64794ba4-9094-466f-b11a-b3d1daf17293",
"created_time": "2024-01-01T20:37:11Z"
},
{
"token": "12959312-675e-44e9-b6be-9dc7a0d996bd",
"reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
"rule_token": "b125a2ea-477d-410f-b6a1-283b8eddb3cd",
"transaction_amount": 500,
"value": 50,
"note": "Account awarded 5000 bonus points for completing customer feedback survey.",
"related_journal_entry_token": "64794ba4-9094-466f-b11a-b3d1daf17293",
"related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
"created_time": "2024-01-02T20:37:11Z"
},
{
"token": "4391dd08-b91f-47be-8577-dc080d4e51a5",
"reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
"rule_token": "5fd9cb86-1ecf-4eb9-beea-db308b051797",
"value": 200,
"note": "Account awarded 5000 bonus points for completing customer feedback survey.",
"created_time": "2024-01-03T20:37:11Z"
},
{
"token": "4d0ff4ee-ee97-48a8-9494-70edcf456aab",
"reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
"value": 20000,
"related_journal_entry_token": "64794ba4-9094-466f-b11a-b3d1daf17293",
"related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
"note": "Customer called in, one time reward for error in statement.",
"created_time": "2024-01-04T20:37:11Z"
},
{
"token": "1417c942-2eba-4238-ac44-d04db1f411cd",
"reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
"value": -1000,
"note": "Account awarded 5000 bonus points for completing customer feedback survey.",
"related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
"created_time": "2024-01-04T20:37:11Z"
}
]
}
Retrieve reward entry
Action:GETEndpoint:
/credit/rewards/accounts/{token}/entries/{entry_token}
Retrieve a specific reward entry for a reward account.
URL path parameters
| Fields | Description |
|---|---|
| entry_token string Required | Unique identifier of the reward entry to retrieve. Allowable Values: 36 char max |
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the reward entry. Allowable Values: 36 char max |
| reward_account_token string Returned | Unique identifier of the reward account for which to return reward entries. Allowable Values: 36 char max |
| rule_token string Conditionally returned | Unique identifier of the rule used to determine the value of the reward entry. Allowable Values: 36 char max |
| transaction_amount decimal Conditionally returned | Transaction amount to which the rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00 |
| value decimal Returned | Value of the reward entry. Allowable Values: Format: 0.00 |
| related_journal_entry_token string Conditionally returned | Unique identifier of the related journal entry to which the rule was applied that triggered the reward entry. Allowable Values: 36 char max Existing journal entry token |
| related_redemption_token string Conditionally returned | Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
| related_entry_token string Conditionally returned | Unique identifier of the related reward entry token for a given dispute. Allowable Values: 36 char max |
| note string Returned | Note providing information on the reward entry. Allowable Values: 255 char max |
| created_time datetime Conditionally returned | Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"token": "1417c942-2eba-4238-ac44-d04db1f411cd",
"reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
"value": -1000,
"note": "Account completed customer feedback survey for 5000 bonus points.",
"related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
"created_time": "2024-01-04T20:37:11Z"
}