Create or replay a canonical Merchant shipment

Resolves the authoritative route, internally selects an eligible service and driver, and freezes the merchant commercial terms. Carrier identity and scoring are never merchant inputs. externalReference is unique per Merchant company.

POST /v2/external/shipments

Create or replay a canonical Merchant shipment

cURL

curl --request POST \
  --url https://api-test.drop-hub.com/v2/external/shipments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "externalReference": "<string>",
  "branchCode": "<string>",
  "pickupLocationCode": "<string>",
  "recipient": {
    "name": "<string>",
    "phone": "<string>",
    "alternateContactName": "<string>",
    "alternateContactPhone": "<string>"
  },
  "destination": {
    "addressLine": "<string>",
    "cityCode": "<string>",
    "latitude": 0,
    "longitude": 0
  },
  "declaredValue": 1,
  "codAmount": 1,
  "currency": "<string>",
  "pickupWindowStart": "2023-11-07T05:31:56Z",
  "pickupWindowEnd": "2023-11-07T05:31:56Z",
  "items": [
    {
      "description": "<string>",
      "quantity": 5000,
      "weightKilograms": 123,
      "lengthCentimetres": 123,
      "widthCentimetres": 123,
      "heightCentimetres": 123
    }
  ],
  "requirements": [
    "<string>"
  ]
}
'

200

{
  "shipmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shipmentNumber": "<string>",
  "externalReference": "<string>",
  "state": "PENDING_APPROVAL",
  "recipientName": "<string>",
  "maskedRecipientPhone": "<string>",
  "totalWeightKilograms": 123,
  "declaredValue": 123,
  "codAmount": 123,
  "currency": "<string>",
  "paymentMethod": "PREPAID",
  "pickupWindowStart": "2023-11-07T05:31:56Z",
  "pickupWindowEnd": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "approvedAt": "2023-11-07T05:31:56Z",
  "version": 1,
  "destination": {
    "addressLine": "<string>",
    "cityCode": "<string>",
    "latitude": 0,
    "longitude": 0
  },
  "pickup": {
    "addressLine": "<string>",
    "cityCode": "<string>",
    "latitude": 0,
    "longitude": 0
  },
  "items": [
    {
      "description": "<string>",
      "quantity": 5000,
      "weightKilograms": 123,
      "lengthCentimetres": 1,
      "widthCentimetres": 1,
      "heightCentimetres": 1
    }
  ],
  "requirements": [
    "<string>"
  ],
  "timelineMedia": [
    {
      "mediaAssetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "purpose": "SHIPMENT_CREATION_EVIDENCE",
      "sortOrder": 49
    }
  ]
}

Authorizations

Authorization · string · header · required

OAuth 2.0 client-credentials flow for external machine-to-machine integrations.

Headers

Accept-Language · string

Preferred response language when a localized representation is available.

Maximum string length: 64

Example:

"en"

Idempotency-Key · string · required

Caller-generated key scoped by the operation, Merchant company, and OAuth client; an exact replay returns the original result.

Required string length: 16 - 128

Example:

"merchant-order-20260822-0001"

Body

application/json

externalReference · string · required

Required string length: 1 - 128

branchCode · string · required

Pattern: ^[A-Z0-9][A-Z0-9_-]{1,63}$

pickupLocationCode · string · required

Pattern: ^[A-Z0-9][A-Z0-9_-]{1,63}$

recipient · object · required

Show child attributes

destination · object · required

Show child attributes

declaredValue · number<decimal> · required

Required range: x >= 0

codAmount · number<decimal> · required

Required range: x >= 0

currency · string · required

Required string length: 3

Pattern: ^[A-Z]{3}$

paymentMethod · enum<string> · required

Available options: PREPAID, COD

pickupWindowStart · string<date-time> · required

pickupWindowEnd · string<date-time> · required

items · object[] · required

Required array length: 1 - 100 elements

Show child attributes

requirements · string[] · required

Maximum array length: 20

Pattern: ^[A-Z][A-Z0-9_]{1,47}$

Response

200

application/json

Merchant-safe canonical shipment

shipmentId · string<uuid> · required

shipmentNumber · string · required

externalReference · string | null · required

Maximum string length: 128

state · enum<string> · required

Available options: PENDING_APPROVAL, READY_FOR_DISPATCH, OFFERED, ACCEPTED, DISPATCH_UNRESOLVED, PICKED_UP, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_FAILED, CANCELLED

recipientName · string · required

maskedRecipientPhone · string · required

Only the final four digits are visible.

totalWeightKilograms · number · required

declaredValue · number · required

codAmount · number · required

currency · string · required

paymentMethod · enum<string> · required

Available options: PREPAID, COD

pickupWindowStart · string<date-time> · required

pickupWindowEnd · string<date-time> · required

createdAt · string<date-time> · required

approvedAt · string<date-time> | null · required

version · integer<int64> · required

Required range: x >= 0

destination · object · required

Show child attributes

pickup · object | null · required

Show child attributes

items · object[] · required

Show child attributes

requirements · string[] · required

timelineMedia · object[]

Existing READY assets attached only to the resulting shipment.created event.

Maximum array length: 10

Show child attributes