/
25 minute read
April 6, 2023

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

Action: POST
Endpoint: /credit/rewardprograms/{token}/redemptions

Create a redemption to redeem rewards on a specific reward program.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the reward program.

Allowable Values:

Existing reward program 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 program 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.

  • ACH - The reward redemption is issued as an ACH transfer to the receiving account.

Allowable Values:

EXTERNAL, STATEMENT_CREDIT, ACH

destination

string
Optional

Destination of the reward redemption.

  • INVESTMENT - The redemption is paid into an investment account.

  • WALLET - The redemption is paid into a digital wallet.

  • ACH - The redemption is paid into an ACH account.

Required for external redemptions.

Allowable Values:

INVESTMENT, WALLET, ACH

amount

decimal
Required

Amount of the reward redemption.

Allowable Values:

0 min

Format: 0.00

note

string
Optional

A note explaining why the reward is being redeemed.

Allowable Values:

255 char max

receiving_account_token

string
Optional

Unique identifier of the external account receiving the reward redemption. This token is equivalent to the payment source token.

Allowable Values:

36 char max

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

token

string
Returned

Unique identifier of the reward redemption.

Allowable Values:

36 char max

reward_program_token

string
Returned

Unique identifier of the reward program for which to redeem rewards.

Allowable Values:

36 char max

type

string
Returned

Type of redemption.

  • EXTERNAL - You issue the redemption on your external platform; Marqeta adjusts the reward program 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.

  • ACH - The reward redemption is issued as an ACH transfer to the receiving account.

Allowable Values:

EXTERNAL, STATEMENT_CREDIT, ACH

destination

string
Conditionally returned

Destination of the reward redemption.

  • INVESTMENT - The redemption is paid into an investment account.

  • WALLET - The redemption is paid into a digital wallet.

  • ACH - The redemption is paid into an ACH account.

Required for external redemptions.

Allowable Values:

INVESTMENT, WALLET, ACH

amount

decimal
Returned

Amount to redeem.

Allowable Values:

Format: 0.00

status

string
Returned

Status of the redemption.

  • new_state is the state to which you want to transition the redemption; must be COMPLETED or RETURNED.

  • initial_status is the initial status of the redemption prior to transition.

Allowable Values:

INITIATED, COMPLETED, RETURNED, PROCESSING, SUBMITTED

note

string
Returned

Allowable Values:

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.

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
Conditionally returned

Contains one or more reward entries related to the redemption.

Allowable Values:

One or more related_reward_entries objects

related_reward_entries[].token

string
Returned

Unique identifier of the reward entry.

Allowable Values:

36 char max

related_reward_entries[].reward_program_token

string
Returned

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
Returned

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
Returned

Status of the reward entry.

Allowable Values:

PENDING, POSTED

related_reward_entries[].transaction_amount

decimal
Returned

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
Conditionally returned

Value of the reward entry.

Allowable Values:

Format: 0.00

related_reward_entries[].mcc

string
Conditionally returned

Merchant category code (MCC) of the related journal entry.

Allowable Values:

Existing MCC

related_reward_entries[].mid

string
Conditionally returned

Merchant identifier (MID) of the related journal entry.

Allowable Values:

related_reward_entries[].related_journal_entry_token

string
Returned

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
Conditionally returned

Unique identifier of the related redemption token that triggered the reward entry.

Allowable Values:

36 char max

related_reward_entries[].note

string
Returned

A note providing information on the reward entry.

Allowable Values:

255 char max

related_reward_entries[].created_time

datetime
Returned

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
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
Returned

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
Conditionally returned

Unique identifier of the external account receiving the reward redemption. This token is equivalent to the payment source token.

Allowable Values:

36 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

List reward redemptions

Action: GET
Endpoint: /credit/rewardprograms/{token}/redemptions

Retrieve an array of reward redemptions for a specific reward program.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the reward program.

Allowable Values:

Existing reward program token

URL query parameters

Fields Description

start_date

datetime
Optional

The starting date (or date-time) of a date range from which to return resources, in UTC.

Allowable Values:

end_date

datetime
Optional

The ending date (or date-time) of a date range from which to return resources, in UTC.

Allowable Values:

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

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, and not by the field names appearing 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, ACH

Response body

Fields Description

data

array of objects
Conditionally returned

Contains one or more redemptions.

Allowable Values:

One or more redemption objects.

data[].token

string
Returned

Unique identifier of the reward redemption.

Allowable Values:

36 char max

data[].reward_program_token

string
Returned

Unique identifier of the reward program for which to redeem rewards.

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 program 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.

  • ACH - The reward redemption is issued as an ACH transfer to the receiving account.

Allowable Values:

EXTERNAL, STATEMENT_CREDIT, ACH

data[].destination

string
Conditionally returned

Destination of the reward redemption.

  • INVESTMENT - The redemption is paid into an investment account.

  • WALLET - The redemption is paid into a digital wallet.

  • ACH - The redemption is paid into an ACH account.

Required for external redemptions.

Allowable Values:

INVESTMENT, WALLET, ACH

data[].amount

decimal
Returned

Amount to redeem.

Allowable Values:

Format: 0.00

data[].status

string
Returned

Status of the redemption.

  • new_state is the state to which you want to transition the redemption; must be COMPLETED or RETURNED.

  • initial_status is the initial status of the redemption prior to transition.

Allowable Values:

INITIATED, COMPLETED, RETURNED, PROCESSING, SUBMITTED

data[].note

string
Returned

Allowable Values:

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.

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
Conditionally returned

Contains one or more reward entries related to the redemption.

Allowable Values:

One or more related_reward_entries objects

data[].related_reward_entries[].token

string
Returned

Unique identifier of the reward entry.

Allowable Values:

36 char max

data[].related_reward_entries[].reward_program_token

string
Returned

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
Returned

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
Returned

Status of the reward entry.

Allowable Values:

PENDING, POSTED

data[].related_reward_entries[].transaction_amount

decimal
Returned

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
Conditionally returned

Value of the reward entry.

Allowable Values:

Format: 0.00

data[].related_reward_entries[].mcc

string
Conditionally returned

Merchant category code (MCC) of the related journal entry.

Allowable Values:

Existing MCC

data[].related_reward_entries[].mid

string
Conditionally returned

Merchant identifier (MID) of the related journal entry.

Allowable Values:

data[].related_reward_entries[].related_journal_entry_token

string
Returned

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
Conditionally returned

Unique identifier of the related redemption token that triggered the reward entry.

Allowable Values:

36 char max

data[].related_reward_entries[].note

string
Returned

A note providing information on the reward entry.

Allowable Values:

255 char max

data[].related_reward_entries[].created_time

datetime
Returned

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
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
Returned

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
Conditionally returned

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
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
Copied

Is this helpful?

Yes
No

Retrieve reward redemption

Action: GET
Endpoint: /credit/rewardprograms/{token}/redemptions/{redemption_token}

Retrieve a specific redemption for a specific reward program.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the reward program.

Allowable Values:

Existing reward program 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

reward_program_token

string
Returned

Unique identifier of the reward program for which to redeem rewards.

Allowable Values:

36 char max

type

string
Returned

Type of redemption.

  • EXTERNAL - You issue the redemption on your external platform; Marqeta adjusts the reward program 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.

  • ACH - The reward redemption is issued as an ACH transfer to the receiving account.

Allowable Values:

EXTERNAL, STATEMENT_CREDIT, ACH

destination

string
Conditionally returned

Destination of the reward redemption.

  • INVESTMENT - The redemption is paid into an investment account.

  • WALLET - The redemption is paid into a digital wallet.

  • ACH - The redemption is paid into an ACH account.

Required for external redemptions.

Allowable Values:

INVESTMENT, WALLET, ACH

amount

decimal
Returned

Amount to redeem.

Allowable Values:

Format: 0.00

status

string
Returned

Status of the redemption.

  • new_state is the state to which you want to transition the redemption; must be COMPLETED or RETURNED.

  • initial_status is the initial status of the redemption prior to transition.

Allowable Values:

INITIATED, COMPLETED, RETURNED, PROCESSING, SUBMITTED

note

string
Returned

Allowable Values:

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.

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
Conditionally returned

Contains one or more reward entries related to the redemption.

Allowable Values:

One or more related_reward_entries objects

related_reward_entries[].token

string
Returned

Unique identifier of the reward entry.

Allowable Values:

36 char max

related_reward_entries[].reward_program_token

string
Returned

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
Returned

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
Returned

Status of the reward entry.

Allowable Values:

PENDING, POSTED

related_reward_entries[].transaction_amount

decimal
Returned

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
Conditionally returned

Value of the reward entry.

Allowable Values:

Format: 0.00

related_reward_entries[].mcc

string
Conditionally returned

Merchant category code (MCC) of the related journal entry.

Allowable Values:

Existing MCC

related_reward_entries[].mid

string
Conditionally returned

Merchant identifier (MID) of the related journal entry.

Allowable Values:

related_reward_entries[].related_journal_entry_token

string
Returned

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
Conditionally returned

Unique identifier of the related redemption token that triggered the reward entry.

Allowable Values:

36 char max

related_reward_entries[].note

string
Returned

A note providing information on the reward entry.

Allowable Values:

255 char max

related_reward_entries[].created_time

datetime
Returned

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
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
Returned

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
Conditionally returned

Unique identifier of the external account receiving the reward redemption. This token is equivalent to the payment source token.

Allowable Values:

36 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve reward redemption balance

Action: GET
Endpoint: /credit/rewardprograms/{token}/redemptions/balance

Retrieve the balance for reward redemptions within a specified date range.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the reward program.

Allowable Values:

Existing reward program token

URL query parameters

Fields Description

start_date

datetime
Optional

The starting date (or date-time) of a date range from which to return resources, in UTC.

Allowable Values:

end_date

datetime
Optional

The ending date (or date-time) of a date range from which to return resources, in UTC.

Allowable Values:

type

array of strings
Optional

Type of reward redemptions in the returned array.

Allowable Values:

EXTERNAL, STATEMENT_CREDIT, ACH

Response body

Fields Description

reward_program_token

string
Returned

Unique identifier of the reward program for which to return the redemption balance.

Allowable Values:

36 char max

redemption_total_amount

decimal
Returned

Total amount of rewards redeemed within a specified date range.

Allowable Values:

start_date

datetime
Returned

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
Returned

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

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Transition reward redemption status

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

Fields Description

token

string
Required

Unique identifier of the reward program.

Allowable Values:

Existing reward program token

redemption_token

string
Required

Unique identifier of the reward redemption.

Allowable Values:

Existing redemption token

Request body

Fields Description

new_state

string
Required

Status of the redemption.

  • new_state is the state to which you want to transition the redemption; must be COMPLETED or RETURNED.

  • initial_status is the initial status of the redemption prior to transition.

Allowable Values:

INITIATED, COMPLETED, RETURNED, PROCESSING, SUBMITTED

external_settlement_date_time

datetime
Optional

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

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

token

string
Returned

Unique identifier of the reward redemption transition.

Allowable Values:

36 char max

redemption_token

string
Returned

Unique identifier of the redemption whose status was transitioned.

Allowable Values:

36 char max

initial_status

string
Returned

Status of the redemption.

  • new_state is the state to which you want to transition the redemption; must be COMPLETED or RETURNED.

  • initial_status is the initial status of the redemption prior to transition.

Allowable Values:

INITIATED, COMPLETED, RETURNED, PROCESSING, SUBMITTED

new_status

string
Returned

Status of the redemption.

  • new_state is the state to which you want to transition the redemption; must be COMPLETED or RETURNED.

  • initial_status is the initial status of the redemption prior to transition.

Allowable Values:

INITIATED, COMPLETED, RETURNED, PROCESSING, SUBMITTED

external_settlement_date_time

datetime
Conditionally returned

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
Returned

Date and time when the reward redemption transition was created on Marqeta’s credit platform.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter