Reward Rules Management

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/rules endpoint to manage and monitor the rules configurations for a reward program. The configurations for global rules for a reward account are defined in the reward policy on the reward account’s associated bundle.

Create new program rule

Action: POST
Endpoint: /credit/rewards/rules Create a new rule for a reward program short code.

Request body

Fields	Description
token string Optional	Unique identifier of the rule. Allowable Values: 36 char max
description string Required	Description of the rule. Allowable Values: 255 char max
type string Required	Type of rule. - `MULTIPLIER_PER_TRANSACTION` - Defined multiplier is applied to every eligible transaction: for example, 1X every transaction ($5 transaction receives five reward points). Allowable Values: `MULTIPLIER_PER_TRANSACTION`
calculation_type string Optional	Type of calculation to use to evaluate if a rule has been satisfied. - `PER_TRANSACTION` - Rule is applied to all transactions, regardless of cumulative spend: for example, earn 1x on all transactions, regardless of category or spend total. Allowable Values: `PER_TRANSACTION`
multiplier decimal Optional	Reward multiplier to apply the transaction, where ‘1’ means 1x the transaction amount. Allowable Values: Any integer
amount decimal Optional	Static amount to reward if rule conditions are met. Allowable Values: Any integer
attributes object Optional	Attributes are additional properties for which the rule can used to determine reward accrual eligibility for a transaction. Allowable Values: `mcc`, `mid`
attributes.mcc array of strings Optional	List of merchant category codes (MCCs). Must be a four-digit number, or a range of two four-digit numbers separated by a hyphen. Allowable Values: One or more four-digit merchant category codes Example Values:`0001-1499`, `1500`
attributes.mid string Optional	Merchant ID for the rule. Allowable Values: 255 char max Example Value:`my_merchant_identifier`
start_time datetime Optional	Start date and time when the rule becomes active, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
end_time datetime Optional	End date and time when the rule becomes active, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
is_active boolean Optional	A value of `true` indicates that the rule is active. Allowable Values: `true`, `false` Default value:`true`

Sample request body

JSON

{
  "token": "00fb5637-2dab-4833-aa12-0463e7cf8cbb",
  "description": "Earn 1x on all purchases.",
  "type": "MULTIPLIER_PER_TRANSACTION",
  "calculation_type": "PER_TRANSACTION",
  "multiplier": 1,
  "start_time": "2024-01-05T20:37:11Z",
  "is_active": true
}

Response body

Fields	Description
data array of objects Returned	List of rule objects. Allowable Values: Valid array of one or more rule objects
data[].token string Returned	Unique identifier of the rule. Allowable Values: 36 char max
data[].description string Returned	Description of the rule. Allowable Values: 255 char max
data[].type string Returned	Type of rule. - `MULTIPLIER_PER_TRANSACTION` - Defined multiplier is applied to every eligible transaction: for example, 1X every transaction ($5 transaction receives five reward points). Allowable Values: `MULTIPLIER_PER_TRANSACTION`
data[].calculation_type string Conditionally returned	Type of calculation to use to evaluate if a rule has been satisfied. - `PER_TRANSACTION` - Rule is applied to all transactions, regardless of cumulative spend: for example, earn 1x on all transactions, regardless of category or spend total. Allowable Values: `PER_TRANSACTION`
data[].multiplier decimal Conditionally returned	Reward multiplier to apply the transaction, where `1` means 1x the transaction amount. Allowable Values: Any integer
data[].amount decimal Conditionally returned	Static amount to reward if rule conditions are met. Allowable Values: Any integer
data[].attributes object Conditionally returned	Attributes are additional properties for which the rule can used to determine reward accrual eligibility for a transaction. Allowable Values: `mcc`, `mid`
data[].attributes.mcc array of strings Conditionally returned	List of merchant category codes (MCCs). Must be a four-digit number, or a range of two four-digit numbers separated by a hyphen. Allowable Values: One or more four-digit merchant category codes Example Values:`0001-1499`, `1500`
data[].attributes.mid string Conditionally returned	Merchant ID for the rule. Allowable Values: 255 char max Example Value:`my_merchant_identifier`
data[].start_time datetime Conditionally returned	Start date and time when the rule should become active, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].end_time datetime Conditionally returned	End date and time when the active rule should become inactive, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].is_active boolean Conditionally returned	A value of `true` indicates that the rule is active. Allowable Values: `true`, `false` Default value:`true`
data[].created_time datetime Conditionally returned	Date and time when the rule 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 rule was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "data": [
    {
      "token": "00fb5637-2dab-4833-aa12-0463e7cf8cbb",
      "description": "Earn 1x on all purchases.",
      "type": "MULTIPLIER_PER_TRANSACTION",
      "calculation_type": "PER_TRANSACTION",
      "multiplier": 1,
      "start_time": "2024-01-05T20:37:11Z",
      "is_active": true,
      "created_time": "2024-01-05T20:37:11Z",
      "updated_time": "2024-01-05T20:37:11Z"
    }
  ]
}

List reward program rules

Action: GET
Endpoint: /credit/rewards/rules Retrieve an array of rules for a reward program.

URL query parameters

Fields	Description
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 rule objects. Allowable Values: Valid array of one or more rule objects
data[].token string Returned	Unique identifier of the rule. Allowable Values: 36 char max
data[].description string Returned	Description of the rule. Allowable Values: 255 char max
data[].type string Returned	Type of rule. - `MULTIPLIER_PER_TRANSACTION` - Defined multiplier is applied to every eligible transaction: for example, 1X every transaction ($5 transaction receives five reward points). Allowable Values: `MULTIPLIER_PER_TRANSACTION`
data[].calculation_type string Conditionally returned	Type of calculation to use to evaluate if a rule has been satisfied. - `PER_TRANSACTION` - Rule is applied to all transactions, regardless of cumulative spend: for example, earn 1x on all transactions, regardless of category or spend total. Allowable Values: `PER_TRANSACTION`
data[].multiplier decimal Conditionally returned	Reward multiplier to apply the transaction, where `1` means 1x the transaction amount. Allowable Values: Any integer
data[].amount decimal Conditionally returned	Static amount to reward if rule conditions are met. Allowable Values: Any integer
data[].attributes object Conditionally returned	Attributes are additional properties for which the rule can used to determine reward accrual eligibility for a transaction. Allowable Values: `mcc`, `mid`
data[].attributes.mcc array of strings Conditionally returned	List of merchant category codes (MCCs). Must be a four-digit number, or a range of two four-digit numbers separated by a hyphen. Allowable Values: One or more four-digit merchant category codes Example Values:`0001-1499`, `1500`
data[].attributes.mid string Conditionally returned	Merchant ID for the rule. Allowable Values: 255 char max Example Value:`my_merchant_identifier`
data[].start_time datetime Conditionally returned	Start date and time when the rule should become active, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].end_time datetime Conditionally returned	End date and time when the active rule should become inactive, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ
data[].is_active boolean Conditionally returned	A value of `true` indicates that the rule is active. Allowable Values: `true`, `false` Default value:`true`
data[].created_time datetime Conditionally returned	Date and time when the rule 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 rule was last updated on the Marqeta platform, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "00fb5637-2dab-4833-aa12-0463e7cf8cbb",
      "description": "Earn 3x on agricultural services, contracted services, and purchases at Target.",
      "type": "MULTIPLIER_PER_TRANSACTION",
      "calculation_type": "PER_TRANSACTION",
      "multiplier": 3,
      "attributes": {
        "mcc": [
          "0001-1499",
          "1500-2999"
        ]
      },
      "start_time": "2024-01-05T20:37:11Z",
      "is_active": true,
      "created_time": "2024-01-05T20:37:11Z",
      "updated_time": "2024-01-05T20:37:11Z"
    },
    {
      "token": "4b3f70e5-b90a-497f-9d50-20445644c3ae",
      "description": "Earn 1 point on all transactions.",
      "type": "MULTIPLIER_PER_TRANSACTION",
      "calculation_type": "PER_TRANSACTION",
      "multiplier": 1,
      "start_time": "2024-01-05T20:37:11Z",
      "is_active": true,
      "created_time": "2024-01-05T20:37:11Z",
      "updated_time": "2024-01-05T20: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

Reward Rules Management

Create new program rule

Request body

Sample request body

Response body

Sample response body

List reward program rules

URL query parameters

Response body

Sample response body

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

​Create new program rule

​Request body

​Sample request body

​Response body

​Sample response body

​List reward program rules

​URL query parameters

​Response body

​Sample response body

Create new program rule

Request body

Sample request body

Response body

Sample response body

List reward program rules

URL query parameters

Response body

Sample response body