POST
Record a failed delivery
Company space For: Manager, Stock keeper · Permission: order_deliveries.deliver Conditions
  • The order must not be cancelled.
  • The delivery must be ready.
  • outcome_reason is required.
  • collected_amount is accepted only when the delivery is set to collect on delivery.
What else happens
  • Sets delivered_quantity to 0 on every item of the delivery.
  • Sets the status to failed and records the reason, any collected amount, the member and delivered_at.
  • The quantities of a failed delivery are released and can be planned again in another delivery.
Part of Deliver orders.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

order
string
required

Identifier of the order.

delivery
string
required

Identifier of the delivery, which must belong to the order in the path.

Body

application/json
outcome_reason
string
required

Why the delivery failed, up to 1000 characters. Required.

Maximum string length: 1000
collected_amount
number | null

Amount collected despite the failure, in major units, not negative. Refused unless the delivery is set to collect on delivery.

Response

OrderDeliveryResource

id
string
required

Identifier of the delivery (27-character KSUID string).

order_id
string
required

Identifier of the order delivered.

customer_id
string | null
required

Identifier of the order's customer, copied at creation. Null for an order without customer.

customer_address_id
string | null
required

Identifier of the customer address chosen for the delivery. Null when a free-text address or the customer's stored address was used.

address_snapshot
string | null
required

Delivery address as text, frozen at creation or at the last address change; later edits of the customer address do not change it. Set by the server.

status
string
required

draft (being prepared), ready (prepared, to ship), delivered, partially_delivered (reason required) or failed. Only draft can be edited; ready can go back to draft; delivered, partially_delivered and failed are final.

zone_id
string | null
required

Identifier of the delivery zone whose fee was applied. Null when a free fee was given.

fee
number
required

Delivery fee in major units of the company currency, copied from the zone at creation or the amount sent. 0 when none.

collect_on_delivery
boolean
required

True when the driver collects money from the customer at delivery.

amount_to_collect
number | null
required

Amount the driver must collect, in major units. Null when not set or when collect_on_delivery is false.

collected_amount
number | null
required

Amount actually collected, in major units, recorded when the delivery is delivered or failed. Null until then.

driver_label
string | null
required

Free-text name of the driver. Defaults to the trip's default driver label when a trip stop is given.

trip_id
string | null
required

Identifier of the trip the delivery is attached to. Null when not on a trip.

trip_stop_id
string | null
required

Identifier of the stop of the trip for this delivery. Null when not on a trip.

scheduled_for
string<date-time> | null
required

Planned delivery date and time, ISO 8601. Null when not planned.

outcome_reason
string | null
required

Reason given when the delivery is partial or failed. Null otherwise.

received_by
string | null
required

Name of the person who received the goods, as entered when recording the delivery. Null until then.

prepared_by_user_id
string | null
required

Identifier of the member who marked the delivery ready. Cleared when returned to draft.

prepared_at
string<date-time> | null
required

Time the delivery was marked ready, ISO 8601. Cleared when returned to draft.

delivered_by_user_id
string | null
required

Identifier of the member who recorded the delivery outcome (delivered, partially delivered or failed).

delivered_at
string<date-time> | null
required

Time the outcome was recorded, ISO 8601. Set for delivered, partially delivered and failed deliveries.

created_at
string<date-time>
required

Creation time, ISO 8601.

updated_at
string<date-time>
required

Last update time, ISO 8601.

items
OrderDeliveryItemResource · object[]

Order items carried by the delivery, with planned quantity, delivered quantity and undelivered quantity.