Roles in the Selling Partner API

How roles are used in Selling Partner API.

Roles in the Selling Partner API

What is a role?

A role is the mechanism used by Selling Partner APIs to determine whether a developer or application has access to an operation or resource. As a developer, you must request and qualify for a particular role, or you will not be able to access the operations and resources grouped under that role. Roles protect access to personally identifiable information (PII) and other sensitive data, and limit data access to ensure developers only access data that is required for an application. This helps ensure that customers trust Amazon and trust Selling Partner Services businesses that employ the Selling Partner APIs.

Role definitions

In the following table, Restricted means the role requires sensitive information which may include personally identifiable information (PII). You will be required to provide additional information about your use of the data and your security controls.

RoleDescription
Brand AnalyticsAccess reports that contain information about seller and vendor performance on Amazon and consumer behavior reports that give insight into how customers find and purchase a selling partner's products on Amazon. Example operations that require this role assignment:
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT report. This report returns data on the top clicked ASINs by search keyword and department for a marketplace.
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_PROMOTION_PERFORMANCE_REPORT report. This report returns data from promotion campaigns to help vendors and sellers optimize their promotions and adjust their advertising strategies.
See Brand Analytics for a complete list of the operations and the feed, report, and notification types that require this role.

Product ListingCreate and manage product listings. Generally used for product catalog related reports and feeds, and operations. Examples of operations that require this role assignment:
  • The getCatalogItem operation of the Selling Partner API for Catalog Items, which returns information about the item indicated and its attributes.
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_MERCHANT_LISTINGS_INACTIVE_DATA report. This report returns detailed inactive listings.
  • The getMyFeesEstimateForSKU operation of the Selling Partner API for Product Fees, which returns the estimated fees for the item indicated.
See Product Listing for a complete list of the operations and the feed, report, and notification types that require this role.

PricingDetermine list prices and automate product pricing. Generally used for pricing related reports, feeds and operations. Examples of operations that require this role assignment:
  • The createFeed operation of the Selling Partner API for Feeds when used to submit a RFQ_UPLOAD_FEED feed. This lets you upload quantity discounts in response to requests from business customers.
  • The getPricing operation of the Selling Partner API for Pricing, which returns pricing information for a seller's offer listings.
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_MERCHANT_CANCELLED_LISTINGS_DATA report. This report returns canceled listings.
See Pricing for a complete list of the operations and the feed, report, and notification types that require this role.

Amazon FulfillmentShip to Amazon, and Amazon ships directly to customers (Fulfillment by Amazon (FBA), Amazon Fulfillment Network (AFN)). Generally used for FBA Sales Reports, Order Tracking Reports, and operations related to order fulfillment. Examples of operations that require this role assignment:
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA report. This report contains estimated Amazon Selling and Fulfillment Fees.
  • The getSubscription operation of the Selling Partner API for Notifications when used to subscribe to FBA_OUTBOUND_SHIPMENT_STATUS notifications. These notifications are sent whenever we create or cancel a FBA shipment for a seller.
  • The getLabels operation of the Selling Partner API for Fulfillment Inbound, which returns package/pallet labels.
  • The createFeed operation of the Selling Partner API for Feeds when used to submit a POST_FBA_INBOUND_CARTON_CONTENTS feed. This lets you submit carton content information when shipping inventory to Amazon’s fulfillment network.
See Amazon Fulfillment for a complete list of the operations and the feed, report, and notification types that require this role.

Buyer CommunicationManage messaging to and from Amazon buyers. Generally used for messaging to Amazon buyers using the Selling Partner API for Messaging. Examples of operations that require this role assignment:
  • The getMessagingActionsForOrder operation of the Selling Partner API for Messaging, which returns a list of message types available for a specified order.
  • The createConfirmOrderDetails operation of the Selling Partner API for Messaging, which sends a message to ask a buyer an order-related question prior to shipping.
  • The createConfirmDeliveryDetails operation of the Selling Partner API for Messaging, which sends a message to a buyer to arrange a deliver or confirm contact information for making a delivery.
See Buyer Communication for a complete list of the operations and the feed, report, and notification types that require this role.

Buyer SolicitationSolicit Amazon buyers for feedback. Generally used to solicit Amazon buyers for feedback using the Selling Partner API for Solicitations. Examples of operations that require this role assignment:
  • The getSolicitationActionsForOrder operation of the Selling Partner API for Solicitations, which returns a list of solicitation types available for an order.
  • The createProductReviewAndSellerFeedbackSolicitation operation, which sends a solicitation to a buyer asking for feedback and a product review for an order.
See Buyer Solicitation for a complete list of the operations and the feed, report, and notification types that require this role.

Selling Partner InsightsView information about the Amazon Selling Partner account and performance. Generally used for reports and operations used to return seller insights. Examples of operations that require this role assignment:
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_V1_SELLER_PERFORMANCE_REPORT report. This report contains individual performance metrics from the Seller Central dashboard.
  • The getMarketplaceParticipations operation of the Selling Partner API for Sellers, which returns a list of marketplaces that a seller can sell in, and information about the seller’s participation in those marketplaces.
See Selling Partner Insights for a complete list of the operations and the feed, report, and notification types that require this role.

Finance and AccountingProduce accounting and financial statements. Generally used for creating accounting and financial statements. Examples of operations that require this role assignment:
  • The getReports operation of the Selling Partner API for Reports, when used to return a list of the GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE reports created.
  • The getSubscription operation of the Selling Partner API for Notifications, when used to return information about subscriptions to the FEE_PROMOTION notification type.
See Finance and Accounting for a complete list of the operations and the feed, report, and notification types that require this role.

Inventory and Order TrackingAnalyze and manage inventory. Generally used for FBA Sales Reports, Order Tracking Reports, and operations related to orders, vendor orders, sales order metrics and inventory management. Operations that require this role do not use PII required to ship an order. Rather, this role is required for applications that track order shipments to manage inventory/manufacturing/purchasing. Examples of operations that require this role assignment:
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_MERCHANT_LISTINGS_DATA report. This report returns detailed active listings.
  • The createFeed operation of the Selling Partner API for Feeds when used to submit a POST_FLAT_FILE_FULFILLMENT_DATA feed. This lets you submit order fulfillment information to Amazon.
  • The getOrderMetrics operation of the Selling Partners API for Sales, which returns aggregated order metrics.
See Inventory and Order Tracking for a complete list of the operations and the feed, report, and notification types that require this role.

Direct-to-Consumer Shipping (Restricted)Ship orders directly to customers using their carrier of choice, including Amazon. Operations that require this role use PII to enable shipping. Generally used for Order Reports, Order Tracking Reports, EasyShip, and for operations related to shipping orders placed on Amazon. Example operations that require this role assignment:
  • The getShipment operation of the Selling Partner API for Merchant Fulfillment, which returns shipment information for a specified shipment.
  • The getOrders operation of the Selling Partner API for Orders, which returns a list of orders and order information based on the criteria specified.
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_FLAT_FILE_ ORDER_REPORT_DATA_SHIPPING report.
  • The createFeed operation of the Selling Partner API for Feeds, when used to submit a POST_ORDER_FULFILLMENT_DATA feed. This feed allows your system to update Amazon's system with order fulfillment information.
See Direct-to-Consumer Shipping (Restricted) for a complete list of the operations and the feed, report, and notification types that require this role.

Tax Invoicing (Restricted)Generate tax invoices to comply with tax regulation. Operations that require this role require PII to enable tax invoice generation. Generally used for Tax Reports and Order Reports, and operations that return information about orders. Examples of operations that require this role assignment:
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_AMAZON_FULFILLED_SHIPMENTS_INVOICING report. This report returns detailed order/shipment/item information.
  • The getOrderAddress operation of the Selling Partner API for Orders, which returns the shipping address for an order.
  • The getOrderBuyerInfo operation of the Selling Partner API for Orders, which returns buyer information for an order.
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_EASYSHIP_DOCUMENTS report. This report contains the invoice, shipping label and warranty documents for an Easy Ship order.
See Tax Invoicing (Restricted) for a complete list of the operations and the feed, report, and notification types that require this role.
Tax Remittance (Restricted)Calculate and remit sales taxes. Operations that require this role may use PII to calculate sales taxes. Generally used for FBA Sales Reports and Order Reports and operations that return information about orders. Examples of operations that require this role assignment:
  • The createReport operation of the Selling Partner API for Reports, when used to request the GET_AMAZON_FULFILLED_SHIPMENTS_REMITTANCE report. This report returns detailed order/shipment/item information.
  • The getOrderItems operation of the Selling Partner API for Orders, which returns detailed order item information for an order.
  • The getOrders operation of the Selling Partner API for Orders, which returns a list of order item information for a time frame and a range of criteria.
See Tax Remittance (Restricted) for a complete list of the operations and the feed, report, and notification types that require this role.

Frequently Asked Questions

How do I request and qualify for a role?

You request and qualify for Selling Partner API roles by populating your Developer Profile. The specific information requested depends on whether you are an already existing Amazon Marketplace Web Service (MWS) developer or not, and whether you have previously registered.

Once your profile is submitted, Amazon evaluates the information provided and approves or denies your request. If denied, you can address the reason for the denial and then resubmit your profile.

How do I choose the roles for my application?

When you create your Selling Partner API application on the application client creation page, you can choose roles from among those that were requested and approved in your developer profile. If the role you need is missing, you must update the roles in your developer profile to include it, and then resubmit your profile for evaluation by Amazon. Once approved, the added role will be available to select for your application.

Note: If you have a published hybrid SP-API application you must relist your application before reauthorization.

How do I determine what roles to request?

Review the role descriptions in this document to understand the purpose of each role, and to see examples of the resources and operations governed by each role. For each role, use the link provided to navigate to documentation that provides a complete list of the operations and the feed, report, and notification types that require the role.

What happens when I call an operation for which I do not have the required role(s)?

The response to the request will have an HTTP status code of 403 and error information in the response body.


Did this page help you?