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

​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