BuyingMesh Quotes API

openapi: 3.2.0
info:
  title: BuyingMesh Procurement Quotes API
  version: 0.5.4
  description: Structured supplier and product API for buying agents. Product discovery exposes reviewed merchant listings with explicit price, lead-time and inventory evidence; the current public catalog contains 86 approved production SKUs from one reviewed supplier and reports confirmed inventory in the current snapshot. Read each SKU inventoryStatus and dataFreshness before quoting. x402 payments and real order creation are disabled until production settlement and fulfillment are ready. All REST responses use the JSON envelope {status, data, error}; MCP remains JSON-RPC. Merchant applications are open now.
servers:
- url: https://buyingmesh.com
tags:
- name: Quotes
paths:
  /v1/quotes:
    post:
      operationId: createQuote
      summary: Create a retrievable quote from SKU, quantity and destination
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '201':
          description: Quote result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiQuoteResponse'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Quotes
  /v1/quotes/compare-suppliers:
    post:
      operationId: compareSupplierOffers
      summary: Compare eligible supplier offers for requested SKUs
      description: Read-only estimate. The shipping object is calculated by the same estimator used by quotes and requires carrier confirmation. Quantities are checked against MOQ and confirmed sellable inventory.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '200':
          description: Supplier offer comparison; each line includes the unit price actually used and whether a price break applied
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Quotes
  /v1/quotes/{quoteId}:
    get:
      operationId: getQuote
      summary: Retrieve a quote snapshot by quote ID
      parameters:
      - name: quoteId
        in: path
        required: true
        schema:
          type: string
          pattern: ^q_
      responses:
        '200':
          description: Quote detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiQuoteResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Quotes
components:
  responses:
    Conflict:
      description: Idempotency or inventory conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ApiQuoteResponse:
      type: object
      required:
      - status
      - data
      - error
      properties:
        status:
          type: string
          const: ok
        data:
          $ref: '#/components/schemas/QuoteResponse'
        error:
          type: 'null'
    QuoteRequest:
      type: object
      required:
      - items
      - destination
      properties:
        environment:
          type: string
          enum:
          - production
          default: production
          description: Only approved merchant listings with supplier-confirmed commercial fields are eligible.
        items:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: object
            required:
            - sku
            - quantity
            properties:
              sku:
                type: string
              quantity:
                type: integer
                minimum: 1
                maximum: 1000000000
                description: Must meet the SKU MOQ and not exceed confirmed sellable inventory
        destination:
          type: object
          required:
          - country
          properties:
            country:
              type: string
              pattern: ^[A-Z]{2}$
              description: ISO 3166-1 alpha-2 country code
            city:
              type: string
            postalCode:
              type: string
    Error:
      type: object
      required:
      - status
      - data
      - error
      properties:
        status:
          type: string
          const: error
        data:
          type: 'null'
        error:
          type: object
          required:
          - code
          - message
          - requestId
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
    QuoteResponse:
      type: object
      properties:
        environment:
          type: string
          enum:
          - production
          default: production
          description: Must match the eligible merchant quote. Live order creation remains disabled until settlement and fulfillment are ready.
        quoteId:
          type: string
        expiresAt:
          type: string
          format: date-time
        options:
          type: array
          items:
            type: object
            properties:
              supplierId:
                type: string
              subtotal:
                type: number
              shipping:
                type: number
                description: Numeric shipping amount in USD for compatibility
              shippingEstimate:
                type: object
                description: Full non-binding shipping estimate and assumptions
              total:
                type: number
              leadTimeDays:
                type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    adminReviewKey:
      type: apiKey
      in: header
      name: X-Admin-Key