MCC Groups

A merchant category code (MCC) is a four-digit number assigned by card networks to a business based on the goods or services offered by the business. On the Marqeta platform, an MCC group defines a set of MCCs. You can include an MCC group within a spend control to limit user spending at a set of merchants.

An MCC group also allows you to automatically increase authorization amounts and to control expiration of authorizations for the specified MCCs. By default, these controls apply to all cards in your program. An MCC group authorization control can have exceptions defined at the card product level.

Note: See Controlling Spending for a tutorial that walks you through the creation of a spend control.

Create MCC group

Action: POST
Endpoint: /mccgroups

Use this endpoint to create an MCC group.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the group.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
name string Yes The name of the group. 40 char max
mccs array Yes The set of merchant category codes that you want to include in this group. For each element, valid characters are 0-9, length must be 4. You can also specify a range like "9876-9880". An MCC can belong to more than one group. Existing merchant category codes
active boolean No Indicates if the group is active or inactive. true | false

Default: false
config object No Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount.

The config object

Name Type Required? Description Allowable Values
authorization_controls object No Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group.

By default, these authorization controls apply program-wide, meaning that they apply to every card in your program. You can, however, exempt cards associated with any particular card product by setting that card product's allow_mcc_group_authorization_controls field to false.

The config.authorization_controls object

Name Type Required? Description Allowable Values
hold_increase object No Controls automatic increases to the authorization amount for MCCs specified in this group.
hold_expiration_days integer No Specifies the number of days after which an authorization associated with this group expires. 1–100

Default: 7

The config.authorization_controls.hold_increase object

Name Type Required? Description Allowable Values
type string Yes Controls whether the value field represents a fixed amount or a percentage of the authorization amount. AMOUNT | PERCENT

Default: AMOUNT
value decimal Yes Specifies the amount of the automatic increase to the authorization amount.

The type field controls whether this amount is a fixed amount or a percentage.
0.00 format

Sample request body

{
"token": "my_mccgroup_01",
"name": "My MCC Group 01",
"mccs": ["0123", "2224-2230", "3876"
],
"active": true,
"config": {
"authorization_controls": {
"hold_increase": {
"type": "PERCENT",
"value": 20
},
"hold_expiration_days": 2
}
}
}

Sample response body

{
"token": "my_mccgroup_01",
"name": "My MCC Group 01",
"mccs": [
"0123",
"2224-2230",
"3876"
],
"active": true,
"config": {
"authorization_controls": {
"hold_increase": {
"type": "PERCENT",
"value": 20
},
"hold_expiration_days": 2
}
}
}


Retrieve MCC group

Action: GET
Endpoint: /mccgroups/{token}

Use this endpoint to retrieve a specific MCC group.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the MCC group. Existing MCC group token.

Issue a GET to /mccgroups to retrieve MCC group tokens.

Sample response body

{
"token": "my_mccgroup_02",
"name": "My MCC Group 02",
"mccs": [
"0123",
"2224-2230"
],
"active": true,
"config": {
"authorization_controls": {
"hold_increase": {
"type": "AMOUNT",
"value": 10
},
"hold_expiration_days": 3
}
}
}


Update MCC group

Action: PUT
Endpoint: /mccgroups/{token}

Use this endpoint to update an MCC group. Include the token path parameter to identify the MCC group to update. You must pass all the merchant category codes you want included in the group, including existing ones you want to retain.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the MCC group. Existing MCC group token.

Issue a GET to /mccgroups to retrieve MCC group tokens.

Body field details

Name Type Required? Description Allowable Values
name string No The name of the MCC group. 40 char max
mccs array No The set of merchant category codes to include in the MCC group.

A merchant category code can belong to more than one group.
Array of existing merchant category codes.

Each code is a 4-digit number. You can also specify ranges such as "9876-9880".

Note: Updating the merchant category codes for the group completely replaces the group's existing codes. For example, if the current MCC group is ["1234"] and you want to add the 2345 code (while retaining the existing code), you must specify ["1234", "2345"] in this field. You delete a code by simply not specifying it in the update.
active boolean No Indicates whether the MCC group is active or inactive. true | false

Default: false
config object No Allows for configuration options for this group, including control over the expiration of authorizations and automatic increases to the authorization amount.

The config object

Name Type Required? Description Allowable Values
authorization_controls object No Controls the expiration of authorizations and automatic increases to the authorization amount for MCCs specified in this group.

The config.authorization_controls object

Name Type Required? Description Allowable Values
hold_increase object No Controls automatic increases to the authorization amount for MCCs specified in this group.
hold_expiration_days integer No Specifies the number of days after which an authorization associated with this group expires. 1–100

Default: 7

The config.authorization_controls.hold_increase object

Name Type Required? Description Allowable Values
type string Yes Controls whether the value field represents a fixed amount or a percentage of the authorization amount. AMOUNT | PERCENT

Default: AMOUNT
value decimal Yes Specifies the amount of the automatic increase to the authorization amount.

The type field controls whether this amount is a flat amount or percentage.
0.00 format

Sample request body

{
"mccs": ["0123", "2224-2230"
]
}

Sample response body

{
"token": "my_mccgroup_02",
"name": "My MCC Group 02",
"mccs": [
"0123",
"2224-2230"
],
"active": true,
"config": {
"authorization_controls": {
"hold_increase": {
"type": "AMOUNT",
"value": 10
},
"hold_expiration_days": 3
}
}
}


List MCC groups

Action: GET
Endpoint: /mccgroups

Use this endpoint to list all MCC groups defined in your program or list MCC groups that contain a specified code.

This endpoint supports field filtering and pagination.

Query parameters

Name Type Required? Description Allowable Values
mcc string No Returns all MCC groups that contain the specified merchant category code. A merchant category code.

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "my_mccgroup_02",
"name": "My MCC Group 02",
"mccs": [
"0123",
"2224-2230"
],
"active": true,
"config": {
"authorization_controls": {
"hold_increase": {
"type": "AMOUNT",
"value": 10
},
"hold_expiration_days": 3
}
}
},
{
"token": "my_mccgroup_01",
"name": "My MCC Group 01",
"mccs": [
"0123",
"2224-2230",
"3876"
],
"active": true,
"config": {
"authorization_controls": {
"hold_increase": {
"type": "PERCENT",
"value": 20
},
"hold_expiration_days": 2
}
}
}
]
}