Upsert appointment requirement for a stop

put

https://api.oway.io/v1/shipper/shipment/{orderNumber}/appointment/{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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

orderNumber

string

required

Order number (PRO)

stop

string

enum

required

pickup | delivery

Allowed:

Query Params

confirmChangeAfterAcceptance

boolean

Defaults to false

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

Body Params

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

string

enum

required

How the appointment is scheduled

Allowed:

portalUrl

string

length between 0 and 512

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

contacts

array of objects

length between 0 and 20

Contacts the carrier can use to schedule the appointment

contacts

instructions

string

length between 0 and 2000

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

referenceNumbers

array of strings

length between 0 and 10

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

referenceNumbers

leadTimeHours

int32

0 to 168

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

Headers

X-Oway-Change-Reason

string

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

Responses

200Appointment requirement upserted; body is the merged effective requirement.

400Validation failure. Response body's violations[] lists field paths and reasons.

404Order does not exist or does not belong to your company.

409Order has reached ACCEPTED; appointment data is locked. Contact [email protected] for changes.