# Retail Sales Analytics
source: https://developer.mastercard.com/small-business-credit-analytics/documentation/use-cases/retail-sales-analytics/index.md

## Overview {#overview}

Retail Sales Analytics metrics provide a weekly/monthly breakdown of an individual merchant location's performance across 45 metrics for up to the last 12 months. Lenders can utilize these metrics to better determine a small business' identity and sales health.

|   Metrics Category    |                              Description                              |                       Sample Metrics                       |
|-----------------------|-----------------------------------------------------------------------|------------------------------------------------------------|
| **Business Metadata** | Metrics on small business identity and operations                     | `Last seen transaction date` `First seen transaction date` |
| **Merchant Sales**    | Metrics on business retail sales and sales growth                     | `Trend on average card spend`                              |
| **Channel Sales**     | Metrics on customer's preferred channel at the business location      | `% Spend from online channels`                             |
| **Customer Loyalty**  | Metrics on recurring customer activity at the small business location | `% of repeat customers`                                    |
| **Returns**           | Metrics on the rate of returned purchases                             | `% of returned transactions`                               |
| **Business Risk**     | Metrics on business authorization and fraud rates                     | `Historical weekly or monthly card spend`                  |

## Scenario Summary {#scenario-summary}

|      Element      |                                                                                                           Detail                                                                                                           |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Context**       | A lender is evaluating a small business loan application and needs transaction-based performance data to supplement traditional financial statements                                                                       |
| **Goal**          | Retrieve 45 weekly or monthly Retail Sales Analytics metrics for a specific merchant location to assess sales health, growth trends, and risk indicators                                                                   |
| **Actors**        | **Lender / Underwriter** --- initiates the API calls; **Small Business** --- provides consent and merchant details                                                                                                         |
| **Preconditions** | 1. Lender has a Mastercard Developers project with Sandbox or Production credentials 2. Lender has the merchant's business name and address, or Acquirer Merchant ID 3. Merchant has provided consent (`has_consent=true`) |
| **Outcome**       | Lender receives up to 12 months of weekly or monthly sales metrics (transaction volume, spend, chargebacks, channel mix, etc.) to incorporate into credit decisioning                                                      |

## Pre-requisites {#pre-requisites}

Prior to accessing the Retail Sales Analytics metrics, clients or lenders must meet the following pre-requisites:

### 1. Merchant Matching {#1-merchant-matching}

The client or lender must have the basic details below for the small business (SMB) merchant location. Small Business Credit Analytics API performs the merchant match based on the information provided for the merchant location. The best matches are shared with the client. The client then decides which result is the intended merchant location to request data on.

* Country
* ID Type
* ID Value
* Merchant Location Name
* Address
* City
* State
* Postal Code

**Note** - The Small Business Credit Analytics API provides clients with access to business metrics pertaining to a distinct merchant location. In case a merchant has presence across multiple locations, the client will need to request details for each merchant location separately.

### 2. Retail Sales Analytics Metrics {#2-retail-sales-analytics-metrics}

* The client must have consent from the merchant before using the API to request merchant metrics.
* The Location ID returned in the merchant match response in the previous step is needed to request merchant metrics.
* To request metrics (weekly or monthly), the client needs to specify "retail_sales_analytics" for the metrics_type parameter, and "weekly" or "monthly" for the metrics_frequency parameter in the request.

## RSA in SMB Lending Flow {#rsa-in-smb-lending-flow}

![RSA in SMB Lending Flow](https://static.developer.mastercard.com/content/small-business-credit-analytics/img/mermaid/retail_sales_analytics.svg)

## Accessing RSA Metrics {#accessing-rsa-metrics}

### Step 1: Merchant Matching {#step-1-merchant-matching}

The Matches endpoint resolves merchant identity from metadata. This step is required before requesting the metrics because the Metrics endpoint only accepts a `location_id`.

API Reference: `GET /matches`

1. The small business or retailer provides their details to the lender for credit purposes

2. The lender makes the Small Business Credit Analytics API call for a merchant match. The request for a merchant match can be made in one of the following two ways:

   1. By providing ID parameters (Recommended)
      * country
      * id type
      * id value
   2. By providing Name and Address details
      * country
      * merchant location name
      * address
      * city
      * state
      * postal code
3. The Small Business Credit Analytics API takes the input to check the merchant database for location:

   * In the case of multiple matches found, the API response returns the location details in decreasing order of similarity between input and match found.
     * For TaxID matching (available in the selected countries), a maximum of 10 matches can be returned as part of the API response. For other matching methods (Name and Address, MID), a maximum of 3 matches can be returned.
   * The response consists of the additional parameters for Location ID (unique ID for location in the Mastercard system).
   * You will receive an error response for an invalid request or any missing request parameter.
4. The lender must check whether the intended merchant location appears in the API response.

   * In case of a validation error or no match is found or the intended merchant location is not in the API response, the lender needs to update the input and repeat step 2.

### Step 2: Retrieve Retail Sales Analytics Metrics {#step-2-retrieve-retail-sales-analytics-metrics}

The Metrics endpoint is used here because the lender now has a confirmed `location_id` and needs to retrieve performance data to inform the credit decision.

API Reference: `GET /metrics/{location_id}`

1. The lender makes the API call for metrics on the identified location from the merchant match response. The request requires the following input parameters:

   * Location ID
   * `has_consent`
   * Metrics Type (Optional)- Default value: "retail_sales_analytics"
   * Metrics Frequency- "weekly" or "monthly"
2. The API validates the inputs and responds with metrics for the selected merchant location. You will receive an error response for an invalid request or any missing request parameter. Some metric values may be `0`, `null`, or `-1` to indicate low or missing transaction volume --- see [Data Explanations](https://developer.mastercard.com/small-business-credit-analytics/documentation/tutorials-and-guides/data-explanations/index.md#retail-sales-analytics-metrics_typeretail_sales_analytics) for what each value means.

3. The lender processes the returned metrics and other data sources for credit decisions, performs internal credit decisioning, and communicates the credit decision outcome to small businesses or retailers.

Retail Sales Benchmarks

## Next Steps {#next-steps}

* [Testing](https://developer.mastercard.com/small-business-credit-analytics/documentation/testing/index.md) --- sandbox test cases for both endpoints
* [Code and Formats](https://developer.mastercard.com/small-business-credit-analytics/documentation/code-and-formats/index.md) --- error handling reference