# Control groups You can group multiple [spending controls](https://www.checkout.com/docs/card-issuing/manage-controls.md) together into a control group and specify how to apply the combined outcome. This enables you to build complex rules for card behavior. Control groups can target either a card or a control profile. Targets can have multiple control groups. You can create control groups to decline a payment if it fails: - All controls in the group – The evaluations function as a logical AND operation - Any control in the group - The evaluations function as a logical OR operation --- ## How it works Create a control group and specify the fail condition, the target, and the controls you want to include in the group. You can then: - Retrieve the control group's details. - Retrieve all control groups for a target. - Remove a control group from a target. --- ## Create a control group Call the [Create a control group](https://api-reference.checkout.com/tag/Control-groups/#operation/createControlGroup) endpoint, and provide the following: - `description` – A description of the control group. - `fail_if` – The fail condition for the control group. This can be one of: - `all_fail` – Decline the payment if all controls fail. - `any_fail` – Decline the payment if any control fails. - `target_id` – The ID of the card (prefixed with `crd_`) or control profile (prefixed with `cpr_`) you want the control group to target. Specify multiple controls in the `controls` array, which contains the following fields: - `description` – A description of the control. - `control_type` – The type of control. This can be one of: - `mcc_limit` – A [merchant category code (MCC)](https://www.checkout.com/docs/card-issuing/manage-controls/card-controls.md#Apply_MCC_controls) control - `mid_limit` – A [merchant identification number (MID)](https://www.checkout.com/docs/card-issuing/manage-controls/card-controls.md#Apply_MID_controls) control - `velocity_limit` – A [velocity control](https://www.checkout.com/docs/card-issuing/manage-controls/card-controls.md#Apply_velocity_controls) For MCC controls, provide an `mcc_limit` object, which contains the following: - `type` – This can be either `allow` or `block`. - `mcc_list` – The array of MCCs that you want to allow or block. For MID controls, provide an `mid_limit` object, which contains the following: - `type` – This can be either `allow` or `block`. - `mid_list` – The array of MIDs you want to allow or block. For velocity controls, provide a `velocity_limit` object, which contains the following: - `amount_limit` – The amount the card can spend. - `velocity_window` – The time frame over which the card can spend the amount. - `velocity_window.type` – This can be one of: - `all_time` – The card can spend the amount at any time. - `daily` – The card can spend the amount within 24 hours. - `monthly` – The card can spend the amount within a calendar month. - `weekly` – The card can spend the amount within a calendar week. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/issuing/control-groups` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/issuing/control-groups` ### Request examples ```json { "description": "Only allow groceries at Walmart up to $1000 per day", "fail_if": "all_fail", "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491", "controls": [ { "description": "Block the card from being used for groceries", "control_type": "mcc_limit", "mcc_limit": { "type": "block", "mcc_list": [ "5422" ] } }, { "description": "Allow the card to be used at Walmart", "control_type": "mid_limit", "mid_limit": { "type": "allow", "mid_list": [ "1234" ] } }, { "description": "Allow the card to spend a maximum of $1000 daily", "control_type": "velocity_limit", "velocity_limit": { "amount_limit": 100000, "velocity_window": { "type": "daily" } } } ] } ``` ### Response examples ```json { "id": "cgr_oemoyd3otivelkhf4zcnimwdva", "description": "Only allow groceries at Walmart up to $1000 per day", "target_id": "crd_dba7tjsh7utufgid7yety4gnxq", "fail_if": "all_fail", "controls": [ { "mcc_limit": { "type": "block", "mcc_list": [ "5422" ] }, "description": "Block the card from being used for groceries", "control_type": "mcc_limit" }, { "mid_limit": { "type": "allow", "mid_list": [ "1234" ] }, "description": "Allow the card to be used at Walmart", "control_type": "mid_limit" }, { "velocity_limit": { "amount_limit": 100000, "velocity_window": { "type": "daily" } }, "description": "Allow the card to spend a maximum of $1000 daily", "control_type": "velocity_limit" } ], "is_editable": true, "created_date":"2025-01-06T14:01:31.7155085Z", "last_modified_date": "2025-01-06T14:01:31.7155085Z", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/issuing/control-groups/cgr_oemoyd3otivelkhf4zcnimwdva", "actions": [ "GET" ], "types": [ "application/json" ] } } } ``` The response returns the control group ID in the `id` field, prefixed with `cgr_`. The `is_editable` boolean is set to `true` because you created the control group and can update it. --- ## Get control group details Call the [Get a control group](https://api-reference.checkout.com/tag/Control-groups/#operation/getControlGroup) endpoint, and provide the ID of the control group you want to retrieve as the `{controlGroupId}` path parameter. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `GET` `https://{prefix}.api.checkout.com/issuing/control-groups/{controlGroupId}` **Sandbox** `GET` `https://{prefix}.api.sandbox.checkout.com/issuing/control-groups/{controlGroupId}` ### Response example ```json { "id": "cgr_oemoyd3otivelkhf4zcnimwdva", "description": "Only allow groceries at Walmart up to $1000 per day", "target_id": "crd_dba7tjsh7utufgid7yety4gnxq", "fail_if": "all_fail", "controls": [ { "mcc_limit": { "type": "block", "mcc_list": [ "5422" ] }, "description": "Block the card from being used for groceries", "control_type": "mcc_limit" }, { "mid_limit": { "type": "allow", "mid_list": [ "1234" ] }, "description": "Allow the card to be used at Walmart", "control_type": "mid_limit" }, { "velocity_limit": { "amount_limit": 100000, "velocity_window": { "type": "daily" } }, "description":"Allow the card to spend a maximum of $1000 daily", "control_type":"velocity_limit" } ], "is_editable": true, "created_date": "2025-01-06T14:01:31.7155085Z", "last_modified_date": "2025-01-06T14:01:31.7155085Z", "_links": { "self":{ "href": "https://{prefix}.api.checkout.com/issuing/control-groups/cgr_oemoyd3otivelkhf4zcnimwdva", "actions": [ "GET" ], "types": [ "application/json" ] } } } ``` The response returns the details of the specified control group and each control in the group, along with associated metadata. --- ## Retrieve control groups by target To retrieve all control groups that target a card or control profile, call the [Get control groups by target](https://api-reference.checkout.com/tag/Control-groups/#operation/getControlGroupByTarget) endpoint, and provide the target ID as the `{targetId}` path parameter. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `GET` `https://{prefix}.api.checkout.com/issuing/control-groups/{targetId}` **Sandbox** `GET` `https://{prefix}.api.sandbox.checkout.com/issuing/control-groups/{targetId}` ### Response example ```json { "control_groups": [ { "id": "cgr_oemoyd3otivelkhf4zcnimwdva", "description": "Only allow groceries at Walmart up to $1000 per day", "target_id": "crd_dba7tjsh7utufgid7yety4gnxq", "fail_if": "all_fail", "controls": [ { "mcc_limit": { "type": "block", "mcc_list": [ "5422" ] }, "description": "Block the card from being used for groceries", "control_type": "mcc_limit" }, { "mid_limit": { "type": "allow", "mid_list": [ "1234" ] }, "description": "Allow the card to be used at Walmart", "control_type": "mid_limit" }, { "velocity_limit":{ "amount_limit": 100000, "velocity_window": { "type": "daily" } }, "description":"Allow the card to spend a maximum of $1000 daily", "control_type":"velocity_limit" } ], "is_editable": true, "created_date": "2025-01-06T14:01:31.7155085Z", "last_modified_date": "2025-01-06T14:01:31.7155085Z" } ] } ``` The response returns the IDs of all control groups that target the card or control profile, along with the details of each control and associated metadata. --- ## Remove a control group Call the [Remove a control group](https://api-reference.checkout.com/tag/Control-groups/#operation/deleteControlGroup) endpoint, and provide the control group ID as the `{controlGroupId}` path parameter. > **Note** > > Removing a control group deletes all controls in the control group. > > To reapply a control group to the target, you must create a new control group. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `DELETE` `https://{prefix}.api.checkout.com/issuing/control-groups/{controlGroupId}` **Sandbox** `DELETE` `https://{prefix}.api.sandbox.checkout.com/issuing/control-groups/{controlGroupId}` ### Response example ```json { "id": "cgr_oemoyd3otivelkhf4zcnimwdva" } ``` The response returns the ID of the control group you removed.