Amazon Selling Partner API Fba Inventory API

openapi: 3.2.0
info:
  description: The Selling Partner API for FBA Inventory lets you programmatically retrieve information about inventory in Amazon's fulfillment network.
  version: v1
  title: Selling Partner Fba Inventory API
  contact:
    name: Selling Partner API Developer Support
    url: https://sellercentral.amazon.com/gp/mws/contactus.html
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://sellingpartnerapi-na.amazon.com
tags:
- name: fbaInventory
paths:
  /fba/inventory/v1/summaries:
    x-amzn-api-sandbox:
      dynamic: {}
    get:
      tags:
      - fbaInventory
      description: 'Returns a list of inventory summaries. The summaries returned depend on the presence or absence of the startDateTime, sellerSkus and sellerSku parameters:


        - All inventory summaries with available details are returned when the startDateTime, sellerSkus and sellerSku parameters are omitted.

        - When startDateTime is provided, the operation returns inventory summaries that have had changes after the date and time specified. The sellerSkus and sellerSku parameters are ignored. Important: To avoid errors, use both startDateTime and nextToken to get the next page of inventory summaries that have changed after the date and time specified.

        - When the sellerSkus parameter is provided, the operation returns inventory summaries for only the specified sellerSkus. The sellerSku parameter is ignored.

        - When the sellerSku parameter is provided, the operation returns inventory summaries for only the specified sellerSku.


        Note: The parameters associated with this operation may contain special characters that must be encoded to successfully call the API. To avoid errors with SKUs when encoding URLs, refer to [URL Encoding](https://developer-docs.amazon.com/sp-api/docs/url-encoding).


        Usage Plan:


        | Rate (requests per second) | Burst |

        | ---- | ---- |

        | 2 | 2 |


        The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see [Usage Plans and Rate Limits in the Selling Partner API](https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits).'
      operationId: getInventorySummaries
      parameters:
      - name: details
        in: query
        description: true to return inventory summaries with additional summarized inventory details and quantities. Otherwise, returns inventory summaries only (default value).
        required: false
        schema:
          type: boolean
          default: false
      - name: granularityType
        in: query
        description: The granularity type for the inventory aggregation level.
        required: true
        x-docgen-enum-table-extension:
        - value: Marketplace
          description: Marketplace
        schema:
          type: string
          enum:
          - Marketplace
      - name: granularityId
        in: query
        description: The granularity ID for the inventory aggregation level.
        required: true
        schema:
          type: string
      - name: startDateTime
        in: query
        description: 'A start date and time in ISO8601 format. If specified, all inventory summaries that have changed since then are returned. You must specify a date and time that is no earlier than 18 months prior to the date and time when you call the API. Note: Changes in inboundWorkingQuantity, inboundShippedQuantity and inboundReceivingQuantity are not detected.'
        required: false
        schema:
          type: string
          format: date-time
      - name: sellerSkus
        in: query
        description: A list of seller SKUs for which to return inventory summaries. You may specify up to 50 SKUs.
        required: false
        schema:
          type: array
          items:
            type: string
          maxItems: 50
      - name: sellerSku
        in: query
        description: A single seller SKU used for querying the specified seller SKU inventory summaries.
        required: false
        schema:
          type: string
      - name: nextToken
        in: query
        description: String token returned in the response of your previous request. The string token will expire 30 seconds after being created.
        required: false
        schema:
          type: string
      - name: marketplaceIds
        in: query
        description: The marketplace ID for the marketplace for which to return inventory summaries.
        required: true
        schema:
          type: array
          items:
            type: string
          maxItems: 1
      responses:
        '200':
          description: OK
          headers:
            x-amzn-RateLimit-Limit:
              description: Your rate limit (requests per second) for this operation.
              schema:
                type: string
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInventorySummariesResponse'
        '400':
          description: Request has missing or invalid parameters and cannot be parsed.
          headers:
            x-amzn-RateLimit-Limit:
              description: Your rate limit (requests per second) for this operation.
              schema:
                type: string
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInventorySummariesResponse'
        '403':
          description: Indicates access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, Invalid Signature or Resource Not Found.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInventorySummariesResponse'
        '404':
          description: The specified resource does not exist.
          headers:
            x-amzn-RateLimit-Limit:
              description: Your rate limit (requests per second) for this operation.
              schema:
                type: string
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInventorySummariesResponse'
        '429':
          description: The frequency of requests was greater than allowed.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInventorySummariesResponse'
        '500':
          description: An unexpected condition occurred that prevented the server from fulfilling the request.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInventorySummariesResponse'
        '503':
          description: Temporary overloading or maintenance of the server.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInventorySummariesResponse'
  /fba/inventory/v1/items:
    x-amzn-api-sandbox:
      dynamic: {}
    x-amzn-api-sandbox-only: true
    post:
      tags:
      - fbaInventory
      description: Requests that Amazon create product-details in the Sandbox Inventory in the sandbox environment. This is a sandbox-only operation and must be directed to a sandbox endpoint. Refer to [Selling Partner API sandbox](https://developer-docs.amazon.com/sp-api/docs/the-selling-partner-api-sandbox) for more information.
      operationId: createInventoryItem
      responses:
        '200':
          description: OK
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInventoryItemResponse'
        '400':
          description: Request has missing or invalid parameters and cannot be parsed.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInventoryItemResponse'
        '403':
          description: Indicates access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, Invalid Signature or Resource Not Found.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInventoryItemResponse'
        '404':
          description: The specified resource does not exist.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInventoryItemResponse'
        '429':
          description: The frequency of requests was greater than allowed.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInventoryItemResponse'
        '500':
          description: An unexpected condition occurred that prevented the server from fulfilling the request.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInventoryItemResponse'
        '503':
          description: Temporary overloading or maintenance of the server.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInventoryItemResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInventoryItemRequest'
        description: CreateInventoryItem Request Body Parameter.
        required: true
  /fba/inventory/v1/items/{sellerSku}:
    x-amzn-api-sandbox:
      dynamic: {}
    x-amzn-api-sandbox-only: true
    delete:
      tags:
      - fbaInventory
      description: Requests that Amazon Deletes an item from the Sandbox Inventory in the sandbox environment. This is a sandbox-only operation and must be directed to a sandbox endpoint. Refer to [Selling Partner API sandbox](https://developer-docs.amazon.com/sp-api/docs/the-selling-partner-api-sandbox) for more information.
      operationId: deleteInventoryItem
      parameters:
      - name: sellerSku
        in: path
        description: A single seller SKU used for querying the specified seller SKU inventory summaries.
        required: true
        schema:
          type: string
      - name: marketplaceId
        in: query
        description: The marketplace ID for the marketplace for which the sellerSku is to be deleted.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInventoryItemResponse'
        '400':
          description: Request has missing or invalid parameters and cannot be parsed.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInventoryItemResponse'
        '403':
          description: Indicates access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, Invalid Signature or Resource Not Found.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInventoryItemResponse'
        '404':
          description: The specified resource does not exist.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInventoryItemResponse'
        '429':
          description: The frequency of requests was greater than allowed.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInventoryItemResponse'
        '500':
          description: An unexpected condition occurred that prevented the server from fulfilling the request.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInventoryItemResponse'
        '503':
          description: Temporary overloading or maintenance of the server.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInventoryItemResponse'
  /fba/inventory/v1/items/inventory:
    x-amzn-api-sandbox:
      dynamic: {}
    x-amzn-api-sandbox-only: true
    post:
      tags:
      - fbaInventory
      description: Requests that Amazon add items to the Sandbox Inventory with desired amount of quantity in the sandbox environment. This is a sandbox-only operation and must be directed to a sandbox endpoint. Refer to [Selling Partner API sandbox](https://developer-docs.amazon.com/sp-api/docs/the-selling-partner-api-sandbox) for more information.
      operationId: addInventory
      parameters:
      - name: x-amzn-idempotency-token
        in: header
        description: A unique token/requestId provided with each call to ensure idempotency.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInventoryResponse'
        '400':
          description: Request has missing or invalid parameters and cannot be parsed.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInventoryResponse'
        '403':
          description: Indicates access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, Invalid Signature or Resource Not Found.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInventoryResponse'
        '404':
          description: The specified resource does not exist.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInventoryResponse'
        '429':
          description: The frequency of requests was greater than allowed.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInventoryResponse'
        '500':
          description: An unexpected condition occurred that prevented the server from fulfilling the request.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInventoryResponse'
        '503':
          description: Temporary overloading or maintenance of the server.
          headers:
            x-amzn-RequestId:
              description: Unique request reference identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddInventoryResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddInventoryRequest'
        description: List of items to add to Sandbox inventory.
        required: true
components:
  schemas:
    AddInventoryResponse:
      type: object
      properties:
        errors:
          description: One or more unexpected errors occurred during the AddInventory operation.
          $ref: '#/components/schemas/ErrorList'
      description: The response schema for the AddInventory operation.
    GetInventorySummariesResult:
      type: object
      required:
      - granularity
      - inventorySummaries
      properties:
        granularity:
          $ref: '#/components/schemas/Granularity'
        inventorySummaries:
          $ref: '#/components/schemas/InventorySummaries'
      description: The payload schema for the getInventorySummaries operation.
    AddInventoryRequest:
      description: The object with the list of Inventory to be added
      type: object
      properties:
        inventoryItems:
          $ref: '#/components/schemas/InventoryItems'
    Granularity:
      type: object
      properties:
        granularityType:
          type: string
          description: The granularity type for the inventory aggregation level.
          x-docgen-enum-table-extension:
          - value: Marketplace
            description: Marketplace
        granularityId:
          type: string
          description: The granularity ID for the specified granularity type. When granularityType is Marketplace, specify the marketplaceId.
      description: Describes a granularity at which inventory data can be aggregated. For example, if you use Marketplace granularity, the fulfillable quantity will reflect inventory that could be fulfilled in the given marketplace.
    UnfulfillableQuantity:
      type: object
      properties:
        totalUnfulfillableQuantity:
          type: integer
          description: The total number of units in Amazon's fulfillment network in unsellable condition.
        customerDamagedQuantity:
          type: integer
          description: The number of units in customer damaged disposition.
        warehouseDamagedQuantity:
          type: integer
          description: The number of units in warehouse damaged disposition.
        distributorDamagedQuantity:
          type: integer
          description: The number of units in distributor damaged disposition.
        carrierDamagedQuantity:
          type: integer
          description: The number of units in carrier damaged disposition.
        defectiveQuantity:
          type: integer
          description: The number of units in defective disposition.
        expiredQuantity:
          type: integer
          description: The number of units in expired disposition.
      description: The quantity of unfulfillable inventory.
    CreateInventoryItemRequest:
      description: An item to be created in the inventory.
      type: object
      properties:
        sellerSku:
          description: The seller SKU of the item.
          type: string
        marketplaceId:
          description: The marketplaceId.
          type: string
        productName:
          description: The name of the item.
          type: string
      required:
      - sellerSku
      - marketplaceId
      - productName
    DeleteInventoryItemResponse:
      type: object
      properties:
        errors:
          description: One or more unexpected errors occurred during the DeleteInventoryItem operation.
          $ref: '#/components/schemas/ErrorList'
      description: The response schema for the DeleteInventoryItem operation.
    ReservedQuantity:
      type: object
      properties:
        totalReservedQuantity:
          type: integer
          description: The total number of units in Amazon's fulfillment network that are currently being picked, packed, and shipped; or are sidelined for measurement, sampling, or other internal processes.
        pendingCustomerOrderQuantity:
          type: integer
          description: The number of units reserved for customer orders.
        pendingTransshipmentQuantity:
          type: integer
          description: The number of units being transferred from one fulfillment center to another.
        fcProcessingQuantity:
          type: integer
          description: The number of units that have been sidelined at the fulfillment center for additional processing.
      description: The quantity of reserved inventory.
    InventorySummary:
      type: object
      properties:
        asin:
          type: string
          description: The Amazon Standard Identification Number (ASIN) of an item.
        fnSku:
          type: string
          description: Amazon's fulfillment network SKU identifier.
        sellerSku:
          type: string
          description: The seller SKU of the item.
        condition:
          type: string
          description: The condition of the item as described by the seller (for example, New Item).
        inventoryDetails:
          $ref: '#/components/schemas/InventoryDetails'
        lastUpdatedTime:
          type: string
          format: date-time
          description: The date and time that any quantity was last updated.
        productName:
          type: string
          description: The localized language product title of the item within the specific marketplace.
        totalQuantity:
          type: integer
          description: The total number of units in an inbound shipment or in Amazon fulfillment centers.
        stores:
          type: array
          description: A list of seller-enrolled stores that apply to this seller SKU.
          items:
            type: string
      description: Inventory summary for a specific item.
    Error:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: An error code that identifies the type of error that occurred.
        message:
          type: string
          description: A message that describes the error condition in a human-readable form.
        details:
          type: string
          description: Additional information that can help the caller understand or fix the issue.
      description: An error response returned when the request is unsuccessful.
    InventoryItems:
      description: List of Inventory to be added
      type: array
      items:
        $ref: '#/components/schemas/InventoryItem'
    ResearchingQuantityEntry:
      type: object
      required:
      - name
      - quantity
      properties:
        name:
          type: string
          description: The duration of the research.
          enum:
          - researchingQuantityInShortTerm
          - researchingQuantityInMidTerm
          - researchingQuantityInLongTerm
          x-docgen-enum-table-extension:
          - value: researchingQuantityInShortTerm
            description: Short Term for 1-10 days.
          - value: researchingQuantityInMidTerm
            description: Mid Term for 11-20 days.
          - value: researchingQuantityInLongTerm
            description: Long Term for 21 days or longer.
        quantity:
          type: integer
          description: The number of units.
      description: The misplaced or warehouse damaged inventory that is actively being confirmed at our fulfillment centers.
    ErrorList:
      type: array
      description: A list of error responses returned when a request is unsuccessful.
      items:
        $ref: '#/components/schemas/Error'
    InventoryItem:
      description: An item in the list of inventory to be added.
      type: object
      properties:
        sellerSku:
          description: The seller SKU of the item.
          type: string
        marketplaceId:
          description: The marketplaceId.
          type: string
        quantity:
          description: The quantity of item to add.
          type: integer
      required:
      - sellerSku
      - marketplaceId
      - quantity
    InventorySummaries:
      type: array
      description: A list of inventory summaries.
      items:
        $ref: '#/components/schemas/InventorySummary'
    CreateInventoryItemResponse:
      type: object
      properties:
        errors:
          description: One or more unexpected errors occurred during the CreateInventoryItem operation.
          $ref: '#/components/schemas/ErrorList'
      description: The response schema for the CreateInventoryItem operation.
    Pagination:
      type: object
      properties:
        nextToken:
          type: string
          description: A generated string used to retrieve the next page of the result. If nextToken is returned, pass the value of nextToken to the next request. If nextToken is not returned, there are no more items to return.
      description: The process of returning the results to a request in batches of a defined size called pages. This is done to exercise some control over result size and overall throughput. It's a form of traffic management.
    InventoryDetails:
      type: object
      properties:
        fulfillableQuantity:
          type: integer
          description: The item quantity that can be picked, packed, and shipped.
        inboundWorkingQuantity:
          type: integer
          description: The number of units in an inbound shipment for which you have notified Amazon.
        inboundShippedQuantity:
          type: integer
          description: The number of units in an inbound shipment that you have notified Amazon about and have provided a tracking number.
        inboundReceivingQuantity:
          type: integer
          description: The number of units that have not yet been received at an Amazon fulfillment center for processing, but are part of an inbound shipment with some units that have already been received and processed.
        reservedQuantity:
          $ref: '#/components/schemas/ReservedQuantity'
        researchingQuantity:
          $ref: '#/components/schemas/ResearchingQuantity'
        unfulfillableQuantity:
          $ref: '#/components/schemas/UnfulfillableQuantity'
      description: Summarized inventory details. This object will not appear if the details parameter in the request is false.
    ResearchingQuantity:
      type: object
      properties:
        totalResearchingQuantity:
          type: integer
          description: The total number of units currently being researched in Amazon's fulfillment network.
        researchingQuantityBreakdown:
          type: array
          description: A list of quantity details for items currently being researched.
          items:
            $ref: '#/components/schemas/ResearchingQuantityEntry'
      description: The number of misplaced or warehouse damaged units that are actively being confirmed at our fulfillment centers.
    GetInventorySummariesResponse:
      type: object
      properties:
        payload:
          description: The payload for the getInventorySummaries operation.
          $ref: '#/components/schemas/GetInventorySummariesResult'
        pagination:
          $ref: '#/components/schemas/Pagination'
        errors:
          description: One or more unexpected errors occurred during the getInventorySummaries operation.
          $ref: '#/components/schemas/ErrorList'
      description: The Response schema.