Sales API v1 Use Case Guide

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. See 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, `ATVPDKIKX0DER` indicates the US marketplace. 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: `2018-09-01T00:00:00-07:00--2018-09-04T00:00:00-07:00` requests order metrics for Sept 1st, 2nd and 3rd in the -07:00 zone. Type: string	Yes
`granularityTimeZone`	An IANA-compatible time zone for determining the day boundary. Required when specifying a granularity value greater than Hour. The `granularityTimeZone` value must align with the offset of the specified interval value. For example, if the interval value uses Z notation, then `granularityTimeZone` must be UTC. If the interval value uses an offset, then `granularityTimeZone` must be an IANA-compatible time zone that matches the offset. Example: US/Pacific to compute day boundaries, accounting for daylight time savings, for US/Pacific zone. Type: string	No
`granularity`	The `granularity` of the grouping of order metrics, based on a unit of time. Specifying `granularity=Hour` results in a successful request only if the interval specified is less than or equal to 30 days from now. For all other granularities, the interval specified must be less or equal to 2 years from now. Specifying `granularity=Total` results in order metrics that are aggregated over the entire interval that you specify. If the interval start and end date don’t align with the specified `granularity`, the head and tail end of the response interval will contain partial data. Example: Day to get a daily breakdown of the request interval, where the day boundary is defined by the `granularityTimeZone`. Type: enum (Granularity)	Yes
`buyerType`	Filters the results by the buyer type that you specify, `B2B` (business to business) or `B2C` (business to customer). Example: `B2B`, if you want the response to include order metrics for only B2B buyers. Type: enum (BuyerType)	No
`fulfillmentNetwork`	Filters the results by the fulfillment network that you specify, `MFN` (merchant fulfillment network) or `AFN` (Amazon fulfillment network). Do not include this filter if you want the response to include order metrics for all fulfillment networks. Example: `AFN`, if you want the response to include order metrics for only Amazon fulfillment network. Type: string	No
`firstDayOfWeek`	Specifies the day that the week starts on when `granularity=Week`, either `Monday` or `Sunday`. Default: `Monday`. Example: `Sunday`, if you want the week to start on a Sunday. Type: enum (FirstDayOfWeek)	No
`asin`	Filters the results by the ASIN that you specify. Specifying both `asin` and `sku` returns an error. Do not include this filter if you want the response to include order metrics for all ASINs. Example: `B0792R1RSN`, if you want the response to include order metrics for only `asin` `B0792R1RSN`. Type: string	No
`sku`	Filters the results by the SKU that you specify. Specifying both `asin` and `sku` returns an error. Do not include this filter if you want the response to include order metrics for all SKUs. Example: `TestSKU`, if you want the response to include order metrics for only SKU `TestSKU`. 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 (ex. Hour, Day, etc.) 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 `2018-09-01T02:00:00Z--2018-09-04T19:00:00Z` and granularity day will result in Sept 1st UTC day and Sept 4th UTC days having partial data). 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"
        }
      }
    ]
  }
}