---
title: "Upsert appointment requirement for a stop"
method: PUT
path: "/v1/shipper/shipment/{orderNumber}/appointment/{stop}"
tags: ["Shipper API"]
---

# Upsert appointment requirement for a stop

`PUT /v1/shipper/shipment/{orderNumber}/appointment/{stop}`

## Request

- Base URL: `https://api.oway.io`
- URL: `https://api.oway.io/v1/shipper/shipment/{orderNumber}/appointment/{stop}`
- Auth: HTTP bearer and API key in header `x-oway-api-key`

Idempotent upsert of the order-level AppointmentRequirement for one stop (pickup or delivery). The full provided requirement replaces any prior value. Returns the merged effective requirement (place-level default + this order-level override) with a per-field provenance diagnostic.

Mutability: writes are accepted until the order reaches ACCEPTED. Writes against ACCEPTED+ orders return 409 order_accepted_appointment_locked.

## Path parameters

- `orderNumber` string, required
- `stop` 'PICKUP' | 'DELIVERY', required

## Query parameters

- `confirmChangeAfterAcceptance` boolean

## Headers

- `X-Oway-Change-Reason` string

## Request body

- AppointmentRequirementRequest: Structured appointment metadata for a single stop on an order. Sent on PUT /v1/shipper/shipment/{orderNumber}/appointment/{stop} or via the appointments block on POST /v1/shipper/shipment.
  - `channel` 'PHONE' | 'EMAIL' | 'PORTAL', required: How the appointment is scheduled
  - `portalUrl` string: Portal URL where the carrier will book the appointment. Required when channel == PORTAL, must be omitted otherwise.
  - `contacts` AppointmentContact[]: Contacts the carrier can use to schedule the appointment
    - `name` string, required: Contact name
    - `email` string, email: Email address
    - `phone` string: Phone in E.164 format
    - `role` string: Role of the contact at the facility
  - `instructions` string: Free-text instructions shown to the carrier. Max 2000 chars.
  - `referenceNumbers` string[]: Reference numbers (PO, customer pickup #, etc.) the carrier will be asked for. Max 10 entries, each max 64 chars.
  - `leadTimeHours` integer: Minimum advance notice (in hours) the receiver requires. 0–168.

## Response `200`

Appointment requirement upserted; body is the merged effective requirement.

- AppointmentRequirementResponse: The effective (merged) appointment requirement for one stop, with per-field provenance in the _merged diagnostic.
  - `channel` 'PHONE' | 'EMAIL' | 'PORTAL': Channel for booking the appointment
  - `portalUrl` string: Portal URL when channel is PORTAL
  - `contacts` AppointmentContact[]: Contacts the carrier can use
    - `name` string, required: Contact name
    - `email` string, email: Email address
    - `phone` string: Phone in E.164 format
    - `role` string: Role of the contact at the facility
  - `instructions` string: Free-text instructions
  - `referenceNumbers` string[]: Reference numbers
  - `leadTimeHours` integer: Minimum advance notice in hours
  - `appointmentRequired` boolean: Whether the merged effective appointmentRequired is true (OR of place-level and order-level booleans).
  - `_merged` MergedDiagnostic: Per-field provenance for the merged appointment requirement. Tells the caller whether each field came from the place-level default, the order-level override, both, or neither.
    - `fields` object: Map of field name -> source. Field names: channel, portalUrl, contacts, instructions, referenceNumbers, leadTimeHours. Values: PLACE | ORDER | PLACE_AND_ORDER | NONE.

## Other responses

- `400`: Validation failure. Response body's `violations[]` lists field paths and reasons.
- `404`: Order does not exist or does not belong to your company.
- `409`: Order has reached ACCEPTED; appointment data is locked. Contact help@oway.io for changes.

---

[API](https://skmtc.dev/shipoway/apis/oway-shipper-api.md) - [All operations](https://skmtc.dev/shipoway/apis/oway-shipper-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shipoway/apis/oway-shipper-api/revisions/35141ac5fb57?raw)