{
"openapi": "3.0.0",
"info": {
"title": " Seller Service Metrics API ",
"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:
ITEM_NOT_AS_DESCRIBED
ITEM_NOT_RECEIVED
TOP_RATED
, ABOVE_STANDARD
, or BELOW_STANDARD
). 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.",
"operationId": "findSellerStandardsProfiles",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FindSellerStandardsProfilesResponse"
}
}
}
},
"400": {
"description": "Bad Request"
},
"500": {
"description": "Internal Server Error"
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.analytics.readonly"
]
}
]
}
},
"/seller_standards_profile/{program}/{cycle}": {
"get": {
"tags": [
"seller_standards_profile"
],
"description": "This call retrieves a single standards profile for the associated seller. TOP_RATED
, ABOVE_STANDARD
, or BELOW_STANDARD
). 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.",
"operationId": "getSellerStandardsProfile",
"parameters": [
{
"name": "cycle",
"in": "path",
"description": "This path parameter is used to specify the cycle for which metrics and metadata will be retrieved.DAY
or LISTING
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, ...
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. LISTING_IMPRESSION_STORE: 157
means the item appeared 157 times in the store during the date range.dimension=LISTING
without specifying any listing_ids in the parameter filter, the traffic report returned in the response contains a maximum of 200 listings.Note: URL encode all the values you supply in the filter parameter. See URL encoding query parameter values as described in URL parameters.
Configure the following properties of the filter parameter to tune the traffic report to your needs: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]
[20240101..20240131]
[ ]
\"), as follows:[yyyy-MM-dd'T'HH:mm:ss.SSS+|-hh:mm..yyyy-MM-dd'T'HH:mm:ss.SSS+|-hh:mm]
[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.dimension=LISTING
without specifying any listing_ids in this parameter, the traffic report returned in the response contains a maximum of 200 listings.{ }
\"), and separate multiple values with a pipe character (\"|
\"). { }
\"). EBAY_AU
EBAY_DE
EBAY_ES
EBAY_FR
EBAY_GB
EBAY_IT
EBAY_US
EBAY_MOTORS_US
DAY
.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
Note: Unlike names for parameters and enumerated values, metric values are not case sensitive.
Valid values:-
\"), for example: sort=-CLICK_THROUGH_RATE
.SALES_CONVERSION_RATE
metric is not supportedTRANSACTION
metric can only be sorted in the descending order (sorting in the ascending order is not supported).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."
}
},
"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."
},
"Cycle": {
"type": "object",
"properties": {
"cycleType": {
"type": "string",
"description": "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. For implementation help, refer to eBay API documentation"
},
"evaluationDate": {
"type": "string",
"description": "The date and time at which the standard compliance values were determined for the profile. [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
2018-08-04T07:09:00.000Z
"
},
"evaluationMonth": {
"type": "string",
"description": "The month in which the currently effective seller level was computed. 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."
}
},
"description": "A complex type that describes a program cycle."
},
"Definition": {
"type": "object",
"properties": {
"dataType": {
"type": "string",
"description": "Indicates the data type of the returned dimension. For example, if the dimension is day
, the data type is DATE
. For implementation help, refer to eBay API documentation"
},
"key": {
"type": "string",
"description": "The value the dimension or metric parameter as submitted in the request."
},
"localizedName": {
"type": "string",
"description": "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\"."
}
},
"description": "A complex type that defines a dimension key and metrics in a traffic report."
},
"Dimension": {
"type": "object",
"properties": {
"dimensionKey": {
"type": "string",
"description": "dimensionKey defines the basis against which the seller's customer service metric is measured. 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
. SHIPPING_REGION
, this field is set to one of following values, which represent established shipping corridors: Domestic
International: Mature region
International: Emerging region
LISTING_CATEGORY
, this field is set to the name of the primary (L1) category in which the items being rated were listed.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. SHIPPING_REGION
, one of the following values is returned: DOMESTIC
INTERNATIONAL_MATURED_REGION
INTERNATIONAL_EMERGING_REGION
API_ANALYTICS
."
},
"errorId": {
"type": "integer",
"description": "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.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A more detailed explanation of the error than given in the message
error field."
},
"message": {
"type": "string",
"description": "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": {
"type": "array",
"description": "Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId
.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "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
.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "If present, indicates which subsystem in which the error occurred."
}
},
"description": "Type that defines the fields that can be returned in an error."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the entity that threw the error."
},
"value": {
"type": "string",
"description": "A description of the error."
}
},
"description": "A complex type that defines an error and error message."
},
"EvaluationCycle": {
"type": "object",
"properties": {
"endDate": {
"type": "string",
"description": "End date and time of the transaction lookback range. All timestamps are based on Mountain Standard Time (MST). 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.[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
2018-08-04T07:09:00.000Z
"
}
},
"description": "This complex type describes the start and end dates of the of the time period over which the associated benchmark is computed. CURRENT
or PROJECTED
) and the transaction lookback period used to calculate the seller's customer service metric.",
"$ref": "#/components/schemas/EvaluationCycle"
},
"marketplaceId": {
"type": "string",
"description": "The eBay marketplace ID of the marketplace upon which the customer service metric evaluation is based. \"key\": \"LISTING_ID\"
"
},
"metadataKeys": {
"type": "array",
"description": "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. \"metadataKeys\": [
\"key\": \"LISTING_TITLE\",
\"localizedName\": \"Listing title\",
\"dataType\": \"STRING\"
\"value\": {
\"value\": \"142133954229\",
\"applicable\": true
}
",
"$ref": "#/components/schemas/Value"
}
},
"description": "A complex type that defines the data records returned in the report."
},
"Metric": {
"type": "object",
"properties": {
"benchmark": {
"description": "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. RATE
.",
"$ref": "#/components/schemas/MetricBenchmark"
},
"distributions": {
"type": "array",
"description": "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. 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. RATE
, the associated value field is set to the value of metricKey TRANSACTION_COUNT
divided by the value of metricKey COUNT
. PEER_BENCHMARK
. For implementation help, refer to eBay API documentation"
},
"metadata": {
"description": "This field contains the benchmark data.",
"$ref": "#/components/schemas/BenchmarkMetadata"
},
"rating": {
"type": "string",
"description": "This field returns seller's rating for the customer service metric. LOW
to VERY HIGH
, and the lower the deviation, the better the seller rating. For implementation help, refer to eBay API documentation"
}
},
"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."
},
"MetricDistribution": {
"type": "object",
"properties": {
"basis": {
"type": "string",
"description": "This field returns the basis, or the method, by which the metric rating is calculated."
},
"data": {
"type": "array",
"description": "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.",
"items": {
"$ref": "#/components/schemas/Distribution"
}
}
},
"description": "This complex data type describes the metric distribution by basis."
},
"Record": {
"type": "object",
"properties": {
"dimensionValues": {
"type": "array",
"description": "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.",
"items": {
"$ref": "#/components/schemas/Value"
}
},
"metricValues": {
"type": "array",
"description": "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. [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
2018-08-20T07:09:00.000Z
"
},
"header": {
"description": "A complex type containing the header for the report.",
"$ref": "#/components/schemas/Header"
},
"lastUpdatedDate": {
"type": "string",
"description": "The date and time, in ISO 8601 format, that indicates the last time the data returned in the report was updated."
},
"records": {
"type": "array",
"description": "A complex type containing the individual data records for the traffic report.",
"items": {
"$ref": "#/components/schemas/Record"
}
},
"startDate": {
"type": "string",
"description": "The start date of the date range used to calculate the report, in ISO 8601 format."
},
"warnings": {
"type": "array",
"description": "An array of any process errors or warnings that were generated during the processing of the call processing.",
"items": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "The complex type that defines that defines the report."
},
"StandardsProfile": {
"type": "object",
"properties": {
"cycle": {
"description": "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. true
, this flag indicates this is the default program for the seller. PROGRAM_DE
, PROGRAM_UK
, PROGRAM_US
, or PROGRAM_GLOBAL
. For implementation help, refer to eBay API documentation"
},
"standardsLevel": {
"type": "string",
"description": "The overall standards level of the seller, one of TOP_RATED
, ABOVE_STANDARD
, or BELOW_STANDARD
. For implementation help, refer to eBay API documentation"
}
},
"description": "A complex type that defines a seller profile."
},
"Value": {
"type": "object",
"properties": {
"applicable": {
"type": "boolean",
"description": "If set to true
, this flag indicates the value in the value field is valid as computed. 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": {
"type": "object",
"description": "The value of the report data."
}
},
"description": "A complex type that contains a value, plus the veracity of that value."
}
},
"securitySchemes": {
"api_auth": {
"type": "oauth2",
"description": "The security definitions for this API. Please check individual operations for applicable scopes.",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope/sell.analytics.readonly": "View your selling analytics data, such as performance reports"
}
}
}
}
}
}
}