Roles in the Selling Partner API

Learn how to use roles in 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 might include personally identifiable information (PII). You will be required to provide additional information about your use of the data and your security controls.

Role	Description
Brand Analytics	Access 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. Refer to Brand Analytics for a complete list of the operations and the feed, report, and notification types that require this role.
Product Listing	Create 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. Refer to Product Listing for a complete list of the operations and the feed, report, and notification types that require this role.
Pricing	Determine 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. Refer to Pricing for a complete list of the operations and the feed, report, and notification types that require this role.
Amazon Fulfillment	Ship 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. Refer to Amazon Fulfillment for a complete list of the operations and the feed, report, and notification types that require this role.
Buyer Communication	Manage 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. Refer to Buyer Communication for a complete list of the operations and the feed, report, and notification types that require this role.
Buyer Solicitation	Solicit 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. Refer to Buyer Solicitation for a complete list of the operations and the feed, report, and notification types that require this role.
Selling Partner Insights	View 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. Refer to Selling Partner Insights for a complete list of the operations and the feed, report, and notification types that require this role.
Finance and Accounting	Produce 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. Refer to Finance and Accounting for a complete list of the operations and the feed, report, and notification types that require this role.
Inventory and Order Tracking	Analyze 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. Refer to Inventory and Order Tracking for a complete list of the operations and the feed, report, and notification types that require this role.
Amazon Warehousing and Distribution	Analyze and manage Amazon Warehousing and Distribution shipments and inventory. Generally used for interacting with AWD inventory information and shipment details using the Selling Partner API for Amazon Warehousing and Distribution. Examples of operations that require this role assignment: The `listInventory` operation of the Selling Partner API for Amazon Warehousing and Distribution, which returns inventory levels and states for products in AWD. The `getInboundShipment` operation, which returns details about the shipment such as status and received quantities for reconciliation. Refer to Amazon Warehousing and Distribution for a complete list of the operations and the feed, report, and notification types that require this role.
Notifications in Seller Central	Send targeted notifications to sellers within Seller Central. Using the App Integrations API v2024-04-01, you can send notifications that inform the seller about their business or to encourage the seller to take action on your website. Examples of operations that require this role assignment: The `createNotification` operation creates and sends a notification to sellers with information relevant to their business. The `deleteNotifications` operation deletes a notification that was previously sent to a seller. For a complete list of the operations that require this role, refer to the Notifications in Seller Central 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. Refer to 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. Refer to 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 might 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. Refer to Tax Remittance (Restricted) for a complete list of the operations and the feed, report, and notification types that require this role.
Professional Services (Restricted)	Provides add-on services such as Room of Choice Delivery, Assembly and Installation to Amazon buyers. Generally used to provide add-on services to Amazon buyers using the Selling Partner API for Services. Examples of operations that require this role assignment: The `getServiceJobs` operation of the Selling Partner API for Services, which returns a list of service job details for the specified filter query. The `addAppointmentForServiceJobByServiceJobId` operation, which adds an appointment to the service job indicated by the service job identifier specified. Refer to Professional Services 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.

After 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. After approval, 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 get 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.

How do I add a new role after my app has been published?

To add a new role after your app has been published, follow these steps:

Go to your developer profile and submit a role to be added.
After your developer profile is approved, go to your application configuration and apply the newly approved role to your application. Save the changes and re-list the application.
After the application is approved, get new authorizations to generate a new refresh token that will grant access to the API operations, reports, feeds and notifications the new role will provide.

Updated 2 months ago