# 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 the latest month for the merchant location identified through merchant match.

## 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.

## Test Cases {#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
            }
        ]
    }
  ]
}
```

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
            }
        ]
    }
  ]
}
```

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."
      }
    ]
  }
}
```

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."
      }
    ]
  }
}
```

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."
      }
    ]
  }
}
```

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'."
      }
    ]
  }
}
```

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"."
      }
    ]
  }
}
```