--- title: Analytics API description: "The **Analytics API** provides information about an individual seller’s business through different report and data gathering resources: * Customer service metric ratings and benchmark data * The Traffic Report * The Seller Standard Profiles Report" api_version: 1.3.2 api_name: analytics_api api_type: REST api_group: sell/analytics_api source_url: html: https://developer.ebay.com/develop/api/sell/analytics_api md: https://developer.ebay.com/develop/api/sell/analytics_api.md --- # Analytics API API The **Analytics API** provides information about an individual seller’s business through different report and data gathering resources: * Customer service metric ratings and benchmark data * The Traffic Report * The Seller Standard Profiles Report ## API Information **Title:** Analytics API **Version:** 1.3.2 **Description:** The _Analytics API_ provides data and information about a seller and their eBay business. The resources and methods in this API let sellers review information on their listing performance, metrics on their customer service performance, and details on their eBay seller performance rating. The three resources in the Analytics API provide the following data and information: * **Customer Service Metric** – Returns benchmark data and a metric rating pertaining to a seller's customer service performance as compared to other seller's in the same peer group. * **Traffic Report** – Returns data and information that shows how buyers are engaging with a seller's listings. * **Seller Standards Profile** – Returns information pertaining to a seller's profile rating. Sellers can use the data and information returned by the various Analytics API methods to determine where they can make improvements to increase sales and how they might improve their seller status as viewed by eBay buyers. For details on using this API, see [Analyzing seller performance](/api-docs/sell/static/performance/analyzing-performance.html "Selling Integration Guide"). **Base Path:** /sell/analytics/v1 ## API Methods The following API methods are available: ### getCustomerServiceMetric #### GET /customer_service_metric/{customer_service_metric_type}/{evaluation_type} **Description:** Use this method to retrieve a seller's performance and rating for the customer service metric. Control the response from the **getCustomerServiceMetric** method using the following path and query parameters: * **customer\_service\_metric\_type** controls the type of customer service transactions evaluated for the metric rating. * **evaluation\_type** controls the period you want to review. * **evaluation\_marketplace\_id** specifies the target marketplace for the evaluation. Currently, metric data is returned for only peer benchmarking. For details on the workings of peer benchmarking, see [Service metrics policy](https://www.ebay.com/help/policies/selling-policies/seller-performance-policy/service-metrics-policy?id=4769 "eBay Help pages"). For details on using and understanding the response from this method, see [Interpreting customer service metric ratings](/api-docs/sell/static/performance/customer-service-metric.html "Selling Integration Guide"). **Parameters:** - **customer_service_metric_type** (string) *required* - Use this path parameter to specify the type of customer service metrics and benchmark data you want returned for the seller. Supported types are: * `ITEM_NOT_AS_DESCRIBED` * `ITEM_NOT_RECEIVED` - **evaluation_marketplace_id** (string) *required* - Use this query parameter to specify the Marketplace ID to evaluate for the customer service metrics and benchmark data. For the list of supported marketplaces, see [Analytics API requirements and restrictions](/api-docs/sell/static/performance/analyzing-performance.html#restrictions). - **evaluation_type** (string) *required* - Use this path parameter to specify the evaluation period to use for the performance metrics. See [EvaluationTypeEnum](/develop/api/sell/analytics_api#sell-analytics_api-customer_service_metric-getcustomerservicemetric.evaluationtypeenum) for more information on the supported values. **OAuth scope** This request requires an access token created with the **Authorization Code Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Authorization Code Grant:** - `https://api.ebay.com/oauth/api_scope/sell.analytics.readonly` ### findSellerStandardsProfiles #### GET /seller_standards_profile **Description:** This call retrieves all the standards profiles for the associated seller. A _standards profile_ is a set of eBay seller metrics and the seller's associated compliance values (either `TOP_RATED`, `ABOVE_STANDARD`, or `BELOW_STANDARD`). A seller's multiple profiles are distinguished by two criteria, a "program" and a "cycle." A profile's _program_ is one of three regions where the seller may have done business, or `PROGRAM_GLOBAL` to indicate all marketplaces where the seller has done business. The _cycle_ value specifies whether the standards compliance values were determined at the last official eBay evaluation or at the time of the request. For more information on the interpreting the response payload of this method, see [Seller standards profile](/api-docs/sell/static/performance/seller-standards.html). **OAuth scope** This request requires an access token created with the **Authorization Code Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Authorization Code Grant:** - `https://api.ebay.com/oauth/api_scope/sell.analytics.readonly` ### getSellerStandardsProfile #### GET /seller_standards_profile/{program}/{cycle} **Description:** This call retrieves a single standards profile for the associated seller. A _standards profile_ is a set of eBay seller metrics and the seller's associated compliance values (either `TOP_RATED`, `ABOVE_STANDARD`, or `BELOW_STANDARD`). A seller can have multiple profiles distinguished by two criteria, a "program" and a "cycle." A profile's _program_ is one of three regions where the seller may have done business, or `PROGRAM_GLOBAL` to indicate all marketplaces where the seller has done business. The _cycle_ value specifies whether the standards compliance values were determined at the last official eBay evaluation (`CURRENT`) or at the time of the request (`PROJECTED`). Both cycle and a program values are required URI parameters for this method. For more information on the interpreting the response payload of this method, see [Seller standards profile](/api-docs/sell/static/performance/seller-standards.html). **Parameters:** - **cycle** (string) *required* - This path parameter is used to specify the cycle for which metrics and metadata will be retrieved. See [CycleTypeEnum](/develop/api/sell/analytics_api#sell-analytics_api-seller_standards_profile-getsellerstandardsprofile.cycletypeenum) for a list of supported values. - **program** (string) *required* - This path parameter is used to specify the seller standards program for which metrics and metadata will be retrieved. See [ProgramEnum](/develop/api/sell/analytics_api#sell-analytics_api-seller_standards_profile-getsellerstandardsprofile.programenum) for a list of supported values. **OAuth scope** This request requires an access token created with the **Authorization Code Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Authorization Code Grant:** - `https://api.ebay.com/oauth/api_scope/sell.analytics.readonly` ### getTrafficReport #### GET /traffic_report **Description:** This method returns a report that details the user traffic received by a seller's listings. A traffic report gives sellers the ability to review how often their listings appeared on eBay, how many times their listings are viewed, and how many purchases were made. The report also returns the report's start and end dates, and the date the information was last updated. For more information, see [Traffic report details](/api-docs/sell/static/performance/traffic-report.html) **Parameters:** - **dimension** (string) *required* - This query parameter specifies the _dimension_, or "attribute," that is applied to the report **metric**. **Valid values:** `DAY` or `LISTING` **Examples** * If you specify `dimension=DAY` and `metric=CLICK_THROUGH_RATE`, the traffic report contains the number of times an item displayed on a search results page and the buyer clicked through to the View Item page for each day in the date range, as in: `12-06-17: 32, 12-07-17: 54, ...` * If you specify `dimension=LISTING` and `metric=LISTING_IMPRESSION_STORE`, the traffic report contains the number of times that listing appeared on the seller's store during the specified date range. For example, `LISTING_IMPRESSION_STORE: 157` means the item appeared 157 times in the store during the date range. * If you specify `dimension=LISTING` without specifying any **listing\_ids** in the parameter filter, the traffic report returned in the response contains a maximum of 200 listings. - **filter** (string) *required* - This query parameter refines the information returned in the traffic report. **Note:** URL encode all the values you supply in the **filter** parameter. See **URL encoding query parameter values** as described in [URL parameters](/api-docs/static/rest-request-components.html#parameters). Configure the following properties of the **filter** parameter to tune the traffic report to your needs: * **date\_range** Limits the report to the specified range of dates. This value can be formatted in one of two ways depending on the user's time zone. * **For America/Los\_Angeles time zone**, input the date range using `YYMMDD` format. As this is the default time zone used for timestamps in the report, the time zone does not need to be specified. Enclose the earliest date and end date for the report in brackets ("`[ ]`"), as follows: `[YYYYMMDD..YYYYMMDD]` For example: \[20240101..20240131\] * **For all other time zones**, input the date range using [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format, and specify the time zone using a UTC offset. A time zone offset is a positive or negative value that represents the number of hours a time zone is from UTC (see [UTC Time Zone Converter](https://www.utctime.net/utc-time-zone-converter) for offset values for your time zone). Enclose the earliest date and end date for the report in brackets ("`[ ]`"), as follows: `[yyyy-MM-dd'T'HH:mm:ss.SSS+|-hh:mm..yyyy-MM-dd'T'HH:mm:ss.SSS+|-hh:mm]` For example: \[2024-01-01T02:00:00.000-05:00..2024-01-31T02:00:00.000-05:00\] **Note:** All time values entered in this format will be dropped, and will be replaced with `00:00:00.000` for **startDate** and `23:59:59.000` for **endDate** in the response body. The maximum range between the start and end dates is 90 days, and the earliest start date you can specify is two years prior to the current date, which is defined as 730 days (365 \* 2), not accounting for Leap Year. The last date for which traffic data exists is a value called **lastUpdatedDate**. eBay returns an error if you specify a date range greater than 90 days, or the start date is after the lastUpdatedDate. If the specified end date is beyond the lastUpdatedDate, eBay returns data up to the lastUpdatedDate. **Required:** Always * **listing\_ids** This filter limits the results to only the supplied list of **listingId** values. **Note:** If you specify `dimension=LISTING` without specifying any listing\_ids in this parameter, the traffic report returned in the response contains a maximum of 200 listings. You can specify to 200 different **listingId** values. Enclose the list of IDs with curly braces ("`{ }`"), and separate multiple values with a pipe character ("`|`"). This filter only returns data for listings that have been either active or sold in last 90 days, and any unsold listings in the last 30 days. All listings must be the seller's and they must be listed on the marketplace specified by the **marketplace\_ids** filter argument. * **marketplace\_ids** This filter limits the report to seller data related to only the specified marketplace ID (currently the filter allows only a single marketplace ID). Enclose the marketplace ID in curly braces ("`{ }`"). **Valid values:** * `EBAY_AU` * `EBAY_DE` * `EBAY_ES` * `EBAY_FR` * `EBAY_GB` * `EBAY_IT` * `EBAY_US` * `EBAY_MOTORS_US` _Required if_ you set the **dimension** parameter to `DAY`. **Example filter parameter** The following example shows how to configure the **filter** parameter with the **marketplace\_ids** and **date\_range** filters: `filter=marketplace_ids:{EBAY_US},date_range:[20170601..20170828]` Encoding this portion of the query parameter sample yields: `filter=marketplace_ids:%7BEBAY_US%7D,date_range:%5B20230601..20230828%5D` - **metric** (string) *required* - This query parameter specifies the metrics you want covered in the report. **Note:** Unlike names for parameters and enumerated values, metric values are not case sensitive. **Valid values:** * [CLICK\_THROUGH\_RATE](/api-docs/sell/static/performance/traffic-report.html#click_through_rate) * [LISTING\_IMPRESSION\_SEARCH\_RESULTS\_PAGE](/api-docs/sell/static/performance/traffic-report.html#listing_impression_search_results_page) * [LISTING\_IMPRESSION\_STORE](/api-docs/sell/static/performance/traffic-report.html#listing_impression_store) * [LISTING\_IMPRESSION\_TOTAL](/api-docs/sell/static/performance/traffic-report.html#listing_impression_total) * [LISTING\_VIEWS\_SOURCE\_DIRECT](/api-docs/sell/static/performance/traffic-report.html#listing_views_source_direct) * [LISTING\_VIEWS\_SOURCE\_OFF\_EBAY](/api-docs/sell/static/performance/traffic-report.html#listing_views_source_off_ebay) * [LISTING\_VIEWS\_SOURCE\_OTHER\_EBAY](/api-docs/sell/static/performance/traffic-report.html#listing_views_source_other_ebay) * [LISTING\_VIEWS\_SOURCE\_SEARCH\_RESULTS\_PAGE](/api-docs/sell/static/performance/traffic-report.html#listing_views_source_search_results_page) * [LISTING\_VIEWS\_SOURCE\_STORE](/api-docs/sell/static/performance/traffic-report.html#listing_views_source_store) * [LISTING\_VIEWS\_TOTAL](/api-docs/sell/static/performance/traffic-report.html#listing_views_total) * [SALES\_CONVERSION\_RATE](/api-docs/sell/static/performance/traffic-report.html#sales_conversion_rate) * [TOTAL\_IMPRESSION\_TOTAL](/api-docs/sell/static/performance/traffic-report.html#total_impression_total) * [TRANSACTION](/api-docs/sell/static/performance/traffic-report.html#transaction) Specify a comma-separated list of the metrics to include them in the report. See [Using different metric parameters](/api-docs/sell/static/performance/traffic-report.html#metric-parameters) for more information including detailed metric descriptions and localized names. - **sort** (string) - This query parameter sorts the report on the specified metric. You can only specify a single metric in the sort parameter and the specified metric must be included in the configuration of the report's [metric](#metrics) parameter. Sorting is helpful when you want to review how a specific metric is performing, such as the CLICK\_THROUGH\_RATE. Most reports can be sorted in ascending or descending order. Precede the value of a descending-order request with a minus sign ("`-`"), for example: `sort=-CLICK_THROUGH_RATE`. **Note:** There are a couple of constraints on sorting the report by different metrics: * Sorting on the `SALES_CONVERSION_RATE` metric is not supported * The `TRANSACTION` metric can only be sorted in the descending order (sorting in the ascending order is not supported). **OAuth scope** This request requires an access token created with the **Authorization Code Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Authorization Code Grant:** - `https://api.ebay.com/oauth/api_scope/sell.analytics.readonly` ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 54401 - API_ANALYTICS **Description:** The specified marketplace ID is not a supported marketplace. For a complete list of the supported marketplace IDs, see the documentation. #### 54400 - API_ANALYTICS **Description:** The specified customer service metric type is not a valid type. Valid metric types are ITEM\_NOT\_AS\_DESCRIBED or ITEM\_NOT\_RECEIVED. #### 54402 - API_ANALYTICS **Description:** The specified evaluation type is not a valid type. Valid evaluation types are CURRENT or PROJECTED. #### 53100 - API_ANALYTICS **Description:** Program Id cannot be empty. #### 53105 - API_ANALYTICS **Description:** Invalid program Id {programId} #### 53110 - API_ANALYTICS **Description:** Cycle Id cannot be empty. #### 53115 - API_ANALYTICS **Description:** Invalid cycle Id {cycleId} #### 50001 - API_ANALYTICS **Description:** Invalid dimension specified. For help, see the documentation. #### 50002 - API_ANALYTICS **Description:** Invalid metric {metricName} specified. For help, see the documentation. #### 50003 - API_ANALYTICS **Description:** Invalid date range. End date must be before or equal to start date. #### 50004 - API_ANALYTICS **Description:** Invalid date range. Start date must be before or equal to end date. #### 50005 - API_ANALYTICS **Description:** No filter is specified, which is required. For help, see the documentation. #### 50006 - API_ANALYTICS **Description:** The sort field value {sortField} is not supported. #### 50008 - API_ANALYTICS **Description:** The call requires at least one metric. For help, see the documentation. #### 50009 - API_ANALYTICS **Description:** The call requires at least one URI query parameter. For help, see the documentation. #### 50013 - API_ANALYTICS **Description:** Invalid date range format - Start Date. The format is yyyyMMdd. #### 50014 - API_ANALYTICS **Description:** Invalid date range format - End Date. The format is yyyyMMdd. #### 50018 - API_ANALYTICS **Description:** Neither the start date nor the end date can be in the future. #### 50021 - API_ANALYTICS **Description:** Invalid filter field {filterField} specified. #### 50022 - API_ANALYTICS **Description:** Specify at least one marketplace ID. #### 50023 - API_ANALYTICS **Description:** The marketplace ID {marketplaceId} is not supported by this call. For help, see the documentation. #### 50024 - API_ANALYTICS **Description:** The marketplace ID {marketplaceId} is not valid. #### 50025 - API_ANALYTICS **Description:** The start date is too far in the past. The start date must be less than or equal to {maxStartDateInThePast}. #### 50026 - API_ANALYTICS **Description:** The date range is too long. The date range must be less than or equal to {maxDateWindow}. #### 50027 - API_ANALYTICS **Description:** The 'listing\_id' value is empty. #### 50028 - API_ANALYTICS **Description:** The maximum number of listing IDs has been exceeded. The maximum number of listing IDs is {maxListingIdsNumber}. #### 50029 - API_ANALYTICS **Description:** Invalid listing ID {listingId}. #### 50030 - API_ANALYTICS **Description:** Data for the listing ID {listingId} could not be found. #### 50031 - API_ANALYTICS **Description:** Date range is required. #### 50033 - API_ANALYTICS **Description:** Invalid date range filter format {invalidDateRangeFilter}. #### 50034 - API_ANALYTICS **Description:** Invalid listing ids filter format {invalidListingIdsFilter}. #### 50035 - API_ANALYTICS **Description:** Requested sort field is not part of the list of metrics requested. #### 50036 - API_ANALYTICS **Description:** {sortOrder} sort order is not supported for {sortField} metric. #### 50037 - API_ANALYTICS **Description:** The Metric {metricName} does not have data available for the requested date range. #### 50600 - API_ANALYTICS **Description:** Data for the listing Ids {delayedListingIds} is not yet updated to {endDate} ### BUSINESS Errors #### 54200 - API_ANALYTICS **Description:** The specified customer service metric is not available for the provided evaluation type and marketplace. Possible error causes are (1) Customer Service Metric values are not returned if the Seller does not have a valid transaction on the specified marketplace during the past 12 months or (2) sellers can retrieve CURRENT values only after they have been active on the specified marketplace for a complete benchmarking period. ### APPLICATION Errors #### 54000 - API_ANALYTICS **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. #### 62000 - GENERIC **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. #### 53120 - API_ANALYTICS **Description:** Internal server error. Wait a few minutes and try the call again. If error persists contact the eBay Developer Program. #### 50032 - API_ANALYTICS **Description:** We are unable to process data for accounts, like this one, which have listed in more than a few thousand leaf categories in the past couple years. #### 50050 - API_ANALYTICS **Description:** We are doing some maintenance and cannot show all your information right now. We are still tracking everything, and you will see your updated stats soon. #### 50500 - API_ANALYTICS **Description:** Internal server error. Wait a few minutes and try the call again. If error persists contact the eBay Developer Program. ## Types ### ApiMetric **Description:** This complex data type defines the details of the customer service metric and benchmark data related to the associated **dimension**. **Type:** object **Properties:** - **benchmark** (MetricBenchmark) - This complex type defines a set of benchmark data, which includes the **average** rating for the group included in the benchmark evaluation and the seller's calculated customer service metric rating for the benchmark. This container is returned only if the associated **metricKey** value is `RATE`. - **distributions** (array) - Returned when **metricKey** equals `COUNT`, this field returns an array of seller data where each set of data is grouped according by an overarching **basis**. When the seller distribution is returned, the numeric value of the associated **value** container equals the sum of the transactions where the seller meets the criteria of the customer service metric type for the given **dimension** during the **evaluationCycle**. - **metricKey** (string) - This field indicates the customer service metric being returned in the associated **metrics** container. The field is set as follows: * `TRANSACTION_COUNT` – When set to this value, the associated **value** field returns the number of transactions completed in the peer group for the metric being evaluated in the associated **dimension** and **evaluationCycle**. * `COUNT` – When set to this value, the associated **value** field is set to the number of transactions completed by the seller for the metric being evaluated in the associated **dimension** and **evaluationCycle**. * `RATE` – When set to this value, the fields in the associated container return the seller's calculated **value** for the associated customer service metric along with the benchmark data against which the seller is evaluated. Specifically, when **metricKey** is set to `RATE`, the associated **value** field is set to the value of **metricKey** `TRANSACTION_COUNT` divided by the value of **metricKey** `COUNT`. The **benchmark.rating** value is the seller's rating for the metric in the associated **dimension** and **evaluationCycle**. - **value** (string) - This field is set to the seller's numeric rating for the associated **metricKey** for the given **dimension** during the **evaluationCycle**. To determine the seller's rating for this metric, the value of this field is compared to the average metric value of the group. ### BenchmarkMetadata **Description:** This complex type defines the fields that comprise the benchmark against which the seller's performance is compared. The comparison determines the seller's rating for the metric. **Type:** object **Properties:** - **average** (string) - This field returns the average value for the group, as defined by the specified **basis**. When the benchmark **basis** is set to `PEER_BENCHMARK`, the value returned in this field is the benchmark value to which the seller's metric **value** is compared to determine the seller's rating for the customer service metric. ### BenchmarkTypeEnum **Description:** This enumerated type defines the different benchmark types supported by the **getCustomerServiceMetric** method. Currently, only `PEER_BENCHMARK` is supported. | - **PEER_BENCHMARK**: This type signifies the benchmark rating is calculated by comparing the seller's rate of requests for `ITEM_NOT_RECEIVED` or `ITEM_NOT_AS_DESCRIBED` transactions to the rate of requests received by the group of sellers offering similar products under similar circumstances (including the selling price, terms of sale, and shipping destination). For more details, see [Peer benchmarks](https://www.ebay.com/help/selling/selling/monitor-service-metrics?id=4785#section1). **Type:** object ### Cycle **Description:** A complex type that describes a program cycle. **Type:** object **Properties:** - **cycleType** (CycleTypeEnum) - The cycle type, either `CURRENT` or `PROJECTED`. `CURRENT` means the profile's metrics values are from the most recent official eBay monthly standards evaluation. `PROJECTED` means the profile values were determined when the profile was requested. - **evaluationDate** (string) - The date and time at which the standard compliance values were determined for the profile. The time stamp is formatted as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, which is based on the 24-hour Universal Coordinated Time (UTC) clock. **Format:** `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` **Example:** `2018-08-04T07:09:00.000Z` - **evaluationMonth** (string) - The month in which the currently effective seller level was computed. The value is always formatted as `YYYY-MM`. If the cycle is `CURRENT`, this value is the month and year the of the last eBay compliance evaluation. If this is for a `PROJECTED` cycle, the value is the month and year of the next scheduled evaluation. Because eBay does official evaluations around the 20th of each month, a `PROJECTED` value may indicate either the current or the next month. ### CycleTypeEnum **Description:** This enumerated type defines the allowable cycle types. | - **CURRENT**: Indicates the evaluation that determines your currently effective seller level. - **PROJECTED**: Indicates the seller's profile level that will take effect on the next evaluation period, as calculated at the time of the request. **Type:** object ### Definition **Description:** A complex type that defines a dimension key and metrics in a traffic report. **Type:** object **Properties:** - **dataType** (SrlDataTypeEnum) - Indicates the data type of the returned dimension. For example, if the **dimension** is `day`, the data type is `DATE`. - **key** (string) - The value the **dimension** or **metric** parameter as submitted in the request. - **localizedName** (string) - The localized name of the metric or dimension (translated into the language specified in the **Accept-Language** HTTP request header). For example, if **Accept-Language** is set to `de-DE`, the value "day" in the **dimension** container is returned as "tag", and a metric of TRANSACTION is returned as "Transaktionsanzahl". ### Dimension **Description:** This complex type defines the dimension, or attributes, by which the associated customer service metric and benchmark data is measured. The value of **dimensionKey** gets set according to the configuration of the input request. The **name** and **value** pair further define dimension under the key. **Type:** object **Properties:** - **dimensionKey** (DimensionTypeEnum) - This enum defines the basis against which the seller's customer service metric is measured. The value of this field gets set according to the value of the **customer\_service\_metric\_type** input parameter. The following input configurations return the responses shown: * `ITEM_NOT_AS_DESCRIBED` – Returns benchmark ratings based on L1 listing categories, so the result shows metrics where the **dimensionKey** is set to `LISTING_CATEGORY`. * `ITEM_NOT_RECEIVED` – Returns benchmark ratings based on world shipping regions, so the result shows metrics where the **dimensionKey** is set to `SHIPPING_REGION`. The shipping region is indicated by the associated **value** field. For specifics on world shipping regions, see the FAQ section on the following page: [Monitor your service metrics](https://www.ebay.com/help/selling/selling/monitor-service-metrics?id=4785 "eBay Help page") - **name** (string) - The dimension name returned in this field depends on the **dimensionKey**: * If **dimensionKey** is set to `SHIPPING_REGION`, this field is set to one of following values, which represent established shipping corridors: * `Domestic` * `International: Mature region` * `International: Emerging region` * If **dimensionKey** is set to `LISTING_CATEGORY`, this field is set to the name of the primary (L1) category in which the items being rated were listed. - **value** (string) - The value returned in this field depends on the **dimensionKey**. If **dimensionKey** equals `LISTING_CATEGORY`, the value returned in this field is the category ID of the primary (L1) category in which the items being rated were listed. If **dimensionKey** equals `SHIPPING_REGION`, one of the following values is returned: * `DOMESTIC` * `INTERNATIONAL_MATURED_REGION` * `INTERNATIONAL_EMERGING_REGION` ### DimensionMetric **Description:** This complex type defines a the customer service metrics and seller benchmark performance related to a given dimension. **Type:** object **Properties:** - **dimension** (Dimension) - This type defines the "dimension," or attributes, against which the associated customer service metric values and benchmark ratings are based. The **dimensionKey** value is set according to the **customer\_service\_metric\_type** request parameter and the values in the associated **name**/**value** pairs relate to the **dimensionKey** that's being used to calculate the benchmark rating. - **metrics** (array) - This is a list of **Metric** elements where each element contains data and information related to the transactions grouped by the associated **dimension**. ### DimensionTypeEnum **Description:** This enum type defines the supported **dimensionType** values. | - **LISTING_CATEGORY**: This dimension type indicates the values in the associated **metric** container are based on transactions in the Level 1 (L1) listing categories in which the seller is active. When `ITEM_NOT_AS_DESCRIBED` is specified as the metric type in the request, the service sets **dimensionKey** to this value. - **SHIPPING_REGION**: This dimension type indicates the values in the associated **metric** container are based on transactions that were shipped to distinct world shipping regions. When `ITEM_NOT_RECEIVED` is specified as the metric type in the request, the service sets **dimensionKey** to this value. For details on the shipping regions, see the FAQ section on the following page: [Monitor your service metrics](https://www.ebay.com/help/selling/selling/monitor-service-metrics?id=4785). **Type:** object ### Distribution **Description:** This complex type defines of a piece of data that is grouped by the associated **basis**. It contains the **name** for the data set and its associated **value**. **Type:** object **Properties:** - **name** (string) - The name of a distribution in which the seller is active. - **value** (string) - This field contains the number of transactions the seller had in the distribution (identified by the associated **name** field) during the metric **evaluationCycle**. ### ErrorDetailV3 **Description:** This type defines the fields that can be returned in an error. **Type:** object **Properties:** - **category** (string) - Identifies whether the error was in the REQUEST or happened when running the APPLICATION. - **domain** (string) - The primary system where the error occurred. This is relevant for application errors. For Analytics errors, it always has the value `API_ANALYTICS`. - **errorId** (integer) - A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. Traffic report error IDs range from 50001 to 50500. - **inputRefIds** (array) - Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use _JSONPath_ notation. - **longMessage** (string) - A more detailed explanation of the error than given in the `message` error field. - **message** (string) - Information on how to correct the problem, in the end user's terms and language where applicable. Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale. - **outputRefIds** (array) - Identifies specific response elements associated with the error, if any. Path format is the same as `inputRefId`. - **parameters** (array) - This optional list of name/value pairs that contain context-specific `ErrorParameter` objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each `ErrorParameter` object consists of two fields, a `name` and a `value`. - **subdomain** (string) - If present, indicates which subsystem in which the error occurred. ### ErrorParameterV3 **Description:** A complex type that defines an error and error message. **Type:** object **Properties:** - **name** (string) - Name of the entity that threw the error. - **value** (string) - A description of the error. ### EvaluationCycle **Description:** This complex type describes the start and end dates of the of the time period over which the associated benchmark is computed. All timestamps are based on Mountain Standard Time (MST). The timestamp is formatted as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html "https://www.iso.org") string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. **Type:** object **Properties:** - **endDate** (string) - End date and time of the transaction lookback range. All timestamps are based on Mountain Standard Time (MST). The timestamp is formatted as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html "https://www.iso.org") string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. - **evaluationDate** (string) - The ISO-8601 date and time at which the seller was evaluated for this customer service metric rating. - **evaluationType** (EvaluationTypeEnum) - This field specifies the transaction _lookback period_ used for the evaluation. The **evaluation\_type** value specified in the request is returned in this field. There are two possible values: * `CURRENT` – A monthly evaluation that occurs on the 20th of every month. * `PROJECTED` – A daily evaluation that provides a projection of how the seller is currently performing with regards to the upcoming evaluation period. - **startDate** (string) - The start date and time of the transaction lookback range. All timestamps are based on Mountain Standard Time (MST). The timestamp is formatted as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html "https://www.iso.org") string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. **Format:** `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` **Example:** `2018-08-04T07:09:00.000Z` ### EvaluationTypeEnum **Description:** This enumerated type defines the different available values for the type of evaluation you want to retrieve. | - **CURRENT**: This is a monthly evaluation that occurs on 20th of every month. - **PROJECTED**: This is a daily evaluation that provides a projection of how the seller is currently performing with regards to the upcoming evaluation period. **Type:** object ### FindSellerStandardsProfilesResponse **Description:** This type returns a list of seller profiles. **Type:** object **Properties:** - **standardsProfiles** (array) - A list of the seller's standards profiles. A "standards profile" is a set of eBay seller standards categories and the values related to the associated seller. Profiles are distinguished by a combination of cycle and program values. The "program" value specifies the region to which the data is from. The "cycle" value specifies whether the values were determined just now, or if the values are from the last official eBay seller standards evaluation. ### GetCustomerServiceMetricResponse **Description:** This complex data type defines the response data that is returned from a request to **getCustomerServiceMetric**. **Type:** object **Properties:** - **dimensionMetrics** (array) - This container provides a seller's customer service **metric** performance for a given **dimension**. In the **getCustomerServiceMetric** request, specify values for the following request parameters to control the returned dimension and the associated metric values: * **customer\_service\_metric\_type** * **evaluation\_type** * **evaluation\_marketplace\_id** - **evaluationCycle** (EvaluationCycle) - This complex type defines the evaluation type (`CURRENT` or `PROJECTED`) and the transaction lookback period used to calculate the seller's customer service metric. - **marketplaceId** (MarketplaceIdEnum) - The eBay marketplace ID of the marketplace upon which the customer service metric evaluation is based. The **customer\_service\_metric** resource supports a limited set of marketplaces. For a complete list of the supported marketplaces, please see the [Service metrics policy](https://www.ebay.com/help/policies/selling-policies/seller-performance-policy/service-metrics-policy?id=4769#section2 "eBay Help pages") page. ### Header **Description:** This type defines the headers for the dimension keys and metrics returned in the report. **Type:** object **Properties:** - **dimensionKeys** (array) - A list of the dimension or metric keys returned in the report. The values for each are is returned in the associated **key** fields. - **metrics** (array) - The list of metrics returned in the report. The values for each are is returned in the associated **key** fields. ### MarketplaceIdEnum **Description:** This enumerated type contains a list of the standard codes that represent each of the eBay marketplaces. | - **EBAY_AT**: eBay Austria (ebay.at) - **EBAY_AU**: eBay Australia (ebay.com/au) - **EBAY_BE**: eBay Belgium (ebay.com/sch/Belgium) - **EBAY_CA**: eBay Canada (English) (ebay.ca) - **EBAY_CH**: eBay Switzerland (ebay.ch) - **EBAY_CN**: eBay China (ebay.com/sch/China) - **EBAY_CZ**: eBay Czech Republic (ebay.com/sch/Czech-Republic) - **EBAY_DE**: eBay Germany (ebay.de) - **EBAY_DK**: eBay Denmark (ebay.com/sch/Denmark) - **EBAY_ES**: eBay Spain (ebay.es) - **EBAY_FI**: eBay Finland (ebay.com/sch/Finland) - **EBAY_FR**: eBay France (ebay.fr) - **EBAY_GB**: eBay UK (ebay.co.uk) - **EBAY_GR**: eBay Greece (ebay.com/sch/Greece) - **EBAY_HK**: eBay Hong Kong (ebay.com.hk) - **EBAY_HU**: eBay Hungary (ebay.com/sch/Hungary) - **EBAY_ID**: eBay Indonesia (id.ebay.com) - **EBAY_IE**: eBay Ireland (ebay.ie) - **EBAY_IL**: eBay Israel (ebay.com/sch/Israel) - **EBAY_IN**: eBay India (ebay.in) **Note:** eBay India is no longer a functioning eBay marketplace. - **EBAY_IT**: eBay Italy (ebay.it) - **EBAY_JP**: eBay Japan (ebay.co.jp) - **EBAY_MY**: eBay Malaysia (ebay.com/my) - **EBAY_NL**: eBay Netherlands (ebay.nl) - **EBAY_NO**: eBay Norway (ebay.com/sch/Norway) - **EBAY_NZ**: eBay New Zealand (ebay.com/sch/New-Zealand) - **EBAY_PE**: eBay Peru (ebay.com/sch/Peru) - **EBAY_PH**: eBay Philippines (ebay.ph) - **EBAY_PL**: eBay Poland (ebay.pl) - **EBAY_PR**: eBay Puerto Rico (ebay.com/sch/Puerto-Rico) - **EBAY_PT**: eBay Portugal (ebay.com/sch/Portugal) - **EBAY_RU**: eBay Russia (ebay.com/sch/Russia) - **EBAY_SE**: eBay Sweden (ebay.com/sch/Sweden) - **EBAY_SG**: eBay Singapore (ebay.com/sg) - **EBAY_TH**: eBay Thailand (export.ebay.co.th) - **EBAY_TW**: eBay Taiwan (ebay.com/tw) - **EBAY_US**: eBay US (ebay.com) - **EBAY_VN**: eBay Vietnam (ebay.vn) - **EBAY_ZA**: eBay South Africa (ebay.com/sch/South-Africa) - **EBAY_HALF_US**: This enumeration value is no longer applicable as the Half.com site no longer exists. - **EBAY_MOTORS_US**: eBay Motors US (ebay.com/motors) **Type:** object ### Metadata **Description:** This type defines the metadata information of the report. This includes the headers and the individual metadata records. **Type:** object **Properties:** - **metadataHeader** (MetadataHeader) - The container that returns the **dimensionKeys** and **metrics** headers for the report. - **metadataRecords** (array) - A list of the individual report records. ### MetadataHeader **Description:** This type defines the metadata header fields. **Type:** object **Properties:** - **key** (string) - The key value used for the report. For example: `"key": "LISTING_ID"` - **metadataKeys** (array) - The list of dimension key values used for the report header. Each list element contains the key name, its data type, and its localized name. For example: `"metadataKeys": [   "key": "LISTING_TITLE",   "localizedName": "Listing title",   "dataType": "STRING"` ### MetadataRecord **Description:** A complex type that defines the data records returned in the report. **Type:** object **Properties:** - **metadataValues** (array) - A list of data in a row returned in the traffic report. The data in each of the cells match the labels in headers of the report. - **value** (Value) - The value of the key on which the report is based. For example, if the key is the listing ID, the value of this container could be: `"value": {   "value": "142133954229",   "applicable": true }` ### MetricBenchmark **Description:** This complex type defines the benchmark data, which includes the **average** value of the metric for the group (the benchmark) and the seller's overall **rating** when compared to the benchmark. **Type:** object **Properties:** - **adjustment** (RatingAdjustmentTypeEnum) - If this field is present, it indicates that the rating given to the seller was "adjusted" for one reason or another. If eBay determines that the normal rating of a seller is impacted by circumstances beyond their control, they can issue an override to adjust the rating given to the seller. - **basis** (BenchmarkTypeEnum) - This field returns the "basis" by which the benchmark is calculated for the customer service metric type. Currently, the only supported basis is `PEER_BENCHMARK`. - **metadata** (BenchmarkMetadata) - This field contains the benchmark data. - **rating** (RatingTypeEnum) - This field returns seller's rating for the customer service metric. The rating is set to a value that equals the relative deviation between the seller's metric value and the benchmark value for the customer service metric. Deviation values range from `LOW` to `VERY HIGH`, and the lower the deviation, the better the seller rating. ### MetricDistribution **Description:** This complex data type describes the metric distribution by basis. **Type:** object **Properties:** - **basis** (string) - This field returns the basis, or the method, by which the metric rating is calculated. - **data** (array) - This field returns a list of name/value pairs, where the **name** indicates the distribution being rated and the **value** indicates the count of seller transactions that meet the distribution criteria. ### ProgramEnum **Description:** This enumerated type defines the regions to which a profile can apply. | - **PROGRAM_DE**: Indicates the program region is Germany, which includes DE (Germany), AT (Austria), and CH (Switzerland). - **PROGRAM_UK**: Indicates the program region is the United Kingdom, which includes both UK (United Kingdom) and IE (Ireland). - **PROGRAM_US**: Indicates the program region is the United States, which includes US (the United States) and US MOTORS. - **PROGRAM_GLOBAL**: Includes all defined programs, plus any marketplace countries where a seller has conducted business. **Type:** object ### RatingAdjustmentTypeEnum **Description:** This enumerated type defines the different classes of adjustments that can impact the rating given to a seller. | - **OVERRIDE**: An adjustment was made due to a system override. If eBay determines that the calculated rating of a seller is impacted by circumstances beyond the normal control of the seller, they can issue an override to adjust the rating given to the seller. **Type:** object ### RatingTypeEnum **Description:** This enumerated type defines the possible rating values that can be given to a seller for the associated dimension. | - **LOW**: Indicates the deviation between the seller's metric rating compared to the benchmark rating is LOW. This is the best rating. - **AVERAGE**: Indicates the deviation between the seller's metric rating compared to the benchmark rating is AVERAGE. - **HIGH**: Indicates the deviation between the seller's metric rating compared to the benchmark rating is HIGH. - **VERY_HIGH**: Indicates the deviation between the seller's metric rating compared to the benchmark rating is VERY HIGH. - **NOT_APPLICABLE**: The seller does not have a rating for this dimension. eBay does not provide a rating if there is not enough data to rate a seller. For example, the seller might not have the minimum number of transactions for the associated dimension, or there might not be enough sellers in the peer group to calculate a peer rating. **Type:** object ### Record **Description:** This type defines the fields of the individual record of the report. **Type:** object **Properties:** - **dimensionValues** (array) - A list where each element contains either the string `DAY` (if the **dimension** is `DAY`), or the listing ID for which the record's metric data is computed. A second array member, **applicable**, is always `true` for dimension values. - **metricValues** (array) - A list where each element contains a **value** field that indicates the record's value for the metric. Each element also contains an **applicable** field that indicates the veracity of the computed **value**. Note that there are no metric names or IDs associated with the values returned in this array. The metadata to which these values relate can be found in the key values in **metadataKeys**. The order of the metric values in this array equals the order of the key values in **metadataHeader**. ### Report **Description:** The complex type that defines that defines the report. **Type:** object **Properties:** - **dimensionMetadata** (array) - A complex type containing the header of the report and the type of data containted in the rows of the report. - **endDate** (string) - The time stamp is formatted as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) string, which is based on the 24-hour Universal Coordinated Time (UTC) clock. If you specify an end date that is beyond the **lastUpdatedDate** value, eBay returns a report that contains data only up to the lastUpdateDate date. **Format:** `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` **Example:** `2018-08-20T07:09:00.000Z` - **header** (Header) - A complex type containing the header for the report. - **lastUpdatedDate** (string) - The date and time, in ISO 8601 format, that indicates the last time the data returned in the report was updated. - **records** (array) - A complex type containing the individual data records for the traffic report. - **startDate** (string) - The start date of the date range used to calculate the report, in ISO 8601 format. - **warnings** (array) - An array of any process errors or warnings that were generated during the processing of the call processing. ### SrlDataTypeEnum **Description:** This enumerated type defines the types of the data returned in a traffic report. | - **NUMBER**: Indicates the value is a number value. - **STRING**: Indicates the value is a string. - **DATE**: Indicates the value is a date. **Type:** object ### SspDataTypeEnum **Description:** This enumerated type defines the supported data types. | - **AMOUNT**: Indicates the data type is an amount value. - **BOOLEAN**: Indicates the data type is a boolean value. - **DATE**: Indicates the data type is a date value. - **FRACTION**: Indicates the data type is a fraction value. - **NUMBER**: Indicates the data type is a number value. - **STRING**: Indicates the data type is a string value. **Type:** object ### SspMetric **Description:** A complex type that defines a single metric which is evaluated as a part of a seller's standards profile. For the specified metric, the `metricKey` value is its name and the `level` specifies how the seller is doing meeting eBay's standards for that metric (either `TOP_RATED`, `ABOVE_STANDARD`, or `BELOW_STANDARD`). The metric's `value` is the absolute number of the metric's value for the associated seller. **Type:** object **Properties:** - **level** (StandardsLevelEnum) - The seller level for this metric, which indicates how well the seller is doing in meeting eBay's standards for this metric. Possible values are `TOP_RATED`, `ABOVE_STANDARD`, and `BELOW_STANDARD`. - **lookbackEndDate** (string) - The end date and time, in ISO 8601 format, when the seller was evaluated for this metric. - **lookbackStartDate** (string) - The start date and time, in ISO 8601 format, when the seller was evaluated for this metric. - **metricKey** (string) - An internal key string specifying a metric. These are short, abbreviated, strings such as `MIN_TXN_COUNT`. - **name** (string) - A descriptive name for the metric. For example, "Transaction defect rate." This value is localized according to the value of the **X-EBAY-C-MARKETPLACE-ID** request header. - **thresholdLowerBound** (object) - Specifies the lowest number **value** can be and still qualify for the currently assigned seller level. For example, if a seller is assigned the level `ABOVE_STANDARD` for the **ROCKS\_INVENTORY** metric, and **thresholdLowerBound** is set to `10`, having fewer than 10 rocks in inventory would result in the seller dropping a level to `BELOW_STANDARD`. See `thresholdMetaData` to determine if the lower bound value is inclusive or exclusive. The lower bound value is optional. For example, if the seller is below standard for this metric, there is no value they can go below for it to further lower their compliance level. Note that each program can have different metric-threshold levels. **Note:** Depending on the metric being returned, this field can be returned as an Integer, Boolean, Amount, Fraction, or Double. - **thresholdMetaData** (string) - An expression that indicates the inclusive and exclusive characteristics of the upper and lower threshold boundaries. A metric's **thresholdLowerBound** and **thresholdUpperBound** values specify the boundary values that define the current standard compliance level (`TOP_RATED`, `ABOVE_STANDARD`, or `BELOW_STANDARD`). The **thresholdMetaData** value consists of two values separated by a comma, which are bounded by either a parenthesis or a square bracket. A parenthesis indicates the adjacent value is exclusive while a square bracket indicates the adjacent value is inclusive (exclusive values are not included in the range while inclusive values are included). The metadata values are either `UPPER` or `LOWER` and these values can be in any order to indicate the characteristics of the metric. For example, suppose a seller's level is `ABOVE_STANDARD`, the lower boundary is `200`, the upper boundary is `300`, and the value for this field is `(LOWER, UPPER]`. This indicates that as long as the value for this metric is an integer from 201 (excluding 200) to 300 (including 300), the metric level is above standard. With this, if the seller wants to get a `TOP_RATED` rating for this metric, they'll have to increase their value to at least 301. - **thresholdUpperBound** (object) - Specifies the highest number **value** can be and still qualify for the currently assigned seller level. For example, if a seller is assigned the level `ABOVE_STANDARD` for the **ROCKS\_INVENTORY** metric, and the **thresholdUpperBound** is set to `20`, having more than 20 rocks in inventory would result in the seller rising a lever, to `TOP_RATED`. See `thresholdMetaData` to determine if the upper bound value is inclusive or exclusive. The upper bound value is optional. For example, if the seller is top rated for this metric, there is no value they can go above for it to further raise their compliance level. Note that each program can have different metric-threshold levels. **Note:** Depending on the metric being returned, this field can be returned as an Integer, Boolean, Amount, Fraction, or Double. - **type** (SspDataTypeEnum) - Indicates the data type of the returned metric. Possible values are: `AMOUNT`, `BOOLEAN`, `DATE`, `FRACTION`, `NUMBER`, and `STRING`. - **value** (object) - The seller's calculated value, or score, for the metric. **Note:** Depending on the metric being returned, this field can be returned as an Integer, Boolean, Fraction, or Amount. ### StandardsLevelEnum **Description:** This enumerated type defines the eBay seller ratings. | - **TOP_RATED**: Indicates the seller or metric meets the Top Rated requirement. - **ABOVE_STANDARD**: Indicates the seller or metric meets the Above Standard requirement. - **BELOW_STANDARD**: Indicates the seller or metric does not meet the minimum standards performance requirement. **Type:** object ### StandardsProfile **Description:** A complex type that defines a seller profile. **Type:** object **Properties:** - **cycle** (Cycle) - A complex type that specifies the profile's evaluation cycle (`CURRENT` or `PROJECTED`), the date the evaluation was calculated, and the month to which the evaluation pertains. Each program has at least one cycle, but a program can include both cycle types. - **defaultProgram** (boolean) - If set to `true`, this flag indicates this is the default program for the seller. Except for sellers in China, a seller's default program is the marketplace where they registered with eBay. Seller's in China select their default program when they register. - **evaluationReason** (string) - Specifies how the overall seller level was calculated. In the event of special circumstances (as determined by eBay), eBay may override the calculated seller level. In general, such overrides protect a seller's level. The usual value for both cycle types is "Seller level generated by standards monthly evaluation cycle." - **metrics** (array) - A list of the metrics upon which a seller's profile is evaluated. Each program's applicable metrics and requirements are listed at [eBay Top Rated seller program standards](http://www.sps.ebay.com/sd/sdrequirements). - **program** (ProgramEnum) - Indicates the program used to generate the profile data. Values can be `PROGRAM_DE`, `PROGRAM_UK`, `PROGRAM_US`, or `PROGRAM_GLOBAL`. - **standardsLevel** (StandardsLevelEnum) - The overall standards level of the seller, one of `TOP_RATED`, `ABOVE_STANDARD`, or `BELOW_STANDARD`. ### Value **Description:** A complex type that contains a value, plus the veracity of that value. **Type:** object **Properties:** - **applicable** (boolean) - If set to `true`, this flag indicates the value in the **value** field is valid as computed. A value of `false` indicates one or more of the values used to calculate the value was invalid. The occurrence of this is a rare, however consider this case: suppose a buyer navigates to a View Item page at 11:59 pm (the end of the day) and purchases the item at 12:05am the next day. In this case, the item would have been purchased with `0` views for the day. - **value** (object) - The value of the report data. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-06-01T18:42:23.444Z*