# Alerts Use Cases
source: https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md

This article provides sample use cases that show how to use the Merchant Self Services API for Ethoca Alerts. Each use case includes a request and response example. See [Code and Formats](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md) for error codes and HTTP response status codes that apply across these use cases.

## Onboard an Alerts Submerchant {#onboard-an-alerts-submerchant}

In this scenario, you are onboarding a new Alerts submerchant and configuring the identifiers that help match Alerts transactions to the correct merchant.

For this use case, you'll:

* [Get organization profile details](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#get-organization-profile-details)
* [Create a submerchant](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#create-a-submerchant)
* [Add submerchant merchant identifiers](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#add-submerchant-merchant-identifiers)
* [Create a card acceptor name configuration](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#create-a-card-acceptor-name-configuration)
* [Create merchant descriptor match criteria](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#create-merchant-descriptor-match-criteria) (when applicable)

You can then retrieve and validate the configurations, update the submerchant, and update its status as needed.

The following use cases provide detailed examples for each stage of the Alerts onboarding workflow, as well as the retrieval, update, and maintenance operations used after onboarding is complete.

## Organization Profiles {#organization-profiles}

Before a merchant, partner, or acquirer can manage merchant identity data within Ethoca Alerts, they must identify the organizations they are authorized to administer. Organization profile details establish the caller's identity and return the organizational structure, including child organizations that can be managed through the API. The response returns a `memberId`. Use this value as the `{member_id}` path parameter in subsequent requests.

### Get organization profile details {#get-organization-profile-details}

For this use case, you retrieve the organization profile associated with your credentials. You send a request to the **getAlertsOrgProfiles** operation. The API validates the request and returns the member name, ID, type, status, and available suborganization profiles.
Diagram alerts-get-profile
API Reference: `GET /alerts/merchants/org-profiles`

## Manage Acquirer Reference IDs {#manage-acquirer-reference-ids}

Acquirer Reference IDs (ARIDs) establish the relationship between a merchant organization and the acquiring institutions that process its card transactions. Before transaction data can be associated with a merchant, the Alerts platform must understand which acquirers represent that merchant across various payment ecosystems. Merchants and partners use ARIDs to publish relationships that become part of their merchant identity configuration.

An acquirer must register their reference identifiers (typically 6-digit BINs for Mastercard/Visa, or up to 20-digit numeric values for AMEX) before they can enroll submerchants for alerts. Each ARID links the acquirer to a specific card scheme, enabling the system to route dispute alerts to the correct acquirer.

Common scenarios include onboarding a new acquirer, reviewing an existing configuration, supporting multiple acquirers, migrating from one acquirer to another, updating matching behavior through `binOnlyMatch`, and removing an acquirer.

### Create an acquirer reference ID configuration {#create-an-acquirer-reference-id-configuration}

For this use case, you add an ARID configuration to an existing merchant. You create an `AlertsAcquirerReferenceIdConfig` object and send a request to the **createAlertsAcquirerReferenceIdConfig** operation. The API validates and adds the configuration to the merchant record. The response returns a `merchantIdentifierConfigId`. Use this value as the `merchant_identifier_config_id` query parameter in subsequent update or delete requests.
Diagram alerts-create-acquirer-reference-id
API Reference: `POST /alerts/merchants/{member_id}/acquirer-reference-ids`

### Get acquirer reference ID configurations {#get-acquirer-reference-id-configurations}

For this use case, you retrieve ARID configurations for an existing merchant. You send a request to the **getAlertsAcquirerReferenceIdConfigs** operation. You can filter the results by ARID and card scheme. The API validates the request and returns a pageable list of matching configurations.
Diagram alerts-get-acquirer-reference-ids
API Reference: `GET /alerts/merchants/{member_id}/acquirer-reference-ids`

### Update an acquirer reference ID configuration {#update-an-acquirer-reference-id-configuration}

For this use case, you update the `binOnlyMatch` setting for an existing ARID configuration. You create an `AlertsAcquirerReferenceIdConfigUpdate` object and send a request to the **updateAlertsAcquirerReferenceIdConfig** operation. Provide the `merchantIdentifierConfigId` value from a create or retrieve response as the `merchant_identifier_config_id` query parameter. The API validates and updates the configuration.
Diagram alerts-update-acquirer-reference-id
API Reference: `PUT /alerts/merchants/{member_id}/acquirer-reference-ids`

### Delete an acquirer reference ID configuration {#delete-an-acquirer-reference-id-configuration}

For this use case, you remove an ARID configuration from an existing merchant. You send a `DELETE` request to the **deleteAlertsAcquirerReferenceIdConfig** operation. Provide the `merchantIdentifierConfigId` value from a create or retrieve response as the `merchant_identifier_config_id` query parameter. The API validates and removes the configuration.
Diagram alerts-delete-acquirer-reference-id
API Reference: `DELETE /alerts/merchants/{member_id}/acquirer-reference-ids`

## Manage Submerchants {#manage-submerchants}

After an acquirer has registered their ARIDs, they can create and then manage submerchants under their organization. Submerchants represent the individual businesses that receive alerts. Each submerchant requires a name and a 4-digit Merchant Category Code (MCC). Submerchants can be activated or deactivated, and their details (name, MCC, contact info) can be updated at any time.

Use these operations to onboard, retrieve, update, and maintain submerchants associated with your organization.

### Create a submerchant {#create-a-submerchant}

For this use case, you add a submerchant to an existing merchant record. You create an `AlertsSubMerchantCreate` object and send a request to the **createAlertsSubMerchant** operation. The API validates and persists the submerchant and returns an `AlertsSubMerchantResource`. The response includes a `subMerchantId`. Use this value as the `{sub_merchant_id}` path parameter in subsequent requests for that submerchant.
Diagram alerts-create-submerchant
API Reference: `POST /alerts/merchants/{member_id}/sub-merchants`

### Get a list of submerchants {#get-a-list-of-submerchants}

For this use case, you retrieve submerchants managed under a parent merchant, partner, or acquirer organization. You send a request to the **getAlertsSubMerchants** operation. You can filter the results by merchant name and status. The API validates the request and returns a pageable list of matching submerchants. Use this operation to verify onboarding, search for merchant records, prepare updates, or audit merchant configurations.
Diagram alerts-get-submerchants
API Reference: `GET /alerts/merchants/{member_id}/sub-merchants`

### Get a submerchant {#get-a-submerchant}

For this use case, you retrieve one existing submerchant. You send a request to the **getAlertsSubMerchantByGuid** operation and provide its `subMerchantId` value as the `{sub_merchant_id}` path parameter. The API validates the request and returns the matching `AlertsSubMerchantResource`.
Diagram alerts-get-submerchant
API Reference: `GET /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}`

### Update a submerchant {#update-a-submerchant}

For this use case, you update an existing submerchant. You create an `AlertsSubMerchantDetailsUpdate` object and send a request to the **updateAlertsSubMerchantDetails** operation. Provide the submerchant's `subMerchantId` value as the `{sub_merchant_id}` path parameter. The API validates and updates the submerchant.
Diagram alerts-update-submerchant
API Reference: `PUT /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}`

### Update a submerchant's status {#update-a-submerchants-status}

For this use case, you activate or deactivate an existing submerchant. You create an `AlertsSubMerchantStatusUpdate` object and send a request to the **updateAlertsSubMerchantStatus** operation. Provide the submerchant's `subMerchantId` value as the `{sub_merchant_id}` path parameter. The API validates and updates the submerchant status.
Diagram alerts-update-submerchant-status
API Reference: `PUT /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/status-changes`

## Manage Card Acceptor Identifiers {#manage-card-acceptor-identifiers}

Card Acceptor Identifiers come in two forms:

* **Card Acceptor IDs (CAIDs)**: Numeric identifiers (up to 15 characters) that associate a submerchant with a specific acquirer reference ID (ARID). The CAID+ARID combination enables transaction-level alert matching and routing. Use these endpoints to create, retrieve, and delete CAID relationships for a submerchant.

* **Card Acceptor Names (CANs)**: Descriptor-based identifiers (up to 200 characters) that enable fuzzy matching when exact payment identifiers are unavailable. CANs can include storefront names, brand names, and location-specific descriptors to help identify a merchant from transaction statement data. Use these endpoints to create, retrieve, and delete CAN relationships for a submerchant.

The use cases in this section show how to manage Card Acceptor Identifiers by creating, retrieving, and deleting CAID and CAN relationships for a submerchant.

### Add submerchant merchant identifiers {#add-submerchant-merchant-identifiers}

Here, you add submerchant identifiers that help identify the equivalent submerchant from an Alert transaction. You can add a Card Acceptor ID (CAID), a Card Acceptor Name (CAN), or both, depending on the identifiers available for the submerchant.
Diagram alerts-add-submerchant-identifiers

#### Create a card acceptor ID configuration {#create-a-card-acceptor-id-configuration}

For this use case, you create an `AlertsCardAcceptorIdConfig` object and send a request to the **createAlertsCardAcceptorIdConfig** operation. The API validates and adds the CAID configuration to the submerchant record. The response returns a `merchantIdentifierConfigId`, which identifies the configuration in a later delete request.
Diagram alerts-create-card-acceptor-id
API Reference: `POST /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/card-acceptor-ids`

#### Create a card acceptor name configuration {#create-a-card-acceptor-name-configuration}

For this use case, you create an `AlertsCardAcceptorNameConfig` object and send a request to the **createAlertsCardAcceptorNameConfig** operation. The API validates and adds the CAN configuration to the submerchant record. The response returns a `merchantIdentifierConfigId`, which identifies the configuration in a later delete request.
Diagram alerts-create-card-acceptor-name
API Reference: `POST /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/card-acceptor-names`

### Get card acceptor ID configurations {#get-card-acceptor-id-configurations}

For this use case, you retrieve CAID configurations for an existing submerchant. You send a request to the **getAlertsCardAcceptorIdConfigs** operation. You can filter the results by ARID and CAID. The API validates the request and returns a pageable list of matching configurations.
Diagram alerts-get-card-acceptor-ids
API Reference: `GET /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/card-acceptor-ids`

### Get card acceptor name configurations {#get-card-acceptor-name-configurations}

For this use case, you retrieve CAN configurations for an existing submerchant. You send a request to the **getAlertsCardAcceptorNameConfigs** operation. You can filter the results by card acceptor name. The API validates the request and returns a pageable list of matching configurations.
Diagram alerts-get-card-acceptor-names
API Reference: `GET /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/card-acceptor-names`

### Delete a card acceptor ID configuration {#delete-a-card-acceptor-id-configuration}

For this use case, you remove a CAID configuration from a submerchant. You send a `DELETE` request to the **deleteAlertsCardAcceptorIdConfig** operation. Provide the `merchantIdentifierConfigId` value from a create or retrieve response as the `merchant_identifier_config_id` query parameter. The API validates and removes the configuration.
Diagram alerts-delete-submerchant-identifiers
API Reference: `DELETE /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/card-acceptor-ids`

### Delete a card acceptor name configuration {#delete-a-card-acceptor-name-configuration}

For this use case, you remove a CAN configuration from a submerchant. You send a `DELETE` request to the **deleteAlertsCardAcceptorNameConfig** operation. Provide the `merchantIdentifierConfigId` value from a create or retrieve response as the `merchant_identifier_config_id` query parameter. The API validates and removes the configuration.
Diagram alerts-delete-card-acceptor-name
API Reference: `DELETE /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/card-acceptor-names`

## Manage Merchant Descriptor Match Criteria {#manage-merchant-descriptor-match-criteria}

Merchant Descriptor Match Criteria (MDMC) help recognize descriptor variations across acquirers, processors, payment channels, and regions. Unlike CAIDs, which require exact ARID and CAID pairing, MDMC uses pattern-based matching against merchant descriptor information in transaction data.

Merchants can define criteria using `EXACT_MATCH` (full string match) or `STARTS_WITH_MATCH` (prefix match, minimum 3 characters). MDMC supports batch creation (up to 100 items per request) with partial success semantics - some criteria may succeed while others fail validation. Use these endpoints to create one or many MDMC(s), retrieve a list of them, or to remove a single criterion at a time.

### Create merchant descriptor match criteria {#create-merchant-descriptor-match-criteria}

For this use case, you add descriptor match criteria to an existing merchant. You create an `AlertsMerchantDescriptorMatchCriteria` object and send a request to the **createAlertsMerchantDescriptorMatchCriteria** operation. The API validates each criterion and returns successful and failed items. Each successful item includes a `merchantIdentifierConfigId`. Use this value as the `{merchant_identifier_config_id}` path parameter when deleting that criterion.
Diagram alerts-create-descriptor-match-criteria
API Reference: `POST /alerts/merchants/{member_id}/merchant-descriptor-match-criteria`

### Get merchant descriptor match criteria {#get-merchant-descriptor-match-criteria}

For this use case, you retrieve descriptor match criteria for an existing merchant. You send a request to the **getAlertsMerchantDescriptorMatchCriteria** operation. You can filter the results by match input, match type, and status. The API validates the request and returns a pageable list of matching criteria.
Diagram alerts-get-descriptor-match-criteria
API Reference: `GET /alerts/merchants/{member_id}/merchant-descriptor-match-criteria`

### Delete a merchant descriptor match criterion {#delete-a-merchant-descriptor-match-criterion}

For this use case, you remove one descriptor match criterion. You send a `DELETE` request to the **deleteAlertsMerchantDescriptorMatchCriterion** operation. Provide the criterion's `merchantIdentifierConfigId` value as the `{merchant_identifier_config_id}` path parameter. The API validates and removes the criterion.
Diagram alerts-delete-descriptor-match-criterion
API Reference: `DELETE /alerts/merchants/{member_id}/merchant-descriptor-match-criteria/{merchant_identifier_config_id}`

## Next Steps {#next-steps}

After completing the applicable use cases, validate your implementation using the [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) section and review the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md#apis) for complete request, response, parameter, and field definitions.

* See [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) for test data relevant to these use cases.
* See [Code and Formats](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md) for common error codes, HTTP response status codes, and recovery guidance.