Sales API v1 Use Case Guide
Use cases for the Sales API.
API Version: v1
What is the Sales API?
The Selling Partner API for Sales (Sales API) provides sellers with sales performance information. This is achieved through returning aggregated order metrics for a given period of time, broken down by granularity, and buyer type. Refer to the Sales API Reference for details about Sales API operations and associated data types and schemas.
Prerequisites
To successfully complete this tutorial, you must have the following:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
- The Pricing role assigned to your developer profile.
- The Pricing role selected in the App registration page for your application.
Tutorial: Receive sales performance information
This section will walk you through the process of receiving sales performance information using the Sales API.
Get the sales performance information
Call the getOrderMetrics
operation with the following parameters to receive aggregated order metrics for a given interval:
Query Parameter:
Parameter | Description | Required |
marketplaceIds |
A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified. For example, Type: < string > array |
Yes |
interval |
A time interval used for selecting order metrics. This takes the form of two dates separated by two hyphens (first date is inclusive; second date is exclusive). Dates are in ISO 8601 format and must represent absolute time (either Z notation or offset notation). Example: Type: string |
Yes |
granularityTimeZone |
An IANA-compatible time zone for determining the day boundary. Required when specifying a granularity value greater than Hour. The Example: US/Pacific to compute day boundaries, accounting for daylight time savings, for US/Pacific zone. Type: string |
No |
granularity |
The Example: Day to get a daily breakdown of the request interval, where the day boundary is defined by the Type: enum (Granularity) |
Yes |
buyerType |
Filters the results by the buyer type that you specify, Example: Type: enum (BuyerType) |
No |
fulfillmentNetwork |
Filters the results by the fulfillment network that you specify, Example: Type: string |
No |
firstDayOfWeek |
Specifies the day that the week starts on when Example: Type: enum (FirstDayOfWeek) |
No |
asin |
Filters the results by the ASIN that you specify. Specifying both Example: Type: string |
No |
sku |
Filters the results by the SKU that you specify. Specifying both Example: Type: string |
No |
Request example
GET https://sellingpartnerapi-na.amazon.com/sales/v1/orderMetrics?marketplaceIds=&interval=&granularityTimeZone=&granularity=&buyerType=&fulfillmentNetwork=&firstDayOfWeek=&asin=&sku="
Response
Parameter | Description | Required |
interval |
The interval of time based on requested granularity (for example, Hour, Day) If this is the first or the last interval from the list, it might contain incomplete data if the requested interval doesn't align with the requested granularity (ex. request interval Type: string |
Yes |
unitCount |
The number of units in orders based on the specified filters. Type: integer |
Yes |
orderItemCount |
The number of order items based on the specified filters. Type: integer |
Yes |
orderCount |
The number of orders based on the specified filters. Type: integer |
Yes |
averageUnitPrice |
The average price for an item based on the specified filters. Formula is totalSales/unitCount. Type: Money |
Yes |
totalSales |
The total ordered product sales for all orders based on the specified filters. Type: Money |
Yes |
Response example
{
"request": {
"parameters": {
"granularity": {
"value": "Day"
}
}
},
"response": {
"payload": [
{
"interval": "2019-08-01T00:00-07:00--2018-08-02T00:00-07:00",
"unitCount": 1,
"orderItemCount": 1,
"orderCount": 1,
"averageUnitPrice": {
"amount": "22.95",
"currencyCode": "USD"
},
"totalSales": {
"amount": "22.95",
"currencyCode": "USD"
}
},
{
"interval": "2019-08-02T00:00-07:00--2018-08-03T00:00-07:00",
"unitCount": 1,
"orderItemCount": 1,
"orderCount": 1,
"averageUnitPrice": {
"amount": "2.05",
"currencyCode": "USD"
},
"totalSales": {
"amount": "2.05",
"currencyCode": "USD"
}
}
]
}
}
Updated 2 months ago