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}/redemptions endpoint to the manage reward redemptions on a credit account. To receive webhook notifications when reward accounts and reward entry events occur, see Credit reward entry events in Event Types.
Create reward redemption
Action:POSTEndpoint:
/credit/rewards/accounts/{token}/redemptions
Create a reward redemption 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 redemption. Allowable Values: 36 char max |
| type string Required | 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 |
| amount decimal Required | Amount of the reward redemption. Allowable Values: 0.01 min Format: 0.00 |
| note string Optional | Note explaining why the reward is being redeemed. Allowable Values: 255 char max |
| destination string Optional | Destination of the EXTERNAL redemption for the brand to track.Allowable Values: 255 char max |
| receiving_account_token string Optional | Unique identifier of the external account receiving the reward redemption. This token is the payment source token. Allowable Values: 36 char max |
Sample request body
JSON
{
"type": "EXTERNAL",
"amount": 1000,
"destination": "BRAND_WALLET",
"note": "Redeeming reward balance to Brand Wallet at brand conversion rate 1.5 per point."
}
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the reward redemption. Allowable Values: 36 char max |
| type string 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 |
| destination string Conditionally returned | Destination of the EXTERNAL redemption for the brand to track.Allowable Values: 255 char max |
| amount decimal Returned | Amount to redeem. Allowable Values: Format: 0.00 |
| conversion_rate decimal Conditionally returned | Rate that points are worth when converting them using the REDEMPTION_TYPE indicated.Allowable Values: 0.001 min Format: 0.000 |
| currency string Conditionally returned | Type of currency used for the conversion rate. Three-digit ISO 4217 currency code. Allowable Values: Any currency code allowed by your program |
| note string Conditionally returned | Note explaining why the reward is being redeemed. Allowable Values: 255 char max |
| sor_reward_token string Conditionally returned | Unique identifier of the system of reward (SOR) reward that was created to represent the reward redemption as a STATEMENT_CREDIT on a credit account. The SOR entry is a positive amount that is added to the account balance.Allowable Values: 36 char max |
| external_settlement_date_time datetime Conditionally returned | Date and time when the reward redemption was settled on your external platform, in UTC. This field is returned if you handled the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| receiving_account_token string Conditionally returned | Unique identifier of the external account receiving the reward redemption. This token is the payment source token. Allowable Values: 36 char max |
| created_time datetime Returned | 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 Conditionally returned | Date and time when the reward redemption was updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"token": "c21b04ad-37de-4433-890a-3cece8adefc7",
"type": "EXTERNAL",
"amount": 1000,
"conversion_rate": 1.5,
"destination": "BRAND_WALLET",
"note": "Redeeming reward balance to Brand Wallet at brand conversion rate 1.5 per point",
"created_time": "2024-01-05T20:37:11Z"
}
List reward redemptions
Action:GETEndpoint:
/credit/rewards/accounts/{token}/redemptions
Retrieve an array of reward redemptions 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 |
| type string Optional | Type of reward redemptions in the returned array. Allowable Values: EXTERNAL, STATEMENT_CREDIT |
Response body
| Fields | Description |
|---|---|
| data array of objects Conditionally returned | List containing one or more redemptions. Allowable Values: Valid array of one or more redemption objects |
| data[].token string Returned | Unique identifier of the reward redemption. Allowable Values: 36 char max |
| data[].type string 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 |
| data[].destination string Conditionally returned | Destination of the EXTERNAL redemption for the brand to track.Allowable Values: 255 char max |
| data[].amount decimal Returned | Amount to redeem. Allowable Values: Format: 0.00 |
| data[].conversion_rate decimal Conditionally returned | Rate that points are worth when converting them using the REDEMPTION_TYPE indicated.Allowable Values: 0.001 min Format: 0.000 |
| data[].currency string Conditionally returned | Type of currency used for the conversion rate. Three-digit ISO 4217 currency code. Allowable Values: Any currency code allowed by your program |
| data[].note string Conditionally returned | Note explaining why the reward is being redeemed. Allowable Values: 255 char max |
| data[].sor_reward_token string Conditionally returned | Unique identifier of the system of reward (SOR) reward that was created to represent the reward redemption as a STATEMENT_CREDIT on a credit account. The SOR entry is a positive amount that is added to the account balance.Allowable Values: 36 char max |
| data[].external_settlement_date_time datetime Conditionally returned | Date and time when the reward redemption was settled on your external platform, in UTC. 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[].receiving_account_token string Conditionally returned | Unique identifier of the external account receiving the reward redemption. This token is the payment source token. Allowable Values: 36 char max |
| data[].created_time datetime Returned | 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 Conditionally returned | Date and time when the reward redemption was updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| count integer Conditionally returned | Number of resources returned. Allowable Values: 1–100 |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. Allowable Values: Any integer |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist.Allowable Values: true, false |
Sample response body
JSON
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "c21b04ad-37de-4433-890a-3cece8adefc7",
"type": "EXTERNAL",
"amount": 10000,
"conversion_rate": 1.5,
"currency": "USD",
"destination": "BRAND_WALLET",
"note": "Redeeming reward balance to Brand Wallet at brand conversion rate 1.5 cents per point.",
"created_time": "2024-01-01T20:37:11Z"
},
{
"token": "132fb632-1197-4d01-9eca-bee3ac2e7502",
"type": "STATEMENT_CREDIT",
"amount": 5000,
"conversion_rate": 0.01,
"note": "Redeeming reward balance to Statement Credit 1 cent for every 1 point",
"created_time": "2024-01-02T20:37:11Z"
},
{
"token": "7d34d209-e350-4bca-a678-29b9fbfe45d5",
"type": "EXTERNAL",
"amount": 900,
"conversion_rate": 1.3,
"destination": "MILEAGE_PLUS",
"note": "Redeeming reward balance to MILEAGE_PLUS Program at a conversion rate of 1.3 miles per point",
"receiving_account_token": "c21b04ad-37de-4433-890a-3cece8adefc7",
"created_time": "2024-01-05T20:37:11Z"
}
]
}
Retrieve reward redemption
Action:GETEndpoint:
/credit/rewards/accounts/{token}/redemptions/{redemption_token}
Retrieve a specific redemption for a specific reward accounts.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
| redemption_token string Required | Unique identifier of the reward redemption. Allowable Values: Existing redemption token |
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the reward redemption. Allowable Values: 36 char max |
| type string 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 |
| destination string Conditionally returned | Destination of the EXTERNAL redemption for the brand to track.Allowable Values: 255 char max |
| amount decimal Returned | Amount to redeem. Allowable Values: Format: 0.00 |
| conversion_rate decimal Conditionally returned | Rate that points are worth when converting them using the REDEMPTION_TYPE indicated.Allowable Values: 0.001 min Format: 0.000 |
| currency string Conditionally returned | Type of currency used for the conversion rate. Three-digit ISO 4217 currency code. Allowable Values: Any currency code allowed by your program |
| note string Conditionally returned | Note explaining why the reward is being redeemed. Allowable Values: 255 char max |
| sor_reward_token string Conditionally returned | Unique identifier of the system of reward (SOR) reward that was created to represent the reward redemption as a STATEMENT_CREDIT on a credit account. The SOR entry is a positive amount that is added to the account balance.Allowable Values: 36 char max |
| external_settlement_date_time datetime Conditionally returned | Date and time when the reward redemption was settled on your external platform, in UTC. This field is returned if you handled the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| receiving_account_token string Conditionally returned | Unique identifier of the external account receiving the reward redemption. This token is the payment source token. Allowable Values: 36 char max |
| created_time datetime Returned | 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 Conditionally returned | Date and time when the reward redemption was updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"token": "7d34d209-e350-4bca-a678-29b9fbfe45d5",
"type": "EXTERNAL",
"destination": "MILEAGE_PLUS",
"amount": 900,
"conversion_rate": 1.3,
"note": "Redeeming reward balance to MILEAGE_PLUS Program at a rate of 1.3 miles per point",
"created_time": "2024-01-05T20:37:11Z",
"update_time": "2024-01-05T20:37:11Z"
}
Modify existing redemption
Action:PUTEndpoint:
/credit/rewards/accounts/{token}/redemptions/{redemption_token}
Modify existing redemption.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the reward account. Allowable Values: Existing reward account token |
| redemption_token string Required | Unique identifier of the reward redemption. Allowable Values: Existing redemption token |
Request body
| Fields | Description |
|---|---|
| note string Optional | Note explaining why the reward is being redeemed. Allowable Values: 255 char max |
| external_settlement_date_time datetime Optional | Date and time when the reward redemption was settled on the external platform. This field is returned if the reward redemption was handled outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample request body
JSON
{
"external_settlement_date_time": "2024-01-06T20:37:11Z"
}
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the reward redemption. Allowable Values: 36 char max |
| type string 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 |
| destination string Conditionally returned | Destination of the EXTERNAL redemption for the brand to track.Allowable Values: 255 char max |
| amount decimal Returned | Amount to redeem. Allowable Values: Format: 0.00 |
| conversion_rate decimal Conditionally returned | Rate that points are worth when converting them using the REDEMPTION_TYPE indicated.Allowable Values: 0.001 min Format: 0.000 |
| currency string Conditionally returned | Type of currency used for the conversion rate. Three-digit ISO 4217 currency code. Allowable Values: Any currency code allowed by your program |
| note string Conditionally returned | Note explaining why the reward is being redeemed. Allowable Values: 255 char max |
| sor_reward_token string Conditionally returned | Unique identifier of the system of reward (SOR) reward that was created to represent the reward redemption as a STATEMENT_CREDIT on a credit account. The SOR entry is a positive amount that is added to the account balance.Allowable Values: 36 char max |
| external_settlement_date_time datetime Conditionally returned | Date and time when the reward redemption was settled on your external platform, in UTC. This field is returned if you handled the reward redemption outside of Marqeta’s credit platform. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| receiving_account_token string Conditionally returned | Unique identifier of the external account receiving the reward redemption. This token is the payment source token. Allowable Values: 36 char max |
| created_time datetime Returned | 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 Conditionally returned | Date and time when the reward redemption was updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
JSON
{
"token": "7d34d209-e350-4bca-a678-29b9fbfe45d5",
"type": "EXTERNAL",
"destination": "MILEAGE_PLUS",
"amount": 900,
"conversion_rate": 1.3,
"note": "Redeeming reward balance to MILEAGE_PLUS Program at a rate of 1.3 miles per point",
"external_settlement_date_time": "2024-01-05T20:37:11Z",
"receiving_account_token": "c21b04ad-37de-4433-890a-3cece8adefc7",
"created_time": "2024-01-05T20:37:11Z",
"updated_time": "2024-01-06T20:37:11Z"
}
Retrieve reward redemption balance
Action:GETEndpoint:
/credit/rewards/accounts/{token}/redemptions/balance
Retrieve redemption amounts for a specified date range by redemption type.
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 |
|---|---|
| start_date datetime Conditionally returned | Starting date and 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 Conditionally returned | Ending date and time of a date range from which to return the redemption balance, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
| redemptions array of objects Conditionally returned | List of each redemption total by type. Allowable Values: Valid array of one or more redemption objects |
| redemptions[].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 |
| redemptions[].destination string Conditionally returned | The brand-managed program to which the reward balance was redeemed. Allowable Values: 255 char max |
| redemptions[].point_redeemed decimal Conditionally returned | Total points redeemed for redemption type for a reward account. Allowable Values: Any integer |
Sample response body
JSON
{
"start_date": "2023-01-05T20:37:11Z",
"end_date": "2024-01-05T20:37:11Z",
"redemptions": [
{
"type": "EXTERNAL",
"destination": "BRAND_WALLET",
"points_redeemed": 100000
},
{
"type": "EXTERNAL",
"destination": "MILEAGE_PLUS",
"points_redeemed": 5000
},
{
"type": "STATEMENT_CREDIT",
"points_redeemed": 5000
}
],
"retrieved_time": "2024-01-05T20:37:11Z"
}