> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant Groups

> Create merchant groups for use in authorization controls and card product configurations.

export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
      text: "mint-text-green-700 dark:mint-text-green-400",
      border: "mint-border-green-300 dark:mint-border-green-700"
    },
    POST: {
      bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
      text: "mint-text-blue-700 dark:mint-text-blue-400"
    },
    PUT: {
      bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
      text: "mint-text-yellow-700 dark:mint-text-yellow-400"
    },
    PATCH: {
      bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
      text: "mint-text-orange-700 dark:mint-text-orange-400"
    },
    DELETE: {
      bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
      text: "mint-text-red-700 dark:mint-text-red-400"
    },
    API: {
      bg: "mint-bg-black",
      text: "mint-text-white"
    }
  };
  const MethodBadge = ({method}) => {
    const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
    return <span className={`
          method-pill rounded-lg font-semibold px-1.5 py-0.5 text-xs leading-5 ${style.bg} ${style.text}`}>
        {method?.toUpperCase()}
      </span>;
  };
  const content = <div className="group flex items-center gap-4 border border-gray-200 dark:border-gray-700 rounded-xl p-5 hover:border-gray-400 dark:hover:border-gray-500 hover:shadow-md transition-all cursor-pointer">
      {}
      <div className="shrink-0">
        <MethodBadge method={method} />
      </div>
      {}
      <div className="flex-1 min-w-0">
        <p className="font-semibold text-gray-900 dark:text-white text-sm leading-snug">{title}</p>
        {children && <p className="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">{children}</p>}
      </div>
    </div>;
  if (!href) return content;
  return <a href={href} className="block no-underline border-b-0 mb-2">
      {content}
    </a>;
};

Use the `/merchantgroups` endpoint to create, update, and retrieve groups of merchant identifiers (MIDs). You can use merchant groups for authorization controls and in card product configurations. For example, use a merchant group to create a [merchant exemption](/core-api/authorization-controls/#post_authcontrols_exemptmids) for a group of merchants rather than an individual merchant.

<h2 id="post_merchant_group">
  Create merchant group
</h2>

**Action:** `POST`\
**Endpoint:** `/merchantgroups`

{/* <EndpointCard
title="Creates a merchant group"
path="/merchantgroups"
method="post"
/> */}

To create a merchant group, send a `POST` request to the `/merchantgroups` endpoint.

<h3 id="_request_body">
  Request body
</h3>

| Fields                                               | Description                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| active<br /><br />boolean<br /><br />Optional        | Indicates if the merchant group is active or not.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                                                                                                                                                                       |
| mids<br /><br />array of strings<br /><br />Optional | Comma-separated list of alphanumeric merchant identifiers. You can include merchant identifiers in multiple merchant groups.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more merchant identifiers                                                                                                                                                       |
| name<br /><br />string<br /><br />Required           | Name of the merchant group.<br /><br />**Allowable Values:**<br /><br />1–40 chars                                                                                                                                                                                                                                                                                             |
| token<br /><br />string<br /><br />Optional          | Unique identifier of the group.<br /><br />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.<br /><br />**Allowable Values:**<br /><br />1–36 chars |

<h3 id="_sample_request_body">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012"
  ],
  "active": true
}
```

<h3 id="_response_body">
  Response body
</h3>

| Fields                                                                     | Description                                                                                                                                            |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| active<br /><br />boolean<br /><br />Conditionally returned                | Indicates if the merchant group is active or not.<br /><br />**Allowable Values:**<br /><br />`true`, `false`                                          |
| created\_time<br /><br />datetime<br /><br />Conditionally returned        | Date and time when the resource was created, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                          |
| last\_modified\_time<br /><br />datetime<br /><br />Conditionally returned | Date and time when the resource was last modified, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                    |
| mids<br /><br />array of strings<br /><br />Conditionally returned         | Comma-separated list of alphanumeric merchant identifiers.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more merchant identifiers |
| name<br /><br />string<br /><br />Conditionally returned                   | Name of the merchant group.<br /><br />**Allowable Values:**<br /><br />40 char max                                                                    |
| token<br /><br />string<br /><br />Conditionally returned                  | Unique identifier of the merchant group.<br /><br />**Allowable Values:**<br /><br />Existing merchant group token                                     |

<h3 id="_sample_response_body">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012"
  ],
  "active": true,
  "created_time": "2022-05-01T13:22:07Z",
  "last_modified_time": "2022-05-01T13:22:07Z"
}
```

<h2 id="get_merchant_groups">
  List merchant groups
</h2>

**Action:** `GET`\
**Endpoint:** `/merchantgroups`

{/* <EndpointCard
title="Lists all Merchant Groups"
path="/merchantgroups"
method="get"
/> */}

To return an array of all merchant groups, send a `GET` request to the `/merchantgroups` endpoint.

To return an array of all merchant groups that include a specific merchant identifier, send a `GET` request to the `/merchantgroups` endpoint that includes the merchant identifier in the query parameters.

<h3 id="_url_query_parameters">
  URL query parameters
</h3>

| Fields                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mid<br /><br />string<br /><br />Optional           | Returns all merchant groups that contain the specified merchant identifier.<br /><br />**Allowable Values:**<br /><br />Existing merchant identifier                                                                                                                                                                                                                                                                      |
| count<br /><br />integer<br /><br />Optional        | Number of resources to retrieve.<br /><br />**Allowable Values:**<br /><br />1-10<br /><br />**Default value:**<br />10                                                                                                                                                                                                                                                                                                   |
| start\_index<br /><br />integer<br /><br />Optional | Sort order index of the first resource in the returned array.<br /><br />**Allowable Values:**<br /><br />Any integer<br /><br />**Default value:**<br />0                                                                                                                                                                                                                                                                |
| sort\_by<br /><br />string<br /><br />Optional      | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.<br /><br />**Allowable Values:**<br /><br />`createdTime`, `lastModifiedTime`, or any field in the resource model<br /><br />**Default value:**<br />`-lastModifiedTime` |

<h3 id="_response_body_2">
  Response body
</h3>

| Fields                                                                                 | Description                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| count<br /><br />integer<br /><br />Conditionally returned                             | Number of resources retrieved.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                                                              |
| data<br /><br />array of objects<br /><br />Conditionally returned                     | Array of merchant group resources.<br /><br />Resources are returned as appropriate to your query.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more merchant group objects                                                                                     |
| data\[].**active**<br /><br />boolean<br /><br />Conditionally returned                | Indicates if the merchant group is active or not.<br /><br />**Allowable Values:**<br /><br />`true`, `false`                                                                                                                                                                        |
| data\[].**created\_time**<br /><br />datetime<br /><br />Conditionally returned        | Date and time when the resource was created, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                                                                                                                                                        |
| data\[].**last\_modified\_time**<br /><br />datetime<br /><br />Conditionally returned | Date and time when the resource was last modified, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                                                                                                                                                  |
| data\[].**mids**<br /><br />array of strings<br /><br />Conditionally returned         | Comma-separated list of alphanumeric merchant identifiers.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more merchant identifiers                                                                                                                               |
| data\[].**name**<br /><br />string<br /><br />Conditionally returned                   | Name of the merchant group.<br /><br />**Allowable Values:**<br /><br />40 char max                                                                                                                                                                                                  |
| data\[].**token**<br /><br />string<br /><br />Conditionally returned                  | Unique identifier of the merchant group.<br /><br />**Allowable Values:**<br /><br />Existing merchant group token                                                                                                                                                                   |
| end\_index<br /><br />integer<br /><br />Conditionally returned                        | The sort order index of the last resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                            |
| is\_more<br /><br />boolean<br /><br />Conditionally returned                          | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />`true`, `false` |
| start\_index<br /><br />integer<br /><br />Conditionally returned                      | Sort order index of the last resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                                |

<h3 id="_sample_response_body_2">
  Sample response body
</h3>

```json JSON expandable lines wrap theme={null}
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_merchantgroup",
      "name": "My Merchant Group",
      "mids": [
        "123456789012345",
        "345123456789012",
        "123456789012"
      ],
      "active": true,
      "created_time": "2022-05-01T13:22:07Z",
      "last_modified_time": "2022-05-01T13:32:07Z"
    },
    {
      "token": "my_merchantgroup_01",
      "name": "My Merchant Group 01",
      "mids": [
        "998877665544331",
        "246813579000"
      ],
      "active": true,
      "created_time": "2021-05-02T01:42:07Z",
      "last_modified_time": "2022-05-02T01:42:07Z"
    }
  ]
}
```

<h2 id="put_merchant_groups_token">
  Update merchant group
</h2>

**Action:** `PUT`\
**Endpoint:** `/merchantgroups/{token}`

{/* <EndpointCard
title="Updates an Merchant Group"
path="/merchantgroups/{token}"
method="put"
/> */}

To update a merchant group, send a `PUT` request to the `/merchantgroups/{token}` endpoint. Include the merchant group `token` path parameter to specify the merchant group to update.

<h3 id="_url_path_parameters">
  URL path parameters
</h3>

| Fields                                      | Description                                                                                                        |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| token<br /><br />string<br /><br />Required | Unique identifier of the merchant group.<br /><br />**Allowable Values:**<br /><br />Existing merchant group token |

<h3 id="_request_body_2">
  Request body
</h3>

| Fields                                               | Description                                                                                                                                                                                                              |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| active<br /><br />boolean<br /><br />Optional        | Indicates if the merchant group is active or not.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default value:**<br />`false`                                                                 |
| mids<br /><br />array of strings<br /><br />Optional | Comma-separated list of alphanumeric merchant identifiers. You can include merchant identifiers in multiple merchant groups.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more merchant identifiers |
| name<br /><br />string<br /><br />Optional           | Name of the merchant group.<br /><br />**Allowable Values:**<br /><br />1–40 chars                                                                                                                                       |

<h3 id="_sample_request_body_2">
  Sample request body
</h3>

```json JSON lines wrap theme={null}
{
  "name": "My Merchant Group",
  "mids": [
    "234567890123"
  ],
  "active": true
}
```

<h3 id="_response_body_3">
  Response body
</h3>

| Fields                                                                     | Description                                                                                                                                            |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| active<br /><br />boolean<br /><br />Conditionally returned                | Indicates if the merchant group is active or not.<br /><br />**Allowable Values:**<br /><br />`true`, `false`                                          |
| created\_time<br /><br />datetime<br /><br />Conditionally returned        | Date and time when the resource was created, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                          |
| last\_modified\_time<br /><br />datetime<br /><br />Conditionally returned | Date and time when the resource was last modified, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                    |
| mids<br /><br />array of strings<br /><br />Conditionally returned         | Comma-separated list of alphanumeric merchant identifiers.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more merchant identifiers |
| name<br /><br />string<br /><br />Conditionally returned                   | Name of the merchant group.<br /><br />**Allowable Values:**<br /><br />40 char max                                                                    |
| token<br /><br />string<br /><br />Conditionally returned                  | Unique identifier of the merchant group.<br /><br />**Allowable Values:**<br /><br />Existing merchant group token                                     |

<h3 id="_sample_response_body_3">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012",
    "234567890123"
  ],
  "active": true,
  "created_time": "2022-05-01T13:22:07Z",
  "last_modified_time": "2022-05-01T13:32:07Z"
}
```

<h2 id="get_merchant_group">
  Retrieve merchant group
</h2>

**Action:** `GET`\
**Endpoint:** `/merchantgroups/{token}`

{/* <EndpointCard
title="Returns a Merchant Group"
path="/merchantgroups/{token}"
method="get"
/> */}

To retrieve a specific merchant group, send a `GET` request to the `/merchantgroups/{token}` endpoint. Include the merchant group `token` path parameter to specify the merchant group to return.

<h3 id="_url_path_parameters_2">
  URL path parameters
</h3>

| Fields                                      | Description                                                                                                        |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| token<br /><br />string<br /><br />Required | Unique identifier of the merchant group.<br /><br />**Allowable Values:**<br /><br />Existing merchant group token |

<h3 id="_response_body_4">
  Response body
</h3>

| Fields                                                                     | Description                                                                                                                                            |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| active<br /><br />boolean<br /><br />Conditionally returned                | Indicates if the merchant group is active or not.<br /><br />**Allowable Values:**<br /><br />`true`, `false`                                          |
| created\_time<br /><br />datetime<br /><br />Conditionally returned        | Date and time when the resource was created, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                          |
| last\_modified\_time<br /><br />datetime<br /><br />Conditionally returned | Date and time when the resource was last modified, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: yyyy-MM-ddThh:mm:ssZ                    |
| mids<br /><br />array of strings<br /><br />Conditionally returned         | Comma-separated list of alphanumeric merchant identifiers.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more merchant identifiers |
| name<br /><br />string<br /><br />Conditionally returned                   | Name of the merchant group.<br /><br />**Allowable Values:**<br /><br />40 char max                                                                    |
| token<br /><br />string<br /><br />Conditionally returned                  | Unique identifier of the merchant group.<br /><br />**Allowable Values:**<br /><br />Existing merchant group token                                     |

<h3 id="_sample_response_body_4">
  Sample response body
</h3>

```json JSON lines wrap theme={null}
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012",
    "234567890123"
  ],
  "active": true,
  "created_time": "2022-05-01T13:22:07Z",
  "last_modified_time": "2022-05-01T13:32:07Z"
}
```