openapi: 3.0.3
info:
  title: EcomSource Product Intelligence API
  description: |
    Comprehensive Amazon Product Data & Real-time Intelligence API. Lookup product details, variations, dimensions, and live pricing using ASIN, UPC, or EAN across 16+ global marketplaces.
    
    ### Authentication
    All requests require your Developer API keys passed as headers:
    - `X-Access-Key`: Your unique access identifier.
    - `X-Secret-Key`: Your private secret key.
    
    ### Regions & Marketplaces
    - **US Region**: US, CA, MX, BR (Default)
    - **EU Region**: UK, DE, FR, IT, ES, NL, SE, PL, and more.
  version: 1.0.0
  contact:
    name: EcomSource Support
    email: support@ecomsource.ai
    url: https://ecomsource.ai

servers:
  - url: https://api.ecomsource.ai/api/v1
    description: Production API Server

components:
  securitySchemes:
    AccessKey:
      type: apiKey
      in: header
      name: X-Access-Key
    SecretKey:
      type: apiKey
      in: header
      name: X-Secret-Key

security:
  - AccessKey: []
    SecretKey: []

paths:
  /search/product:
    post:
      summary: Single Product Lookup
      description: |
        Fetch full product catalog data including titles, descriptions, images, bullet points, weights, dimensions, and categories. 
        Supports ASIN, UPC, and EAN identifiers.
      operationId: getProductData
      tags:
        - Product Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - identifier
                - identifierType
              properties:
                identifier:
                  type: string
                  description: The ASIN, UPC, or EAN to lookup.
                  example: "B0BTJD6LCL"
                identifierType:
                  type: string
                  enum: [asin, upc, ean]
                  description: Type of identifier provided.
                  example: "asin"
                region:
                  type: string
                  enum: [US, EU]
                  description: Amazon region to search in.
                  default: "US"
                  example: "US"
                refresh:
                  type: boolean
                  description: |
                    If true, forces a real-time re-sync from Amazon instead of using cached data. 
                    **Note: Refreshing costs 2 credits.**
                  default: false
                locale:
                  type: string
                  description: Specific marketplace code (e.g. UK, DE, FR). Overrides region priority.
                  example: "UK"
              example:
                identifier: "B0BTJD6LCL"
                identifierType: "asin"
                region: "US"
                refresh: false
      responses:
        '200':
          description: Product data found and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'
        '400':
          description: Invalid identifier or missing required fields.
        '429':
          description: Quota exceeded (Insufficient credits).

  /search/bulk:
    post:
      summary: Bulk Product Lookup
      description: |
        Lookup multiple products in a single request. Provide an array of identifiers to retrieve data for each.
      operationId: bulkProductLookup
      tags:
        - Product Search
      parameters:
        - in: query
          name: marketplace
          schema:
            type: string
            default: "amazon"
        - in: query
          name: locale
          schema:
            type: string
            default: "US"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - identifier
                  - identifierType
                properties:
                  identifier:
                    type: string
                    example: "5706991016970"
                  identifierType:
                    type: string
                    enum: [asin, upc, ean]
                    example: "upc"
              example:
                - identifier: "5706991016970"
                  identifierType: "upc"
                - identifier: "B0BTJD6LCL"
                  identifierType: "asin"
      responses:
        '200':
          description: Array of product results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        identifier:
                          type: string
                        success:
                          type: boolean
                        data:
                          $ref: '#/components/schemas/ProductData'

  /search/offers:
    post:
      summary: Real-time Offers & Buy Box
      description: |
        Fetch live pricing and offer summaries directly from Amazon. Returns Buy Box price, lowest listing prices, and offer counts.
        **Supports ASIN lookups only.**
      operationId: getProductOffers
      tags:
        - Pricing & Offers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - identifier
                - identifierType
              properties:
                identifier:
                  type: string
                  description: Amazon ASIN.
                  example: "B0BTJD6LCL"
                identifierType:
                  type: string
                  enum: [asin]
                  default: "asin"
                region:
                  type: string
                  enum: [US, EU]
                  example: "EU"
                countryCode:
                  type: string
                  description: Specific marketplace code (e.g. UK, DE, FR).
                  example: "UK"
      responses:
        '200':
          description: Live offer data retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffersResponse'

components:
  schemas:
    ProductResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProductData'
        message:
          type: string

    ProductData:
      type: object
      properties:
        asin:
          type: string
        variationType:
          type: string
          enum: [PARENT, CHILD]
        identifiers:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              identifier:
                type: string
        summary:
          type: array
          items:
            type: object
            properties:
              brand:
                type: string
              itemName:
                type: string
              manufacturer:
                type: string
              modelNumber:
                type: string
              htmlDescription:
                type: string
              category:
                type: string
              listPrice:
                type: number
              listPriceCurrency:
                type: string
        attributes:
          type: object
          properties:
            bulletPoint:
              type: array
              items:
                type: object
                properties:
                  value:
                    type: string
        dimensions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              height:
                type: number
              width:
                type: number
              length:
                type: number
              weight:
                type: number
        images:
          type: array
          items:
            type: object
            properties:
              variant:
                type: string
              link:
                type: string
        salesRanks:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              categoryName:
                type: string
              rank:
                type: integer
        affiliateLink:
          type: string

    OffersResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            asin:
              type: string
            marketplaceId:
              type: string
            currency:
              type: string
            totalOffers:
              type: integer
            buyBox:
              type: array
              items:
                type: object
                properties:
                  condition:
                    type: string
                  price:
                    type: number
            lowestPrices:
              type: array
              items:
                type: object
                properties:
                  condition:
                    type: string
                  fulfillmentChannel:
                    type: string
                  price:
                    type: number
            listPrice:
              type: number
            lastUpdated:
              type: string
              format: date-time