Replenishment API v2022-11-07 Use Case Guide
Return a selling partner's replenishment program metrics and offer information.
API Version: 2022-11-07
What is the Replenishment API?
With the Selling Partner API for Replenishment (Replenishment API), you can return information about a selling partner's replenishment program business. Currently, the Subscribe & Save replenishment program is supported. With the Replenishment API, you can create applications that return metrics about a selling partner's replenishment business performance and information about their replenishment program offers.
Some attributes or use cases might not be applicable to both sellers and vendors. Refer to the Replenishment API v2022-11-07 reference for details.
The Replenishment API is available wherever Amazon Subscribe & Save is live. The API is also available to vendors and Fulfillment by Amazon (FBA) selling partners.
Key features
-
Retrieve business metric data: The Replenishment API can return a number of metrics aggregated over a period of time. Data can also be returned at the catalog item (ASIN) level.
-
Retrieve seller offer details: The Replenishment API can return details about a seller's replenishment program offers in the Subscribe & Save program.
Terminology
-
Replenishment program: A program which provides recurring delivery of a replenishable item at a frequency chosen by the recipient.
-
Subscribe & Save: An Amazon replenishment program which provides recurring delivery (automatic or manual) of any replenishable item at a frequency chosen by the customer.
-
Offer: A replenishable offer, which is different from a listings offer. A replenishable offer is uniquely identified in the backend service by Amazon Standard Identification Number (ASIN), selling partner ID, marketplace ID, and SKU.
-
Enabled offer: A replenishment program offer which is eligible for new subscriptions.
-
Selling partner: A selling partner can be a seller or a vendor.
Tutorial: Get all of a selling partner's replenishment offers filtered by specific criteria
This tutorial shows you how to use the Replenishment API to return a selling partner's replenishment (currently Subscribe & Save) offers based on filtering criteria.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- The Brand Analytics role assigned to your developer profile.
- The Brand Analytics role selected in the app registration page for your application.
- The marketplace identifier for the marketplace for which to return data. Refer to Marketplace IDs to find the identifier for a marketplace. Refer to the Replenishment API v2022-11-07 reference for details about supported marketplaces.
Task 1 - Get all of a selling partner's enabled offers
Enabled offers are those which are eligible for new subscriptions. To return enabled offers, call the listOffers
operation, passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
pagination
|
Use these parameters to paginate through the response. | Yes |
filters
|
Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array.
Type: |
Yes |
sort
|
Use these parameters to sort the response.
Type: |
No |
The filters
parameter supports an optional eligibilities
array where you can provide the eligibility statuses for the offers that you want to return. To return only the enabled or eligible offers, specify only the "ELIGIBLE
" enum value in the eligibilities
array, as shown in the following request example.
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/offers/search
{
"filters":{
"eligibilities":["ELIGIBLE"],
"marketplaceId": "A21TJRUUN4KGV",
"programTypes": ["SUBSCRIBE_AND_SAVE"]
},
"pagination": {
"limit": 25,
"offset": 10
}
}
Response
A successful response includes the list of enabled offers as well as additional details for each offer.
Response example
{
"offers": [
{
"marketplaceId": "ATVPDKIKX0DER",
"offerProgramConfiguration": {
"preferences": {
"autoEnrollment": "OPTED_IN"
},
"promotions": {
"sellingPartnerFundedBaseDiscount": {
"percentage": 5
},
"sellingPartnerFundedTieredDiscount": {
"percentage": 0
},
"amazonFundedBaseDiscount": {
"percentage": 5
},
"amazonFundedTieredDiscount": {
"percentage": 10
}
},
"enrollmentMethod": "AUTOMATIC"
},
"programType": "SUBSCRIBE_AND_SAVE",
"eligibility": "ELIGIBLE",
"asin": "ASIN_1",
"sku": "SKU_OPTED_IN"
}
],
"pagination": {
"totalResults": 1
}
}
Task 2 - Get all of a selling partner's offers under the given ASINs
To return all of the offers under the given ASINs, call the listOffers
operation, passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
pagination
|
Use these parameters to paginate through the response. | Yes |
filters
|
Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array.
Type: |
Yes |
sort
|
Use these parameters to sort the response.
Type: |
No |
The filters
parameter supports an optional asins
array where you can provide the list of ASINs for the offers that you want to return, as shown in the following request example.
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/offers/search
{
"filters": {
"asins": ["ASIN_1", "ASIN_2"],
"marketplaceId": "A21TJRUUN4KGV",
"programTypes": ["SUBSCRIBE_AND_SAVE"]
},
"pagination": {
"limit": 25,
"offset": 10
}
}
Response
A successful response includes the list of offers which have one of the requested ASINs, as well as additional details for each of the offers.
Response example
{
"offers": [
{
"marketplaceId": "ATVPDKIKX0DER",
"offerProgramConfiguration": {
"preferences": {
"autoEnrollment": "OPTED_IN"
},
"promotions": {
"sellingPartnerFundedBaseDiscount": {
"percentage": 5
},
"sellingPartnerFundedTieredDiscount": {
"percentage": 0
},
"amazonFundedBaseDiscount": {
"percentage": 5
},
"amazonFundedTieredDiscount": {
"percentage": 10
}
},
"enrollmentMethod": "AUTOMATIC"
},
"programType": "SUBSCRIBE_AND_SAVE",
"eligibility": "ELIGIBLE",
"asin": "ASIN_1",
"sku": "SKU_OPTED_IN"
}
],
"pagination": {
"totalResults": 1
}
}
Task 3 - Get all of a selling partner's offers which have the given seller funded discount
To return all of the offers which have the given seller funded discount, call the listOffers
operation, passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
pagination
|
Use these parameters to paginate through the response. | Yes |
filters
|
Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array.
Type: |
Yes |
sort
|
Use these parameters to sort the response.
Type: |
No |
The filters
parameter supports an optional promotions
property where you can filter the results to include only offers with the specified percentage discounts, as shown in the following request example.
Request example to return offers with either 0
or 5
seller funding
0
or 5
seller fundingPOST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/offers/search
{
"filters": {
"marketplaceId": "ATVPDKIKX0DER",
"promotions": {
"sellingPartnerFundedBaseDiscount": {
"percentage": [
0,
5
]
}
},
"programTypes": [
"SUBSCRIBE_AND_SAVE"
]
},
"pagination": {
"limit": 25,
"offset": 10
},
"sort": {
"order": "ASC",
"key": "ASIN"
}
}
Response
A successful response includes the list of offers which have one of the requested seller funded discounts, as well as additional details for each of the offers.
Response example
{
"offers": [
{
"marketplaceId": "ATVPDKIKX0DER",
"offerProgramConfiguration": {
"preferences": {
"autoEnrollment": "OPTED_IN"
},
"promotions": {
"sellingPartnerFundedBaseDiscount": {
"percentage": 0
},
"sellingPartnerFundedTieredDiscount": {
"percentage": 0
},
"amazonFundedBaseDiscount": {
"percentage": 5
},
"amazonFundedTieredDiscount": {
"percentage": 10
}
},
"enrollmentMethod": "AUTOMATIC"
},
"programType": "SUBSCRIBE_AND_SAVE",
"eligibility": "ELIGIBLE",
"asin": "ASIN_1",
"sku": "SKU_OPTED_IN"
},
{
"marketplaceId": "ATVPDKIKX0DER",
"offerProgramConfiguration": {
"preferences": {
"autoEnrollment": "OPTED_IN"
},
"promotions": {
"sellingPartnerFundedBaseDiscount": {
"percentage": 5
},
"sellingPartnerFundedTieredDiscount": {
"percentage": 0
},
"amazonFundedBaseDiscount": {
"percentage": 5
},
"amazonFundedTieredDiscount": {
"percentage": 10
}
},
"enrollmentMethod": "AUTOMATIC"
},
"programType": "SUBSCRIBE_AND_SAVE",
"eligibility": "ELIGIBLE",
"asin": "ASIN_2",
"sku": "SKU_OPTED_IN_2"
}
],
"pagination": {
"totalResults": 2
}
}
Task 4 - Get all of a selling partner's offers which have the given auto enrollment preferences (applicable only for sellers)
To return all offers which have the requested auto enrollment preference, call the listOffers
operation, passing following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
pagination
|
Use these parameters to paginate through the response. | Yes |
filters
|
Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array.
Type: |
Yes |
sort
|
Use these parameters to sort the response.
Type: |
No |
The filters
parameter supports an optional preferences
property where you can filter the results to include only offers with the specified autoEnrollment
preferences, as shown in the following request example.
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/offers/search
{
"filters": {
"marketplaceId": "A21TJRUUN4KGV",
"preferences": {
"autoEnrollment": [
"OPTED_IN"
]
},
"programTypes": [
"SUBSCRIBE_AND_SAVE"
]
},
"pagination": {
"limit": 10,
"offset": 20
},
"sort": {
"order": "ASC",
"key": "ASIN"
}
}
Response
A successful response includes the list of offers which have one of the specified auto enrollment preferences, as well as additional details for each of the offers.
Response example
{
"offers": [
{
"marketplaceId": "ATVPDKIKX0DER",
"offerProgramConfiguration": {
"preferences": {
"autoEnrollment": "OPTED_IN"
},
"promotions": {
"sellingPartnerFundedBaseDiscount": {
"percentage": 5
},
"sellingPartnerFundedTieredDiscount": {
"percentage": 0
},
"amazonFundedBaseDiscount": {
"percentage": 5
},
"amazonFundedTieredDiscount": {
"percentage": 10
}
},
"enrollmentMethod": "AUTOMATIC"
},
"programType": "SUBSCRIBE_AND_SAVE",
"eligibility": "ELIGIBLE",
"asin": "ASIN_2",
"sku": "SKU_OPTED_IN_2"
}
],
"pagination": {
"totalResults": 2
}
}
Tutorial: Get a selling partner's replenishment business metrics
This tutorial shows you how to use the Replenishment API to return a selling partner's replenishment program (currently Subscribe & Save) business metrics. The following metrics are supported:
SHIPPED_SUBSCRIPTION_UNITS
TOTAL_SUBSCRIPTIONS_REVENUE
ACTIVE_SUBSCRIPTIONS
NOT_DELIVERED_DUE_TO_OOS
SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REVENUE
LOST_REVENUE_DUE_TO_OOS
SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REORDERS
COUPONS_REVENUE_PENETRATION
Refer to Metric
for the metric names and descriptions.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- The Brand Analytics role assigned to your developer profile.
- The Brand Analytics role selected in the app registration page for your application.
- The marketplace identifier for the marketplace for which to return data.. Refer to Marketplace IDs to find the identifier for a marketplace. Refer to the Replenishment API v2022-11-07 reference for details about supported marketplaces.
Task 1 - Get all performance metrics aggregated over the specified frequency
To return a selling partner's past performance metrics, call the getSellingPartnerMetrics
operation, passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
aggregationFrequency
|
The time period used to group data in the response. Note that this is only valid for the performance time period type.
Type: |
No |
timeInterval
|
A time interval used to compute metrics.
Type: |
Yes |
metrics
|
The list of metrics requested. If no metric value is provided, data for all of the metrics is returned.
Type: < |
No |
timePeriodType
|
The time period type that determines whether the metrics requested are backward-looking (performance) or forward-looking (forecast).
Type: |
Yes |
marketplaceId
|
The marketplace identifier. The supported marketplaces for both sellers and vendors are US, CA, ES, UK, FR, IT, IN, DE and JP. The supported marketplaces for vendors only are BR, AU, MX, AE and NL. Refer to MarketPlace IDs to find the identifier for the marketplace.
Type: string |
Yes |
programTypes
|
The list of replenishment program types for which to return metrics.
Type: |
Yes |
The default for the metrics
parameter is to return all available metrics. Therefore, to return all of the available metrics, omit the metrics
parameter, as shown in the following request example:
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/sellingPartners/metrics/search
{
"aggregationFrequency": "WEEK",
"timeInterval": {
"endDate": "2023-03-11T00:00:00Z",
"startDate": "2023-03-05T00:00:00Z"
},
"timePeriodType": "PERFORMANCE",
"marketplaceId": "ATVPDKIKX0DER",
"programTypes": [
"SUBSCRIBE_AND_SAVE"
]
}
Response
A successful response includes the data for each available metric. For each metric, the timeInterval
used is returned in the response and is determined based on the aggregation frequency. Refer to TimeInterval
for more information.
Response example
{
"metrics": [
{
"shippedSubscriptionUnits": 5290,
"notDeliveredDueToOOS": 5.54,
"totalSubscriptionsRevenue": 131340.24,
"lostRevenueDueToOOS": 93.29,
"couponsRevenuePenetration": 46.22,
"activeSubscriptions": 0,
"currencyCode": "USD",
"timeInterval": {
"endDate": "2023-03-11T00:00:00Z",
"startDate": "2023-03-05T00:00:00Z"
}
},
{
"subscriberAverageRevenue": 125.93,
"nonSubscriberAverageRevenue": 73.62,
"currencyCode": "USD",
"subscriberAverageReorders": 4.61,
"nonSubscriberAverageReorders": 2.38,
"timeInterval": {
"endDate": "2023-05-24T21:13:55Z",
"startDate": "2022-05-24T21:13:55Z"
}
}
]
}
Task 2 - Get a specific performance metric aggregated over the specified frequency
You can request specific metrics instead of returning all available metrics by providing the optional metrics
parameter.
To return a selling partner's past performance metrics, call the getSellingPartnerMetrics
operation, passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
aggregationFrequency
|
The time period used to group data in the response. Note that this is only valid for the performance time period type.
Type: |
No |
timeInterval
|
A time interval used to compute metrics.
Type: |
Yes |
metrics
|
The list of metrics requested. If no metric value is provided, data for all of the metrics is returned.
Type: < |
No |
timePeriodType
|
The time period type that determines whether the metrics requested are backward-looking (performance) or forward-looking (forecast).
Type: |
Yes |
marketplaceId
|
The marketplace identifier. The supported marketplaces for both sellers and vendors are US, CA, ES, UK, FR, IT, IN, DE and JP. The supported marketplaces for vendors only are BR, AU, MX, AE and NL. Refer to MarketPlace IDs to find the identifier for the marketplace.
Type: string |
Yes |
programTypes
|
The list of replenishment program types for which to return metrics.
Type: |
Yes |
To request specific metrics for a selling partner, provide one or more Metric
values in the metrics
parameter, as shown in the following request example:
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/sellingPartners/metrics/search
{
"aggregationFrequency": "WEEK",
"timeInterval": {
"endDate": "2023-03-11T00:00:00Z",
"startDate": "2023-03-05T00:00:00Z"
},
"metrics": [
"SHIPPED_SUBSCRIPTION_UNITS",
],
"timePeriodType": "PERFORMANCE",
"marketplaceId": "ATVPDKIKX0DER",
"programTypes": [
"SUBSCRIBE_AND_SAVE"
]
}
Response
A successful response includes the requested metrics. For each metric, the timeInterval
used is returned in the response and is determined based on the aggregation frequency. Refer to TimeInterval
for more information.
Response example
{
"metrics": [
{
"shippedSubscriptionUnits": 50,
"timeInterval": {
"endDate": "2023-03-11T00:00:00Z",
"startDate": "2023-03-05T00:00:00Z"
}
}
]
}
Task 3 - Get forecast metrics data for the next 30, 60, or 90 days (applicable only for sellers)
To return forecast metrics for the next 30, 60, or 90 days, call the getSellingPartnerMetrics
operation, passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
timeInterval
|
A time interval used to compute metrics.
Type: |
Yes |
metrics
|
The list of metrics requested. If no metric value is provided, data for all of the metrics are returned.
Type: < |
No |
timePeriodType
|
The time period type that determines whether the metrics requested are backward-looking (performance) or forward-looking (forecast).
Type: |
Yes |
marketplaceId
|
The marketplace identifier. The supported marketplaces for both sellers and vendors are US, CA, ES, UK, FR, IT, IN, DE and JP. The supported marketplaces for vendors only are BR, AU, MX, AE and NL. Refer to MarketPlace IDs to find the identifier for the marketplace.
Type: string |
Yes |
programTypes
|
The list of replenishment program types for which to return metrics.
Type: |
Yes |
When you call the getSellingPartnerMetrics
operation you can choose to return forward-looking forecast metrics instead of past performance metrics. To request forecast metrics, specify FORECAST
as the value for the timePeriodType
parameter.
Data is available for the next 30, 60 and 90 days. To return forecast data you must represent a 30, 60, or 90 day period in the requested date-time range values that you provide for the timeInterval
parameter. If the timeInterval
you provide does not have a duration that exactly matches 30, 60, or 90 days, it is rounded up to provide the next higher number of forecast days.
For example, if the duration of the interval is 91 days, the response contains forecast metrics for the next 30, 60, and 90 days. If the duration is 89 days, the response contains forecast metrics for the next 30, 60, and 90 days. If the interval duration is 59 days, the response contains forecast metrics for the next 30 and 60 days.
The TOTAL_SUBSCRIPTIONS_REVENUE
and SHIPPED_SUBSCRIPTION_UNITS
metrics are the only forecast metrics supported.
Forecast metrics are available for sellers only.
Suppose today is 2023-05-25T00:00:00Z
and you want to return a forecast metric. The following request example shows how to request the next 90 days forecast data for the SHIPPED_SUBSCRIPTION_UNITS
metric:
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/sellingPartners/metrics/search
{
"timeInterval": {
"endDate": "2023-08-23T00:00:00Z",
"startDate": "2023-05-25T00:00:00Z"
},
"metrics":["SHIPPED_SUBSCRIPTION_UNITS"],
"timePeriodType": "FORECAST",
"marketplaceId": "ATVPDKIKX0DER",
"programTypes": ["SUBSCRIBE_AND_SAVE"]
}
Response
A successful response includes the requested metrics. For each metric, the timeInterval
returned in the response is of either 30, 60, or 90 days duration depending on the timeInterval
values provided in the request.
Response example
{
"metrics": [
{
"shippedSubscriptionUnits": 10,
"timeInterval": {
"endDate": "2023-06-24T00:00:00Z",
"startDate": "2023-05-25T00:00:00Z"
}
},
{
"shippedSubscriptionUnits": 20,
"timeInterval": {
"endDate": "2023-07-24T00:00:00Z",
"startDate": "2023-05-25T00:00:00Z"
}
},
{
"shippedSubscriptionUnits": 30,
"timeInterval": {
"endDate": "2023-08-23T00:00:00Z",
"startDate": "2023-05-25T00:00:00Z"
}
}
]
}
Tutorial: Get replenishment business metrics for each of a selling partner's offers
This tutorial shows you how to use the Replenishment API to return a selling partner's replenishment metrics at an ASIN level. The following metrics are supported:
SHIPPED_SUBSCRIPTION_UNITS
TOTAL_SUBSCRIPTIONS_REVENUE
ACTIVE_SUBSCRIPTIONS
NOT_DELIVERED_DUE_TO_OOS
SUBSCRIBER_NON_SUBSCRIBER_AVERAGE_REVENUE
LOST_REVENUE_DUE_TO_OOS
COUPONS_REVENUE_PENETRATION
Refer to Metric
for the metric names and descriptions.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- The Brand Analytics role assigned to your developer profile.
- The Brand Analytics role selected in the app registration page for your application.
- The marketplace identifier for the marketplace for which to return data.. Refer to Marketplace IDs to find the identifier for a marketplace. Refer to the Replenishment API v2022-11-07 reference for details about supported marketplaces.
Task 1 - Get performance metrics data aggregated over the specified frequency
To return a selling partner's performance metrics for every ASIN, call the listOfferMetrics
operation, passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
pagination
|
Use these parameters to paginate through the response. | Yes |
sort
|
Use these parameters to sort the response. | No |
filters
|
Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array. | Yes |
The filters
parameter supports a timePeriodType
property that allows you to choose backward-looking performance metrics or forward-looking forecast metrics. To return performance metrics you must specify PERFORMANCE
as the timePeriodType
value.
The listOfferMetrics
operation only supports a time interval which covers a single unit of the aggregation frequency. For example, for a MONTH
aggregation frequency, the duration of the interval between the startDate
and endDate
can not be more than one month.
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/offers/metrics/search
{
"filters": {
"aggregationFrequency": "WEEK",
"timeInterval": {
"endDate": "2023-03-11T00:00:00Z",
"startDate": "2023-03-05T00:00:00Z"
},
"timePeriodType": "PERFORMANCE",
"marketplaceId": "ATVPDKIKX0DER",
"programTypes": [
"SUBSCRIBE_AND_SAVE"
]
},
"pagination": {
"limit": 10,
"offset": 10
},
"sort": {
"order": "ASC",
"key": "SHIPPED_SUBSCRIPTION_UNITS"
}
}
Response
A successful response includes the requested metrics for each ASIN.
Response example
{
"offers": [
{
"notDeliveredDueToOOS": 30.78,
"shippedSubscriptionUnits": 20,
"totalSubscriptionsRevenue": 12.89,
"asin": "B000TMUDOW",
"revenuePenetration": 10.34,
"lostRevenueDueToOOS": 34.79,
"couponsRevenuePenetration": 2.62,
"timeInterval": {
"endDate": "2023-03-11T00:00:00Z",
"startDate": "2023-03-05T00:00:00Z"
},
"currencyCode": "USD"
},
{
"notDeliveredDueToOOS": 40.78,
"shippedSubscriptionUnits": 40,
"totalSubscriptionsRevenue": 34.03,
"asin": "B004CLH5CY",
"revenuePenetration": 9.87,
"lostRevenueDueToOOS": 45.29,
"couponsRevenuePenetration": 1.36,
"timeInterval": {
"endDate": "2023-03-11T00:00:00Z",
"startDate": "2023-03-05T00:00:00Z"
},
"currencyCode": "USD"
}
],
"pagination": {
"totalResults": 17
}
}
Task 2 - Get forecast metrics data for the next 30, 60, or 90 days (applicable only for sellers)
To return forecast metrics data for every ASIN, call the listOfferMetrics
operation,
passing the following parameters:
Body parameter
Parameter | Description | Required |
---|---|---|
pagination
|
Use these parameters to paginate through the response. | Yes |
sort
|
Use these parameters to sort the response. | No |
filters
|
Use these parameters to filter results. Any result must match all provided parameters. For any parameter that is an array, the result must match at least one element in the provided array. | Yes |
When you call the listOfferMetrics
operation you can choose to return forward-looking forecast metrics instead of past performance metrics. To request forecast metrics, specify FORECAST
as the value for the timePeriodType
property in the filters
parameter.
The listOfferMetrics
operation only supports a time interval which covers a single unit of the aggregation frequency. For example, for a MONTH
aggregation frequency, the duration of the interval between the startDate
and endDate
can not be more than one month.
The TOTAL_SUBSCRIPTIONS_REVENUE
and SHIPPED_SUBSCRIPTION_UNITS
metrics are the only forecast metrics supported.
Forecast metrics are available for sellers only.
The following request shows how to request forecast data for the next 90 days given an example present date of 2023-05-25T00:00:00Z
:
Request example
POST https://sellingpartnerapi-na.amazon.com/replenishment/2022-11-07/offers/metrics/search
{
"filters": {
"timeInterval": {
"endDate": "2023-08-23T00:00:00Z",
"startDate": "2023-05-25T00:00:00Z"
},
"timePeriodType": "FORECAST",
"marketplaceId": "ATVPDKIKX0DER",
"programTypes": [
"SUBSCRIBE_AND_SAVE"
]
},
"pagination": {
"limit": 10,
"offset": 10
}
}
Response
A successful response includes the available forecast metrics for each ASIN.
Response example
{
"offers": [
{
"next30DayTotalSubscriptionsRevenue": 0,
"next60DayTotalSubscriptionsRevenue": 61.8,
"next90DayTotalSubscriptionsRevenue": 30.9,
"asin": "B0872JRNS2",
"next90DayShippedSubscriptionUnits": 20,
"next60DayShippedSubscriptionUnits": 10,
"next30DayShippedSubscriptionUnits": 2,
"currencyCode": "USD",
"timeInterval": {
"endDate": "2023-08-23T00:00:00Z",
"startDate": "2023-05-25T00:00:00Z"
}
}
],
"pagination": {
"totalResults": 17
}
}
Updated about 2 months ago