Create shipment draft

Creates a priced shipment draft.

Prerequisites

Use a service and package type returned by service discovery for your account.
Carrier pickup dates cannot be in the past on the Copenhagen calendar.

Behavior

Returns 201 with a PENDING draft. Request booking separately.
Saves address snapshots and the calculated price.
An inline receiver is saved to the address book.

Permission

SHIPMENTS_WRITE

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

POST/shipments

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.

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

requiredapplication/json

Shipment details for a new unbooked PENDING draft. Creating the draft does not request carrier booking.

serviceCodestringrequired

Choose a serviceCode returned by GET /services for this account. The enum lists recognized codes; availability depends on the account and route. OTHER has no carrier booking or printable label. Express services require pickup and delivery within Denmark.

Allowed:PALLETLEMAN_PALLETBUSINESS_PARCELPRIVATE_PARCELPICKUP_SHIPMENTSHOP_DELIVERYDIRECT_SHOPSHOP_RETURNPICKUP_RETURNGLOBAL_EXPRESSEXPRESS_10EXPRESS_12OTHER

senderIdstringrequired

Required ID of a saved sender belonging to this account. Obtain it from GET /senders or POST /senders.

min length 1

receiverIdstring

ID of a saved receiver belonging to this account. Provide exactly one of receiverId or receiver.

min length 1

receiverAddress

Inline receiver address instead of receiverId. Creating or replacing a draft saves it in the address book; price preview does not save it.

Show properties

namestringrequired

Person or company name. Required and nonempty after trimming; see maxLength. Shipment services may impose a lower name limit.

min length 1 · max length 40

street1stringrequired

Primary street address, including house number. Required and nonempty after trimming; see maxLength and service fieldLimits.

min length 1 · max length 54

street2string | any

Optional additional address line. Omit or send null to clear it; see maxLength and service fieldLimits.

default: null

Show properties

Any of:

string

string

any

any

citystringrequired

Town or city. Required and nonempty after trimming; see maxLength.

min length 1 · max length 30

zipstringrequired

Postal code as text, preserving leading zeros. It must match the country for carrier shipments; see maxLength.

min length 1 · max length 10

countrystringrequired

Supported country code in two-letter uppercase ISO format, such as DK. The country and service must have an available route and price.

matches ^[A-Z]{2}$

addressTypestringrequired

RESIDENTIAL for a private address or COMMERCIAL for a business address.

Allowed:RESIDENTIALCOMMERCIAL

regionstring | any

Optional state, province, or region as text. Omit or send null to clear it.

default: null

Show properties

Any of:

string

string

any

any

attentionstring | any

Optional contact person or attention line. Omit or send null to clear it; see maxLength.

default: null

Show properties

Any of:

string

string

any

any

emailstring<email> | any

Valid contact email address, or null. Required for a shipment receiver when GET /services reports receiverEmailRequired.

default: null

Show properties

Any of:

string<email>

string<email>

any

any

phonestring | any

Telephone number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverPhoneRequired is true.

default: null

Show properties

Any of:

string

string

any

any

mobilestring | any

Mobile number in international E.164 format, such as +4512345678, or null. Required for a shipment receiver when receiverMobileRequired is true.

default: null

Show properties

Any of:

string

string

any

any

pickupDatestringrequired

Valid YYYY-MM-DD date on the Copenhagen calendar. Carrier shipments cannot use a past date; OTHER still requires a valid date.

matches ^\d{4}-\d{2}-\d{2}$

packagesobject[]

One item per physical package or pallet. At least one is required for carrier services. OTHER accepts an omitted or empty array. Each item requires type, positive weight, and hasDg.

default: []

Show properties

Array of object

typestringrequired

Choose a packageTypes[].type returned by GET /services for the selected serviceCode. A recognized enum value is not necessarily enabled for this account.

Allowed:EURO_PALLET_QUARTEREURO_PALLET_HALFEURO_PALLETPKKLEMAN_EURO_PALLET_HALFLEMAN_EURO_PALLETINDUSTRIAL_PALLETBUSINESS_PARCELPRIVATE_PARCELPICKUP_SHIPMENTSHOP_DELIVERYDIRECT_SHOPSHOP_RETURNPICKUP_RETURNGLOBAL_EXPRESSEXPRESS_10EXPRESS_12OTHER

weightnumberrequired

Positive weight of this package in kg, no greater than the selected package type's maxWeight from GET /services.

lengthnumber | any

Positive package length in cm, no greater than maxLength from GET /services. Required with width and height for international volume-weight pricing; otherwise may be omitted or null.

Show properties

Any of:

number

number

any

any

widthnumber | any

Positive package width in cm, no greater than maxWidth from GET /services. Required with length and height for international volume-weight pricing; otherwise may be omitted or null.

Show properties

Any of:

number

number

any

any

heightnumber | any

Positive package height in cm, no greater than maxHeight from GET /services. Required when listed in requiredPackageFields or for international volume-weight pricing; otherwise may be omitted or null.

Show properties

Any of:

number

number

any

any

descriptionstring

Package contents or goods description. Required when GET /services lists description in requiredPackageFields. Must not exceed the service's maxDescriptionLength.

hasDgbooleanrequired

Required boolean. Set true for dangerous goods and supply dg. Only GLS and LEMAN services support dangerous goods. Set false for ordinary goods and omit dg or send null.

dgobject | any

Dangerous-goods details, required when hasDg is true. Must be omitted or null when hasDg is false.

default: null

Show properties

Any of:

object

hazardClassstringrequired

Nonempty dangerous-goods hazard-class designation for the shipment.

min length 1

unNumberstringrequired

Four-digit UN number as a string without the UN prefix, such as 1234. Leading zeros are preserved.

min length 1 · matches ^\d{4}$

properShippingNamestringrequired

Nonempty proper shipping name of the dangerous goods.

min length 1

weightnumberrequired

Positive weight of the dangerous goods in kg.

packingGroupstringrequired

Nonempty packing-group designation as text, such as II, appropriate for the goods and carrier.

min length 1

flashPointstring | any

Optional flash-point value as text. Omit or send null when not needed.

default: null

Show properties

Any of:

string

string

any

any

technicalNamestring | any

Optional technical or chemical name. Omit or send null when not needed.

default: null

Show properties

Any of:

string

string

any

any

marinePollutantstring | any

Optional marine-pollutant designation as text. Omit or send null when not needed.

default: null

Show properties

Any of:

string

string

any

any

any

any

pickupLocationobject | any

Selected GLS parcel-shop ID. Required for SHOP_DELIVERY. Optional for other carrier services; ignored for OTHER. Bookogsend resolves the shop details and checks that the shop exists in the receiver country.

Show properties

Any of:

object

externalLocationIdstringrequired

Carrier's ID for the selected parcel shop, not a Bookogsend address-book ID.

min length 1

any

any

isExchangePalletsboolean

Enable pallet exchange for serviceCode PALLET only; otherwise ignored. Defaults to false when omitted. If all exchange-count fields are omitted, eligible quarter, half, and full euro pallets are counted from packages.

exchangePalletsQuarterinteger

Optional quarter-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero.

min 0 · max 99

exchangePalletsHalfinteger

Optional half-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero.

min 0 · max 99

exchangePalletsFullinteger

Optional full-euro-pallet exchange count, integer 0–99, used with PALLET and isExchangePallets=true. Supplying any exchange count overrides automatic counting; omitted sizes count as zero.

min 0 · max 99

deliveryNotestring | any

Optional delivery instructions as text. Omit or send null to clear the value when replacing a draft.

default: null

Show properties

Any of:

string

string

any

any

customerReferencestring | any

Optional reference from your system, such as an order number. Omit or send null to clear the value when replacing a draft. Listing filters match this value exactly.

default: null

Show properties

Any of:

string

string

any

any

Responses

201

Successful result

successanyrequired

messagestringrequired

dataobjectrequired

Show properties

idstringrequired

statusstringrequired

pricePrice

Show properties

currencystringrequired

baseAmountstringrequired

surchargeAmountstringrequired

palletExchangeAmountstringrequired

taxAmountstringrequired

totalAmountstringrequired

customerReferencestring | null

receiverIdstring

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

Pickup locations or receiver coordinates are temporarily unavailable. Retry later.

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" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: <unique-operation-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "serviceCode": "BUSINESS_PARCEL",
  "senderId": "<sender-id>",
  "receiverId": "<receiver-id>",
  "pickupDate": "2030-01-15",
  "packages": [
    {
      "type": "BUSINESS_PARCEL",
      "weight": 1,
      "length": 30,
      "width": 20,
      "height": 10,
      "hasDg": false
    }
  ]
}'

const response = await fetch("https://bookogsend.dk/api/v1/customer/shipments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "<unique-operation-key>",
    "Content-Type": "application/json"
  },
  body: "{\n  \"serviceCode\": \"BUSINESS_PARCEL\",\n  \"senderId\": \"<sender-id>\",\n  \"receiverId\": \"<receiver-id>\",\n  \"pickupDate\": \"2030-01-15\",\n  \"packages\": [\n    {\n      \"type\": \"BUSINESS_PARCEL\",\n      \"weight\": 1,\n      \"length\": 30,\n      \"width\": 20,\n      \"height\": 10,\n      \"hasDg\": false\n    }\n  ]\n}"
});

Response

{
  "success": true,
  "message": "Shipment created.",
  "data": {
    "id": "<shipment-id>",
    "status": "PENDING",
    "price": {
      "currency": "DKK",
      "baseAmount": "100.00",
      "surchargeAmount": "0.00",
      "palletExchangeAmount": "0.00",
      "taxAmount": "25.00",
      "totalAmount": "125.00"
    },
    "customerReference": null,
    "receiverId": "<receiver-id>"
  },
  "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": "Pickup locations are temporarily unavailable. Try again later.",
  "data": null,
  "requestId": "<request-id>",
  "errorCode": "PICKUP_LOCATIONS_UNAVAILABLE",
  "errors": null
}