Reward Accounts

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} endpoint to manage reward accounts and track rewards balances, accruals, and entries on a credit account. The configurations for a reward account are defined in the reward policy on the account’s associated bundle. To receive webhook notifications when reward accounts and reward entry events occur, see Credit reward entry events in Event Types.

List reward accounts

Action: GET
Endpoint: /credit/rewards/accounts Retrieve a list of reward accounts.

URL query parameters

Fields	Description
credit_account_token string Optional	Unique identifier of the credit account for which you want to retrieve reward accounts. Allowable Values: Existing credit account token
is_active boolean Optional	A value of `true` returns active resources. A value of `false` returns inactive resources. Allowable Values: `true`, `false`
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_updated 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 `updatedTime`. Do not sort by field names that appear in response bodies, such as `updated_time`. Allowable Values: `updatedTime`, `-updatedTime`

Response body

Fields	Description
count integer Returned	Number of resources returned. Allowable Values: 1–100
start_index integer Returned	Sort order index of the first resource in the returned array. Allowable Values: Any integer
end_index integer Returned	Sort order index of the last resource in the returned array. Allowable Values: Any integer
is_more boolean Returned	A value of `true` indicates that more unreturned resources exist. Allowable Values: `true`, `false`
data array of objects Returned	List of reward account objects. Allowable Values: Valid array of one or more reward account objects
data[].token string Returned	Unique identifier of the reward account. Allowable Values: 36 char max
data[].credit_account_token string Returned	Unique identifier of the associated credit account. Allowable Values: 36 char max
data[].bundle_token string Conditionally returned	Unique identifier of the associated bundle that contains the reward policy on which the reward account is based. Allowable Values: 36 char max
data[].is_active boolean Returned	A value of `true` indicates that the reward account is active. Allowable Values: `true`, `false`
data[].global_rules array of objects Conditionally returned	List of global rules. Allowable Values: Valid array of one or more global rules
data[].global_rules[].rule_token string Conditionally returned	Unique identifier of the rule. Allowable Values: 36 char max
data[].global_rules[].description string Conditionally returned	Description of the rule, pulled from the rule entry. Allowable Values: 255 char max
data[].created_time datetime Returned	Date and time when the reward account 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 account was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "4829608d-97e4-4a8c-bdab-20b26e7f243d",
      "credit_account_token": "bbf6c086-4286-4a1c-a3dd-2f54bf6fd799",
      "bundle_token": "f0cf97cb-76f7-47a5-83e7-188b9e741cf9",
      "is_active": true,
      "created_time": "2024-01-05T20:37:11Z",
      "updated_time": "2024-01-05T20:37:11Z"
    }
  ]
}

Retrieve reward account

Action: GET
Endpoint: /credit/rewards/accounts/{token} Retrieve 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
expand array of strings Optional	Embeds the specified object into the response `GLOBAL_RULES`. Allowable Values: `RULES`

Response body

Fields	Description
token string Returned	Unique identifier of the reward account. Allowable Values: 36 char max
credit_account_token string Returned	Unique identifier of the associated credit account. Allowable Values: 36 char max
bundle_token string Conditionally returned	Unique identifier of the associated bundle that contains the reward policy on which the reward account is based. Allowable Values: 36 char max
is_active boolean Returned	A value of `true` indicates that the reward account is active. Allowable Values: `true`, `false`
global_rules array of objects Conditionally returned	List of global rules. Allowable Values: Valid array of one or more global rules
global_rules[].rule_token string Conditionally returned	Unique identifier of the rule. Allowable Values: 36 char max
global_rules[].description string Conditionally returned	Description of the rule, pulled from the rule entry. Allowable Values: 255 char max
created_time datetime Returned	Date and time when the reward account 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 account was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "4829608d-97e4-4a8c-bdab-20b26e7f243d",
  "credit_account_token": "bbf6c086-4286-4a1c-a3dd-2f54bf6fd799",
  "bundle_token": "f0cf97cb-76f7-47a5-83e7-188b9e741cf9",
  "is_active": true,
  "global_rules": [
    {
      "rule_token": "00fb5637-2dab-4833-aa12-0463e7cf8cbb",
      "description": "Earn 3x on agricultural services, contracted services, and purchases at Target."
    }
  ],
  "created_time": "2024-01-05T20:37:11Z",
  "updated_time": "2024-01-05T20:37:11Z"
}

Update active state

Action: PUT
Endpoint: /credit/rewards/accounts/{token} Update a reward account’s active state.

URL path parameters

Fields	Description
token string Required	Unique identifier of the reward account. Allowable Values: Existing reward account token

Request body

Fields	Description
is_active boolean Optional	A value of `true` indicates that the reward account is active and rewards can be accrued for the associated account. Allowable Values: `true`, `false`

Sample request body

JSON

{
  "is_active": false
}

Response body

Fields	Description
token string Returned	Unique identifier of the reward account. Allowable Values: 36 char max
credit_account_token string Returned	Unique identifier of the associated credit account. Allowable Values: 36 char max
bundle_token string Conditionally returned	Unique identifier of the associated bundle that contains the reward policy on which the reward account is based. Allowable Values: 36 char max
is_active boolean Returned	A value of `true` indicates that the reward account is active. Allowable Values: `true`, `false`
global_rules array of objects Conditionally returned	List of global rules. Allowable Values: Valid array of one or more global rules
global_rules[].rule_token string Conditionally returned	Unique identifier of the rule. Allowable Values: 36 char max
global_rules[].description string Conditionally returned	Description of the rule, pulled from the rule entry. Allowable Values: 255 char max
created_time datetime Returned	Date and time when the reward account 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 account was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "4829608d-97e4-4a8c-bdab-20b26e7f243d",
  "credit_account_token": "bbf6c086-4286-4a1c-a3dd-2f54bf6fd799",
  "bundle_token": "f0cf97cb-76f7-47a5-83e7-188b9e741cf9",
  "is_active": true,
  "created_time": "2024-01-05T20:37:11Z",
  "updated_time": "2024-01-05T20:37:11Z"
}

Retrieve reward account balances

Action: GET
Endpoint: /credit/rewards/accounts/{token}/balances Retrieve rewards balances 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

Response body

Fields	Description
billing_cycle_opening_date datetime Returned	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 Returned	Closing date of the billing cycle for which rewards were accrued, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
total_spend_this_cycle decimal Returned	Total amount spent during a given billing cycle, minus any refunds or disputes, even if transactions did not result in a reward. Used to determine reward accrual. Allowable Values: Format: 0.00
points_balance object Returned	Pending and total accrual balance (in points) for the reward account. Allowable Values: `accrued_this_cycle`, `total_reward_balance`
points_balance.accrued_this_cycle decimal Returned	Pending balance (in points) for a reward account. Allowable Values: Any integer
points_balance.total_reward_balance decimal Returned	Total reward balance (in points) for a reward account. Allowable Values: Any integer
reward_values array of objects Returned	List of possible reward conversion values. Allowable Values: Valid array of one or more `reward_values` objects
reward_values[].redemption_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`
reward_values[].conversion_rate decimal Returned	Conversion rate of the reward account’s points, if they were used for this redemption type. Allowable Values: 0.001 min Format: 0.000
reward_values[].conversion_increment decimal Returned	Allowed point increments that the reward account must have to use this redemption type. Allowable Values: Any integer
retrieved_time datetime Conditionally returned	Retrieval date of the reward account’s accrual balance, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "billing_cycle_opening_date": "2023-12-25T20:37:11Z",
  "billing_cycle_closing_date": "2024-01-24T20:37:11Z",
  "total_spend_this_cycle": 5832,
  "points_balance": {
    "accrued_this_cycle": 10000,
    "total_reward_balance": 25000
  },
  "reward_values": [
    {
      "redemption_type": "STATEMENT_CREDIT",
      "conversion_rate": 0.001,
      "conversion_increment": 10
    }
  ],
  "retrieved_time": "2024-01-05T20:37:11Z"
}

Retrieve reward account accruals

Action: GET
Endpoint: /credit/rewards/accounts/{token}/accruals Use this endpoint to retrieve the reward accounts rewards accrual by rule for a specified time frame. If you do not specify a time frame in your query parameters, the query defaults to the current billing cycle.

URL path parameters

Fields	Description
token string Required	Unique identifier of the reward account. Allowable Values: Existing reward account token

Response body

Fields	Description
start_date datetime Conditionally returned	Start date of rewards accrual retrieval, in UTC. Defaults to the billing cycle closing date. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
end_date datetime Conditionally returned	End date of rewards accrual retrieval, in UTC. Defaults to the billing cycle closing date. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
rules array of objects Conditionally returned	List of accrual information by rule. Allowable Values: Valid array of one or more rule accrual objects
rules[].description string Conditionally returned	Description of the rule, pulled from the rule entry. Allowable Values: 255 char max
rules[].total_spend decimal Conditionally returned	Total spend contributed to the reward accrual for this rule. Allowable Values: Any integer
rules[].total_rewards_earned decimal Conditionally returned	Total settled rewards accrued against the rule. Allowable Values: Any integer
retrieved_time datetime Conditionally returned	Retrieval date of the reward account’s accruals, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "start_date": "2023-12-25T20:37:11Z",
  "end_date": "2024-01-24T20:37:11Z",
  "rules": [
    {
      "description": "Earn 3x on agricultural services, contracted services, and purchases at Target.",
      "total_spend": 12300,
      "total_rewards_earned": 30000
    },
    {
      "description": "Earn 5x on Lyft, up to $500.",
      "total_spend": 600,
      "total_rewards_earned": 2500
    },
    {
      "description": "Earn 50 points by spending $50 at Target.",
      "total_spend": 2500,
      "total_rewards_earned": 50
    },
    {
      "description": "Earn one point on all transactions.",
      "total_spend": 5863,
      "total_rewards_earned": 5000
    }
  ],
  "retrieved_time": "2024-01-05T20:37:11Z"
}

Create reward entry

Action: POST
Endpoint: /credit/rewards/accounts/{token}/entries Create a reward entry 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 entry. Allowable Values: 36 char max
value decimal Required	Value of the reward granted to the account. Allowable Values: 0.001 min Format: 0.000
note string Required	Note explaining why the reward entry is being created. Allowable Values: 255 char max
created_time datetime Optional	Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample request body

JSON

{
  "value": 5000,
  "note": "Account awarded 5000 bonus points for completing customer feedback survey."
}

Response body

Fields	Description
token string Returned	Unique identifier of the reward entry. Allowable Values: 36 char max
reward_account_token string Returned	Unique identifier of the reward account for which to return reward entries. Allowable Values: 36 char max
rule_token string Conditionally returned	Unique identifier of the rule used to determine the value of the reward entry. Allowable Values: 36 char max
transaction_amount decimal Conditionally returned	Transaction amount to which the rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00
value decimal Returned	Value of the reward entry. Allowable Values: Format: 0.00
related_journal_entry_token string Conditionally returned	Unique identifier of the related journal entry to which the rule was applied that triggered the reward entry. Allowable Values: 36 char max Existing journal entry token
related_redemption_token string Conditionally returned	Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max
related_entry_token string Conditionally returned	Unique identifier of the related reward entry token for a given dispute. Allowable Values: 36 char max
note string Returned	Note providing information on the reward entry. Allowable Values: 255 char max
created_time datetime Conditionally returned	Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "948d82d0-2f6f-46e9-bfa2-68e0f2e1192a",
  "reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
  "value": 5000,
  "note": "Account completed customer feedback survey for 5000 bonus points.",
  "created_time": "2024-01-04T20:37:11Z"
}

List reward entries for a reward account

Action: GET
Endpoint: /credit/rewards/accounts/{token}/entries Retrieve an array of reward entries 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`
status string Required	Status of the reward entries in the returned array. Allowable Values: `PENDING`, `POSTED`

Response body

Fields	Description
count integer Returned	Number of resources returned. Allowable Values: 1–100
start_index integer Returned	Sort order index of the first resource in the returned array. Allowable Values: Any integer
end_index integer Returned	Sort order index of the last resource in the returned array. Allowable Values: Any integer
is_more boolean Returned	A value of `true` indicates that more unreturned resources exist. Allowable Values: `true`, `false`
data array of objects Returned	List of reward entry objects. Allowable Values: Valid array of one or more reward entry objects
data[].token string Returned	Unique identifier of the reward entry. Allowable Values: 36 char max
data[].reward_account_token string Returned	Unique identifier of the reward account for which to return reward entries. Allowable Values: 36 char max
data[].rule_token string Conditionally returned	Unique identifier of the rule used to determine the value of the reward entry. Allowable Values: 36 char max
data[].transaction_amount decimal Conditionally returned	Transaction amount to which the rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00
data[].value decimal Returned	Value of the reward entry. Allowable Values: Format: 0.00
data[].related_journal_entry_token string Conditionally returned	Unique identifier of the related journal entry to which the rule was applied that triggered the reward entry. Allowable Values: 36 char max Existing journal entry token
data[].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_entry_token string Conditionally returned	Unique identifier of the related reward entry token for a given dispute. Allowable Values: 36 char max
data[].note string Returned	Note providing information on the reward entry. Allowable Values: 255 char max
data[].created_time datetime Conditionally returned	Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "count": 5,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "12959312-675e-44e9-b6be-9dc7a0d996bd",
      "reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
      "rule_token": "b125a2ea-477d-410f-b6a1-283b8eddb3cd",
      "transaction_amount": 100,
      "value": 200,
      "note": "Account awarded 5000 bonus points for completing customer feedback survey.",
      "related_journal_entry_token": "64794ba4-9094-466f-b11a-b3d1daf17293",
      "created_time": "2024-01-01T20:37:11Z"
    },
    {
      "token": "12959312-675e-44e9-b6be-9dc7a0d996bd",
      "reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
      "rule_token": "b125a2ea-477d-410f-b6a1-283b8eddb3cd",
      "transaction_amount": 500,
      "value": 50,
      "note": "Account awarded 5000 bonus points for completing customer feedback survey.",
      "related_journal_entry_token": "64794ba4-9094-466f-b11a-b3d1daf17293",
      "related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
      "created_time": "2024-01-02T20:37:11Z"
    },
    {
      "token": "4391dd08-b91f-47be-8577-dc080d4e51a5",
      "reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
      "rule_token": "5fd9cb86-1ecf-4eb9-beea-db308b051797",
      "value": 200,
      "note": "Account awarded 5000 bonus points for completing customer feedback survey.",
      "created_time": "2024-01-03T20:37:11Z"
    },
    {
      "token": "4d0ff4ee-ee97-48a8-9494-70edcf456aab",
      "reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
      "value": 20000,
      "related_journal_entry_token": "64794ba4-9094-466f-b11a-b3d1daf17293",
      "related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
      "note": "Customer called in, one time reward for error in statement.",
      "created_time": "2024-01-04T20:37:11Z"
    },
    {
      "token": "1417c942-2eba-4238-ac44-d04db1f411cd",
      "reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
      "value": -1000,
      "note": "Account awarded 5000 bonus points for completing customer feedback survey.",
      "related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
      "created_time": "2024-01-04T20:37:11Z"
    }
  ]
}

Retrieve reward entry

Action: GET
Endpoint: /credit/rewards/accounts/{token}/entries/{entry_token} Retrieve a specific reward entry for a reward account.

URL path parameters

Fields	Description
entry_token string Required	Unique identifier of the reward entry to retrieve. Allowable Values: 36 char max
token string Required	Unique identifier of the reward account. Allowable Values: Existing reward account token

Response body

Fields	Description
token string Returned	Unique identifier of the reward entry. Allowable Values: 36 char max
reward_account_token string Returned	Unique identifier of the reward account for which to return reward entries. Allowable Values: 36 char max
rule_token string Conditionally returned	Unique identifier of the rule used to determine the value of the reward entry. Allowable Values: 36 char max
transaction_amount decimal Conditionally returned	Transaction amount to which the rule was applied. Used to determine the value of the reward entry. Allowable Values: Format: 0.00
value decimal Returned	Value of the reward entry. Allowable Values: Format: 0.00
related_journal_entry_token string Conditionally returned	Unique identifier of the related journal entry to which the rule was applied that triggered the reward entry. Allowable Values: 36 char max Existing journal entry token
related_redemption_token string Conditionally returned	Unique identifier of the related redemption token that triggered the reward entry. Allowable Values: 36 char max
related_entry_token string Conditionally returned	Unique identifier of the related reward entry token for a given dispute. Allowable Values: 36 char max
note string Returned	Note providing information on the reward entry. Allowable Values: 255 char max
created_time datetime Conditionally returned	Date and time when the reward entry was created on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "1417c942-2eba-4238-ac44-d04db1f411cd",
  "reward_account_token": "bb0bbc60-ba92-42c8-8556-f4b807fafb2f",
  "value": -1000,
  "note": "Account completed customer feedback survey for 5000 bonus points.",
  "related_redemption_token": "fd3efc80-bd54-49bd-acae-0e2dd96ccc01",
  "created_time": "2024-01-04T20:37:11Z"
}

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

​List reward accounts

​URL query parameters

​Response body

​Sample response body

​Retrieve reward account

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Update active state

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve reward account balances

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve reward account accruals

​URL path parameters

​Response body

​Sample response body

​Create reward entry

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​List reward entries for a reward account

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve reward entry

​URL path parameters

​Response body

​Sample response body

List reward accounts

URL query parameters

Response body

Sample response body

Retrieve reward account

URL path parameters

URL query parameters

Response body

Sample response body

Update active state

URL path parameters

Request body

Sample request body

Response body

Sample response body

Retrieve reward account balances

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve reward account accruals

URL path parameters

Response body

Sample response body

Create reward entry

URL path parameters

Request body

Sample request body

Response body

Sample response body

List reward entries for a reward account

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve reward entry

URL path parameters

Response body

Sample response body