Booking a job

این محتوا هنوز به زبان شما در دسترس نیست.

A job is a booked delivery. You book it against a quote rather than describing the journey again, so the price is the one you were quoted — and a quote can only be booked once.

POST /v1/jobs
Idempotency-Key: <a key you choose>

The Idempotency-Key header is required. It is what makes a timed-out booking safe to send again — see Retries and idempotency.

Request

Field	Type
`quote_id`	string	Required. The `id` of an unexpired, unused quote.
`pickup`	contact	Required. Who the courier collects from.
`dropoff`	contact	Required. Who the courier delivers to.
`scheduled_for`	string	When the delivery should happen. Must match what the quote was priced for. Omitted means now.
`items`	array	What is in the bag, line by line. See Order items.
`discount_minor`	integer	Money off the items. Cannot exceed what they come to.
`items_total_minor`	integer	What the customer was billed for the goods, if not the items less the discount.
`notify_customer`	boolean	Whether to text the customer the tracking link when the courier collects. Omitted means your account’s setting.

Each contact is:

Field	Type
`latitude`, `longitude`	number	Required. The same points you quoted.
`address`	string	Required. As the courier should read it.
`contact_name`	string	Required.
`contact_phone`	string	Required. The most-used field in the courier app — the commonest problem is a locked door. Use international format.
`postcode`	string	Optional.
`notes`	string	Optional. “Ask at the counter”, “Second floor, buzzer 4”.

curl -u "$COURIER_KEY:$COURIER_SECRET" "$COURIER_API/v1/jobs" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042' \
  -d '{
    "quote_id": "0199d2c4-6b1e-7a42-9c35-2f0d8e1b7a10",
    "pickup": {
      "latitude": 51.5080, "longitude": -0.1281,
      "address": "Trafalgar Square, London",
      "contact_name": "The kitchen", "contact_phone": "+44 20 7946 0100",
      "notes": "Ask at the counter."
    },
    "dropoff": {
      "latitude": 51.5081, "longitude": -0.0759,
      "address": "Tower Hill, London",
      "contact_name": "Alex Rivera", "contact_phone": "+44 7700 900456",
      "notes": "Second floor, buzzer 4."
    },
    "items": [
      { "name": "Margherita", "unit_price_minor": 900, "quantity": 2 },
      { "name": "Garlic bread", "unit_price_minor": 450, "quantity": 1 }
    ],
    "discount_minor": 300
  }'

Response

201 Created:

{
  "id": "0199d2c5-1f3a-7d10-8b2e-6c4a9e0f2d31",
  "reference": "JOB-7F3K2Q",
  "status": "searching",
  "currency": "GBP",
  "price_amount_minor": 918,
  "vehicle": "bicycle",
  "tracking_url": "https://track.courier.example/4mZ8qPx2",
  "booked_at": "2026-10-10T12:04:31+00:00",
  "scheduled_for": null
}

status is searching: the offer is already out to couriers nearby. A scheduled job is pending until twenty minutes before its time.
price_amount_minor is what you are charged — fixed by the quote.
tracking_url is the public page your customer can follow the delivery on. See Tracking.
Store the id. Every later call and every webhook names the job by it, and by reference.

Order items

items is optional. Send it when there is an itemised order: the courier reads it at the counter and at the customer’s door, and it is on the job for your support team afterwards. Leave it out for a parcel.

Field	Type
`name`	string	Required. As it appears on the receipt.
`unit_price_minor`	integer	Required. What one costs, in the quote’s currency. Zero is allowed.
`quantity`	integer	Required. A whole number, at least one.

None of these amounts is what you are charged. They describe the customer’s order; your charge is the delivery price.

Scheduled deliveries

Quote and book with the same scheduled_for. The job stays pending until twenty minutes before that time, when it starts looking for a courier on its own. A time that has already passed is refused with job.scheduled_in_past.

Texting the customer

When the courier collects, the person at the drop-off can be texted the tracking link. Your account has a default, set in the merchant portal; notify_customer overrides it for one booking — false for a customer with no mobile, true for one who asked. Only numbers in the countries we operate in are texted, and nothing is ever texted from the sandbox.

When a booking is refused

422 Unprocessable Entity with an error body:

`code`	Meaning
`quote.not_found`	No quote with that id.
`quote.expired`	The quote is more than ten minutes old. Ask for a new one.
`quote.already_used`	That quote has been booked already.
`job.scheduled_in_past`	`scheduled_for` has already passed.
`request.invalid_stop`	A contact is missing its address, name or a usable phone number. The message says which.
`order.item_invalid`	An item has no name, a negative price or a quantity under one.
`order.discount_exceeds_items`	The discount is more than the items come to.
`request.missing_idempotency_key`	The `Idempotency-Key` header is missing.