> ## Documentation Index > Fetch the complete documentation index at: https://docs.drop-hub.com/llms.txt > Use this file to discover all available pages before exploring further. # Change the destination or recipient of an own Direct API shipment > If-Match carries the shipment version from its ETag. A new destination is accepted before pickup (CREATED, ASSIGNED, NO_DRIVER_AVAILABLE) when it is inside the same coverage checkout serviceability applies and the merchant's agreement prices the new route exactly as the frozen delivery fee; the fee is never restated. A new recipient is accepted until the shipment is delivered, failed or cancelled. The assigned driver keeps the assignment and sees the new destination; a shipment.updated webhook is sent. A new pickupWindow is accepted until a driver accepts the shipment and must fit the pickup location's opening hours (422 PICKUP_OUTSIDE_OPERATING_HOURS); the price does not depend on it. Shipments that came from a store platform (Salla, Zid) are changed in that platform: 409 SHIPMENT_CHANGE_NOT_SUPPORTED. Other refusals: 412 PRECONDITION_FAILED (stale If-Match), 409 SHIPMENT_CHANGE_NOT_ALLOWED (state), 409 SHIPMENT_PRICE_WOULD_CHANGE, 422 OUTSIDE_MERCHANT_COVERAGE or NO_PROVIDER_AVAILABLE, 422 SHIPMENT_VALIDATION_FAILED (nothing to change). ## OpenAPI ````yaml /openapi.yaml patch /api/v2/external/shipments/{shipmentId} openapi: 3.1.0 info: title: DropHub External API version: v2 description: The public machine-to-machine integration surface of DropHub. servers: - url: https://api-test.drop-hub.com description: Sandbox. Isolated data and credentials. - url: https://api.drop-hub.com description: Production. Production credentials only. security: [] tags: - name: Authentication description: >- Authentication, sessions, the company a principal is, and merchant API credentials - name: External Shipments description: OAuth-scoped Merchant shipment creation, lookup, and cancellation - name: External Tracking description: Merchant-authenticated and privacy-minimized public tracking projections - name: External Webhooks - name: Sandbox description: >- Tenant-bound self-service fixture lifecycle, available only on the isolated sandbox deployment paths: /api/v2/external/shipments/{shipmentId}: patch: tags: - External Shipments summary: Change the destination or recipient of an own Direct API shipment description: >- If-Match carries the shipment version from its ETag. A new destination is accepted before pickup (CREATED, ASSIGNED, NO_DRIVER_AVAILABLE) when it is inside the same coverage checkout serviceability applies and the merchant's agreement prices the new route exactly as the frozen delivery fee; the fee is never restated. A new recipient is accepted until the shipment is delivered, failed or cancelled. The assigned driver keeps the assignment and sees the new destination; a shipment.updated webhook is sent. A new pickupWindow is accepted until a driver accepts the shipment and must fit the pickup location's opening hours (422 PICKUP_OUTSIDE_OPERATING_HOURS); the price does not depend on it. Shipments that came from a store platform (Salla, Zid) are changed in that platform: 409 SHIPMENT_CHANGE_NOT_SUPPORTED. Other refusals: 412 PRECONDITION_FAILED (stale If-Match), 409 SHIPMENT_CHANGE_NOT_ALLOWED (state), 409 SHIPMENT_PRICE_WOULD_CHANGE, 422 OUTSIDE_MERCHANT_COVERAGE or NO_PROVIDER_AVAILABLE, 422 SHIPMENT_VALIDATION_FAILED (nothing to change). operationId: changeExternalShipment parameters: - $ref: '#/components/parameters/ShipmentId' - name: If-Match in: header required: true schema: type: string example: '"3"' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalShipmentChangeRequest' examples: newDestinationAndRecipient: value: destination: latitude: 24.775 longitude: 46.739 recipient: name: Noura mobile: 559876543 responses: '200': $ref: '#/components/responses/ExternalShipmentResource' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/AuthenticationFailed' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/StateConflict' '412': $ref: '#/components/responses/PreconditionFailed' '422': $ref: '#/components/responses/ValidationFailed' '428': $ref: '#/components/responses/PreconditionRequired' security: - oauthClientCredentials: - shipments:write components: parameters: ShipmentId: name: shipmentId in: path required: true schema: type: string format: uuid schemas: ExternalShipmentChangeRequest: type: object additionalProperties: false description: >- Include destination, recipient, pickupWindow, or any combination. Absent parts are not changed. properties: destination: $ref: '#/components/schemas/ExternalCoordinate' recipient: $ref: '#/components/schemas/ExternalRecipient' pickupWindow: $ref: '#/components/schemas/ExternalPickupWindow' ExternalCoordinate: type: object additionalProperties: false required: - latitude - longitude properties: latitude: $ref: '#/components/schemas/Latitude' longitude: $ref: '#/components/schemas/Longitude' ExternalRecipient: type: object additionalProperties: false required: - name - mobile properties: name: type: string minLength: 1 maxLength: 120 mobile: type: string pattern: ^(?:05|5|\\+9665)[0-9]{8}$ description: Saudi mobile; DropHub stores canonical +9665XXXXXXXX. ExternalPickupWindow: type: object additionalProperties: false required: - start - end properties: start: $ref: '#/components/schemas/InstantUtc' end: $ref: '#/components/schemas/InstantUtc' ExternalShipment: type: object additionalProperties: false required: - id - reference - status - trackingUrl - createdAt - version properties: id: $ref: '#/components/schemas/Uuid' reference: type: string status: $ref: '#/components/schemas/ExternalShipmentStatus' trackingUrl: type: string format: uri-reference codAmount: type: - number - 'null' format: decimal minimum: 0 deliveryFeeAmount: type: - number - 'null' format: decimal minimum: 0 deliveryFeeCurrency: type: - string - 'null' example: SAR eta: oneOf: - $ref: '#/components/schemas/LiveEta' - type: 'null' proofAvailable: type: boolean proofType: type: - string - 'null' enum: - PHOTO - SIGNATURE - null deliveredAt: oneOf: - $ref: '#/components/schemas/InstantUtc' - type: 'null' failureReasonCode: type: - string - 'null' cancellationReasonCode: type: - string - 'null' driver: oneOf: - $ref: '#/components/schemas/ExternalAssignedDriver' - type: 'null' createdAt: $ref: '#/components/schemas/InstantUtc' version: type: integer format: int64 minimum: 0 Problem: type: object description: RFC 9457 Problem Details with stable DropHub extensions additionalProperties: true required: - type - title - status - code - timestamp - correlationId - requestId properties: type: type: string format: uri title: type: string maxLength: 128 status: type: integer format: int32 minimum: 400 maximum: 599 detail: type: string maxLength: 512 instance: type: string format: uri-reference code: type: string pattern: ^[A-Z][A-Z0-9_]{1,63}$ timestamp: type: string format: date-time correlationId: type: string format: uuid requestId: type: string format: uuid violations: type: array maxItems: 20 items: $ref: '#/components/schemas/Violation' example: type: https://api.drophub.example/problems/access-denied title: Access denied status: 403 detail: Access to this resource is denied. instance: /api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206 code: ACCESS_DENIED timestamp: '2026-08-22T18:30:00Z' correlationId: 018f2d8a-1f00-7000-8000-000000000207 requestId: 018f2d8a-1f00-7000-8000-000000000208 Latitude: type: number minimum: -90 maximum: 90 multipleOf: 0.000001 Longitude: type: number minimum: -180 maximum: 180 multipleOf: 0.000001 InstantUtc: type: string format: date-time Uuid: type: string format: uuid ExternalShipmentStatus: type: string enum: - CREATED - ASSIGNED - PICKED_UP - OUT_FOR_DELIVERY - DELIVERED - FAILED - NO_DRIVER_AVAILABLE - CANCELLED description: >- ASSIGNED covers an offer awaiting the driver's acceptance and an accepted one. NO_DRIVER_AVAILABLE means the bounded driver search ended without a driver; the shipment can still be cancelled. LiveEta: type: object additionalProperties: false required: - target - estimatedArrivalAt - estimatedMinutes - calculatedAt - distanceMetres properties: target: type: string enum: - PICKUP - DELIVERY estimatedArrivalAt: $ref: '#/components/schemas/InstantUtc' estimatedMinutes: type: integer format: int64 calculatedAt: $ref: '#/components/schemas/InstantUtc' distanceMetres: type: integer format: int64 ExternalAssignedDriver: type: object additionalProperties: false description: >- The driver who accepted the shipment, while it is still moving. Phone number, surname, licence and identifiers are not disclosed; contact goes through the shipment conversation. properties: firstName: type: - string - 'null' vehicleType: type: - string - 'null' enum: - MOTORCYCLE - CAR - VAN - TRUCK - null vehiclePlate: type: - string - 'null' Violation: type: object additionalProperties: false required: - field - code - message properties: field: type: string maxLength: 128 code: type: string maxLength: 64 message: type: string maxLength: 256 responses: ExternalShipmentResource: description: Minimal partner-safe shipment headers: ETag: $ref: '#/components/headers/EntityTag' content: application/json: schema: $ref: '#/components/schemas/ExternalShipment' BadRequest: description: >- The request syntax, path parameter, query parameter, or JSON document is malformed. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' AuthenticationFailed: description: Authentication failed without account, token, or tenant enumeration. headers: WWW-Authenticate: $ref: '#/components/headers/WwwAuthenticate' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://api.drophub.example/problems/authentication-required title: Authentication required status: 401 detail: Authentication is required for this resource. instance: /api/v2/external/shipments/018f2d8a-1f00-7000-8000-000000000206 code: AUTHENTICATION_REQUIRED timestamp: '2026-08-22T18:30:00Z' correlationId: 018f2d8a-1f00-7000-8000-000000000207 requestId: 018f2d8a-1f00-7000-8000-000000000208 AccessDenied: description: >- Access denied without exposing internal policy or resource ownership. No operation requires a second factor or a fresher live session. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ResourceNotFound: description: Resource not found; existence is hidden across authorization boundaries. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' StateConflict: description: Current state prevents the requested transition. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' PreconditionFailed: description: The supplied strong entity version is stale. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ValidationFailed: description: The request fails strict syntax or semantic validation. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' PreconditionRequired: description: A strong If-Match precondition is required. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' headers: EntityTag: description: Strong numeric entity version for the next state-changing request. schema: type: string pattern: ^"[0-9]+"$ WwwAuthenticate: description: Bearer challenge for an unauthenticated or invalid-token request. schema: type: string example: Bearer securitySchemes: oauthClientCredentials: type: oauth2 description: >- OAuth 2.0 client-credentials flow for external machine-to-machine integrations. flows: clientCredentials: tokenUrl: /api/v2/oauth/token scopes: quotes:write: Calculate shipment quotes without creating shipments shipments:read: Read Merchant-owned shipments shipments:write: Create and cancel Merchant-owned shipments tracking:read: Read merchant-owned shipment tracking projections webhooks:manage: Configure and rotate the merchant's single signed shipment webhook ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.