# Retail Sales Benchmarks
source: https://developer.mastercard.com/small-business-credit-analytics/documentation/testing/merchant-metrics/retail-sales-benchmarks/index.md

## Introduction {#introduction}

The end-point allows the client to retrieve 14 retail sales benchmark metrics for up to 12 latest months (depending on the region) for the merchant location identified through merchant match. The final number of months in the response depends on the selected country. Please contact your Mastercard representative to know more.

## Pre-requisites {#pre-requisites}

Refer to the [Merchant Metrics - Retail Sales Benchmarks](https://developer.mastercard.com/small-business-credit-analytics/documentation/use-cases/retail-sales-benchmarks/index.md) use case details.

## RSB Test Cases {#rsb-test-cases}

### Positive Test Cases {#positive-test-cases}

Test Data

Below you may find the query parameters associated with this test case.

|  Parameter Name   |                Value                 |
|-------------------|--------------------------------------|
| location_id       | a1b2c3d4-0000-1234-abcd-000000000001 |
| metrics_type      | retail_sales_benchmarks              |
| metrics_frequency | Monthly                              |
| has_consent       | true                                 |

Request

```python
{
    "location_id": "a1b2c3d4-0000-1234-abcd-000000000001", #note that this is specified in the url path, not the query string
    "metrics_type": "retail_sales_benchmarks",
    "metrics_frequency": "Monthly",
    "has_consent": "true"
}
```

Response

```python
{
  "locationId": "a1b2c3d4-0000-1234-abcd-000000000001",
  "merchantCategoryCode": 478,
  "naicsCode": "454113",
  "industryName": "Arts and Craft Stores",
  "firstSeenTxnDate": "2008-08-14",
  "lastSeenTxnDate": "2023-02-18",
  "metricsFrequency": "Monthly",
  "metricsLists": [
    {
        "periodStartDate": "2022-01-01",
        "periodEndDate": "2022-01-31",
        "year": 2023,
        "metrics": [
            {
                "name": "return_txn_amt_index",
                "value": 116.0
            },
            {
                "name": "spend_per_card_avg_index",
                "value": 100.0
            },
            {
                "name": "return_txn_cnt_index",
                "value": 69.0
            },
            {
                "name": "txn_cnt_index",
                "value": 118.0
            },
            {
                "name": "chargeback_rate_perc_disputed_index",
                "value": 93.0
            },
            {
                "name": "cards_repeated_6m_index",
                "value": 124.0
            },
            {
                "name": "num_cards_index",
                "value": 121.0
            },
            {
                "name": "cards_repeated_12m_index",
                "value": 114.0
            },
            {
                "name": "online_txn_perc_index",
                "value": 107.0
            },
            {
                "name": "net_spend_index",
                "value": 114.0
            },
            {
                "name": "chargeback_rate_perc_fraud_index",
                "value": 107.0
            },
            {
                "name": "recurring_txn_perc_index",
                "value": 122.0
            },
            {
                "name": "tkt_size_avg_index",
                "value": 100.0
            },
            {
                "name": "declined_rate_perc_index",
                "value": 103.0
            }
        ]
    },
          # Month 2 to 12
      ...
      {
          "periodStartDate": "2022-02-01",
          "periodEndDate": "2022-02-28",
          "year": 2023,
          "metrics": [
              ...
          ]
      }
  ]
}
```

**Validate:**

* HTTP status is `200 OK`
* `locationId` matches the requested `location_id`
* `metricsFrequency` is `Monthly`
* `metricsLists` contains up to 12 monthly entries
* Each entry has 14 benchmark index metrics (e.g., `txn_cnt_index`, `spend_per_card_avg_index`)
For merchants with low transaction volume, you may receive below valid responses including:

* 0: In the event that no transactions were observed for the respective metrics at the merchant location.
* null: In the event that the minimum number of transactions needed to calculate the respective metrics was not met in that period for the merchant location.
* -1 : In the event that there were transactions at the merchant location but insufficient transactions in the merchant competition set.

<br />

Test Data

Below you may find the query parameters associated with this test case.

|  Parameter Name   |                Value                 |
|-------------------|--------------------------------------|
| location_id       | a1b2c3d4-0000-1234-abcd-000000000002 |
| metrics_type      | retail_sales_benchmarks              |
| metrics_frequency | Weekly                               |
| has_consent       | true                                 |

Request

```python
{
    "location_id": "a1b2c3d4-0000-1234-abcd-000000000002", #note that this is specified in the url path, not the query string
    "metrics_type": "retail_sales_benchmarks",
    "metrics_frequency": "Monthly",
    "has_consent": "true"
}
```

Response

```python
{
  "locationId": "a1b2c3d4-0000-1234-abcd-000000000002",
  "merchantCategoryCode": 479,
  "naicsCode": "454114",
  "industryName": "Arts and Craft Stores",
  "firstSeenTxnDate": "2015-08-26",
  "lastSeenTxnDate": "2023-02-18",
  "metricsFrequency": "Monthly",
  "metricsLists": [
    {
        "periodStartDate": "2022-01-01",
        "periodEndDate": "2022-01-31",
        "year": 2023,
        "metrics": [
            {
                "name": "return_txn_amt_index",
                "value": 0
            },
            {
                "name": "spend_per_card_avg_index",
                "value": 175.0
            },
            {
                "name": "return_txn_cnt_index",
                "value": null
            },
            {
                "name": "txn_cnt_index",
                "value": 140.0
            },
            {
                "name": "chargeback_rate_perc_disputed_index",
                "value": 0
            },
            {
                "name": "cards_repeated_6m_index",
                "value": -1
            },
            {
                "name": "num_cards_index",
                "value": 98.0
            },
            {
                "name": "cards_repeated_12m_index",
                "value": -1
            },
            {
                "name": "online_txn_perc_index",
                "value": null
            },
            {
                "name": "net_spend_index",
                "value": 116.0
            },
            {
                "name": "chargeback_rate_perc_fraud_index",
                "value": 0
            },
            {
                "name": "recurring_txn_perc_index",
                "value": 0
            },
            {
                "name": "tkt_size_avg_index",
                "value": 170.0
            },
            {
                "name": "declined_rate_perc_index",
                "value": -1
            }
        ]
    },
          # Month 2 to 12
      ...
      {
          "periodStartDate": "2022-02-01",
          "periodEndDate": "2022-02-28",
          "year": 2023,
          "metrics": [
              ...
          ]
      }
  ]
}
```

**Validate:**

* HTTP status is `200 OK`
* Metrics contain `0`, `null`, or `-1` alongside valid numeric values
* `0` = no transactions at merchant; `null` = insufficient transactions; `-1` = insufficient competitor data

### Negative Test Cases {#negative-test-cases}

Test Data

Below you may find the query parameters associated with this test case.

|  Parameter Name   |                Value                 |
|-------------------|--------------------------------------|
| location_id       | a1b2c3d4-0000-1234-abcd-000000000005 |
| metrics_type      | retail_sales_benchmarks              |
| metrics_frequency | Monthly                              |
| has_consent       | true                                 |

Request

```python
{
    "location_id": "a1b2c3d4-0000-1234-abcd-000000000005", #note that this is specified in the url path, not the query string
    "metrics_type": "retail_sales_benchmarks",
    "metrics_frequency": "Monthly",
    "has_consent": "true"
}
```

Response

```python
{
  "Errors": {
    "Error": [
      {
        "Source": "CreditAnalytics",
        "ReasonCode": "METRICS_NOT_FOUND",
        "Description": "No available metrics for the provided merchant information",
        "Recoverable": false,
        "Details": "Retail Sales benchmarks not available due to insufficient transactions or benchmarking data at selected merchant location in the previous month."
      }
    ]
  }
}
```

**Validate:**

* HTTP status is `404`
* `ReasonCode` is `METRICS_NOT_FOUND`

**Refer:** [Code and Formats](https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md) for details and structure of error response.
Test Data

Below you may find the query parameters associated with this test case.

|  Parameter Name   |                Value                 |
|-------------------|--------------------------------------|
| location_id       | a1b2c3d4-0000-1234-abcd-000000000006 |
| metrics_type      | retail_sales_benchmarks              |
| metrics_frequency | Monthly                              |
| has_consent       | true                                 |

Request

```python
{
    "location_id": "a1b2c3d4-0000-1234-abcd-000000000006", #note that this is specified in the url path, not the query string
    "metrics_type": "retail_sales_benchmarks",
    "metrics_frequency": "Monthly",
    "has_consent": "true"
}
```

Response

```python
{
  "Errors": {
    "Error": [
      {
        "Source": "CreditAnalytics",
        "ReasonCode": "LOCATION_NOT_FOUND",
        "Description": "No matched merchant found",
        "Recoverable": false,
        "Details": "Ensure that the Location ID is consistent with the provided response from Matches API. Otherwise, try calling the Matches API again to get a Location ID."
      }
    ]
  }
}
```

**Validate:**

* HTTP status is `404`
* `ReasonCode` is `LOCATION_NOT_FOUND`

**Refer:** [Code and Formats](https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md) for details and structure of error response.
Test Data

Below you may find the query parameters associated with this test case.

|  Parameter Name   |                Value                 |
|-------------------|--------------------------------------|
| location_id       | a1b2c3d4-0000-1234-abcd-000000000007 |
| metrics_type      | retail_sales_benchmarks              |
| metrics_frequency | Monthly                              |
| has_consent       | false                                |

Request

```python
{
    "location_id": "a1b2c3d4-0000-1234-abcd-000000000007", #note that this is specified in the url path, not the query string
    "metrics_type": "retail_sales_benchmarks",
    "metrics_frequency": "Monthly",
    "has_consent": "false"
}
```

Response

```python
{
  "Errors": {
    "Error": [
      {
        "Source": "CreditAnalytics",
        "ReasonCode": "CONSENT_NOT_PROVIDED",
        "Description": "has_consent parameter was set to 'false'",
        "Recoverable": false,
        "Details": "Consent from the merchant is required in order to access performance metrics for said merchant."
      }
    ]
  }
}
```

**Validate:**

* HTTP status is `403`
* `ReasonCode` is `CONSENT_NOT_PROVIDED`

**Refer:** [Code and Formats](https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md) for details and structure of error response.
Test Data

Below you may find the query parameters associated with this test case.

|  Parameter Name   |                Value                 |
|-------------------|--------------------------------------|
| location_id       | a1b2c3d4-0000-1234-abcd-000000000011 |
| metrics_type      | RSB                                  |
| metrics_frequency | Monthly                              |
| has_consent       | true                                 |

Request

```python
{
    "location_id": "a1b2c3d4-0000-1234-abcd-000000000011", #note that this is specified in the url path, not the query string
    "metrics_type": "RSB",
    "metrics_frequency": "Monthly",
    "has_consent": "true"
}
```

Response

```python
{
  "Errors": {
    "Error": [
      {
        "Source": "CreditAnalytics",
        "ReasonCode": "INVALID_DATA: metrics_type",
        "Description": "Validation failed for metrics_type parameter",
        "Recoverable": false,
        "Details": "An invalid value was entered for metrics_type. Valid values are 'retail_sales_analytics' or 'retail_sales_benchmarks'."
      }
    ]
  }
}
```

**Validate:**

* HTTP status is `400`
* `ReasonCode` is `INVALID_DATA`

**Refer:** [Code and Formats](https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md) for details and structure of error response.
Test Data

Below you may find the query parameters associated with this test case.

|  Parameter Name   |                Value                 |
|-------------------|--------------------------------------|
| location_id       | a1b2c3d4-0000-1234-abcd-000000000011 |
| metrics_type      | retail_sales_analytics               |
| metrics_frequency | Weekly                               |
| has_consent       | true                                 |

Request

```python
{
    "location_id": "a1b2c3d4-0000-1234-abcd-000000000011", #note that this is specified in the url path, not the query string
    "metrics_type": "retail_sales_benchmarks",
    "metrics_frequency": "Weekly",
    "has_consent": "true"
}
```

Response

```python
{
  "Errors": {
    "Error": [
      {
        "Source": "CreditAnalytics",
        "ReasonCode": "INVALID_DATA: metrics_frequency",
        "Description": "Validation failed for metrics_frequency parameter",
        "Recoverable": false,
        "Details": "An invalid value was entered for metrics_frequency, the value must match "monthly" for metrics_type "retail_sales_benchmarks"."
      }
    ]
  }
}
```

**Validate:**

* HTTP status is `400`
* `ReasonCode` is `INVALID_DATA`

**Refer:** [Code and Formats](https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md) for details and structure of error response.