Skip to content
API Reference/
/
Update a service

MVMNT API (1.0.0)

The MVMNT API enables you to automate freight brokerage workflows by integrating directly with our Transportation Management System.

Authentication

OAuth 2.0 client credentials flow. See Authentication Guide for details.

Token Endpoint

POST https://api.mvmnt.io/oauth2/token

Request

Headers:

Content-Type: application/x-www-form-urlencoded

Body Parameters:

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Example Request

curl -X POST https://api.mvmnt.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Success Response

Status: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response Fields:

  • access_token: JWT Bearer token to use for API requests
  • token_type: Always Bearer
  • expires_in: Token lifetime in seconds (3600 = 1 hour)
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://docs.mvmnt.io
MVMNT Support
support@mvmnt.io
License
Proprietary
Languages
Servers
Mock server
https://docs.mvmnt.io/_mock/apis/openapi
Production
https://api.mvmnt.io/v1

Carriers

Carrier management operations

Operations

Carrier Contacts

Carrier contact management operations

Operations

Carrier Factors

Carrier factor (factoring company) management operations

Operations

Carrier Payment Methods

Carrier payment method management operations

Operations

Companies

Company management operations

Operations

Credit Memos

AR credit memo management operations. Credit memos represent customer credits that can be applied to invoices.

Operations

Bills

AP bill management operations. Bills represent carrier and vendor invoices to be paid.

Operations

Bill Payments

AP bill payment management operations. Bill payments record payments made to carriers and vendors.

Operations

Customers

Customer management operations

Operations

Customer Contacts

Customer contact management operations

Operations

Documents

Document management operations. Documents are files (PDFs, images) that can be attached to orders, loads, or services.

Operations

Invoices

AR invoice management operations. Invoices represent customer billing for shipment services.

Operations

Loads

Load management operations. Loads represent carrier execution - which carrier is moving the freight.

Operations

Locations

Location management operations

Operations

Location Contacts

Location contact management operations

Operations

Payment Terms

Payment term management operations

Operations

Payments

AR payment management operations. Payments represent received customer payments applied to invoices.

Operations

Quotes

Quote management operations. Quotes are pricing requests/responses that can be converted to shipments.

Operations

Saved Searches

Saved search management operations

Operations

Services

Service (vended service) management operations. Services represent non-carrier vendor work (drayage, customs, warehousing).

Operations

Filter services

Request

Search for services using filter criteria.

Common Filters

  • By shipment: { "filter": { "shipmentId": { "equalTo": "uuid" } } }
  • By vendor: { "filter": { "vendorId": { "equalTo": "uuid" } } }
  • Awaiting invoice: { "filter": { "status": { "equalTo": "AWAITING_INVOICE" } } }
Security
BearerAuth
Bodyapplication/jsonrequired
filterobject(ServiceFilter)
pageSizeinteger[ 1 .. 100 ]
Default 50
cursorstring
curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/services/filter \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "shipmentId": {
        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }'

Responses

Services matching filter criteria

Bodyapplication/json
dataArray of objects(Service)required
data[].​idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
data[].​keystring or null

Human-readable service ID

Example: "SVC-12345"
data[].​shipmentIdstring(uuid)

Parent shipment

data[].​shipmentKeystring or null

Parent shipment friendly ID

data[].​vendorobject(VendorReference)

Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.

data[].​vendorContactobject
data[].​serviceTypestring(ServiceType)

Type of service.

  • DRAYAGE: Port/rail drayage
  • CUSTOMS_CLEARANCE: Customs brokerage
  • WAREHOUSING: Warehouse storage
  • CROSS_DOCK: Cross-dock handling
  • TRANSLOAD: Transloading service
  • FUMIGATION: Cargo fumigation
  • INSPECTION: Cargo inspection
  • DOCUMENTATION: Documentation handling
  • INSURANCE: Cargo insurance
  • CARGO_HANDLING: General cargo handling
  • OTHER: Other service type
Enum"DRAYAGE""CUSTOMS_CLEARANCE""WAREHOUSING""CROSS_DOCK""TRANSLOAD""FUMIGATION""INSPECTION""DOCUMENTATION""INSURANCE""CARGO_HANDLING"
data[].​statusstring(ServiceStatus)required

Current status of the service.

Active states:

  • ACTIVE: Service is active/in progress

Billing states (AP):

  • AWAITING_INVOICE: Waiting for vendor invoice
  • INVOICE_IN_REVIEW: Invoice received, under review
  • APPROVED_TO_PAY: Approved for payment
  • PAID: Paid to vendor

Final states:

  • CANCELED: Service canceled
Enum"ACTIVE""AWAITING_INVOICE""INVOICE_IN_REVIEW""APPROVED_TO_PAY""PAID""CANCELED"
data[].​descriptionstring or null

Service description

data[].​chargesArray of objects(ServiceCharge)

Flattened charges array

data[].​totalCostnumber or null

Sum of all charges

data[].​scheduledDatestring or null(date)
data[].​completedDatestring or null(date)
data[].​referenceNumberstring or null

Vendor reference number

data[].​createdAtstring(date-time)required
data[].​updatedAtstring or null(date-time)
paginationobject(PaginationInfo)required
pagination.​pageSizeintegerrequired

Number of items per page

Example: 50
pagination.​hasNextPagebooleanrequired

Whether there are more pages

Example: true
pagination.​hasPreviousPageboolean

Whether there are previous pages

Example: false
pagination.​endCursorstring or null

Cursor for the next page (null if no next page)

Example: "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "pageSize": 50,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "endCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
  }
}

Create a service

Request

Create a new service for a shipment.

What happens

  • Service is created for the specified shipment
  • Vendor is associated with the service
  • Charges are recorded

Note

Services are typically created as part of shipment creation. Use this endpoint to add additional services to an existing shipment.

Security
BearerAuth
Bodyapplication/jsonrequired
shipmentIdstring(uuid)required

Parent shipment ID

serviceobject(ServiceInput)required
service.​vendorobject(ResourceReferenceInput)required
One of:

Vendor reference

service.​vendor.​idstring(uuid)required

Resource UUID

service.​vendor.​keystring

Client-defined reference ID

service.​vendorContactobject(ResourceReferenceInput)
One of:

Vendor contact

service.​serviceTypestring(ServiceType)required

Type of service.

  • DRAYAGE: Port/rail drayage
  • CUSTOMS_CLEARANCE: Customs brokerage
  • WAREHOUSING: Warehouse storage
  • CROSS_DOCK: Cross-dock handling
  • TRANSLOAD: Transloading service
  • FUMIGATION: Cargo fumigation
  • INSPECTION: Cargo inspection
  • DOCUMENTATION: Documentation handling
  • INSURANCE: Cargo insurance
  • CARGO_HANDLING: General cargo handling
  • OTHER: Other service type
Enum"DRAYAGE""CUSTOMS_CLEARANCE""WAREHOUSING""CROSS_DOCK""TRANSLOAD""FUMIGATION""INSPECTION""DOCUMENTATION""INSURANCE""CARGO_HANDLING"
service.​descriptionstring<= 2000 characters
service.​chargesArray of objects
service.​scheduledDatestring(date)
service.​referenceNumberstring
curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/services \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
    "service": {
      "vendor": {
        "id": "660e8400-e29b-41d4-a716-446655440001"
      },
      "serviceType": "DRAYAGE",
      "description": "Port drayage from Long Beach",
      "charges": [
        {
          "chargeCode": {
            "key": "DRAY"
          },
          "amount": 450
        }
      ],
      "scheduledDate": "2025-01-20"
    }
  }'

Responses

Service created successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
keystring or null

Human-readable service ID

Example: "SVC-12345"
shipmentIdstring(uuid)

Parent shipment

shipmentKeystring or null

Parent shipment friendly ID

vendorobject(VendorReference)

Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.

vendorContactobject
serviceTypestring(ServiceType)

Type of service.

  • DRAYAGE: Port/rail drayage
  • CUSTOMS_CLEARANCE: Customs brokerage
  • WAREHOUSING: Warehouse storage
  • CROSS_DOCK: Cross-dock handling
  • TRANSLOAD: Transloading service
  • FUMIGATION: Cargo fumigation
  • INSPECTION: Cargo inspection
  • DOCUMENTATION: Documentation handling
  • INSURANCE: Cargo insurance
  • CARGO_HANDLING: General cargo handling
  • OTHER: Other service type
Enum"DRAYAGE""CUSTOMS_CLEARANCE""WAREHOUSING""CROSS_DOCK""TRANSLOAD""FUMIGATION""INSPECTION""DOCUMENTATION""INSURANCE""CARGO_HANDLING"
statusstring(ServiceStatus)required

Current status of the service.

Active states:

  • ACTIVE: Service is active/in progress

Billing states (AP):

  • AWAITING_INVOICE: Waiting for vendor invoice
  • INVOICE_IN_REVIEW: Invoice received, under review
  • APPROVED_TO_PAY: Approved for payment
  • PAID: Paid to vendor

Final states:

  • CANCELED: Service canceled
Enum"ACTIVE""AWAITING_INVOICE""INVOICE_IN_REVIEW""APPROVED_TO_PAY""PAID""CANCELED"
descriptionstring or null

Service description

chargesArray of objects(ServiceCharge)

Flattened charges array

totalCostnumber or null

Sum of all charges

scheduledDatestring or null(date)
completedDatestring or null(date)
referenceNumberstring or null

Vendor reference number

createdAtstring(date-time)required
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "SVC-12345",
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "shipmentKey": "string",
  "vendor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-VENDOR-ABC-001",
    "friendlyId": "V123456",
    "name": "ABC Warehouse Services",
    "email": "billing@abcwarehouse.com",
    "phone": "+1-555-123-4567",
    "status": "ACTIVE",
    "currency": "USD",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "vendorContact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "serviceType": "DRAYAGE",
  "status": "ACTIVE",
  "description": "string",
  "charges": [
    { … }
  ],
  "totalCost": 0,
  "scheduledDate": "2019-08-24",
  "completedDate": "2019-08-24",
  "referenceNumber": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get a service

Request

Retrieve a service by ID.

The response includes vendor info and charges.

Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
curl -i -X GET \
  'https://docs.mvmnt.io/_mock/apis/openapi/services/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Service retrieved successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
keystring or null

Human-readable service ID

Example: "SVC-12345"
shipmentIdstring(uuid)

Parent shipment

shipmentKeystring or null

Parent shipment friendly ID

vendorobject(VendorReference)

Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.

vendorContactobject
serviceTypestring(ServiceType)

Type of service.

  • DRAYAGE: Port/rail drayage
  • CUSTOMS_CLEARANCE: Customs brokerage
  • WAREHOUSING: Warehouse storage
  • CROSS_DOCK: Cross-dock handling
  • TRANSLOAD: Transloading service
  • FUMIGATION: Cargo fumigation
  • INSPECTION: Cargo inspection
  • DOCUMENTATION: Documentation handling
  • INSURANCE: Cargo insurance
  • CARGO_HANDLING: General cargo handling
  • OTHER: Other service type
Enum"DRAYAGE""CUSTOMS_CLEARANCE""WAREHOUSING""CROSS_DOCK""TRANSLOAD""FUMIGATION""INSPECTION""DOCUMENTATION""INSURANCE""CARGO_HANDLING"
statusstring(ServiceStatus)required

Current status of the service.

Active states:

  • ACTIVE: Service is active/in progress

Billing states (AP):

  • AWAITING_INVOICE: Waiting for vendor invoice
  • INVOICE_IN_REVIEW: Invoice received, under review
  • APPROVED_TO_PAY: Approved for payment
  • PAID: Paid to vendor

Final states:

  • CANCELED: Service canceled
Enum"ACTIVE""AWAITING_INVOICE""INVOICE_IN_REVIEW""APPROVED_TO_PAY""PAID""CANCELED"
descriptionstring or null

Service description

chargesArray of objects(ServiceCharge)

Flattened charges array

totalCostnumber or null

Sum of all charges

scheduledDatestring or null(date)
completedDatestring or null(date)
referenceNumberstring or null

Vendor reference number

createdAtstring(date-time)required
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "SVC-12345",
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "shipmentKey": "string",
  "vendor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-VENDOR-ABC-001",
    "friendlyId": "V123456",
    "name": "ABC Warehouse Services",
    "email": "billing@abcwarehouse.com",
    "phone": "+1-555-123-4567",
    "status": "ACTIVE",
    "currency": "USD",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "vendorContact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "serviceType": "DRAYAGE",
  "status": "ACTIVE",
  "description": "string",
  "charges": [
    { … }
  ],
  "totalCost": 0,
  "scheduledDate": "2019-08-24",
  "completedDate": "2019-08-24",
  "referenceNumber": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update a service

Request

Update service fields.

Note: Status changes happen automatically based on billing workflow.

Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
Bodyapplication/jsonrequired
vendorContactobject(ResourceReferenceInput)
One of:

Reference to another resource by either ID or client key (used in create/update requests)

serviceTypestring(ServiceType)

Type of service.

  • DRAYAGE: Port/rail drayage
  • CUSTOMS_CLEARANCE: Customs brokerage
  • WAREHOUSING: Warehouse storage
  • CROSS_DOCK: Cross-dock handling
  • TRANSLOAD: Transloading service
  • FUMIGATION: Cargo fumigation
  • INSPECTION: Cargo inspection
  • DOCUMENTATION: Documentation handling
  • INSURANCE: Cargo insurance
  • CARGO_HANDLING: General cargo handling
  • OTHER: Other service type
Enum"DRAYAGE""CUSTOMS_CLEARANCE""WAREHOUSING""CROSS_DOCK""TRANSLOAD""FUMIGATION""INSPECTION""DOCUMENTATION""INSURANCE""CARGO_HANDLING"
descriptionstring or null
scheduledDatestring or null(date)
completedDatestring or null(date)
referenceNumberstring or null
curl -i -X PATCH \
  'https://docs.mvmnt.io/_mock/apis/openapi/services/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scheduledDate": "2025-01-22"
  }'

Responses

Service updated successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
keystring or null

Human-readable service ID

Example: "SVC-12345"
shipmentIdstring(uuid)

Parent shipment

shipmentKeystring or null

Parent shipment friendly ID

vendorobject(VendorReference)

Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.

vendorContactobject
serviceTypestring(ServiceType)

Type of service.

  • DRAYAGE: Port/rail drayage
  • CUSTOMS_CLEARANCE: Customs brokerage
  • WAREHOUSING: Warehouse storage
  • CROSS_DOCK: Cross-dock handling
  • TRANSLOAD: Transloading service
  • FUMIGATION: Cargo fumigation
  • INSPECTION: Cargo inspection
  • DOCUMENTATION: Documentation handling
  • INSURANCE: Cargo insurance
  • CARGO_HANDLING: General cargo handling
  • OTHER: Other service type
Enum"DRAYAGE""CUSTOMS_CLEARANCE""WAREHOUSING""CROSS_DOCK""TRANSLOAD""FUMIGATION""INSPECTION""DOCUMENTATION""INSURANCE""CARGO_HANDLING"
statusstring(ServiceStatus)required

Current status of the service.

Active states:

  • ACTIVE: Service is active/in progress

Billing states (AP):

  • AWAITING_INVOICE: Waiting for vendor invoice
  • INVOICE_IN_REVIEW: Invoice received, under review
  • APPROVED_TO_PAY: Approved for payment
  • PAID: Paid to vendor

Final states:

  • CANCELED: Service canceled
Enum"ACTIVE""AWAITING_INVOICE""INVOICE_IN_REVIEW""APPROVED_TO_PAY""PAID""CANCELED"
descriptionstring or null

Service description

chargesArray of objects(ServiceCharge)

Flattened charges array

totalCostnumber or null

Sum of all charges

scheduledDatestring or null(date)
completedDatestring or null(date)
referenceNumberstring or null

Vendor reference number

createdAtstring(date-time)required
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "SVC-12345",
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "shipmentKey": "string",
  "vendor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-VENDOR-ABC-001",
    "friendlyId": "V123456",
    "name": "ABC Warehouse Services",
    "email": "billing@abcwarehouse.com",
    "phone": "+1-555-123-4567",
    "status": "ACTIVE",
    "currency": "USD",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "vendorContact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "serviceType": "DRAYAGE",
  "status": "ACTIVE",
  "description": "string",
  "charges": [
    { … }
  ],
  "totalCost": 0,
  "scheduledDate": "2019-08-24",
  "completedDate": "2019-08-24",
  "referenceNumber": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a service

Request

Soft delete a service.

Prerequisites

  • Service must not be paid
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
curl -i -X DELETE \
  'https://docs.mvmnt.io/_mock/apis/openapi/services/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Service deleted successfully

Response
No content

Shipments

Shipment tracking and management operations. Shipments contain orders, loads, and services.

Operations

Teams

Team management operations

Operations

Users

User management operations

Operations

Vendors

Vendor management operations

Operations

Vendor Contacts

Vendor contact management operations

Operations

Vendor Payment Methods

Vendor payment method management operations

Operations

Event Notifications

Webhooks