> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a purchase order

> Creates a purchase order together with its line items (incomingLineItems). supplierCompanyId and supplierFacilityId are derived from the contact associated with the API key; if the contact has no facility/company a 400 is returned. totalCost is required unless the supplier company's inventory settings mark PO cost as non-mandatory (mandatory by default). Returns the created purchase order.



## OpenAPI

````yaml /openapi/partners.json post /v1/partners/inventory/purchase_orders
openapi: 3.1.0
info:
  title: OpenWrench Internal Teams API
  version: 1.0.0
  description: >-
    External partners API for OpenWrench supplier inventory: purchase requests,
    purchase orders, receipts, parts, equipment types, vendors, stock locations,
    per-stock-location inventory, and work order part/equipment usage.


    ## Authentication

    Every request must include an API key in the `X-API-KEY` header. Requests
    with a missing or invalid key receive `401 Unauthorized`. All data is scoped
    to the supplier company/facility of the contact the API key belongs to.


    ## Rate limiting

    Each API key is limited to 10 requests per 20-second window. Requests beyond
    that receive `429 Too Many Requests`.


    ## Response envelope

    Single-entity responses are wrapped as `{ "type": "<EntityName>", "data": {
    ... }, "status": "ok" }`. List responses are wrapped as `{ "type":
    "<EntityName>", "data": [ ... ], "count": <total>, "status": "ok" }` where
    `count` is the total number of matching records. Count endpoints return `{
    "type": "Count", "data": <integer>, "status": "ok" }`. Errors are returned
    as `{ "message": "...", "type": "<ExceptionType>", "status": "error",
    "traceId": "..." }` with HTTP status 400 (bad input), 401 (missing/invalid
    key), 404 (not found), or 429 (rate limited).


    ## Pagination and filtering

    List endpoints accept `offset`, `limit` (default 10, max 25), `sort_by`, and
    `order` (`asc`|`desc`) query parameters. Any other query parameter is passed
    through as an equality filter on the corresponding entity column.


    ## Date formats

    Date-time fields serialize as strings in one of two shapes depending on the
    underlying type: ISO 8601 with offset (e.g. `2026-08-14T13:05:22.000-07:00`)
    for most timestamps, or `yyyy-MM-dd HH:mm:ss.S` (space-separated, no offset)
    for database timestamp fields. Plain dates are `yyyy-MM-dd`. When sending
    date-times, ISO 8601 is accepted.


    ## API keys

    These endpoints require a **partner API key**, which is separate from buyer
    and supplier API keys. A buyer API key will not authenticate against
    `/v1/partners/` endpoints. Contact support@useopenwrench.com to have a
    partner key issued.


    ## Required headers

    Every request must carry BOTH `X-API-KEY` (your API key) and `OW-KEY` (the
    OpenWrench shared secret issued with it). Requests missing either return
    401.
servers:
  - url: https://api.useopenwrench.com/api/external
security:
  - ApiKeyAuth: []
    OwKeyAuth: []
tags:
  - name: Ping
    description: Health/authentication check
  - name: Purchase Requests
    description: Supplier inventory purchase requests
  - name: Purchase Request Line Items
    description: Line items on purchase requests
  - name: Purchase Orders
    description: Supplier inventory purchase orders
  - name: Purchase Order Line Items
    description: Line items on purchase orders
  - name: Purchase Order Receipts
    description: Receipts recorded against purchase order line items
  - name: Parts
    description: Supplier part catalog
  - name: Equipment Types
    description: Supplier equipment type catalog
  - name: Vendors
    description: Part/equipment vendors
  - name: Stock Locations
    description: Warehouses and mobile stock locations
  - name: Parts Per Stock Location
    description: Part stocking records per stock location
  - name: Equipment Per Stock Location
    description: Individual equipment held per stock location
  - name: Work Order Parts and Equipment
    description: Parts and equipment used on work orders
paths:
  /v1/partners/inventory/purchase_orders:
    post:
      tags:
        - Purchase Orders
      summary: Create a purchase order
      description: >-
        Creates a purchase order together with its line items
        (incomingLineItems). supplierCompanyId and supplierFacilityId are
        derived from the contact associated with the API key; if the contact has
        no facility/company a 400 is returned. totalCost is required unless the
        supplier company's inventory settings mark PO cost as non-mandatory
        (mandatory by default). Returns the created purchase order.
      operationId: createPurchaseOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierPurchaseOrderCreateRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierPurchaseOrderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    SupplierPurchaseOrderCreateRequest:
      type: object
      description: >-
        Purchase order create payload (fields consumed by the server, verified
        from source). supplierCompanyId and supplierFacilityId are always
        derived from the API key's contact and override any values sent. The
        purchase order is created together with its line items
        (incomingLineItems). totalCost is additionally required unless the
        supplier company's inventory settings mark PO cost as non-mandatory (it
        is mandatory by default); a missing mandatory totalCost is rejected with
        400 "Total cost of PO cannot be empty". Unknown fields are ignored.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
          description: >-
            Optional id of an existing purchase order; when supplied, that
            purchase order is loaded and its writable fields are replaced with
            this payload instead of creating a new one
        name:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - new
            - ordered
            - received
            - cancelled
            - closed
            - partially_received
          description: Status of the purchase order, typically "new" on create
        paymentTerms:
          type:
            - string
            - 'null'
        shippingTerms:
          type:
            - string
            - 'null'
        partEquipmentVendorId:
          type: integer
          format: int32
          description: Vendor the order is placed with
        stockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        locationId:
          type:
            - integer
            - 'null'
          format: int64
        brandId:
          type:
            - integer
            - 'null'
          format: int32
        freightTotalBeforeTax:
          type:
            - number
            - 'null'
        miscTotalBeforeTax:
          type:
            - number
            - 'null'
        totalBeforeTax:
          type:
            - number
            - 'null'
        tax:
          type:
            - number
            - 'null'
        totalCost:
          type:
            - number
            - 'null'
          description: >-
            Total cost of the PO. Required unless the supplier company's
            inventory settings mark PO cost as non-mandatory
        currencyId:
          type: string
        internalNotes:
          type:
            - string
            - 'null'
        createdByEmail:
          type: string
          description: Email recorded as the creator of the purchase order
        incomingLineItems:
          type: array
          items:
            $ref: '#/components/schemas/SupplierPurchaseOrderIncomingLineItem'
          description: >-
            Line items to create with the purchase order; omitting it creates a
            PO with no line items
      required:
        - status
        - partEquipmentVendorId
        - currencyId
        - createdByEmail
    SupplierPurchaseOrderResponse:
      type: object
      description: Standard single-entity envelope wrapping a SupplierPurchaseOrder.
      properties:
        type:
          type: string
          description: Entity type name, e.g. "SupplierPurchaseOrder"
        data:
          $ref: '#/components/schemas/SupplierPurchaseOrder'
        status:
          type: string
          enum:
            - ok
      required:
        - type
        - data
        - status
    SupplierPurchaseOrderIncomingLineItem:
      type: object
      description: Incoming (write-side) purchase order line item.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        status:
          type:
            - string
            - 'null'
          enum:
            - new
            - ordered
            - received
            - partially_received
            - cancelled
            - closed
            - null
        isEquipmentLine:
          type: boolean
        viaStockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        partId:
          type:
            - integer
            - 'null'
          format: int64
        partCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        partQuantity:
          type:
            - integer
            - 'null'
          format: int32
        partUomId:
          type: integer
          format: int32
        partCost:
          type:
            - number
            - 'null'
        partCurrencyId:
          type: string
        equipmentTypeId:
          type:
            - integer
            - 'null'
          format: int64
        equipmentCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        equipmentQuantity:
          type:
            - integer
            - 'null'
          format: int32
        equipmentUomId:
          type: integer
          format: int32
        equipmentCost:
          type:
            - number
            - 'null'
        equipmentCurrencyId:
          type: string
        prLineItemIds:
          type:
            - array
            - 'null'
          items:
            type: integer
            format: int64
          description: Purchase request line item ids fulfilled by this PO line
        warrantyAssetId:
          type:
            - integer
            - 'null'
          format: int64
        glCode:
          type:
            - string
            - 'null'
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - isEquipmentLine
        - partUomId
        - partCurrencyId
        - equipmentUomId
        - equipmentCurrencyId
    SupplierPurchaseOrder:
      type: object
      description: A supplier inventory purchase order (PO).
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        purchaseOrderUniqueId:
          type:
            - integer
            - 'null'
          format: int32
          description: Sequential PO number unique within the supplier company
        purchaseOrderUniqueIdWithPrefix:
          type:
            - string
            - 'null'
          description: PO number rendered with the stock location's purchase order prefix
        purchaseOrderCustomIdentifier:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - new
            - ordered
            - received
            - cancelled
            - closed
            - partially_received
        paymentTerms:
          type:
            - string
            - 'null'
        shippingTerms:
          type:
            - string
            - 'null'
        partEquipmentVendorId:
          type: integer
          format: int32
        partEquipmentVendor:
          anyOf:
            - $ref: '#/components/schemas/PartEquipmentVendor'
            - type: 'null'
        stockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        stockLocation:
          anyOf:
            - $ref: '#/components/schemas/StockLocation'
            - type: 'null'
        locationId:
          type:
            - integer
            - 'null'
          format: int64
        location:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated location (abridged).
        brandId:
          type:
            - integer
            - 'null'
          format: int32
        brand:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated brand (abridged).
        freightTotalBeforeTax:
          type:
            - number
            - 'null'
        miscTotalBeforeTax:
          type:
            - number
            - 'null'
        totalBeforeTax:
          type:
            - number
            - 'null'
        tax:
          type:
            - number
            - 'null'
        totalCost:
          type:
            - number
            - 'null'
        actualCost:
          type:
            - number
            - 'null'
        currencyId:
          type: string
        currency:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated currency (abridged).
        partIds:
          type:
            - string
            - 'null'
        equipmentTypeIds:
          type:
            - string
            - 'null'
        purchaseRequestIds:
          type:
            - string
            - 'null'
          description: Comma-separated ids of purchase requests fulfilled by this PO
        notes:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/AbridgedEntity'
        internalNotes:
          type:
            - string
            - 'null'
        supplierFacilityId:
          type: integer
          format: int32
        supplierFacility:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier facility (abridged).
        supplierCompanyId:
          type: integer
          format: int32
        supplierCompany:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier company (abridged).
        createdByEmail:
          type: string
        createdByContact:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated contact (abridged).
        partSupplierPurchaseOrderLineItems:
          type: array
          items:
            $ref: '#/components/schemas/SupplierPurchaseOrderLineItem'
        equipmentSupplierPurchaseOrderLineItems:
          type: array
          items:
            $ref: '#/components/schemas/SupplierPurchaseOrderLineItem'
        deletedPartSupplierPurchaseOrderLineItems:
          type: array
          items:
            $ref: '#/components/schemas/SupplierPurchaseOrderLineItem'
        deletedEquipmentSupplierPurchaseOrderLineItems:
          type: array
          items:
            $ref: '#/components/schemas/SupplierPurchaseOrderLineItem'
        incomingLineItems:
          type: array
          items:
            $ref: '#/components/schemas/SupplierPurchaseOrderIncomingLineItem'
        integratorName:
          type:
            - string
            - 'null'
        integratorStatus:
          type:
            - string
            - 'null'
          enum:
            - in_progress
            - success
            - failure
            - null
        dueDate:
          type:
            - string
            - 'null'
          format: date
          description: ISO 8601 date (yyyy-MM-dd)
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - status
        - partEquipmentVendorId
        - currencyId
        - supplierFacilityId
        - supplierCompanyId
        - createdByEmail
        - partSupplierPurchaseOrderLineItems
        - equipmentSupplierPurchaseOrderLineItems
        - deletedPartSupplierPurchaseOrderLineItems
        - deletedEquipmentSupplierPurchaseOrderLineItems
        - incomingLineItems
        - isDeleted
    Error:
      type: object
      description: Standard error envelope.
      properties:
        message:
          type: string
          description: Human-readable error message
        type:
          type: string
          description: >-
            Exception type, e.g. badRequestException, unauthorizedException,
            notFoundException
        status:
          type: string
          enum:
            - error
        traceId:
          type: string
          description: >-
            Server-generated trace identifier (11 alphanumeric characters) for
            support/debugging
      required:
        - message
        - type
        - status
        - traceId
    PartEquipmentVendor:
      type: object
      description: A vendor that supplies parts and/or equipment.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int32
        name:
          type: string
        vendorId:
          type:
            - string
            - 'null'
          description: External/custom vendor identifier
        address:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Postal address (abridged).
        currencyId:
          type: string
        email:
          type:
            - string
            - 'null'
        logoUrl:
          type:
            - string
            - 'null'
        phoneNumber:
          type:
            - string
            - 'null'
        paymentTerms:
          type:
            - string
            - 'null'
        shippingTerms:
          type:
            - string
            - 'null'
        orderingEmails:
          type:
            - array
            - 'null'
          items:
            type: string
        accountManagerEmails:
          type:
            - array
            - 'null'
          items:
            type: string
        accountManagerContacts:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/VendorContact'
        salesRepEmails:
          type:
            - array
            - 'null'
          items:
            type: string
        salesRepContacts:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/VendorContact'
        accountsPayableEmails:
          type:
            - array
            - 'null'
          items:
            type: string
        accountsPayableContacts:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/VendorContact'
        defaultWarrantyMonths:
          type:
            - integer
            - 'null'
          format: int32
        notes:
          type:
            - string
            - 'null'
        isActive:
          type: boolean
        supplierFacilityId:
          type: integer
          format: int32
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - name
        - currencyId
        - isActive
        - supplierFacilityId
        - isDeleted
    StockLocation:
      type: object
      description: A stock location (warehouse or mobile stock, e.g. a truck).
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        warehouseId:
          type:
            - string
            - 'null'
        name:
          type: string
        images:
          type: array
          items:
            type: string
        description:
          type:
            - string
            - 'null'
        isMobile:
          type: boolean
        address:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Postal address (abridged).
        latitude:
          type:
            - number
            - 'null'
        longitude:
          type:
            - number
            - 'null'
        timeZoneId:
          type:
            - string
            - 'null'
        locationId:
          type:
            - integer
            - 'null'
          format: int64
        location:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated location (abridged).
        supplierFacilityId:
          type: integer
          format: int32
        supplierFacility:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier facility (abridged).
        supplierCompanyId:
          type: integer
          format: int32
        supplierCompany:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier company (abridged).
        burdenRates:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BurdenRateWithYear'
        taxRates:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TaxRateWithYear'
        purchaseOrderPrefix:
          type:
            - string
            - 'null'
        hasAccessFieldTechEmailsString:
          type:
            - string
            - 'null'
        canManageFieldTechEmailsString:
          type:
            - string
            - 'null'
        hasAssociatedEntities:
          type:
            - boolean
            - 'null'
        isActive:
          type: boolean
        glCode:
          type:
            - string
            - 'null'
        allowEquipmentForwarding:
          type: boolean
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - name
        - images
        - isMobile
        - supplierFacilityId
        - supplierCompanyId
        - isActive
        - allowEquipmentForwarding
        - isDeleted
    AbridgedEntity:
      type: object
      additionalProperties: true
      description: >-
        Nested hydrated entity whose full schema is not expanded in this spec
        (the shape is abridged). Present only when the record has the
        association hydrated.
    SupplierPurchaseOrderLineItem:
      type: object
      description: A single part or equipment line on a purchase order.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        status:
          type:
            - string
            - 'null'
          enum:
            - new
            - ordered
            - received
            - partially_received
            - cancelled
            - closed
            - null
        supplierPurchaseOrderId:
          type: integer
          format: int64
        supplierPurchaseOrder:
          anyOf:
            - $ref: '#/components/schemas/SupplierPurchaseOrderLite'
            - type: 'null'
        stockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        locationId:
          type:
            - integer
            - 'null'
          format: int64
        viaStockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        viaStockLocation:
          anyOf:
            - $ref: '#/components/schemas/StockLocation'
            - type: 'null'
        isEquipmentLine:
          type: boolean
        partId:
          type:
            - integer
            - 'null'
          format: int64
        part:
          anyOf:
            - $ref: '#/components/schemas/Part'
            - type: 'null'
        partCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        partCatalog:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated part catalog (abridged).
        partQuantity:
          type:
            - integer
            - 'null'
          format: int32
        partUomId:
          type: integer
          format: int32
        partUom:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated unit of measure (abridged).
        partCost:
          type:
            - number
            - 'null'
        partCurrencyId:
          type: string
        partCurrency:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated currency (abridged).
        partReceivedQuantity:
          type:
            - integer
            - 'null'
          format: int32
        partReceivedAverageCost:
          type:
            - number
            - 'null'
        equipmentTypeId:
          type:
            - integer
            - 'null'
          format: int64
        equipmentType:
          anyOf:
            - $ref: '#/components/schemas/EquipmentType'
            - type: 'null'
        equipmentCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        equipmentCatalog:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated equipment catalog (abridged).
        equipmentQuantity:
          type:
            - integer
            - 'null'
          format: int32
        equipmentUomId:
          type: integer
          format: int32
        equipmentUom:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated unit of measure (abridged).
        equipmentCost:
          type:
            - number
            - 'null'
        equipmentCurrencyId:
          type: string
        equipmentCurrency:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated currency (abridged).
        equipmentReceivedQuantity:
          type:
            - integer
            - 'null'
          format: int32
        equipmentReceivedAverageCost:
          type:
            - number
            - 'null'
        prLineItemIds:
          type:
            - array
            - 'null'
          items:
            type: integer
            format: int64
        warrantyAssetId:
          type:
            - integer
            - 'null'
          format: int64
        warrantyAsset:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated asset (abridged).
        glCode:
          type:
            - string
            - 'null'
        supplierPurchaseRequestLineItems:
          type: array
          items:
            $ref: '#/components/schemas/SupplierPurchaseRequestLineItemLite'
        supplierFacilityId:
          type: integer
          format: int32
        supplierFacility:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier facility (abridged).
        supplierCompanyId:
          type: integer
          format: int32
        supplierCompany:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier company (abridged).
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - supplierPurchaseOrderId
        - isEquipmentLine
        - partUomId
        - partCurrencyId
        - equipmentUomId
        - equipmentCurrencyId
        - supplierPurchaseRequestLineItems
        - supplierFacilityId
        - supplierCompanyId
        - isDeleted
    VendorContact:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
        phoneNumber:
          type:
            - string
            - 'null'
        vendorId:
          type: integer
          format: int32
        supplierFacilityId:
          type: integer
          format: int32
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - email
        - name
        - vendorId
        - supplierFacilityId
    BurdenRateWithYear:
      type: object
      properties:
        year:
          type: integer
          format: int32
        rate:
          type: string
      required:
        - year
        - rate
    TaxRateWithYear:
      type: object
      properties:
        year:
          type: integer
          format: int32
        rate:
          type: string
      required:
        - year
        - rate
    SupplierPurchaseOrderLite:
      type: object
      description: Compact representation of a purchase order, embedded in line items.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        purchaseOrderUniqueId:
          type:
            - integer
            - 'null'
          format: int32
        purchaseOrderUniqueIdWithPrefix:
          type:
            - string
            - 'null'
        purchaseOrderCustomIdentifier:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - new
            - ordered
            - received
            - cancelled
            - closed
            - partially_received
        paymentTerms:
          type:
            - string
            - 'null'
        shippingTerms:
          type:
            - string
            - 'null'
        partEquipmentVendorId:
          type: integer
          format: int32
        stockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        stockLocation:
          anyOf:
            - $ref: '#/components/schemas/StockLocation'
            - type: 'null'
        locationId:
          type:
            - integer
            - 'null'
          format: int64
        location:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated location (abridged).
        brandId:
          type:
            - integer
            - 'null'
          format: int32
        freightTotalBeforeTax:
          type:
            - number
            - 'null'
        miscTotalBeforeTax:
          type:
            - number
            - 'null'
        totalBeforeTax:
          type:
            - number
            - 'null'
        tax:
          type:
            - number
            - 'null'
        totalCost:
          type:
            - number
            - 'null'
        actualCost:
          type:
            - number
            - 'null'
        currencyId:
          type: string
        partIds:
          type:
            - string
            - 'null'
        equipmentTypeIds:
          type:
            - string
            - 'null'
        purchaseRequestIds:
          type:
            - string
            - 'null'
        supplierFacilityId:
          type: integer
          format: int32
        supplierCompanyId:
          type: integer
          format: int32
        createdByEmail:
          type: string
        dueDate:
          type:
            - string
            - 'null'
          format: date
          description: ISO 8601 date (yyyy-MM-dd)
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - status
        - partEquipmentVendorId
        - currencyId
        - supplierFacilityId
        - supplierCompanyId
        - createdByEmail
        - isDeleted
    Part:
      type: object
      description: A part in the supplier's inventory catalog.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        partUUID:
          type:
            - string
            - 'null'
        manufacturerId:
          type:
            - string
            - 'null'
        manufacturerName:
          type:
            - string
            - 'null'
        partNumber:
          type:
            - string
            - 'null'
        aliasPartId:
          type:
            - string
            - 'null'
        name:
          type: string
        images:
          type: array
          items:
            type: string
          description: Image URLs
        description:
          type:
            - string
            - 'null'
        cost:
          type:
            - number
            - 'null'
        uomId:
          type: integer
          format: int32
          description: Unit-of-measure id
        unitOfMeasure:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated unit of measure (abridged).
        defaultVendorId:
          type:
            - integer
            - 'null'
          format: int32
        defaultVendor:
          anyOf:
            - $ref: '#/components/schemas/PartEquipmentVendor'
            - type: 'null'
        defaultPartCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        defaultPartCatalog:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated part catalog (abridged).
        assetTypeId:
          type:
            - integer
            - 'null'
          format: int32
        assetType:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated asset type (abridged).
        assetModelId:
          type:
            - integer
            - 'null'
          format: int32
        assetModel:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated asset model (abridged).
        isActive:
          type: boolean
        glCode:
          type:
            - string
            - 'null'
        partEquipmentVendorCount:
          type: integer
          format: int64
        isStocked:
          type: boolean
        isAssociatedWithOtherEntities:
          type:
            - boolean
            - 'null'
        customFieldDetails:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/AbridgedEntity'
        labelIds:
          type:
            - array
            - 'null'
          items:
            type: integer
            format: int64
        labels:
          type:
            - array
            - 'null'
          items:
            type: string
        partLabels:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/PartLabel'
        supplierCompanyId:
          type: integer
          format: int32
        supplierCompany:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier company (abridged).
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - name
        - images
        - uomId
        - isActive
        - partEquipmentVendorCount
        - isStocked
        - supplierCompanyId
        - isDeleted
    EquipmentType:
      type: object
      description: An equipment type (model) in the supplier's inventory catalog.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        equipmentTypeNumber:
          type:
            - string
            - 'null'
        aliasEquipmentTypeNumber:
          type:
            - string
            - 'null'
        manufacturerId:
          type:
            - string
            - 'null'
        manufacturerName:
          type:
            - string
            - 'null'
        modelName:
          type: string
        images:
          type: array
          items:
            type: string
          description: Image URLs
        description:
          type:
            - string
            - 'null'
        cost:
          type:
            - number
            - 'null'
        defaultVendorId:
          type:
            - integer
            - 'null'
          format: int32
        defaultVendor:
          anyOf:
            - $ref: '#/components/schemas/PartEquipmentVendor'
            - type: 'null'
        defaultEquipmentCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        defaultEquipmentCatalog:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated equipment catalog (abridged).
        assetTypeId:
          type:
            - integer
            - 'null'
          format: int64
        assetType:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated asset type (abridged).
        isActive:
          type: boolean
        glCode:
          type:
            - string
            - 'null'
        partEquipmentVendorCount:
          type: integer
          format: int64
        supplierFacilityId:
          type: integer
          format: int32
        supplierCompanyId:
          type: integer
          format: int32
        isAssociatedWithOtherEntities:
          type:
            - boolean
            - 'null'
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - modelName
        - images
        - isActive
        - partEquipmentVendorCount
        - supplierFacilityId
        - supplierCompanyId
        - isDeleted
    SupplierPurchaseRequestLineItemLite:
      type: object
      description: >-
        Compact purchase request line item, embedded in purchase order line
        items.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        status:
          type: string
          enum:
            - requested
            - denied
            - cancelled
            - approved
            - orderInProgress
            - ordered
            - partially_ordered
            - fulfilled
            - partially_fulfilled
        supplierPurchaseRequestId:
          type: integer
          format: int64
        supplierPurchaseRequest:
          anyOf:
            - $ref: '#/components/schemas/SupplierPurchaseRequestLite'
            - type: 'null'
        stockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        locationId:
          type:
            - integer
            - 'null'
          format: int64
        isEquipmentLine:
          type: boolean
        partId:
          type:
            - integer
            - 'null'
          format: int64
        part:
          anyOf:
            - $ref: '#/components/schemas/Part'
            - type: 'null'
        partCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        partCatalog:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated part catalog (abridged).
        partQuantity:
          type:
            - integer
            - 'null'
          format: int32
        partUomId:
          type: integer
          format: int32
        partUom:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated unit of measure (abridged).
        partUnitCost:
          type:
            - number
            - 'null'
        partCost:
          type:
            - number
            - 'null'
        partCurrencyId:
          type: string
        partCurrency:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated currency (abridged).
        equipmentTypeId:
          type:
            - integer
            - 'null'
          format: int64
        equipmentType:
          anyOf:
            - $ref: '#/components/schemas/EquipmentType'
            - type: 'null'
        equipmentCatalogId:
          type:
            - integer
            - 'null'
          format: int64
        equipmentCatalog:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated equipment catalog (abridged).
        equipmentQuantity:
          type:
            - integer
            - 'null'
          format: int32
        equipmentUomId:
          type: integer
          format: int32
        equipmentUom:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated unit of measure (abridged).
        equipmentUnitCost:
          type:
            - number
            - 'null'
        equipmentCost:
          type:
            - number
            - 'null'
        equipmentCurrencyId:
          type: string
        equipmentCurrency:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated currency (abridged).
        stockLocation:
          anyOf:
            - $ref: '#/components/schemas/StockLocation'
            - type: 'null'
        location:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated location (abridged).
        supplierFacilityId:
          type: integer
          format: int32
        supplierFacility:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier facility (abridged).
        supplierCompanyId:
          type: integer
          format: int32
        supplierCompany:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated supplier company (abridged).
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - status
        - supplierPurchaseRequestId
        - isEquipmentLine
        - partUomId
        - partCurrencyId
        - equipmentUomId
        - equipmentCurrencyId
        - supplierFacilityId
        - supplierCompanyId
        - isDeleted
    PartLabel:
      type: object
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        label:
          type: string
        color:
          type:
            - string
            - 'null'
        associatedPartsCount:
          type: integer
          format: int64
        supplierCompanyId:
          type: integer
          format: int32
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - label
        - associatedPartsCount
        - supplierCompanyId
        - isDeleted
    SupplierPurchaseRequestLite:
      type: object
      description: Compact representation of a purchase request, embedded in line items.
      properties:
        id:
          type:
            - integer
            - 'null'
          format: int64
        purchaseRequestUniqueId:
          type:
            - integer
            - 'null'
          format: int32
        purchaseRequestCustomIdentifier:
          type:
            - string
            - 'null'
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - requested
            - denied
            - cancelled
            - approved
            - orderInProgress
            - ordered
            - partially_ordered
            - fulfilled
            - partially_fulfilled
        stockLocationId:
          type:
            - integer
            - 'null'
          format: int64
        stockLocation:
          anyOf:
            - $ref: '#/components/schemas/StockLocation'
            - type: 'null'
        locationId:
          type:
            - integer
            - 'null'
          format: int64
        location:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated location (abridged).
        totalCost:
          type:
            - number
            - 'null'
        currencyId:
          type: string
        currency:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated currency (abridged).
        workOrderId:
          type:
            - integer
            - 'null'
          format: int64
        asset:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated asset (abridged).
        warrantyAssetId:
          type:
            - integer
            - 'null'
          format: int64
        warrantyAsset:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated asset (abridged).
        partIds:
          type:
            - string
            - 'null'
          description: Comma-separated part ids on the request
        equipmentTypeIds:
          type:
            - string
            - 'null'
          description: Comma-separated equipment type ids on the request
        createdByEmail:
          type: string
        createdByContact:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated contact (abridged).
        approvedOrDeclinedOrCancelledAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        approvedOrDeclinedOrCancelledByEmail:
          type:
            - string
            - 'null'
        approvedOrDeclinedOrCancelledByContact:
          anyOf:
            - $ref: '#/components/schemas/AbridgedEntity'
            - type: 'null'
          description: Hydrated contact (abridged).
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
        isDeleted:
          type: boolean
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date-time
      required:
        - name
        - status
        - currencyId
        - createdByEmail
        - isDeleted
  responses:
    BadRequest:
      description: >-
        Bad request — invalid input, a disallowed state transition, the API
        key's contact is not associated with the required company/facility, or
        the key lacks read/write permission for the entity (permission failures
        are returned as 400 with type "unauthorizedException", not as 403)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid X-API-KEY
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded (10 requests per 20-second window per key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Supplier partner API key. Rate limited to 10 requests per 20-second
        window.
    OwKeyAuth:
      type: apiKey
      in: header
      name: OW-KEY
      description: >-
        OpenWrench shared secret. Required on every request alongside X-API-KEY;
        issued together with your API key.

````