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

This article provides sample use cases to show different ways you can use the Merchant Self Services API for the Consumer Clarity service. Each use case includes a specific request and response example corresponding to that use case. [Code and Formats](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md) provides information on error codes and response status codes, which are common to all of these use cases.

## Onboard a submerchant {#onboard-a-submerchant}

In this scenario, you are adding one of your submerchants to your existing merchant record. A submerchant requires basic merchant information and locations, card acceptor names, or acquirer reference IDs to complete the onboarding. You can also add a logo.

For this use case, you'll [create a submerchant](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#create-a-submerchant), then [add locations](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#add-locations-to-an-existing-submerchant), [add card acceptor names](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#add-card-acceptor-names-to-an-existing-submerchant-default-location), [add acquirer reference IDs](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#add-acquirer-reference-ids-to-an-existing-submerchant-default-location), [add a logo](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#add-a-logo-to-an-existing-submerchant), and [add descriptors](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#add-descriptors-to-an-existing-submerchant-location) to that submerchant.

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

Here, you're adding one of your submerchants to your existing merchant record. You create a `SubMerchant` object and send a request to the **createSubMerchant** endpoint of the Merchant Self Services API. The API validates and persists the `SubMerchant` and returns a `SubMerchantResource`.

**Corresponding test case data:** [TD1: Create a submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td1-create-a-submerchant)
Diagram create-submerchant
API Reference: `GET /sub-merchants`

### Add locations to an existing submerchant {#add-locations-to-an-existing-submerchant}

In this use case, you're adding location information to the submerchant to help make the them more recognizable. You send a request to the **addLocations** endpoint that contains a set of two unique locations: one default location and one non-default location. The Merchant Self Services API validates the request and returns a response containing a list of two items with the corresponding `locationId`, and returns a status of `PASS`.

**Corresponding test case data:** [TD8: Add locations to an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td8-add-locations-to-an-existing-submerchant)
Diagram add-location
API Reference: `POST /sub-merchants/{guid}/locations`

### Add card acceptor names to an existing submerchant default location {#add-card-acceptor-names-to-an-existing-submerchant-default-location}

Here, you send a request to the **addCardAcceptorNames** endpoint containing a unique set of card acceptor names. The Merchant Self Services API validates the request and returns a response containing a set of accepted card acceptor names with the corresponding `cardAcceptorId`, and returns a status of `PASS`.

**Corresponding test case data:** [TD16: Add card acceptor names to an existing submerchant default location](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td16-add-card-acceptor-names-to-an-existing-submerchant-default-location)
Diagram add-card-acceptor-name
API Reference: `POST /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names`

### Add acquirer reference IDs to an existing submerchant default location {#add-acquirer-reference-ids-to-an-existing-submerchant-default-location}

Now, you'll send a request to the **addAcquirerMerchantIds** endpoint to add acquirer reference IDs to the submerchant. The Merchant Self Services API validates the request and returns a response containing accepted and rejected Acquirer Reference ID/Card Acceptor ID pairs.

**Corresponding test case data:** [TD13: Add acquirer reference IDs to an existing submerchant default location](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td13-add-acquirer-reference-ids-to-an-existing-submerchant-default-location)
Diagram add-arid
API Reference: `POST /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids`

### Add a logo to an existing submerchant {#add-a-logo-to-an-existing-submerchant}

In this example, you want to add your logo to your merchant record to further make yourself recognizable for consumers. You create a `MerchantLogo` object by converting a JPG or PNG image to Base64 String and send a request to the **createMerchantLogo** endpoint. The Merchant Self Services API validates and persists the `MerchantLogo` and returns a `LogoResource`.

**Corresponding test case data:** [TD4: Add a logo to an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td4-add-a-logo-to-an-existing-submerchant)
Diagram add-logo
API Reference: `POST /merchants/{guid}/logos`

### Add descriptors to an existing submerchant location {#add-descriptors-to-an-existing-submerchant-location}

Here, you want to add descriptors to your merchant record to further help customers identify transactions. You send a request to the **addDescriptors** endpoint that contains a list of descriptors and their type. The Merchant Self Services API validates the request and returns a response containing a list of descriptors with their corresponding IDs.

**Corresponding test case data:** [TD21: Add descriptors to an existing submerchant location](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td21-add-descriptors-to-an-existing-submerchant-location)
Diagram add-descriptors
API Reference: `POST /sub-merchants/{guid}/locations/{location_id}/descriptors`

## Get an existing submerchant {#get-an-existing-submerchant}

Here, you want to retrieve version information for one of your submerchants. You send a request to the **getSubMerchantByGuid** endpoint. The Merchant Self Services API validates the request and returns your merchant record.

**Corresponding test case data:** [TD2: Get an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td2-get-an-existing-submerchant)
Diagram get-sub
API Reference: `GET /sub-merchants/{guid}`

## Update the legalAddress of an existing sub-merchant {#update-the-legaladdress-of-an-existing-sub-merchant}

In this example, you create a `SubMerchant` object and send a request to the **updateSubMerchant** endpoint of the Merchant Self Services API. The API validates and persists the whole `SubMerchant` object, including the updated legal address, and returns a `SubMerchantResource`.

**Corresponding test case data:** [TD3: Update the legalAddress of an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td3-update-the-legaladdress-of-an-existing-submerchant)
Diagram update-legal-address
API Reference: `PUT /sub-merchants/{guid}`

## Get a logo of an existing submerchant {#get-a-logo-of-an-existing-submerchant}

For this use case, you want to retrieve your existing logo from the Merchant Self Services API. You send a request to the **getLogoByMerchantGuid** endpoint and the API validates the request and returns a `LogoImageResource`.

**Corresponding test case data:** [TD6: Get logo of an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td6-get-logo-of-an-existing-submerchant)
Diagram get-logo
API Reference: `GET /merchants/{guid}/logos`

## Update a logo of an existing submerchant {#update-a-logo-of-an-existing-submerchant}

Here, you want to update your existing logo. You create a `MerchantLogo` object by converting a JPG or PNG image to Base64 String and send a request to the **updateMerchantLogo** endpoint. The Merchant Self Services API validates and persists the `MerchantLogo` and returns a `LogoResource`.

**Corresponding test case data:** [TD5: Update logo of an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td5-update-logo-of-an-existing-submerchant)
Diagram update-logo
API Reference: `PUT /merchants/{guid}/logos`

## Delete a logo of an existing submerchant {#delete-a-logo-of-an-existing-submerchant}

In this example, you want to delete your logo from the Merchant Self Services API. You send a request to the **deleteLogoByMerchantGuid** endpoint and the API validates the request and deletes your merchant logo.

**Corresponding test case data:** [TD7: Delete logo of an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td7-delete-logo-of-an-existing-submerchant)
Diagram delete-logo
API Reference: `DELETE /merchants/{guid}/logos`

## Get all locations of an existing submerchant {#get-all-locations-of-an-existing-submerchant}

In this scenario, you send a request to the **getAllLocations** endpoint. The Merchant Self Services API validates the request and returns a pageable response including all locations of the submerchant.

**Corresponding test case data:** [TD9: Get all locations of an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td9-get-all-locations-of-an-existing-submerchant)
Diagram get-all-locations
API Reference: `GET /sub-merchants/{guid}/locations`

## Get a location by ID {#get-a-location-by-id}

For this use case, you send a request to the **getLocationById** endpoint. The Merchant Self Services API validates the request and returns a `LocationWithoutCardAcceptorsResource`.

**Corresponding test case data:** [TD10: Get a location by ID](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td10-get-a-location-by-id)
Diagram get-location-by-id
API Reference: `GET /sub-merchants/{guid}/locations/{location_id}`

## Update a location of an existing submerchant {#update-a-location-of-an-existing-submerchant}

Here, you send a request to the **updateLocation** endpoint. The Merchant Self Services API validates the request and persists the location and returns a `LocationWithoutCardAcceptorsResource`.

**Corresponding test case data:** [TD11: Update location of an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td11-update-location-of-an-existing-submerchant)
Diagram update-location
API Reference: `PUT /sub-merchants/{guid}/locations/{location_id}`

## Get accepted Acquirer Reference ID - Card Acceptor ID pairs {#get-accepted-acquirer-reference-id---card-acceptor-id-pairs}

In this use case, you want to retrieve only the accepted Acquirer Reference ID/Card Acceptor ID pairs by sending a request to the **getAcceptedAcquirerMerchantIds** endpoint.

The Merchant Self Services API validates the request and returns a response containing accepted Acquirer Reference ID/Card Acceptor ID pairs only.

**Corresponding test case data:** [TD14: Get accepted Acquirer Reference ID - Card Acceptor ID pairs](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td14-get-accepted-acquirer-reference-id---card-acceptor-id-pairs)
Diagram get-aquirer-ref-id
API Reference: `GET /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids`

## Delete existing Acquirer Reference ID - Card Acceptor ID pair {#delete-existing-acquirer-reference-id---card-acceptor-id-pair}

In this example, you want to delete an accepted Acquirer Reference ID/Card Acceptor ID pair by sending a request to the **deleteAcceptedAcquirerMerchantId** endpoint.

The Merchant Self Services API validates the request, deletes the accepted Acquirer Reference ID/Card Acceptor ID pair, and returns a 204 response code.

**Corresponding test case data:** [TD15: Delete existing Acquirer Reference ID - Card Acceptor ID pair](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td15-delete-existing-acquirer-reference-id---card-acceptor-id-pair)
Diagram delete-aquirer-ref-id
API Reference: `DELETE /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids/{acquirer_merchant_id}`

## Get all card acceptor names {#get-all-card-acceptor-names}

Here, you send a request to the **getCardAcceptorNames** endpoint. The Merchant Self Services API validates the request and returns a pageable response of all card acceptor names under a location.

**Corresponding test case data:** [TD17: Get all card acceptor names of a submerchant location](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td17-get-all-card-acceptor-names-of-a-submerchant-location)
Diagram get-all-card-acceptor-names
API Reference: `GET /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names`

## Get a card acceptor name by ID {#get-a-card-acceptor-name-by-id}

Here, you send a request to the **getCardAcceptorNameById** endpoint. The Merchant Self Services API validates the request and returns a `CardAcceptorDataResource`.

**Corresponding test case data:** [TD18: Get a card acceptor name by ID](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td18-get-a-card-acceptor-name-by-id)
Diagram get-card-acceptor-name-by-id
API Reference: `GET /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names/{id}`

## Update a card acceptor name {#update-a-card-acceptor-name}

In this scenario, you send a request to the **updateCardAcceptorNameById** endpoint. The Merchant Self Services API validates the request, persists the card acceptor name, and returns a `CardAcceptorDataResource`.

**Corresponding test case data:** [TD19: Update a card acceptor name](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td19-update-a-card-acceptor-name)
Diagram update-card-acceptor-name
API Reference: `PUT /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names/{id}`

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

For this use case, you send a request to the **deleteCardAcceptorNameById** endpoint. The Merchant Self Services API validates the request and deletes the `cardAcceptorName`.

**Corresponding test case data:** [TD20: Delete a card acceptor name](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td20-delete-a-card-acceptor-name)
Diagram delete-card-acceptor-name
API Reference: `DELETE /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names/{id}`

## Get all descriptors of an existing submerchant {#get-all-descriptors-of-an-existing-submerchant}

Here, you send a request to the **getDescriptors** endpoint. The Merchant Self Services API validates the request and returns a pageable response of all descriptors associated with a location.

**Corresponding test case data:** [TD22: Get all descriptors of a submerchant location](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td22-get-all-descriptors-of-a-submerchant-location)
Diagram get-all-descriptors
API Reference: `GET /sub-merchants/{guid}/locations/{location_id}/descriptors`

## Delete a descriptor of an existing submerchant {#delete-a-descriptor-of-an-existing-submerchant}

For this use case, you send a request to the **deleteRawDescriptor** endpoint. The Merchant Self Services API validates the request and deletes the specified descriptor.

**Corresponding test case data:** [TD23: Delete the raw descriptor of a submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td23-delete-the-raw-descriptor-of-a-submerchant)
Diagram delete-descriptor
API Reference: `DELETE /sub-merchants/{guid}/locations/{location_id}/descriptors/{descriptor_id}`

## Delete a location of an existing submerchant {#delete-a-location-of-an-existing-submerchant}

In this scenario, you send a request to the **deleteLocation** endpoint. The Merchant Self Services API validates the request and deletes the location.

**Corresponding test case data:** [TD12: Delete location of an existing submerchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td12-delete-location-of-an-existing-submerchant)
Diagram delete-location
API Reference: `DELETE /sub-merchants/{guid}/locations/{location_id}`

## Deactivate or activate an existing merchant {#deactivate-or-activate-an-existing-merchant}

In this use case, you might want to deactivate your merchant record in the Merchant Self Services API. You send a request to the **changeSubMerchantState** endpoint and the API validates the request and deactivates the merchant.

To re-activate a deactivated merchant record, send the same request to the **changeSubMerchantState** endpoint.

**Corresponding test case data:** [TD24: Deactivate an existing merchant](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td24-deactivate-an-existing-merchant)
Diagram deactivate-merchant
API Reference: `GET /sub-merchants/{guid}/states`

## Add only invalid card acceptor names to an existing submerchant default location {#add-only-invalid-card-acceptor-names-to-an-existing-submerchant-default-location}

In this scenario, you send a request to the **addCardAcceptorNames** endpoint that contains card acceptor names that are already associated with another merchant and are all invalid.

The Merchant Self Services API validates and persists the card acceptor names and returns a response containing a set of accepted card acceptor names with the corresponding `cardAcceptorId`, and returns a status of `FAILED`.

**Corresponding test case data:** [TD25: Add only invalid card acceptor names to an existing submerchant default location](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td25-add-only-invalid-card-acceptor-names-to-an-existing-submerchant-default-location)
Diagram add-invalid-card-acceptor-name
API Reference: `POST /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names`

## Add card acceptor names to an existing submerchant default location with at least one valid card acceptor name {#add-card-acceptor-names-to-an-existing-submerchant-default-location-with-at-least-one-valid-card-acceptor-name}

For this use case, you send a request to the **addCardAcceptorNames** endpoint that contains one valid card acceptor name. It also contains other card acceptor names that are already associated with another merchant.

The Merchant Self Services API validates and persists the card acceptor names. Duplicate card acceptor names are returned with a status of `FAILED` in the response and the others with a status of `PASS`.

**Corresponding test case data:** [TD26: Add card acceptor names to an existing submerchant default location with at least one valid card acceptor name](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td26-add-card-acceptor-names-to-an-existing-submerchant-default-location-with-at-least-one-valid-card-acceptor-name)
Diagram add-valid-invalid-card-acceptor-name
API Reference: `POST /sub-merchants/{guid}/locations/{location_id}/card-acceptor-names`

## Add AcquirerMerchant object with one invalid Acquirer Reference ID - Card Acceptor ID pair {#add-acquirermerchant-object-with-one-invalid-acquirer-reference-id---card-acceptor-id-pair}

Here, you try adding an Acquirer Reference ID/Card Acceptor ID pair that's already associated with another merchant and send a request to the **addAcquirerMerchantIds** endpoint.

The Merchant Self Services API validates the request and returns a response containing an empty list of `acceptedIds`. Any duplicate Acquirer Reference ID/Card Acceptor ID pairs are added to the list of `rejectedIds` in the response.

**Corresponding test case data:** [TD27: Add an AcquirerMerchant object with one invalid Acquirer Reference ID - Card Acceptor ID pair](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td27-add-an-acquirermerchant-object-with-one-invalid-acquirer-reference-id---card-acceptor-id-pair)
Diagram add-invalid-aquirer-ref-id
API Reference: `POST /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids`

## Add AcquirerMerchant object with one valid and one invalid Acquirer Reference ID - Card Acceptor ID pair {#add-acquirermerchant-object-with-one-valid-and-one-invalid-acquirer-reference-id---card-acceptor-id-pair}

In this use case, you try adding a new Acquirer Reference ID/Card Acceptor ID pair and another one that's already associated with another merchant and you send a request to the **addAcquirerMerchantIds** endpoint.

The Merchant Self Services API validates and persists the valid Acquirer Reference ID/Card Acceptor ID pair and adds it to the `acceptedIds` in the response. Any duplicate Acquirer Reference ID/Card Acceptor ID pairs are added to the list of `rejectedIds` in the response.

**Corresponding test case data:** [TD28: Add an AcquirerMerchant object with one valid and one invalid Acquirer Reference ID - Card Acceptor ID pair](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md#td28-add-an-acquirermerchant-object-with-one-valid-and-one-invalid-acquirer-reference-id---card-acceptor-id-pair)
Diagram add-valid-invalid-aquirer-ref-id
API Reference: `POST /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids`

## Next Steps {#next-steps}

* See our [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) article for all specific test data relevant to these use cases.
* [Code and Formats](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md) provides information on the error codes and response status codes that are common to all of these use cases.