Reward Programs (Beta)
Use the /credit/rewardprograms/{token} endpoint to manage reward programs and track reward accruals on a credit account.
The configurations for a reward program are defined in the reward policy on the account’s associated bundle.
To receive webhook notifications when reward entry events occur, see Credit reward entry events in Event Types.
List reward programs
Copy section link
Action: GET
Endpoint: /credit/rewardprograms
Retrieve an array of reward programs.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
account_token
string
|
The unique identifier of the credit account for which you want to retrieve reward programs. Allowable Values: 36 char max |
is_active
boolean
|
A value of Allowable Values:
|
count
integer
|
Number of resources to retrieve. Allowable Values: 1–100 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: 0 min |
sort_by
string
|
Field on which to sort.
Prefix the field name with a hyphen ( NOTE:
You must sort using system field names such as Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources returned. Allowable Values: 1–100 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
end_index
integer
|
Sort order index of the last resource in the returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of Allowable Values:
|
data
array of objects
|
An array of reward program objects. Allowable Values: One or more reward program objects |
data[].token
string
|
Unique identifier of the reward program. Allowable Values: 36 char max |
data[].account_token
string
|
Unique identifier of the associated credit account. Allowable Values: 36 char max |
data[].bundle_token
string
|
Unique identifier of the associated bundle that contains the reward policy on which the reward program is based. Allowable Values: 36 char max |
data[].calculation_type
string
|
Type of calculation for the reward.
Allowable Values:
|
data[].is_active
boolean
|
A value of Allowable Values:
|
data[].note
string
|
A note that provides information on the reward program. Allowable Values: 255 char max |
data[].created_time
datetime
|
Date and time when the reward program was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].updated_time
datetime
|
Date and time when the reward program was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Retrieve reward program
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}
Retrieve a specific reward program.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: 36 char max |
account_token
string
|
Unique identifier of the associated credit account. Allowable Values: 36 char max |
bundle_token
string
|
Unique identifier of the associated bundle that contains the reward policy on which the reward program is based. Allowable Values: 36 char max |
calculation_type
string
|
Type of calculation for the reward.
Allowable Values:
|
is_active
boolean
|
A value of Allowable Values:
|
note
string
|
A note that provides information on the reward program. Allowable Values: 255 char max |
created_time
datetime
|
Date and time when the reward program was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
updated_time
datetime
|
Date and time when the reward program was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Activate or deactivate reward program
Copy section link
Action: PUT
Endpoint: /credit/rewardprograms/{token}
Activate or deactivate a specific reward program.
Caution
This endpoint is available for banks only. Do not use this endpoint if you are a brand contributor.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
Request body
Copy section link
| Fields | Description |
|---|---|
is_active
boolean
|
A value of Allowable Values:
|
note
string
|
A note explaining why the reward program is being activated or deactivated. Allowable Values: 255 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: 36 char max |
account_token
string
|
Unique identifier of the associated credit account. Allowable Values: 36 char max |
bundle_token
string
|
Unique identifier of the associated bundle that contains the reward policy on which the reward program is based. Allowable Values: 36 char max |
calculation_type
string
|
Type of calculation for the reward.
Allowable Values:
|
is_active
boolean
|
A value of Allowable Values:
|
note
string
|
A note that provides information on the reward program. Allowable Values: 255 char max |
created_time
datetime
|
Date and time when the reward program was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
updated_time
datetime
|
Date and time when the reward program was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Retrieve reward program balances
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/balances
Retrieve the balances for a specific reward program.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
Response body
Copy section link
| Fields | Description |
|---|---|
reward_program_token
string
|
Unique identifier of reward program for which to return balances. Allowable Values: 36 char max |
net_balance
decimal
|
The net balance for a billing cycle, which is total amount spent during a billing cycle, minus any refunds or reversals. Used to determine reward accrual. Allowable Values: |
pending_reward_balance
decimal
|
The pending balance of the rewards accrued for the current billing cycle. Pending rewards cannot be redeemed. Allowable Values: |
total_reward_balance
decimal
|
The total balance of the rewards accrued to date minus the rewards redeemed to date. Allowable Values: |
percentage
integer
|
The reward percentage applied to the balance for the current billing cycle. Determined by the reward rules config. Allowable Values: |
billing_cycle_opening_date
datetime
|
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
|
Closing date of the billing cycle for which rewards were accrued, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Create reward entry
Copy section link
Action: POST
Endpoint: /credit/rewardprograms/{token}/entries
Create a reward entry on a specific reward program.
Use this endpoint to manually create a reward entry if an existing reward is being disputed.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
Request body
Copy section link
| Fields | Description |
|---|---|
value
decimal
|
Value of the reward granted to the account. Allowable Values: Format: 0.00 |
note
string
|
A note explaining why the reward entry is being created manually. Allowable Values: 255 char max |
created_time
datetime
|
Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward entry. Allowable Values: 36 char max |
reward_program_token
string
|
Unique identifier of the reward program for which to return reward entries. Allowable Values: 36 char max |
reward_rules_config_token
string
|
Unique identifier of the reward rules config used to determine the value of the reward entry. Allowable Values: 36 char max |
status
string
|
Status of the reward entry. Allowable Values:
|
transaction_amount
decimal
|
The transaction amount to which the reward rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00 |
value
decimal
|
Value of the reward entry. Allowable Values: Format: 0.00 |
mcc
string
|
Merchant category code (MCC) of the related journal entry. Allowable Values: Existing MCC |
mid
string
|
Merchant identifier (MID) of the related journal entry. Allowable Values: |
related_journal_entry_token
string
|
Unique identifier of the related journal entry to which the reward rule was applied to trigger the reward entry. Allowable Values: 36 char max Existing journal entry token |
related_redemption_token
string
|
Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
note
string
|
A note providing information on the reward entry. Allowable Values: 255 char max |
created_time
datetime
|
Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
List reward entries
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/entries
Retrieve an array of reward entries on a specific reward program.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
start_date
datetime
|
The starting date (or date-time) of a date range from which to return resources, in UTC. Allowable Values: |
end_date
datetime
|
The ending date (or date-time) of a date range from which to return resources, in UTC. Allowable Values: |
count
integer
|
Number of resources to retrieve. Allowable Values: 1–100 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: 0 min |
sort_by
string
|
Field on which to sort.
Prefix the field name with a hyphen ( NOTE:
You must sort using system field names such as Allowable Values:
|
status
array of strings
|
Status of the reward entries in the returned array. Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources returned. Allowable Values: 1–100 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
end_index
integer
|
Sort order index of the last resource in the returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of Allowable Values:
|
data
array of objects
|
An array of reward entry objects. Allowable Values: One or more reward entry objects |
data[].token
string
|
Unique identifier of the reward entry. Allowable Values: 36 char max |
data[].reward_program_token
string
|
Unique identifier of the reward program for which to return reward entries. Allowable Values: 36 char max |
data[].reward_rules_config_token
string
|
Unique identifier of the reward rules config used to determine the value of the reward entry. Allowable Values: 36 char max |
data[].status
string
|
Status of the reward entry. Allowable Values:
|
data[].transaction_amount
decimal
|
The transaction amount to which the reward rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00 |
data[].value
decimal
|
Value of the reward entry. Allowable Values: Format: 0.00 |
data[].mcc
string
|
Merchant category code (MCC) of the related journal entry. Allowable Values: Existing MCC |
data[].mid
string
|
Merchant identifier (MID) of the related journal entry. Allowable Values: |
data[].related_journal_entry_token
string
|
Unique identifier of the related journal entry to which the reward rule was applied to trigger the reward entry. Allowable Values: 36 char max Existing journal entry token |
data[].related_redemption_token
string
|
Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
data[].note
string
|
A note providing information on the reward entry. Allowable Values: 255 char max |
data[].created_time
datetime
|
Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Retrieve reward entries balance
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/entries/balance
Retrieve the balance of reward entries, which is the accrued rewards amount, within a specified date range.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
start_date
datetime
|
The starting date (or date-time) of a date range from which to return resources, in UTC. Allowable Values: |
end_date
datetime
|
The ending date (or date-time) of a date range from which to return resources, in UTC. Allowable Values: |
Response body
Copy section link
| Fields | Description |
|---|---|
reward_program_token
string
|
Unique identifier of the reward program for which to retrieve the reward entries balance. Allowable Values: 36 char max |
total_reward_balance
decimal
|
The total balance of rewards accrued within a date range. Allowable Values: |
start_date
datetime
|
The starting date (or date-time) of a date range from which to return accrued rewards, in UTC. Reward entries created on or after this date count toward the total reward balance. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
end_date
datetime
|
The ending date (or date-time) of a date range from which to return accrued rewards, in UTC. Reward entries created on or before this date count toward the total reward balance. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
created_date
datetime
|
Date and time the reward entries balance was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Retrieve reward entry
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/entries/{entry_token}
Retrieve a specific reward entry on a reward program.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
entry_token
string
|
Unique identifier of the reward entry to retrieve. Allowable Values: |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward entry. Allowable Values: 36 char max |
reward_program_token
string
|
Unique identifier of the reward program for which to return reward entries. Allowable Values: 36 char max |
reward_rules_config_token
string
|
Unique identifier of the reward rules config used to determine the value of the reward entry. Allowable Values: 36 char max |
status
string
|
Status of the reward entry. Allowable Values:
|
transaction_amount
decimal
|
The transaction amount to which the reward rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00 |
value
decimal
|
Value of the reward entry. Allowable Values: Format: 0.00 |
mcc
string
|
Merchant category code (MCC) of the related journal entry. Allowable Values: Existing MCC |
mid
string
|
Merchant identifier (MID) of the related journal entry. Allowable Values: |
related_journal_entry_token
string
|
Unique identifier of the related journal entry to which the reward rule was applied to trigger the reward entry. Allowable Values: 36 char max Existing journal entry token |
related_redemption_token
string
|
Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
note
string
|
A note providing information on the reward entry. Allowable Values: 255 char max |
created_time
datetime
|
Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
List rules configurations
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/rulesconfigs
Retrieve an array of rules configs for a specific reward program.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
is_active
boolean
|
A value of Allowable Values:
|
count
integer
|
Number of resources to retrieve. Allowable Values: 1–100 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: 0 min |
sort_by
string
|
Field on which to sort.
Prefix the field name with a hyphen ( NOTE:
You must sort using system field names such as Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources returned. Allowable Values: 1–100 |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer |
end_index
integer
|
Sort order index of the last resource in the returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of Allowable Values:
|
data
array of objects
|
An array of rules config objects. Allowable Values: One or more rules config objects |
data[].token
string
|
Unique identifier of the reward rules config. Allowable Values: 36 char max |
data[].reward_program_token
string
|
Unique identifier of the reward program on which the rules config is applied. Allowable Values: 36 char max |
data[].accrual_type
string
|
Type of reward accrued. Allowable Values:
|
data[].less_than
decimal
|
Maximum amount that the balance for a billing cycle can be to apply the specified reward percentage.
For example, if the Allowable Values: 0 min |
data[].greater_than
decimal
|
Minimum amount that the balance for a billing cycle can be to apply the specified reward percentage.
For example, if the Allowable Values: 0 min |
data[].percentage
integer
|
The reward percentage applied when the balance for a billing cycle is within the range specified in the Allowable Values: |
data[].is_active
boolean
|
A value of Allowable Values:
|
data[].created_time
datetime
|
Date and time when the reward rules config was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].updated_time
datetime
|
Date and time when the reward rules config was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Retrieve last rules configuration applied
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/rulesconfigs/applied
Retrieve the most recently applied rules config on a specific reward program.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward rules config. Allowable Values: 36 char max |
reward_program_token
string
|
Unique identifier of the reward program on which the rules config is applied. Allowable Values: 36 char max |
accrual_type
string
|
Type of reward accrued. Allowable Values:
|
less_than
decimal
|
Maximum amount that the balance for a billing cycle can be to apply the specified reward percentage.
For example, if the Allowable Values: 0 min |
greater_than
decimal
|
Minimum amount that the balance for a billing cycle can be to apply the specified reward percentage.
For example, if the Allowable Values: 0 min |
percentage
integer
|
The reward percentage applied when the balance for a billing cycle is within the range specified in the Allowable Values: |
is_active
boolean
|
A value of Allowable Values:
|
created_time
datetime
|
Date and time when the reward rules config was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
updated_time
datetime
|
Date and time when the reward rules config was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |