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 this guide.
items:
properties:
:
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:
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
description: The current PRO number of the shipment
newProNumber:
type: string
description: The new PRO number of the shipment
required:
- currentProNumber
- newProNumber
securitySchemes:
api_key:
type: apiKey
in: header
name: apiKey
sec0:
type: apiKey
in: header
name: apiKey
x-refined-from:
- 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