Reward Redemptions (Beta)
Use the /credit/rewardprograms/{token}/redemptions endpoint to the manage reward redemptions on a credit account.
A reward program’s rules configuration specifies how rewards are redeemed and is defined in the reward policy on the account’s associated bundle.
To receive webhook notifications when reward redemption transition events occur, see Credit reward redemption transition events in Event Types.
Create reward redemption
Copy section link
Action: POST
Endpoint: /credit/rewardprograms/{token}/redemptions
Create a redemption to redeem rewards 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 |
Request body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward redemption. Allowable Values: 36 char max |
type
string
|
Type of redemption.
Allowable Values:
|
destination
string
|
Destination of the reward redemption.
Required for external redemptions. Allowable Values:
|
amount
decimal
|
Amount of the reward redemption. Allowable Values: 0 min Format: 0.00 |
note
string
|
A note explaining why the reward is being redeemed. Allowable Values: 255 char max |
receiving_account_token
string
|
Unique identifier of the external account receiving the reward redemption. This token is equivalent to the payment source token. Allowable Values: 36 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward redemption. Allowable Values: 36 char max |
reward_program_token
string
|
Unique identifier of the reward program for which to redeem rewards. Allowable Values: 36 char max |
type
string
|
Type of redemption.
Allowable Values:
|
destination
string
|
Destination of the reward redemption.
Required for external redemptions. Allowable Values:
|
amount
decimal
|
Amount to redeem. Allowable Values: Format: 0.00 |
status
string
|
Status of the redemption.
Allowable Values:
|
note
string
|
Allowable Values: |
sor_reward_token
string
|
Unique identifier of the system of reward (SOR) reward that was created to represent the reward redemption as a Allowable Values: 36 char max |
external_settlement_date_time
datetime
|
Date and time when the reward redemption was settled on your external platform. This field is returned if you handled the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
related_reward_entries
array of objects
|
Contains one or more reward entries related to the redemption. Allowable Values: One or more |
related_reward_entries[].token
string
|
Unique identifier of the reward entry. Allowable Values: 36 char max |
related_reward_entries[].reward_program_token
string
|
Unique identifier of the reward program for which to return reward entries. Allowable Values: 36 char max |
related_reward_entries[].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 |
related_reward_entries[].status
string
|
Status of the reward entry. Allowable Values:
|
related_reward_entries[].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 |
related_reward_entries[].value
decimal
|
Value of the reward entry. Allowable Values: Format: 0.00 |
related_reward_entries[].mcc
string
|
Merchant category code (MCC) of the related journal entry. Allowable Values: Existing MCC |
related_reward_entries[].mid
string
|
Merchant identifier (MID) of the related journal entry. Allowable Values: |
related_reward_entries[].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_reward_entries[].related_redemption_token
string
|
Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
related_reward_entries[].note
string
|
A note providing information on the reward entry. Allowable Values: 255 char max |
related_reward_entries[].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 |
created_time
datetime
|
Date and time when the reward redemption 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 redemption was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
receiving_account_token
string
|
Unique identifier of the external account receiving the reward redemption. This token is equivalent to the payment source token. Allowable Values: 36 char max |
List reward redemptions
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/redemptions
Retrieve an array of reward redemptions 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 |
|---|---|
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:
|
type
string
|
Type of reward redemptions in the returned array. Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
data
array of objects
|
Contains one or more redemptions. Allowable Values: One or more redemption objects. |
data[].token
string
|
Unique identifier of the reward redemption. Allowable Values: 36 char max |
data[].reward_program_token
string
|
Unique identifier of the reward program for which to redeem rewards. Allowable Values: 36 char max |
data[].type
string
|
Type of redemption.
Allowable Values:
|
data[].destination
string
|
Destination of the reward redemption.
Required for external redemptions. Allowable Values:
|
data[].amount
decimal
|
Amount to redeem. Allowable Values: Format: 0.00 |
data[].status
string
|
Status of the redemption.
Allowable Values:
|
data[].note
string
|
Allowable Values: |
data[].sor_reward_token
string
|
Unique identifier of the system of reward (SOR) reward that was created to represent the reward redemption as a Allowable Values: 36 char max |
data[].external_settlement_date_time
datetime
|
Date and time when the reward redemption was settled on your external platform. This field is returned if you handled the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].related_reward_entries
array of objects
|
Contains one or more reward entries related to the redemption. Allowable Values: One or more |
data[].related_reward_entries[].token
string
|
Unique identifier of the reward entry. Allowable Values: 36 char max |
data[].related_reward_entries[].reward_program_token
string
|
Unique identifier of the reward program for which to return reward entries. Allowable Values: 36 char max |
data[].related_reward_entries[].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[].related_reward_entries[].status
string
|
Status of the reward entry. Allowable Values:
|
data[].related_reward_entries[].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[].related_reward_entries[].value
decimal
|
Value of the reward entry. Allowable Values: Format: 0.00 |
data[].related_reward_entries[].mcc
string
|
Merchant category code (MCC) of the related journal entry. Allowable Values: Existing MCC |
data[].related_reward_entries[].mid
string
|
Merchant identifier (MID) of the related journal entry. Allowable Values: |
data[].related_reward_entries[].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_reward_entries[].related_redemption_token
string
|
Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
data[].related_reward_entries[].note
string
|
A note providing information on the reward entry. Allowable Values: 255 char max |
data[].related_reward_entries[].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 |
data[].created_time
datetime
|
Date and time when the reward redemption 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 redemption was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].receiving_account_token
string
|
Unique identifier of the external account receiving the reward redemption. This token is equivalent to the payment source token. Allowable Values: 36 char max |
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:
|
Retrieve reward redemption
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/redemptions/{redemption_token}
Retrieve a specific redemption 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 |
redemption_token
string
|
Unique identifier of the reward redemption. Allowable Values: Existing redemption token |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward redemption. Allowable Values: 36 char max |
reward_program_token
string
|
Unique identifier of the reward program for which to redeem rewards. Allowable Values: 36 char max |
type
string
|
Type of redemption.
Allowable Values:
|
destination
string
|
Destination of the reward redemption.
Required for external redemptions. Allowable Values:
|
amount
decimal
|
Amount to redeem. Allowable Values: Format: 0.00 |
status
string
|
Status of the redemption.
Allowable Values:
|
note
string
|
Allowable Values: |
sor_reward_token
string
|
Unique identifier of the system of reward (SOR) reward that was created to represent the reward redemption as a Allowable Values: 36 char max |
external_settlement_date_time
datetime
|
Date and time when the reward redemption was settled on your external platform. This field is returned if you handled the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
related_reward_entries
array of objects
|
Contains one or more reward entries related to the redemption. Allowable Values: One or more |
related_reward_entries[].token
string
|
Unique identifier of the reward entry. Allowable Values: 36 char max |
related_reward_entries[].reward_program_token
string
|
Unique identifier of the reward program for which to return reward entries. Allowable Values: 36 char max |
related_reward_entries[].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 |
related_reward_entries[].status
string
|
Status of the reward entry. Allowable Values:
|
related_reward_entries[].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 |
related_reward_entries[].value
decimal
|
Value of the reward entry. Allowable Values: Format: 0.00 |
related_reward_entries[].mcc
string
|
Merchant category code (MCC) of the related journal entry. Allowable Values: Existing MCC |
related_reward_entries[].mid
string
|
Merchant identifier (MID) of the related journal entry. Allowable Values: |
related_reward_entries[].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_reward_entries[].related_redemption_token
string
|
Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max |
related_reward_entries[].note
string
|
A note providing information on the reward entry. Allowable Values: 255 char max |
related_reward_entries[].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 |
created_time
datetime
|
Date and time when the reward redemption 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 redemption was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
receiving_account_token
string
|
Unique identifier of the external account receiving the reward redemption. This token is equivalent to the payment source token. Allowable Values: 36 char max |
Retrieve reward redemption balance
Copy section link
Action: GET
Endpoint: /credit/rewardprograms/{token}/redemptions/balance
Retrieve the balance for reward redemptions 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: |
type
array of strings
|
Type of reward redemptions in the returned array. Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
reward_program_token
string
|
Unique identifier of the reward program for which to return the redemption balance. Allowable Values: 36 char max |
redemption_total_amount
decimal
|
Total amount of rewards redeemed within a specified date range. Allowable Values: |
start_date
datetime
|
The starting date (or date-time) of a date range from which to return the redemption balance, in UTC. 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 the redemption balance, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Transition reward redemption status
Copy section link
Action: POST
Endpoint: /credit/rewardprograms/{token}/redemptions/{redemption_token}/transitions
Transition the current status of a reward redemption to a new status.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward program. Allowable Values: Existing reward program token |
redemption_token
string
|
Unique identifier of the reward redemption. Allowable Values: Existing redemption token |
Request body
Copy section link
| Fields | Description |
|---|---|
new_state
string
|
Status of the redemption.
Allowable Values:
|
external_settlement_date_time
datetime
|
Date and time when the reward redemption was settled on your external platform. Pass this field if you handle the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the reward redemption transition. Allowable Values: 36 char max |
redemption_token
string
|
Unique identifier of the redemption whose status was transitioned. Allowable Values: 36 char max |
initial_status
string
|
Status of the redemption.
Allowable Values:
|
new_status
string
|
Status of the redemption.
Allowable Values:
|
external_settlement_date_time
datetime
|
Date and time when the reward redemption was settled on your external platform. This field is returned if you handled the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
created_time
datetime
|
Date and time when the reward redemption transition was created on Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |