# Create a stop

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.

Endpoint: POST /stops
Version: 1.1.0
Security: BearerAuth

## Request fields (application/json):

  - `orderId` (string, required)
    The order this stop belongs to

  - `stop` (object, required)

  - `stop.type` (string, 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"

  - `stop.sequence` (integer, required)
    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.

  - `stop.location` (any)

  - `stop.postalCode` (string)
    Place the stop by postal code.

  - `stop.cityId` (string)
    Place the stop in a city from the reference catalog.

  - `stop.airportCode` (string)
    Place the stop at an airport terminal.

  - `stop.requestedStartDate` (string)

  - `stop.requestedEndDate` (string)

  - `stop.requestedStartTime` (string)

  - `stop.requestedEndTime` (string)

  - `stop.dropTrailer` (boolean)

  - `stop.notes` (string)

## Response 201 fields (application/json):

  - `id` (string, required)

  - `type` (string, required)
    Whether freight is collected (PICK) or delivered (DROP) at this stop.
    Enum: "PICK", "DROP"

  - `sequence` (integer, required)
    Position in the route, starting at 1.

  - `location` (object)
    Set when the stop was placed by location.

  - `location.id` (string, required)
    Resource UUID

  - `location.key` (string,null)
    Client-defined reference ID if set

  - `address` (object)
    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.

  - `address.line1` (string, required)
    Primary street address line
    Example: "123 Main St"

  - `address.line2` (string,null)
    Secondary address line (suite, floor, etc.)
    Example: "Suite 400"

  - `address.city` (string, required)
    City name
    Example: "Chicago"

  - `address.state` (string,null)
    State or province code
    Example: "IL"

  - `address.zipCode` (string,null)
    Postal / ZIP code
    Example: "60601"

  - `address.country` (string, required)
    Country name or code
    Example: "USA"

  - `address.market` (string, required)
    Market or region identifier
    Example: "CHI"

  - `address.latitude` (string,null)
    Latitude coordinate
    Example: "41.8781"

  - `address.longitude` (string,null)
    Longitude coordinate
    Example: "-87.6298"

  - `address.isAirportOrAirbase` (boolean, required)
    Whether this location is an airport or airbase

  - `address.isConstructionOrUtilitySite` (boolean, required)
    Whether this location is a construction or utility site

  - `address.isSmartyValidated` (boolean, required)
    Whether address has been validated by SmartyStreets
    Example: true

  - `address.obeysDst` (boolean, required)
    Whether this location observes daylight saving time
    Example: true

  - `address.cityId` (string,null)
    Reference to standardized city record (internal use)

  - `postalCode` (string,null)

  - `city` (object,null)

  - `city.name` (string)

  - `city.stateProvince` (string)

  - `airportCode` (string,null)

  - `requestedStartDate` (string,null)

  - `requestedEndDate` (string,null)

  - `requestedStartTime` (string,null)

  - `requestedEndTime` (string,null)

  - `actualArrival` (string,null)

  - `actualDeparture` (string,null)

  - `dropTrailer` (boolean)
    Whether the carrier drops the trailer rather than waiting.

  - `notes` (string,null)
    Instructions shown to the carrier.

  - `createdAt` (string, required)

  - `updatedAt` (string,null)

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the problem type
    Example: "https://api.mvmnt.io/problems/not-found"

  - `title` (string, required)
    Short summary of the problem type
    Example: "Not Found"

  - `status` (integer, required)
    HTTP status code
    Example: 404

  - `detail` (string)
    Explanation specific to this occurrence
    Example: "Customer not found: 550e8400-e29b-41d4-a716-446655440000"

  - `instance` (string)
    The request path that produced the problem
    Example: "/v1/customers/550e8400-e29b-41d4-a716-446655440000"

  - `code` (string)
    Machine-readable error code, when one applies

  - `errors` (array, required)
    Per-field problems, when the error concerns specific fields

  - `errors.field` (string, required)
    The field the message refers to
    Example: "/required"

  - `errors.message` (string, required)
    What is wrong with it
    Example: "missing property 'status'"