DOCSEARCHbyAlgolia
Submit Docs

Amazon Selling Partner API

website·Indexed 35 days ago

https://sp-api.apifox.cn

Developer documentation and OpenAPI definitions for the Selling Partner API (SP-API), including the Feeds v2021-06-30 API, Fulfillment Outbound versions 2020-07-01 and 2026-07-04, grantless operations, and application client secret rotation.

Tokens
6.1K
Snippets
12
Records
35
Agent score
50%

What's inside Selling Partner API

  1. Overview of Fulfillment Outbound Dynamic Sandbox

    The Fulfillment Outbound dynamic sandbox allows developers to test Multi-Channel Fulfillment (MCF) workflows without affecting production data. While production order and package status transitions are driven by physical events (picking, packing, carrier scans), the sandbox provides programmatic control over these transitions using specific simulation operations. This enables end-to-end validation of integration logic for various order and package status scenarios.

  2. Understand the Feed object in the Selling Partner API

    The Feed object provides detailed information about a specific feed. It is used to track the lifecycle and status of a feed submission. Key properties include:

    • feedId: Unique identifier for the feed (unique when combined with a seller ID).
    • feedType: The type of feed submitted.
    • marketplaceIds: A list of marketplace identifiers the feed applies to.
    • createdTime: ISO 8601 timestamp of when the feed was created.
    • processingStatus: The current state of the feed. Possible values are:
      • IN_QUEUE: Waiting to be processed.
      • IN_PROGRESS: Currently being processed.
      • DONE: Processing complete. Check the result document for specific operation errors.
      • CANCELLED: Cancelled before processing started.
      • FATAL: Aborted due to a fatal error; some operations may have succeeded.
    • processingStartTime: ISO 8601 timestamp of when processing began.
    • processingEndTime: ISO 8601 timestamp of when processing finished.
    • resultFeedDocumentId: The identifier for the resulting feed document (unique when combined with a seller ID).

  3. Understand the Feed object schema

    The Feed object provides detailed metadata about a data upload. Key properties include:

    • feedId: Unique identifier for the feed (unique when combined with seller ID).
    • feedType: The type of feed being processed.
    • marketplaceIds: List of marketplaces the feed applies to.
    • createdTime: ISO 8601 timestamp of creation.
    • processingStatus: Current state (e.g., DONE, IN_PROGRESS).
    • processingStartTime / processingEndTime: ISO 8601 timestamps for the processing window.

  4. Register an SQS queue for new client secrets

    Before rotating a secret, you must configure where the new credential will be sent:

    1. Sign in to the Developer Console (via Solution Provider Portal, Seller Central 'Develop Apps', or Vendor Central 'API Integration').
    2. Navigate to Notification Preferences.
    3. On the Subscription page, locate the target application.
    4. In the Application Client New Secret row, enter the ARN or URL of the SQS queue intended to receive the new credential.

  5. Rotate the Selling Partner API application client secret

    To rotate your application's client secret, you must register an SQS queue to receive the new credentials, call the rotateApplicationClientSecret operation, and then retrieve the secret from the queue.

    Prerequisites:

    • Access to the Developer Console.
    • Access to Amazon SQS and a new SQS queue.
    • The application's current client credentials.

    Important Constraints:

    • Credential rotation is only available for regular/production applications; it cannot be used with sandbox applications.
    • The current credential used to call the rotation operation expires after seven days. You must update your credentials within this window to avoid application downtime.

  6. Create a feed using the Selling Partner API

    The createFeed operation is used to create a feed for processing data on behalf of a selling partner. A critical prerequisite is that the contents of the feed document must be uploaded to Amazon before calling this operation.

    Rate Limits:

    • Default Rate: 0.0083 requests per second
    • Burst: 15
    • The x-amzn-RateLimit-Limit response header provides the specific rate limits applied to the request.

    Important Note: The rate limit for the JSON_LISTINGS_FEED feed type is different from the general createFeed operation rate limit. Developers using JSON listings feeds should refer to the Building Listings Management Workflows Guide for specific throughput constraints.

  7. Create and complete a sandbox Fulfillment Outbound order

    Follow these steps to test the end-to-end fulfillment process in the sandbox environment.

    Prerequisites:

    • Authorization from the selling partner.
    • The 'Amazon Fulfillment' role assigned to your developer profile and selected in the App registration page.

    Workflow:

    1. Create Order: Call the createOrder operation.
    2. Verify Initial Status: Call getOrder and verify the status is PROCESSING.
    3. Update Status: Call updateOrderStatus with the status value set to COMPLETE.
    4. Verify Final Status: Call getOrder and verify the status is COMPLETE.
    5. Update Packages: Use updatePackage with the packageId (obtained from getOrder) to advance individual packages independently.

  8. Execute grantless operations in the SP-API

    Grantless operations are SP-API calls that do not require explicit authorization (a refresh token) from a selling partner. These operations are available only to seller applications. To call a grantless operation, request a Login with Amazon (LWA) access token and use the scope parameter to specify the scope of the LWA authorization grant instead of providing a refresh token.

  10. Integrate Fulfillment Outbound and FBA Inventory Sandboxes

    You can combine the FBA Inventory and Fulfillment Outbound dynamic sandboxes to test specific SKUs and observe virtual inventory movements.

    Workflow:

    1. Create inventory items using createInventoryItem in the FBA Inventory sandbox.
    2. Add stock using addInventory.
    3. Create Fulfillment Outbound orders referencing those specific SKUs.

    Behavioral Note: When used together, HOLD orders are initially created in the Received state, and SHIP orders are created in the Planning state (unless INVALID).

  11. Create a feed using the SP-API createFeed operation

    To create a feed in the Selling Partner API, you must provide a CreateFeedSpecification object. This operation requires that you have already called createFeedDocument to obtain an inputFeedDocumentId and uploaded the feed contents to that document before calling createFeed.
    {
  "feedType": "string",
  "marketplaceIds": ["string"],
  "inputFeedDocumentId": "string",
  "feedOptions": {
    "optionKey": "optionValue"
  }
}

  12. Encode URLs for SP-API SKUs

    To avoid errors when including SKUs in URLs, characters that are forbidden, non-ASCII, or have special meanings must be percent-encoded. This is done by converting each byte of the UTF-8 encoding of the character to a two-digit hexadecimal number preceded by a percent sign (%). For example, a backslash (\) is encoded as %5C.
    import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.io.UnsupportedEncodingException;

// Method to encode a SKU using `UTF-8` encoding scheme
private static String encodeSKU(String sSKU) {
  try {
    return URLEncoder.encode(sSKU, StandardCharsets.UTF_8.toString());
  } catch (UnsupportedEncodingException ex) {
    ex.printStackTrace();
  }
}