> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.goautolane.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.goautolane.com/_mcp/server.

# Update a delivery: cancel it, or edit its pickup or dropoff instructions

PATCH https://api.goautolane.com/dd/v1/deliveries/{external_delivery_id}
Content-Type: application/json

Send `{ "status": "CANCELLED" }` on its own, optionally with `cancellation_reason`, to cancel; an instruction field set to `null` or an empty string next to `status` is ignored. Before the order is loaded the delivery is cancelled. Once it is loaded, a cancel starts a return for stores with returns enabled: the response carries `status: RETURN_IN_PROGRESS`, or `RETURN_ARRIVED` when the vehicle is still at the store, and the delivery then reports `RETURN_IN_PROGRESS`, `RETURN_ARRIVED`, and `RETURNED`. A repeated cancel during or after a return answers 200 with the current status. A cancel that lands after the handoff, or once the trunk has opened at the customer's door, answers 409 with code `DELIVERY_ALREADY_COMPLETED`. For stores with returns enabled, a cancel on a delivery that already failed records the cancel instead of a no-op: the response carries `status: CANCELLED` and the pickup and order both move to `CANCELLED`. Send `pickup_instructions` and/or `dropoff_instructions` to edit them; `null` or an empty string clears a field, an absent field is left unchanged. Instructions can be edited until the delivery reaches `COMPLETED`, `FAILED`, `CANCELLED`, `EXPIRED`, or a return status.

Reference: https://docs.goautolane.com/direct-delivery/api-reference/deliveries/update

## Authentication

- `Authorization` header (bearer token, required) — Autolane Platform API key. Org-scoped with granular permissions. Deliveries endpoints additionally require an `x-retailer-id` header containing the site UUID from the Autolane Portal; webhooks endpoints do not.

## Request

### Path parameters

- `external_delivery_id` (string, required)

### Headers

- `x-retailer-id` (string, required) — Site ID (UUID) from the Autolane Portal identifying the store location

### Body (application/json)

This endpoint expects an object.

- `status` (enum, optional) — Send `CANCELLED` on its own (optionally with `cancellation_reason`) to cancel the delivery. Once the order is loaded, a cancel starts a return for stores with returns enabled and the response carries `status: RETURN_IN_PROGRESS`, or `RETURN_ARRIVED` when the vehicle is still at the store. Once the trunk has opened at the customer's door, the handoff wins instead: 409 `DELIVERY_ALREADY_COMPLETED`. For stores with returns enabled, a cancel on a `FAILED` delivery records the cancel: the response carries `status: CANCELLED`. A cancel never edits instructions: an instruction field sent next to `status` must be `null` or an empty string, and is ignored.
  - Allowed values: `CANCELLED`
- `cancellation_reason` (string, optional, nullable) — Why the delivery is being cancelled: `CUSTOMER_CANCELLED`, `COLD_CHAIN_EXPIRED`, or `OTHER`. Any other value is recorded as `OTHER`. Optional. The reason never decides what happens; the delivery status does. Once the order is loaded, a cancel starts a return for stores with returns enabled (statuses `RETURN_IN_PROGRESS`, `RETURN_ARRIVED`, `RETURNED`), and the reason is echoed as `return_reason`.
- `pickup_instructions` (string, optional, nullable) — Store-side instructions for the driver at pickup, such as a pickup or driver code. Shown to the driver from assignment until the order is loaded. Max 2000 characters. Integrations created before `dropoff_instructions` existed may be in legacy mode, where `pickup_instructions` is treated as the dropoff note and both fields read back the same value; when both are sent, `dropoff_instructions` is used unless it is `null` or empty. Ask Autolane to switch your account to the current behavior.
- `dropoff_instructions` (string, optional, nullable) — Customer-side delivery instructions, such as a gate code or where to leave the order. Shown to the driver on the way to and at the customer. Max 2000 characters. Integrations created before `dropoff_instructions` existed may be in legacy mode, where `pickup_instructions` is treated as the dropoff note and both fields read back the same value; when both are sent, `dropoff_instructions` is used unless it is `null` or empty. Ask Autolane to switch your account to the current behavior.

## Response

### 200

Delivery updated

- `success` (boolean, required)
- `data` (DdV1DeliveriesExternalDeliveryIdPatchResponsesContentApplicationJsonSchemaData, required)

## Errors

### 400 Bad Request Error

Validation error: invalid JSON, empty body, an instruction field with a value other than `null` or an empty string next to `status`, or a field over 2000 characters

- `error` (string, required)
- `code` (enum, required)
  - Allowed values: `VALIDATION_ERROR`
- `details` (list of ValidationErrorResponseDetailsItems, required) — Zod validation error details

### 401 Unauthorized Error

Invalid API key

- `error` (string, required) — Human-readable error message
- `code` (string, optional) — Machine-readable error code
- `details` (any, optional) — Additional error context

### 403 Forbidden Error

Missing permission

- `error` (string, required) — Human-readable error message
- `code` (string, optional) — Machine-readable error code
- `details` (any, optional) — Additional error context

### 404 Not Found Error

Not found

- `error` (string, required) — Human-readable error message
- `code` (string, optional) — Machine-readable error code
- `details` (any, optional) — Additional error context

### 409 Conflict Error

Cancel with returns enabled: code `DELIVERY_ALREADY_COMPLETED` when the delivery is `COMPLETED`, or when the trunk has already opened at the customer's door. Cancel with returns disabled: code `CONFLICT` in both of those cases, and when the delivery is terminal (`CANCELLED`, `FAILED`, `EXPIRED`) or past the pre-load cancellable window. With returns enabled, a repeated cancel on an already-`CANCELLED` or `EXPIRED` delivery answers 200 with the current status instead; a cancel on a `FAILED` delivery instead records the cancel and answers 200 with `CANCELLED`. Returns enabled does not cover every terminal case, though: an order that is independently `CANCELLED` or `EXPIRED` while its pickup is still live (for example an `EXPIRED` order with a still-`SCHEDULED` pickup) answers `CONFLICT` either way. Instructions edit: delivery already terminal, or a return in progress; `RETURN_IN_PROGRESS`, `RETURN_ARRIVED`, and `RETURNED` are not terminal order statuses but block an instructions edit the same way. `details.current_status` carries the current delivery status; on a handoff refusal it is `COMPLETED`, or `ARRIVED_AT_CUSTOMER` when the handoff is the trunk opening at the door

- `error` (string, required) — Human-readable error message
- `code` (string, optional) — Machine-readable error code
- `details` (any, optional) — Additional error context

## Types

### DdV1DeliveriesExternalDeliveryIdPatchResponsesContentApplicationJsonSchemaData

- `external_delivery_id` (string, required)
- `status` (enum, required)
  - Allowed values: `SCHEDULED`, `ASSIGNED`, `EN_ROUTE_TO_STORE`, `ARRIVED_AT_STORE`, `WAITING_FOR_LOAD`, `LOADED`, `EN_ROUTE_TO_CUSTOMER`, `ARRIVED_AT_CUSTOMER`, `COMPLETED`, `FAILED`, `CANCELLED`, `RETURN_IN_PROGRESS`, `RETURN_ARRIVED`, `RETURNED`, `EXPIRED`
- `pickup_instructions` (string, optional, nullable)
- `dropoff_instructions` (string, optional, nullable)

### ValidationErrorResponseDetailsItems

- `path` (list of string, required)
- `message` (string, required)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "success": true,
  "data": {
    "external_delivery_id": "string",
    "status": "SCHEDULED",
    "pickup_instructions": "string",
    "dropoff_instructions": "string"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.goautolane.com/dd/v1/deliveries/external_delivery_id"

payload = {}
headers = {
    "x-retailer-id": "x-retailer-id",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.goautolane.com/dd/v1/deliveries/external_delivery_id';
const options = {
  method: 'PATCH',
  headers: {
    'x-retailer-id': 'x-retailer-id',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.goautolane.com/dd/v1/deliveries/external_delivery_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-retailer-id", "x-retailer-id")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.goautolane.com/dd/v1/deliveries/external_delivery_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-retailer-id"] = 'x-retailer-id'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.goautolane.com/dd/v1/deliveries/external_delivery_id")
  .header("x-retailer-id", "x-retailer-id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.goautolane.com/dd/v1/deliveries/external_delivery_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'x-retailer-id' => 'x-retailer-id',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.goautolane.com/dd/v1/deliveries/external_delivery_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("x-retailer-id", "x-retailer-id");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-retailer-id": "x-retailer-id",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.goautolane.com/dd/v1/deliveries/external_delivery_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```