openapi: 3.0.0
"x-mint": {
    "mcp": {
      "enabled": true
    }
  }
info:
  title: Dropship Inventory API
  version: 1.0.0
  description: |
    Endpoints to retrieve and view Dropship retailer inventory and inventory history.
servers:
  - url: https://marketplace-api.fabric.inc
    description: Production server
tags:
  - name: Inventory
    description: Inventory status and history
security:
  - Bearer: []
paths:
  /v1/retailers/{retailer_id}/inventory/:
    get:
      tags:
        - Inventory
      summary: List inventory
      description: Retrieve a list of inventory items for the specified retailer.
      parameters:
        - name: retailer_id
          in: path
          required: true
          description: The unique retailer ID. In the Dropship UI this is called the **Merchant ID**. To find your Merchant ID, click your merchant name in the top nav.
          schema:
            type: integer
            example: 1001
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                required:
                  - count
                  - results
                type: object
                properties:
                  count:
                    description: Total number of records
                    example: 2231
                    type: integer
                  next:
                    description: Next page (applicable in a paginated response)
                    example: https://api.example.org/demo/accounts/?page=2
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    description:
                      Previous page (applicable in a paginated response)
                    example: https://api.example.org/demo/accounts/?page=1
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/InventoryHistory'

  /v1/retailers/{retailer_id}/inventory/{id}/:
    get:
      tags:
        - Inventory
      summary: Get inventory item
      description: Retrieve details of a specific inventory item.
      parameters:
        - name: retailer_id
          in: path
          required: true
          description: The unique retailer ID. In the Dropship UI this is called the **Merchant ID**. To find your Merchant ID, click your merchant name in the top nav.
          schema:
            type: integer
            example: 1001
        - name: id
          in: path
          required: true
          description: The unique inventory item identifier. This ID is automatically generated when new inventory is created.
          schema:
            type: integer
            example: 6006
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItem'

  /v1/retailers/{retailer_id}/inventory/{id}/history/:
    get:
      tags:
        - Inventory
      summary: Get inventory history
      description: Retrieve historical records of an inventory item.
      parameters:
        - name: retailer_id
          in: path
          required: true
          description: The unique retailer ID. In the Dropship UI this is called the **Merchant ID**. To find your Merchant ID, click your merchant name in the top nav.
          schema:
            type: integer
            example: 1001
        - name: id
          in: path
          required: true
          description: The unique inventory item identifier. This ID is automatically generated when new inventory is created.
          schema:
            type: integer
            example: 6006
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItem'

  /v1/brands/{brand_id}/inventory/{id}/:
    get:
        tags:
          - Inventory
        summary: Get an inventory item
        description: Retrieve details of a specific inventory item.
        parameters:
          - name: brand_id
            in: path
            required: true
            schema:
              type: number
            description:
              The unique brand ID. In the Dropship UI this is called the **Supplier ID**. To find your Supplier ID, click your supplier name in the top nav.
            example:
            - 1249
          - name: id
            in: path
            required: true
            description: The unique inventory item identifier. This ID is automatically generated when new inventory is created.
            schema:
              type: integer
              example: 2002
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/InventoryItem'

components:
  schemas:
    InventoryItem:
      type: object
      required:
        - inventory_updated_at
        - inventory_last_submitted_at
        - brand_inventory_updated_at
        - sellable_updated_at
        - estimated_availability_date
      properties:
        connection:
          description: The connection through which the inventory is managed
          example: "conn-12345"
          type: string
          readOnly: true
        variant:
          description: The variant (SKU) of the product
          example: "SKU-001-BLUE"
          type: string
          readOnly: true
        inventory_policy:
          description: Determines how inventory is managed for this variant
          example: "managed"
          type: string
          enum:
            - unmanaged
            - managed
        inventory:
          description: Current available inventory quantity
          example: "150"
          type: string
          readOnly: true
        inventory_updated_at:
          description: Timestamp when the inventory was last updated by the retailer
          example: "2024-04-15T12:00:00Z"
          type: string
          format: date-time
        inventory_last_submitted_at:
          description: Timestamp when inventory was last submitted to the platform
          example: "2024-04-15T12:05:00Z"
          type: string
          format: date-time
        brand_inventory_updated_at:
          description: Timestamp when the brand last updated the inventory
          example: "2024-04-14T08:30:00Z"
          type: string
          format: date-time
        discontinued:
          description: Indicates if the product variant is discontinued
          example: false
          type: boolean
          readOnly: true
        discontinued_updated_at:
          description: Timestamp when the discontinued status was last updated
          example: "2024-03-01T10:00:00Z"
          type: string
          format: date-time
          readOnly: true
        replenishable:
          description: Indicates if the product is regularly replenished
          example: true
          type: boolean
          readOnly: true
        sellable:
          description: Indicates if the product is currently sellable
          example: "yes"
          type: string
          readOnly: true
        sellable_updated_at:
          description: Timestamp when the sellable status was last updated
          example: "2024-04-10T09:15:00Z"
          type: string
          format: date-time
        estimated_availability_date:
          description: Estimated date when the product will be back in stock or available
          example: "2024-05-01"
          type: string
          minLength: 1
        locations:
          description: List of locations where inventory is held, separated by commas.
          example: "Warehouse A, Warehouse B"
          type: string
          readOnly: true
    InventoryHistory:
      type: object
      required:
        - inventory
      properties:
        id:
          description: Unique identifier for the inventory history record
          example: 9876
          type: integer
          readOnly: true
        updated_at:
          description: Timestamp of when this inventory record was updated
          example: "2024-04-18T14:22:00Z"
          type: string
          format: date-time
          readOnly: true
        inventory:
          description: Inventory level associated with the record
          example: 50
          type: integer
          minimum: -2147483648
          maximum: 2147483647
        event:
          description: Type of event that caused the inventory change (e.g., restock, sale)
          example: "restock"
          type: string
          readOnly: true
        location:
          description: Inventory location where the event occurred
          example: "Main Warehouse"
          type: string
          readOnly: true
        user:
          description: User responsible for the inventory update
          example: "admin@example.com"
          type: string
          readOnly: true
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer