Shipper API

Upsert appointment requirement for a stop

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.

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

Path parameters

orderNumberstring required

Order number (PRO)

stop'PICKUP' | 'DELIVERY' required

pickup | delivery

Query parameters

confirmChangeAfterAcceptanceboolean

Set to true to override the post-acceptance mutability lock. Required together with the X-Oway-Change-Reason header.

Headers

X-Oway-Change-Reasonstring

Required when confirmChangeAfterAcceptance=true. Surfaces verbatim in the carrier-change notification email.

Request body

channel'PHONE' | 'EMAIL' | 'PORTAL' required

How the appointment is scheduled

portalUrlstring

Portal URL where the carrier will book the appointment. Required when channel == PORTAL, must be omitted otherwise.

instructionsstring

Free-text instructions shown to the carrier. Max 2000 chars.

referenceNumbersstring[]

Reference numbers (PO, customer pickup #, etc.) the carrier will be asked for. Max 10 entries, each max 64 chars.

leadTimeHoursinteger

Minimum advance notice (in hours) the receiver requires. 0–168.

Example request

{
  "channel": "PORTAL",
  "portalUrl": "https://retaillink.example.com/scheduling",
  "contacts": [
    {
      "name": "Maria Lopez",
      "email": "maria@aqua.com",
      "phone": "+15555550101",
      "role": "Warehouse Manager"
    }
  ],
  "instructions": "Driver must check in at gate B. Lift gate required. Schedule via portal at least 24 hours in advance.",
  "referenceNumbers": [
    "81CRR",
    "DOCK-12"
  ],
  "leadTimeHours": 24
}

Response

Appointment requirement upserted; body is the merged effective requirement.

channel'PHONE' | 'EMAIL' | 'PORTAL'

Channel for booking the appointment

portalUrlstring

Portal URL when channel is PORTAL

instructionsstring

Free-text instructions

referenceNumbersstring[]

Reference numbers

leadTimeHoursinteger

Minimum advance notice in hours

appointmentRequiredboolean

Whether the merged effective appointmentRequired is true (OR of place-level and order-level booleans).

Example response

{
  "contacts": [
    {
      "name": "Maria Lopez",
      "email": "maria@aqua.com",
      "phone": "+15555550101",
      "role": "Warehouse Manager"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.