Skip to main content
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.
Use the /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: POST
Endpoint: /credit/rewards/accounts/{token}/redemptions Create a reward redemption for a specific reward account.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the reward account.

Allowable Values:

Existing reward account token

​
Request body

FieldsDescription
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

FieldsDescription
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: GET
Endpoint: /credit/rewards/accounts/{token}/redemptions Retrieve an array of reward redemptions for a specific reward account.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the reward account.

Allowable Values:

Existing reward account token

​
URL query parameters

FieldsDescription
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

FieldsDescription
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: GET
Endpoint: /credit/rewards/accounts/{token}/redemptions/{redemption_token} Retrieve a specific redemption for a specific reward accounts.

​
URL path parameters

FieldsDescription
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

FieldsDescription
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: PUT
Endpoint: /credit/rewards/accounts/{token}/redemptions/{redemption_token} Modify existing redemption.

​
URL path parameters

FieldsDescription
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

FieldsDescription
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

FieldsDescription
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: GET
Endpoint: /credit/rewards/accounts/{token}/redemptions/balance Retrieve redemption amounts for a specified date range by redemption type.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the reward account.

Allowable Values:

Existing reward account token

​
URL query parameters

FieldsDescription
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

FieldsDescription
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"
}

Related topics

About Reward AccountsReward AccountsAccount RewardsCredit RewardsReward Global Configurations