Onboarding to the SP-API

This guide walks you through the steps to build applications for a selling partner by using the Selling Partner API (SP-API). The SP-API offers a collection of REST-based APIs that you can use to automate selling operations such as order processing, shipment tracking, and payment management.

Requirements

To integrate with the SP-API, you need the following prerequisites:

• Basic understanding of REST APIs
• Some programming experience

Integration steps

SP-API integration involves the following steps:

Example use cases

The SP-API supports different workflows for sellers and vendors. The following diagrams illustrate which APIs you might use at each stage of these workflows.

Key terminology

The following terms help you understand and work with the SP-API.

Selling partner

A business that works with Amazon as either a seller or vendor. Selling partners manage their business through a workflow that includes planning inventory, creating listings, managing prices, receiving orders, and fulfilling sales.

Seller

A business that lists and sells their own goods on Amazon. Sellers fulfill orders directly or use Fulfillment by Amazon (FBA). Sellers can use the SP-API to automate catalog management, pricing updates, order processing, and inventory tracking. They can also access analytics to optimize their business performance.

Vendor

A business that supplies inventory to Amazon. Amazon sells these products directly to customers. Vendors can use the SP-API to manage product listings, analyze brand performance, and integrate retail and direct fulfillment processes.

Application

Software that integrates with the SP-API. Applications fall into two categories:

• Public applications: These applications are available to multiple selling partners through the selling partner's website or through the Selling Partner Appstore. Public applications are widely accessible solutions that address common needs and are designed for multiple selling partners to use. Public applications require Amazon approval for publishing to the Selling Partner Appstore and selling partners must authorize their use. For details, refer to Publish an SP-API application.
• Private applications: These applications are for exclusive use by a single organization. These applications don't require listing in the Selling Partner Appstore. For details, refer to Register your Application.

Developer

A person or organization who builds applications using the SP-API on behalf of a selling partner. Developers fall into two categories:

• Public developers: These developers build applications for multiple selling partners to use. Because the applications that these developers build are public, these developers must list their applications in the Selling Partner Appstore, which requires Amazon's approval. For details, refer to Register as a Public SP-API Developer.
• Private developers: These developers build applications solely for their own organization's use. The custom solutions that these developers build don't require listing in the Selling Partner Appstore. For details, refer to Register as a Private SP-API Developer.

Solution Provider Portal

A single platform for all developers who build solutions with Amazon Services APIs. Examples of Amazon Services APIs include the SP-API, the Amazon Business API, the Shipping API, and the Multi-Channel Fulfillment API. For details, refer to the Solution Provider Portal FAQ.

Authorization

The process by which a selling partner grants an application permission to call the SP-API on the selling partner's behalf. The authorization method is either OAuth 2.0 (for public applications) or self-authorization (for private applications):

• Public applications: Public applications must use OAuth 2.0 to obtain authorization from selling partners to call the SP-API on the selling partner's behalf. This authorization model is based on Login with Amazon (LWA), which is Amazon's implementation of OAuth 2.0. This process generates an LWA refresh token that must be renewed annually. Selling partners can grant permission to an application through the Selling Partner Appstore or through the developer's website.
• Private applications: You can self-authorize your applications directly from the developer console in the Solution Provider Portal. The self-authorization process generates an LWA refresh token. There is a maximum of 10 authorizations per application.

Roles

The mechanism that controls access to specific SP-API operations and resources. Examples of roles include Product Listing (to create and manage product listings), Pricing (to determine list prices and automate product pricing), and so on. To provide granular approach to access control, roles are available at the developer level and the application level.

There are two types of roles:

• Restricted roles: Provide access to personally identifiable information (PII) and require enhanced security
• Non-restricted roles: Handle general marketplace data with standard security requirements

When you create a developer account, you must request and qualify for the specific roles that align with your intended use of the SP-API.

To learn which roles you need for your use case, refer to Roles in the Selling Partner API. To see which roles grant access to specific operations, browse the role mappings documentation.

API access methods

Ways to retrieve and send data through the SP-API. There are individual, batch, and bulk operations:

• Individual operations: Make single API calls for specific requests, such as checking an order status or updating a price.
• Batch operations: Send up to 20 similar requests in one call, useful for tasks like searching multiple products or getting pricing for several items. For details, refer to Batch operations.
• Bulk operations: Handle large amounts of data. There are bulk upload and bulk download operations:
  • Upload data: You can use the Feeds API to send large amounts of data to update listings, prices, or inventory.
  • Download data: You can use the Reports API to download data like inventory levels and order history. For certain use cases, you can use the Data Kiosk API to query data using GraphQL for custom reports.

Rate limits

Restrictions on the number of API requests that you can make in a specific timeframe. If you exceed the rate limit for an operation, your requests to the SP-API are throttled. For details about how to find rate limits and tips to avoid throttling, refer to Usage Plans and Rate Limits and Optimize Rate Limits for Application Workloads.

Notifications

A way to receive real-time updates about events in your selling operations. Instead of repeatedly checking for changes, you can have the Notifications API send you alerts about events like order updates, catalog changes, and pricing modifications. You can receive these notifications through Amazon Simple Queue Service or Amazon EventBridge. For details, refer to the Notifications API Use Case Guide.

Sandbox

A test environment for trying SP-API operations. There are two types of sandbox environments:

• Static sandbox: This sandbox, which provides basic testing capabilities, has the following functionality:
  • Supports all SP-API operations.
  • Uses pattern matching to return static, mocked responses.
  • Provides basic functionality for initial development and testing.
• Dynamic sandbox: This sandbox provides advanced testing, and has the following functionality:
  • Supports only certain operations. For details, refer to SP-API dynamic sandbox.
  • Routes requests to a sandbox backend that can return realistic responses based on the request parameters, to simulate real-world data interactions and business logic.

For details about the sandbox, refer to Selling Partner API Sandbox.