Maven Machines Shipment API

openapi: 3.2.0
info:
  title: Maven Machines Shipment API
  version: '1.0'
  description: 'Operations tagged shipment across 6 of this provider''s published API definitions: maven-machines-aaa-cooper-middleware-openapi.json, maven-machines-averitt-middleware-openapi.json, maven-machines-planning-and-dispatch-openapi.json, maven-machines-reddy-ice-middleware-openapi.json, maven-machines-roy-miller-middleware-openapi.json, maven-machines-shipments-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://integrations.mavenmachines.com
- url: https://integrations.mavenmachines.com/companies/{companyKey}/
  variables:
    companyKey:
      default: companyKey
- url: https://reddy-ice.middleware.mavenmachines.com
  description: Middleware (target env selected by apiKey)
tags:
- name: shipment
paths:
  /shipment:
    post:
      operationId: ShipmentController_handleShipment
      summary: POST /shipment
      description: API to send shipment data
      parameters: []
      responses:
        '200':
          description: A successful API response for shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialsResponseDto'
      tags:
      - shipment
      security:
      - api_key: []
    servers:
    - url: https://integrations.mavenmachines.com
  /shipment/bulkUpsert:
    post:
      summary: POST /shipments/bulkUpsert
      description: ''
      operationId: shipmentbulkupsert
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shipments:
                  type: array
                  description: List of shipments to be created or updated.
                  items:
                    properties:
                      shipmentType:
                        type: string
                        description: Type classification for this shipment record
                        enum:
                        - pickup
                        - delivery
                        - checkstop
                        - lunch
                      proNumber:
                        type: string
                        description: Patch update. TMS-assigned PRO Number. Required if shipmentType is "delivery". Default is null.
                      refNumber:
                        type: string
                        description: Patch update. TMS-assigned shipment reference. Required if shipmentType is "pickup". Default is null.
                      pickupSequenceNumber:
                        type: integer
                        description: For fleets that associate more than one shipment to a pickup request, the pickupSequenceNumber can be used to differentiate shipments. The combination of refNumber and pickupSequenceNumber must be unique.
                        format: int32
                      pickupDate:
                        type: string
                        description: Patch update. Default is null. Requested date for this order (as a pickup) to be handled. See "Duplicated fields" in documentation.
                        format: date
                      deliveryDate:
                        type: string
                        description: Patch update. Default is null. Requested date for this order (as a delivery) to be handled. See "Duplicated fields" in documentation.
                        format: date
                      deliveryServiceStartDate:
                        type: string
                        description: The earliest date the delivery can be made.
                        format: date
                      deliveryServiceDueDate:
                        type: string
                        description: The latest date the delivery can be made. Duplicated deliveryDate.
                        format: date
                      completionCode:
                        type: string
                        description: 4 digit completion code. When filled in, marks the pickup or delivery as completed in Maven.
                      shipperCustomerNumber:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. ID of the shipper (for the pickup) customer. Can be provided in place of manually specifying name, address, etc. See "Duplicated fields" in documentation.'
                      shipperCustomerName:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. Name of the shipper customer associated with the shipment.'
                      shipperCustomerName2:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. Optional additional name of shipper customer associated with the shipment. See "Duplicated fields" in documentation.'
                      shipperCustomerAddress:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. Address of shipper customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      shipperCustomerAddress2:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. Optional address 2 of shipper customer. See "Duplicated fields" in documentation.'
                      shipperCustomerCity:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. City of customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      shipperCustomerState:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. State of customer. 2 char ISO state code. Used for geocoding. See "Duplicated fields" in documentation.'
                      shipperCustomerZip:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. Zip of customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      shipperCustomerCountry:
                        type: string
                        description: 'Patch update: shipper information will not be overridden for delivery, required for pickup. Country of customer. 2 or 3 char ISO country code. Used for geocoding. See "Duplicated fields" in documentation.'
                      shipperContactName:
                        type: string
                        description: Override for pickup, patch for delivery. Default is null. The name of the person to contact at the shipper.
                      shipperContactPhone:
                        type: string
                        description: Override for pickup, patch for delivery. Default is null. The phone number of the person to contact at the shipper.
                      shipperContactEmail:
                        type: string
                        description: Override for pickup, patch for delivery. Default is null. The email of the person to contact at the shipper.
                      customerOrderNumber:
                        type: string
                        description: '[In Development] Order identification number provided by the shipper.'
                        default: '1234'
                      consigneeCustomerNumber:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. ID of the consignee (for the delivery) customer. Can be provided in place of manually specifying name, address, etc. See "Duplicated fields" in documentation.'
                      consigneeCustomerName:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. Name of the consignee customer associated with the shipment.'
                      consigneeCustomerName2:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. Optional additional name of consignee customer associated with the shipment. See "Duplicated fields" in documentation.'
                      consigneeCustomerAddress:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. Address of consignee customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      consigneeCustomerAddress2:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. Optional address 2 of consignee customer. See "Duplicated fields" in documentation.'
                      consigneeCustomerCity:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. City of consignee customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      consigneeCustomerState:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. State of consignee customer. 2 char ISO state code. Used for geocoding. See "Duplicated fields" in documentation.'
                      consigneeCustomerZip:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. Zip of consignee customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      consigneeCustomerCountry:
                        type: string
                        description: 'Patch update: consignee information will not be overridden for pickup, required for delivery. Country of consignee customer. 2 or 3 char ISO country code. Used for geocoding. See "Duplicated fields" in documentation.'
                      consigneeContactName:
                        type: string
                        description: Override for delivery, patch for pickup. Default is null. The name of the person to contact at the consignee.
                      consigneeContactPhone:
                        type: string
                        description: Override for delivery, patch for pickup. Default is null. The phone number of the person to contact at the consignee.
                      consigneeContactEmail:
                        type: string
                        description: Override for delivery, patch for pickup. Default is null. The email of the person to contact at the consignee.
                      originTerminalCode:
                        type: string
                        description: 'Patch update: originTerminal information will not be overridden for delivery, required for pickup. The terminal code of where the shipment originated (picked up). See "Duplicated fields" in documentation.'
                      destinationTerminalCode:
                        type: string
                        description: 'Patch update: destinationTerminal information will not be overridden for pickup, required for delivery. The terminal code destination of the shipment (when the shipment is a delivery). See "Duplicated fields" in documentation.'
                      destinationZipCode:
                        type: string
                        description: Patch update. The zipcode destination of the shipment when the consignee is not yet known.
                      destinationCity:
                        type: string
                        description: The city destination of the shipment. Used if the consignee address is not yet known.
                      destinationState:
                        type: string
                        description: The state destination of the shipment. Used if the consignee address is not yet known.
                      destinationTerminalETA:
                        type: string
                        description: Override update. Default is null. The ETA of when the shipment will arrive at the destination terminal.
                        format: date
                      atDestinationTerminal:
                        type: boolean
                        description: Override update. Default is false. Whether the shipment is currently at the destination terminal or not.
                      instructions:
                        type: string
                        description: Override update. Default is null. Instructions related to order. Will be shown to driver.
                      comments:
                        type: string
                        description: Override update. Default is null. Comments related to order. Will be shown to driver.
                      windowStart:
                        type: string
                        description: Override update. Default is null. 24 hour HH:mm format. Beginning time when the customer is ready for the driver. In the terminal's timezone.
                      windowEnd:
                        type: string
                        description: Override update. Default is null. 24 hour HH:mm format. Ending time when the customer is ready for the driver. In the terminal's timezone.
                      serviceTime:
                        type: integer
                        description: Override update. Default is null. Estimated service time, in seconds, for this shipment at the customer/location.
                        format: int32
                      signatureRequired:
                        type: boolean
                        description: Override update. Default is false. Whether a signature is required during pickup or delivery
                      shipmentTotalWeight:
                        type: number
                        description: Override update. Total weight of the shipment. See "Duplicated fields" in documentation.
                        format: float
                      shipmentTotalPalletEquivalents:
                        type: number
                        description: Override update. Total pallet equivalents of the shipment. See "Duplicated fields" in documentation.
                        format: float
                      shipmentTotalPalletSpaces:
                        type: number
                        description: Override update. Total volume of the shipment, in pallets. See "Duplicated fields" in documentation.
                        format: float
                      shipmentTotalHandlingUnits:
                        type: number
                        description: Override update. Total handling units of the shipment. See "Duplicated fields" in documentation.
                        format: float
                      shipmentTotalPieces:
                        type: integer
                        description: Override update. Total pieces of the shipment. See "Duplicated fields" in documentation.
                        format: int32
                      shipmentItems:
                        type: array
                        description: Array of shipmentItem objects. Override update. See "Duplicated fields" in documentation.
                        items:
                          properties:
                            description:
                              type: string
                              description: Description of line item for shipment
                            sku:
                              type: string
                              description: SKU of line item.
                            weight:
                              type: number
                              description: Weight of line item
                              format: float
                            palletEquivalents:
                              type: number
                              description: Number of pallet equivalents of line item
                              format: float
                            palletSpaces:
                              type: number
                              description: Number of pallet spaces of line item
                              format: float
                            pieces:
                              type: number
                              description: Number of pieces of the line item
                              format: float
                            handlingUnits:
                              type: number
                              description: Number of handling units of line item
                              format: float
                            hazmat:
                              type: boolean
                              description: Whether the line item contains any hazardous materials.
                              default: false
                            quantities:
                              type: array
                              description: Quantity of the line item.
                              items:
                                properties:
                                  unit:
                                    type: string
                                    description: Unit of measurement.
                                  quantity:
                                    type: number
                                    description: Quantity.
                                    default: 1
                                    format: float
                                type: object
                          type: object
                      shipmentAccessorials:
                        type: array
                        description: Array of strings. Override update. Default is an empty array. Accessorials associated with the shipment.
                        default: []
                        items:
                          type: string
                      shipmentTags:
                        type: array
                        description: Array of strings. Override update. Default is an empty array. Tags associated with the shipment.
                        default: []
                        items:
                          type: string
                      callAheadPhone:
                        type: string
                        description: Override update. Default is null. A phone number available for the driver to click to call the customer for pickup/delivery.
                      callAheadMinutes:
                        type: integer
                        description: Override update. Default is null. The number of minutes ahead of the stop that the driver should be instructed to call to confirm pickup/delivery
                        format: int32
                      inboundInterlineCarrierName:
                        type: string
                        description: The name of the partner carrier who is giving you freight to deliver.
                      inboundInterlineProNumber:
                        type: string
                        description: The PRO number given by the partner carrier who is giving you freight to deliver.
                      outboundInterlineCarrierName:
                        type: string
                        description: The name of the partner carrier who you are handing the freight off to for later delivery.
                      outboundInterlineProNumber:
                        type: string
                        description: The PRO number given by the partner carrier who you are handing the freight off to for later delivery.
                      inboundPlanningStatus:
                        type: string
                        description: '["unplanned", "planning"]'
                      requiresCOD:
                        type: boolean
                        description: Requires cash on delivery?
                        default: false
                      requestedDate:
                        type: string
                        description: '[deprecated. Use deliveryDate or pickupDate]. Not patch or override: either required, or a higher priority field takes precedence. Requested date for this order to be handled. See "Duplicated fields" in documentation.'
                        format: date
                      customerNumber:
                        type: string
                        description: '[deprecated. Use consigeeCustomerNumber or shipperCustomerNumber] Not patch or override: either required, or a higher priority field takes precedence. ID of the customer. Can be provided in place of manually specifying name, address, etc. See "Duplicated fields" in documentation.'
                      customerName:
                        type: string
                        description: '[deprecated. Use consigeeCustomerName or shipperCustomerName] Not patch or override: either required, or a higher priority field takes precedence. Name of the customer associated with the shipment. See "Duplicated fields" in documentation.'
                      customerName2:
                        type: string
                        description: '[deprecated. Use consigeeCustomerName2 or shipperCustomerName2] Not patch or override: either required, or a higher priority field takes precedence. Additional name of customer associated with the shipment. See "Duplicated fields" in documentation.'
                      customerAddress:
                        type: string
                        description: '[deprecated. Use consigeeCustomerAddress or shipperCustomerAddress] Not patch or override: either required, or a higher priority field takes precedence. Address of customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      customerAddress2:
                        type: string
                        description: '[deprecated. Use consigeeCustomerAddress2 or shipperCustomerAddress2] Not patch or override: either required, or a higher priority field takes precedence. Address 2 of customer. See "Duplicated fields" in documentation.'
                      customerCity:
                        type: string
                        description: '[deprecated. Use consigeeCustomerCity or shipperCustomerCity] Not patch or override: either required, or a higher priority field takes precedence. City of customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      customerState:
                        type: string
                        description: '[deprecated. Use consigeeCustomerState or shipperCustomerState] Not patch or override: either required, or a higher priority field takes precedence. State of customer. 2-char ISO state code. Used for geocoding. See "Duplicated fields" in documentation.'
                      customerZip:
                        type: string
                        description: '[deprecated. Use consigeeCustomerZip or shipperCustomerZip] Not patch or override: either required, or a higher priority field takes precedence. Zip of customer. Used for geocoding. See "Duplicated fields" in documentation.'
                      customerCountry:
                        type: string
                        description: '[deprecated. Use consigeeCustomerCountry or shipperCustomerCountry] Not patch or override: either required, or a higher priority field takes precedence. Country of customer. 2 or 3 char ISO country code. Used for geocoding. See "Duplicated fields" in documentation.'
                      deliveryPriorityLevel:
                        type: integer
                        description: The priority level of the shipment. 1 to 4, 4 being highest.
                        format: int32
                      currentTerminalCode:
                        type: string
                        description: The string code for the terminal the shipment is currently located at. This takes precedence over atDestinationTerminal.
                      referenceIds:
                        type: array
                        description: Reference IDs of shipment. Used to look up and uniquely identify a shipment. For more details see the section "Reference IDs" in <a href="https://maven-machines.readme.io/docs/commands-and-event-sourcing">this guide</a>.
                        items:
                          properties:
                            <referenceIdName>:
                              type: string
                              description: User definable referenceID key/value pair. When provided the referenceID is used to look up the shipment in Maven. If multiple IDs are provided and associate to more than one shipment, an error will be returned.
                              default: <referenceIdValue>
                          type: object
                    required:
                    - shipmentType
                    type: object
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n  requestStatusUrl: \"https://integrations.mavenmachines.com/requestStatus/bulkShipmentUpsert?requestId=16f269b3-6ce8-49aa-bdca-2a0f5635a9ce\",\n  requestId: \"16f269b3-6ce8-49aa-bdca-2a0f5635a9ce\"\n}"
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: "errors: [{\n  proNumber: \"23902321\",\n  error: \"Delivery date reqired\"\"\n}]"
      deprecated: false
      tags:
      - shipment
      security:
      - sec0: []
    servers:
    - url: https://integrations.mavenmachines.com/companies/{companyKey}/
      variables:
        companyKey:
          default: companyKey
  /shipment/updateShipmentProNumber:
    post:
      operationId: ShipmentController_updateShipmentProNumber
      summary: POST /shipment/updateShipmentProNumber
      description: "\n    Updates a shipment's PRO number.\n    "
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShipmentProNumberDto'
      responses:
        '202':
          description: ''
        '400':
          description: When a request to update a shipment's PRO number fails due to wrong client input
        '500':
          description: Unknown error response.
      tags:
      - shipment
      security:
      - api_key: []
components:
  schemas:
    CredentialsResponseDto:
      type: object
      properties: {}
    ShipmentRequestDto:
      type: object
      properties:
        associatedShipment:
          $ref: '#/components/schemas/AssociatedShipmentDto'
      required:
      - associatedShipment
    ShipmentQuantityDto:
      type: object
      properties:
        quantity:
          oneOf:
          - type: number
          - type: string
          example: 196
        unit:
          type: string
          example: Bags
      required:
      - quantity
      - unit
    PaymentTypeDto:
      type: object
      properties:
        check:
          type: boolean
          example: true
        cash:
          type: boolean
          example: true
        credit:
          type: boolean
          example: true
    PaymentOnDeliveryDto:
      type: object
      properties:
        required:
          type: boolean
          example: false
        accept:
          $ref: '#/components/schemas/PaymentTypeDto'
      required:
      - required
      - accept
    PodRequirementsDto:
      type: object
      properties:
        onDeliveryPo:
          type: boolean
          example: false
        printNameAndSignature:
          type: boolean
          example: true
        storeStampImg:
          type: boolean
          example: false
        customerDocumentImg:
          type: boolean
          example: false
      required:
      - onDeliveryPo
      - printNameAndSignature
      - storeStampImg
      - customerDocumentImg
    AssociatedShipmentDto:
      type: object
      properties:
        consigneeCustomerNumber:
          type: string
          example: '045037666'
          description: FK! - consignee customer number, if used, must be a valid customer number in the environment.
        distributorId:
          type: string
          example: relationship123
        deliveryServiceStartDate:
          type: string
          example: '2025-12-11'
          format: date
        deliveryServiceDueDate:
          type: string
          example: '2025-12-10'
          format: date
        destinationTerminalCode:
          type: string
          description: FK! - Terminal code must be a valid terminal code in the environment.  See directory service terminalCompanyLocationAssociation table.
          example: '206'
        instructions:
          type: string
          example: printNameAndSignature
        proNumber:
          type: string
          example: '808003052_168'
        inboundInterlineProNumber:
          type: string
          example: '2025-10-02'
        shipmentItems:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentItemDto'
        podRequirements:
          $ref: '#/components/schemas/PodRequirementsDto'
        paymentOnDelivery:
          $ref: '#/components/schemas/PaymentOnDeliveryDto'
        customerOrderNumber:
          type: string
          example: '23979620'
        reddyiceGUID:
          type: string
          example: 67d2a718-578a-f011-b4cb-7c1e5280196d
          format: uuid
        purchaseOrderNumber:
          type: string
          example: varchar36
        shipmentTags:
          example:
          - 3P
          type: array
          items:
            type: string
        shipmentType:
          type: string
          example: delivery
        ticketType:
          type: string
          example: '1'
        deliveryPriorityLevel:
          type: number
          example: 4
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
        deliveryDate:
          type: string
          example: '2025-11-20'
          format: date
      required:
      - destinationTerminalCode
      - proNumber
      - shipmentItems
      - podRequirements
      - paymentOnDelivery
      - shipmentType
    ShipmentItemDto:
      type: object
      properties:
        description:
          type: string
          example: 7_LB Bags
        sku:
          type: string
          example: 7_LB
        productCode:
          type: string
          description: FK! - Product code must be the value of an existing Product in the system.  See sales service product_blurb table.
          example: '200771'
        upc:
          type: string
          example: 00860006114916
        required:
          type: boolean
          example: true
        quantities:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentQuantityDto'
        pieces:
          oneOf:
          - type: number
          - type: string
          example: 200
        weight:
          oneOf:
          - type: number
          - type: string
          example: 1444
        palletEquivalents:
          oneOf:
          - type: number
          - type: string
          example: 1.22
        price:
          oneOf:
          - type: number
          - type: string
          example: 1.17
        discount:
          oneOf:
          - type: number
          - type: string
          example: 0.1
        taxRate:
          oneOf:
          - type: number
          - type: string
          example: 0.017
      required:
      - sku
      - productCode
      - upc
      - quantities
      - pieces
      - weight
      - palletEquivalents
      - price
      - discount
      - taxRate
    UpdateShipmentProNumberDto:
      type: object
      properties:
        currentProNumber:
          type: string
        

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maven-machines/refs/heads/main/openapi/maven-machines-shipment-api-openapi.yml