Skip to content
API Reference/
/
Update a stop

MVMNT API (1.1.0)

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

Postman setup guide: API Clients.

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)

Idempotency

Mutating requests (POST, PATCH, DELETE) accept an optional Idempotency-Key header (up to 255 characters). Retrying a request with the same key and the same body returns the original result instead of repeating the operation; reusing a key with a different body fails. Keys are scoped to your organization — keys chosen by other tenants can never collide with yours. Use a stable identifier from your system (for example your own record id plus the action) rather than a random value per attempt.

Download OpenAPI description
openapi.json
openapi.yaml
openapi-3.0.yaml (legacy tooling)
Postman Collection
Postman Environment — Demo
Postman Environment — Production
Overview
URL
https://docs.mvmnt.io
MVMNT Support
support@mvmnt.io
License
Proprietary
Languages
Servers
Production
https://api.mvmnt.io/v1
Demo (non-production)
https://api.demo.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

Reference Data

Read-only catalogs (equipment, charge codes, special requirements) referenced by id from other resources.

Every catalog also answers on its short top-level path, so GET /v1/charge-codes and GET /v1/reference-data/charge-codes are the same endpoint. The documented /reference-data/* form is canonical — it keeps the catalogs grouped here as more are added (port codes, cities, zip codes) — and the short form is a convenience alias.

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

Stops

Stop management operations. A stop is a place an order visits; orders and loads both point at it, so editing one changes the journey for every order and load that visits it.

Operations

Filter stops

Request

Search for stops using filter criteria.

Common Filters

  • By location: { "filter": { "shipperLocationId": { "equalTo": "uuid" } } }
  • By postal code: { "filter": { "postalCode": { "equalTo": "60601" } } }
  • Recently updated: { "filter": { "updatedAt": { "greaterThan": "2025-01-01T00:00:00Z" } } }

To list the stops of one shipment, read the shipment instead: its orders carry them in route order, which a filter cannot express.

Security
BearerAuth
Bodyapplication/jsonrequired
filterobject(StopFilter)
pageSizeinteger[ 1 .. 100 ]
Default 50
cursorstring
curl -i -X POST \
  https://api.mvmnt.io/v1/stops/filter \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "shipperLocationId": {
        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }'

Responses

Stops matching filter criteria

Bodyapplication/json
dataArray of objects(Stop)required
idstring(uuid)required
typestring(StopType)required

Whether freight is collected (PICK) or delivered (DROP) at this stop.

Enum"PICK""DROP"
sequenceintegerrequired

Position in the route, starting at 1.

locationobject(ResourceReference)

Set when the stop was placed by location.

addressobject

Full address from the stop's linked location. Absent for a stop placed by postal code, city or airport code, none of which carry a street address.

postalCodestring or null
cityobject or null
airportCodestring or null
requestedStartDatestring or null(date)
requestedEndDatestring or null(date)
requestedStartTimestring or null
requestedEndTimestring or null
actualArrivalstring or null(date-time)
actualDeparturestring or null(date-time)
dropTrailerboolean

Whether the carrier drops the trailer rather than waiting.

notesstring or null

Instructions shown to the carrier.

createdAtstring(date-time)required
updatedAtstring or null(date-time)
paginationobject(PaginationInfo)required
pageSizeintegerrequired

Number of items per page

Example: 50
hasNextPagebooleanrequired

Whether there are more pages

Example: true
hasPreviousPageboolean

Whether there are previous pages

Example: false
endCursorstring or null

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

Example: "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
errorsArray of objects(FieldError)

Filter fields this endpoint did not apply. Present only when the request used one; the request still succeeds and data is returned without that clause, so treat the rows as unfiltered by these fields.

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

Create a stop

Request

Create a stop on an order.

A stop is placed exactly one way — by location, postalCode, cityId or airportCode. Only a location carries a street address; the other three exist because freight is routinely tendered before an address is known.

What happens

  • The stop is created and attached to the order
  • sequence decides where it falls in the route

Note

Stops are normally created with their shipment. Use this endpoint to add one to an order that already exists.

Security
BearerAuth
Bodyapplication/jsonrequired
orderIdstring(uuid)required

The order this stop belongs to

stopobject(StopInput)required
typestring(StopInputType)required

Whether freight is collected or delivered at this stop. PICKUP and DELIVERY are accepted as aliases and stored as PICK and DROP.

Enum"PICK""DROP""PICKUP""DELIVERY"
sequenceinteger>= 1required

Position in the route, starting at 1. Must fall inside the existing route or immediately after it: a two-stop route accepts 1, 2 or 3. Stops already at or after the position shift up by one to make room. A position past the end is rejected rather than clamped — it would leave the skipped positions empty.

The route is every order sharing the shipment detail, not just the order named here, so a consolidated shipment counts all of its stops.

A route consolidated inside the TMS is numbered from 0 rather than 1. Its first position is therefore not addressable here — 1 is the lowest this contract accepts — and a stop sent at 1 lands immediately after it. Every other position behaves the same on both.

Set only on create: renumbering an existing route is not a patchable column, and sending sequence to PATCH /stops/{id} is rejected.

locationobject(ResourceReferenceInput)
One of:

Reference to an existing location. The only placement carrying a street address. Mutually exclusive with the three below.

postalCodestring<= 32 characters

Place the stop by postal code.

cityIdstring(uuid)

Place the stop in a city from the reference catalog.

airportCodestring<= 8 characters

Place the stop at an airport terminal.

requestedStartDatestring(date)
requestedEndDatestring(date)
requestedStartTimestring^([01]\d|2[0-3]):([0-5]\d)$
requestedEndTimestring^([01]\d|2[0-3]):([0-5]\d)$
dropTrailerboolean
notesstring<= 2000 characters
curl -i -X POST \
  https://api.mvmnt.io/v1/stops \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "stop": {
      "type": "DROP",
      "sequence": 3,
      "location": {
        "id": "660e8400-e29b-41d4-a716-446655440001"
      },
      "requestedStartDate": "2025-01-25"
    }
  }'

Responses

Stop created successfully

Bodyapplication/json
idstring(uuid)required
typestring(StopType)required

Whether freight is collected (PICK) or delivered (DROP) at this stop.

Enum"PICK""DROP"
sequenceintegerrequired

Position in the route, starting at 1.

locationobject(ResourceReference)

Set when the stop was placed by location.

addressobject

Full address from the stop's linked location. Absent for a stop placed by postal code, city or airport code, none of which carry a street address.

postalCodestring or null
cityobject or null
airportCodestring or null
requestedStartDatestring or null(date)
requestedEndDatestring or null(date)
requestedStartTimestring or null
requestedEndTimestring or null
actualArrivalstring or null(date-time)
actualDeparturestring or null(date-time)
dropTrailerboolean

Whether the carrier drops the trailer rather than waiting.

notesstring or null

Instructions shown to the carrier.

createdAtstring(date-time)required
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": "PICK",
  "sequence": 0,
  "location": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345"
  },
  "address": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60601",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "postalCode": "string",
  "city": {
    "name": "string",
    "stateProvince": "string"
  },
  "airportCode": "string",
  "requestedStartDate": "2019-08-24",
  "requestedEndDate": "2019-08-24",
  "requestedStartTime": "string",
  "requestedEndTime": "string",
  "actualArrival": "2019-08-24T14:15:22Z",
  "actualDeparture": "2019-08-24T14:15:22Z",
  "dropTrailer": true,
  "notes": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get a stop

Request

Security
BearerAuth
Path
idstring(uuid)required

Stop ID

curl -i -X GET \
  'https://api.mvmnt.io/v1/stops/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Stop details

Bodyapplication/json
idstring(uuid)required
typestring(StopType)required

Whether freight is collected (PICK) or delivered (DROP) at this stop.

Enum"PICK""DROP"
sequenceintegerrequired

Position in the route, starting at 1.

locationobject(ResourceReference)

Set when the stop was placed by location.

addressobject

Full address from the stop's linked location. Absent for a stop placed by postal code, city or airport code, none of which carry a street address.

postalCodestring or null
cityobject or null
airportCodestring or null
requestedStartDatestring or null(date)
requestedEndDatestring or null(date)
requestedStartTimestring or null
requestedEndTimestring or null
actualArrivalstring or null(date-time)
actualDeparturestring or null(date-time)
dropTrailerboolean

Whether the carrier drops the trailer rather than waiting.

notesstring or null

Instructions shown to the carrier.

createdAtstring(date-time)required
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": "PICK",
  "sequence": 0,
  "location": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345"
  },
  "address": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60601",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "postalCode": "string",
  "city": {
    "name": "string",
    "stateProvince": "string"
  },
  "airportCode": "string",
  "requestedStartDate": "2019-08-24",
  "requestedEndDate": "2019-08-24",
  "requestedStartTime": "string",
  "requestedEndTime": "string",
  "actualArrival": "2019-08-24T14:15:22Z",
  "actualDeparture": "2019-08-24T14:15:22Z",
  "dropTrailer": true,
  "notes": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update a stop

Request

Update a stop. Omitted fields keep their value; an explicit null clears the field.

The change reaches every order and load that visits this stop.

Security
BearerAuth
Path
idstring(uuid)required

Stop ID

Bodyapplication/jsonrequired
locationResourceReferenceInput (ResourceReferenceInput (object)) or null

Re-place the stop at a location. A stop sits in exactly one place, so naming any one of location, postalCode, cityId or airportCode replaces the placement outright and clears the other three — there is no need to null them individually. A patch that clears the only placement without naming a replacement is rejected, because a stop with nowhere to be is a state creation will not produce either.

Any of:

Re-place the stop at a location. A stop sits in exactly one place, so naming any one of location, postalCode, cityId or airportCode replaces the placement outright and clears the other three — there is no need to null them individually. A patch that clears the only placement without naming a replacement is rejected, because a stop with nowhere to be is a state creation will not produce either.

One of:

Re-place the stop at a location. A stop sits in exactly one place, so naming any one of location, postalCode, cityId or airportCode replaces the placement outright and clears the other three — there is no need to null them individually. A patch that clears the only placement without naming a replacement is rejected, because a stop with nowhere to be is a state creation will not produce either.

postalCodestring or null<= 32 characters
cityIdstring or null(uuid)
airportCodestring or null<= 8 characters
requestedStartDatestring or null(date)
requestedEndDatestring or null(date)
requestedStartTimestring or null^([01]\d|2[0-3]):([0-5]\d)$
requestedEndTimestring or null^([01]\d|2[0-3]):([0-5]\d)$
arrivedAtDatestring or null(date)

Records the carrier's arrival.

arrivedAtTimestring or null^([01]\d|2[0-3]):([0-5]\d)$
departedAtDatestring or null(date)
departedAtTimestring or null^([01]\d|2[0-3]):([0-5]\d)$
dropTrailerboolean or null
notesstring or null<= 2000 characters
curl -i -X PATCH \
  'https://api.mvmnt.io/v1/stops/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "requestedStartDate": "2025-01-26",
    "requestedStartTime": "08:00"
  }'

Responses

Stop updated successfully

Bodyapplication/json
idstring(uuid)required
typestring(StopType)required

Whether freight is collected (PICK) or delivered (DROP) at this stop.

Enum"PICK""DROP"
sequenceintegerrequired

Position in the route, starting at 1.

locationobject(ResourceReference)

Set when the stop was placed by location.

addressobject

Full address from the stop's linked location. Absent for a stop placed by postal code, city or airport code, none of which carry a street address.

postalCodestring or null
cityobject or null
airportCodestring or null
requestedStartDatestring or null(date)
requestedEndDatestring or null(date)
requestedStartTimestring or null
requestedEndTimestring or null
actualArrivalstring or null(date-time)
actualDeparturestring or null(date-time)
dropTrailerboolean

Whether the carrier drops the trailer rather than waiting.

notesstring or null

Instructions shown to the carrier.

createdAtstring(date-time)required
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": "PICK",
  "sequence": 0,
  "location": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345"
  },
  "address": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60601",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "postalCode": "string",
  "city": {
    "name": "string",
    "stateProvince": "string"
  },
  "airportCode": "string",
  "requestedStartDate": "2019-08-24",
  "requestedEndDate": "2019-08-24",
  "requestedStartTime": "string",
  "requestedEndTime": "string",
  "actualArrival": "2019-08-24T14:15:22Z",
  "actualDeparture": "2019-08-24T14:15:22Z",
  "dropTrailer": true,
  "notes": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a stop

Request

Remove a stop from its order.

Prerequisites

  • An order keeps at least an origin and a destination, so the last two stops of an order cannot be removed
  • A stop a load already covers cannot be removed; take it off the load first
Security
BearerAuth
Path
idstring(uuid)required

Stop ID

curl -i -X DELETE \
  'https://api.mvmnt.io/v1/stops/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Stop 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