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 <<glossary: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.

To learn more about the terms that are used on this page, refer to Terminology.

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.

Step 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.

Step 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.

Step 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.

Step 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.

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
REVENUE_BY_DELIVERIES
SUBSCRIBER_RETENTION
REVENUE_PENETRATION_BY_SELLER_FUNDING
SHARE_OF_COUPON_SUBSCRIPTIONS

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.

Step 1. Get all performance metrics aggregated over the specified frequency

To return a selling partner's past performance metrics, call the getSellingPartnerMetrics operation.

Step 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.

Step 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.

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.

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
REVENUE_BY_DELIVERIES
SUBSCRIBER_RETENTION
REVENUE_PENETRATION_BY_SELLER_FUNDING
SHARE_OF_COUPON_SUBSCRIPTIONS

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.

Step 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.

Step 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.

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.

Updated 2 months ago