spec.yaml

name: amazon-seller
display_name: Amazon Seller
description: Read FBA inventory, orders, sales reports, listings, and catalog data for an Amazon seller account.
cli_description: "Operate an Amazon seller account from the terminal: inventory, orders, reports, listings, and catalog."
version: "0.1.0"
spec_source: official
category: commerce
website_url: https://developer-docs.amazon.com/sp-api/
base_url: https://sellingpartnerapi-na.amazon.com
http_transport: standard

auth:
  type: oauth2
  oauth2_grant: refresh_token
  token_url: https://api.amazon.com/auth/o2/token
  header: x-amz-access-token
  format: "{token}"
  env_var_specs:
    - name: SP_API_LWA_CLIENT_ID
      kind: auth_flow_input
      required: true
      sensitive: true
      description: LWA client ID from your private SP-API application.
    - name: SP_API_LWA_CLIENT_SECRET
      kind: auth_flow_input
      required: true
      sensitive: true
      description: LWA client secret from your private SP-API application.
    - name: SP_API_REFRESH_TOKEN
      kind: auth_flow_input
      required: true
      sensitive: true
      description: Refresh token from self-authorizing your private SP-API application.
  key_url: https://sellercentral.amazon.com/sellingpartner/developerconsole
  verify_path: /sellers/v1/marketplaceParticipations

config:
  format: toml
  path: ~/.config/amazon-seller-pp-cli/config.toml

mcp:
  transport:
    - stdio
    - http

resources:
  sellers:
    description: Verify seller authorization and list marketplace participations.
    endpoints:
      marketplaces:
        method: GET
        path: /sellers/v1/marketplaceParticipations
        description: List marketplace participations for the authorized seller account.
        response:
          type: array
          item: MarketplaceParticipation
        meta:
          mcp:read-only: "true"

  fba-inventory:
    description: Inspect Fulfillment by Amazon inventory summaries.
    endpoints:
      list:
        method: GET
        path: /fba/inventory/v1/summaries
        description: List FBA inventory summaries. For North America marketplace-level inventory, pass granularityType=Marketplace, granularityId=ATVPDKIKX0DER, and marketplaceIds=ATVPDKIKX0DER.
        params:
          - name: granularityType
            type: string
            required: true
            description: Inventory granularity type, usually Marketplace.
          - name: granularityId
            type: string
            required: true
            description: Marketplace or marketplace group identifier for the requested granularity.
          - name: marketplaceIds
            type: string
            required: true
            description: Comma-separated marketplace IDs.
          - name: details
            type: bool
            description: Include detailed inventory fields.
          - name: startDateTime
            type: string
            description: Return summaries changed after this RFC3339 timestamp.
          - name: sellerSkus
            type: string
            description: Comma-separated seller SKUs.
          - name: sellerSku
            type: string
            description: Single seller SKU.
          - name: nextToken
            type: string
            description: Continuation token from pagination.nextToken.
        response:
          type: array
          item: InventorySummary
        response_path: inventorySummaries
        pagination:
          type: page_token
          cursor_param: nextToken
          next_cursor_path: pagination.nextToken
        meta:
          mcp:read-only: "true"

  orders:
    description: Search and inspect Orders API v2026-01-01 order records.
    endpoints:
      search:
        method: GET
        path: /orders/2026-01-01/orders
        description: Search orders. Provide exactly one of createdAfter or lastUpdatedAfter; Amazon returns 400 for invalid combinations.
        params:
          - name: createdAfter
            type: string
            description: Lower bound for order creation time, RFC3339. Use exactly one of createdAfter or lastUpdatedAfter.
          - name: createdBefore
            type: string
            description: Upper bound for order creation time, RFC3339.
          - name: lastUpdatedAfter
            type: string
            description: Lower bound for last update time, RFC3339. Use exactly one of createdAfter or lastUpdatedAfter.
          - name: lastUpdatedBefore
            type: string
            description: Upper bound for last update time, RFC3339.
          - name: marketplaceIds
            type: string
            description: Comma-separated marketplace IDs.
          - name: fulfillmentStatuses
            type: string
            description: Comma-separated fulfillment statuses.
          - name: fulfilledBy
            type: string
            description: Comma-separated fulfillment channels.
          - name: maxResultsPerPage
            type: int
            description: Maximum orders per page.
          - name: paginationToken
            type: string
            description: Continuation token from pagination.nextToken.
          - name: includedData
            type: string
            description: Comma-separated included data. Prefer non-PII values such as FULFILLMENT, PROCEEDS, EXPENSE, PROMOTION, CANCELLATION, TAX, and PAYMENT.
        response:
          type: array
          item: Order
        response_path: orders
        pagination:
          type: page_token
          cursor_param: paginationToken
          next_cursor_path: pagination.nextToken
        meta:
          mcp:read-only: "true"
      get:
        method: GET
        path: /orders/2026-01-01/orders/{orderId}
        description: Get one Orders API v2026-01-01 order.
        params:
          - name: orderId
            type: string
            required: true
            positional: true
            description: Amazon order ID.
          - name: includedData
            type: string
            description: Comma-separated included data. Avoid BUYER and RECIPIENT in v1 examples.
        response:
          type: object
          item: Order
        meta:
          mcp:read-only: "true"

  reports:
    description: Create reports, poll report status, and inspect report document metadata.
    endpoints:
      create:
        method: POST
        path: /reports/2021-06-30/reports
        description: Create a report request. Prefer --stdin for JSON bodies so marketplaceIds remains a JSON array and reportOptions remains a JSON object.
        body:
          - name: reportType
            type: string
            required: true
            description: Report type, for example GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL or GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL.
          - name: marketplaceIds
            type: array
            required: true
            description: JSON array of marketplace IDs.
          - name: dataStartTime
            type: string
            required: true
            description: Report data start timestamp, RFC3339.
          - name: dataEndTime
            type: string
            required: true
            description: Report data end timestamp, RFC3339.
          - name: reportOptions
            type: object
            description: Optional reportOptions JSON object.
        response:
          type: object
          item: CreateReportResponse
      get:
        method: GET
        path: /reports/2021-06-30/reports/{reportId}
        description: Get one report by report ID. This is the manual polling endpoint for report processing status.
        params:
          - name: reportId
            type: string
            required: true
            positional: true
            description: Report ID returned by reports create.
        response:
          type: object
          item: Report
        meta:
          mcp:read-only: "true"
      list:
        method: GET
        path: /reports/2021-06-30/reports
        description: List reports. If nextToken is set, Amazon requires it to be the only query parameter; pass no other filters with nextToken.
        params:
          - name: reportTypes
            type: string
            description: Comma-separated report types.
          - name: processingStatuses
            type: string
            description: Comma-separated processing statuses.
          - name: marketplaceIds
            type: string
            description: Comma-separated marketplace IDs.
          - name: pageSize
            type: int
            description: Maximum reports per page.
          - name: createdSince
            type: string
            description: Lower bound for report creation time, RFC3339.
          - name: createdUntil
            type: string
            description: Upper bound for report creation time, RFC3339.
          - name: nextToken
            type: string
            description: Continuation token. Must be the only query parameter when set.
        response:
          type: array
          item: Report
        response_path: reports
        meta:
          mcp:read-only: "true"
      document:
        method: GET
        path: /reports/2021-06-30/documents/{reportDocumentId}
        description: Get report document metadata and the presigned download URL. This command does not download or open the document.
        params:
          - name: reportDocumentId
            type: string
            required: true
            positional: true
            description: Report document ID from a completed report.
        response:
          type: object
          item: ReportDocument
        meta:
          mcp:read-only: "true"

  listings:
    description: Read Listings Items API data for seller SKUs.
    endpoints:
      get:
        method: GET
        path: /listings/2021-08-01/items/{sellerId}/{sku}
        description: Get one listing item by seller ID and SKU.
        params:
          - name: sellerId
            type: string
            required: true
            positional: true
            description: Seller ID.
          - name: sku
            type: string
            required: true
            positional: true
            description: Seller SKU.
          - name: marketplaceIds
            type: string
            required: true
            description: Comma-separated marketplace IDs.
          - name: issueLocale
            type: string
            description: Locale for issue text.
          - name: includedData
            type: string
            description: Comma-separated included data.
        response:
          type: object
          item: ListingItem
        meta:
          mcp:read-only: "true"
      search:
        method: GET
        path: /listings/2021-08-01/items/{sellerId}
        description: Search listing items for a seller.
        params:
          - name: sellerId
            type: string
            required: true
            positional: true
            description: Seller ID.
          - name: marketplaceIds
            type: string
            required: true
            description: Comma-separated marketplace IDs.
          - name: includedData
            type: string
            description: Comma-separated included data.
          - name: identifiers
            type: string
            description: Comma-separated identifiers to search.
          - name: identifiersType
            type: string
            description: Identifier type for identifiers.
          - name: createdAfter
            type: string
            description: Created after timestamp, RFC3339.
          - name: createdBefore
            type: string
            description: Created before timestamp, RFC3339.
          - name: lastUpdatedAfter
            type: string
            description: Last updated after timestamp, RFC3339.
          - name: lastUpdatedBefore
            type: string
            description: Last updated before timestamp, RFC3339.
          - name: withIssueSeverity
            type: string
            description: Comma-separated issue severities to include.
          - name: withStatus
            type: string
            description: Comma-separated listing statuses to include.
          - name: withoutStatus
            type: string
            description: Comma-separated listing statuses to exclude.
          - name: sortBy
            type: string
            description: Sort field.
          - name: sortOrder
            type: string
            description: Sort order.
          - name: pageSize
            type: int
            description: Maximum listing items per page.
          - name: pageToken
            type: string
            description: Continuation token.
        response:
          type: array
          item: ListingItem
        response_path: items
        meta:
          mcp:read-only: "true"

  catalog:
    description: Read Catalog Items API item data.
    endpoints:
      get:
        method: GET
        path: /catalog/2022-04-01/items/{asin}
        description: Get one catalog item by ASIN.
        params:
          - name: asin
            type: string
            required: true
            positional: true
            description: ASIN.
          - name: marketplaceIds
            type: string
            required: true
            description: Comma-separated marketplace IDs.
          - name: includedData
            type: string
            description: Comma-separated included data.
          - name: locale
            type: string
            description: Locale for localized fields.
        response:
          type: object
          item: CatalogItem
        meta:
          mcp:read-only: "true"
      search:
        method: GET
        path: /catalog/2022-04-01/items
        description: Search catalog items. Provide marketplaceIds plus one valid search mode such as keywords or identifiers with identifiersType.
        params:
          - name: marketplaceIds
            type: string
            required: true
            description: Comma-separated marketplace IDs.
          - name: sellerId
            type: string
            description: Seller ID.
          - name: keywords
            type: string
            description: Search keywords.
          - name: brandNames
            type: string
            description: Comma-separated brand names.
          - name: classificationIds
            type: string
            description: Comma-separated classification IDs.
          - name: identifiers
            type: string
            description: Comma-separated identifiers.
          - name: identifiersType
            type: string
            description: Identifier type for identifiers.
          - name: pageSize
            type: int
            description: Maximum catalog items per page.
          - name: pageToken
            type: string
            description: Continuation token.
          - name: keywordsLocale
            type: string
            description: Locale for keywords.
          - name: locale
            type: string
            description: Locale for localized fields.
          - name: includedData
            type: string
            description: Comma-separated included data.
        response:
          type: array
          item: CatalogItem
        response_path: items
        meta:
          mcp:read-only: "true"