Book shipment

Submits a shipment draft for carrier booking.

Prerequisites

The shipment must be PENDING.
It must have no linked payments, quotations, proforma data, or automatic returns.
The service must support carrier booking. OTHER cannot be booked.
The stored shipment must meet current service requirements and have an available price greater than zero.

Behavior

Booking revalidates the draft and recalculates its price. For parcel-shop delivery, it also revalidates the stored shop ID and refreshes the shop details.
200 with PROCESSING confirms queue dispatch. Read the shipment for the completed booking result.
409 PRICE_CHANGED keeps the draft PENDING, updates its price, and returns errors.price. Review the price and use a new idempotency key to accept it. The previous key replays the conflict.
409 SERVICE_NO_LONGER_AVAILABLE queues no booking.
Retry a 503 dispatch failure with the same idempotency key.

Permission

SHIPMENTS_WRITE

See Troubleshooting for authentication, access, rate-limit, and service errors.

POST/shipments/{id}/book

Authorization

AuthorizationBearer token · headerrequired

Required header: Authorization: Bearer <customer-api-key>. Use a Customer API key with the operation's required permission. Never use a dashboard or webshop token.

Path parameters

idstringrequired

ID of the shipment. Obtain it from a list or create response. Unavailable IDs return 404.

min length 1

Header parameters

Idempotency-Keystringrequired

Unique operation key, at most 255 characters after trimming. Retry the same request with the same key; use a new key for a changed request.

min length 1 · max length 255

Request body

application/json

Empty JSON object ({}). No payload fields are accepted. The shipment ID comes from the URL.

object

Responses

200

Successful result

successanyrequired

messagestringrequired

dataobjectrequired

Show properties

idstringrequired

statusstringrequired

pricePrice

Show properties

currencystringrequired

baseAmountstringrequired

surchargeAmountstringrequired

palletExchangeAmountstringrequired

taxAmountstringrequired

totalAmountstringrequired

customerReferencestring | null

requestIdstringrequired

400

Invalid shipment input, including an invalid GLS shop ID or receiver-country mismatch.

successanyrequired

messagestringrequired

dataanyrequired

requestIdstringrequired

errorCodestringrequired

errorsobject | anyrequired

Show properties

Any of:

object

fieldsobject[]

Show properties

Array of object

pathstringrequired

errorCodestringrequired

messagestringrequired

pricePrice

Show properties

currencystringrequired

baseAmountstringrequired

surchargeAmountstringrequired

palletExchangeAmountstringrequired

taxAmountstringrequired

totalAmountstringrequired

currentStatusstring

retryAfterSecondsinteger

min 1

any

any

404

Resource does not exist or belongs to another account.

successanyrequired

messagestringrequired

dataanyrequired

requestIdstringrequired

errorCodestringrequired

errorsobject | anyrequired

Show properties

Any of:

object

fieldsobject[]

Show properties

Array of object

pathstringrequired

errorCodestringrequired

messagestringrequired

pricePrice

Show properties

currencystringrequired

baseAmountstringrequired

surchargeAmountstringrequired

palletExchangeAmountstringrequired

taxAmountstringrequired

totalAmountstringrequired

currentStatusstring

retryAfterSecondsinteger

min 1

any

any

409

State, idempotency, price, or label conflict; inspect errorCode and errors.

successanyrequired

messagestringrequired

dataanyrequired

requestIdstringrequired

errorCodestringrequired

errorsobject | anyrequired

Show properties

Any of:

object

fieldsobject[]

Show properties

Array of object

pathstringrequired

errorCodestringrequired

messagestringrequired

pricePrice

Show properties

currencystringrequired

baseAmountstringrequired

surchargeAmountstringrequired

palletExchangeAmountstringrequired

taxAmountstringrequired

totalAmountstringrequired

currentStatusstring

retryAfterSecondsinteger

min 1

any

any

503

Shop lookup or booking dispatch is temporarily unavailable. Retry booking with the same Idempotency-Key.

successanyrequired

messagestringrequired

dataanyrequired

requestIdstringrequired

errorCodestringrequired

errorsobject | anyrequired

Show properties

Any of:

object

fieldsobject[]

Show properties

Array of object

pathstringrequired

errorCodestringrequired

messagestringrequired

pricePrice

Show properties

currencystringrequired

baseAmountstringrequired

surchargeAmountstringrequired

palletExchangeAmountstringrequired

taxAmountstringrequired

totalAmountstringrequired

currentStatusstring

retryAfterSecondsinteger

min 1

any

any

Request

curl -X POST "https://bookogsend.dk/api/v1/customer/shipments/%3Cshipment-id%3E/book" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: <unique-operation-key>" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch("https://bookogsend.dk/api/v1/customer/shipments/%3Cshipment-id%3E/book", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "<unique-operation-key>",
    "Content-Type": "application/json"
  },
  body: "{}"
});

Response

{
  "success": true,
  "message": "Shipment queued for booking.",
  "data": {
    "id": "<shipment-id>",
    "status": "PROCESSING",
    "price": {
      "currency": "DKK",
      "baseAmount": "100.00",
      "surchargeAmount": "0.00",
      "palletExchangeAmount": "0.00",
      "taxAmount": "25.00",
      "totalAmount": "125.00"
    },
    "customerReference": null
  },
  "requestId": "<request-id>"
}

{
  "success": false,
  "message": "string",
  "data": null,
  "requestId": "string",
  "errorCode": "string",
  "errors": {
    "fields": [
      {
        "path": "string",
        "errorCode": "string",
        "message": "string"
      }
    ],
    "price": {
      "currency": "string",
      "baseAmount": "string",
      "surchargeAmount": "string",
      "palletExchangeAmount": "string",
      "taxAmount": "string",
      "totalAmount": "string"
    },
    "currentStatus": "string",
    "retryAfterSeconds": 1
  }
}

{
  "success": false,
  "message": "Resource does not exist or belongs to another account.",
  "data": null,
  "requestId": "request-id",
  "errorCode": "NOT_FOUND",
  "errors": null
}

{
  "success": false,
  "message": "State, idempotency, price, or label conflict; inspect errorCode and errors.",
  "data": null,
  "requestId": "request-id",
  "errorCode": "IDEMPOTENCY_KEY_REUSED",
  "errors": null
}

{
  "success": false,
  "message": "string",
  "data": null,
  "requestId": "string",
  "errorCode": "string",
  "errors": {
    "fields": [
      {
        "path": "string",
        "errorCode": "string",
        "message": "string"
      }
    ],
    "price": {
      "currency": "string",
      "baseAmount": "string",
      "surchargeAmount": "string",
      "palletExchangeAmount": "string",
      "taxAmount": "string",
      "totalAmount": "string"
    },
    "currentStatus": "string",
    "retryAfterSeconds": 1
  }
}