> ## 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. # List or reconcile Merchant shipments > List or reconcile Merchant shipments. ## OpenAPI ````yaml /openapi.yaml get /v2/external/shipments openapi: 3.1.0 info: title: DropHub External API version: v2 description: >- DropHub API v2 for Merchant, shipping-company, shipment, and OAuth 2.0 integrations. contact: name: DropHub API Governance license: name: Proprietary servers: - url: https://api-test.drop-hub.com description: Sandbox deployment with isolated data and credentials. - url: https://api.drop-hub.com description: Production deployment; production credentials only. security: [] tags: - name: Authentication description: >- Authentication, sessions, the company a principal is, and merchant API credentials - name: External Price Estimates description: OAuth-scoped transient route-distance and tariff calculation - 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: Sandbox description: >- Tenant-bound self-service fixture lifecycle, available only on the isolated sandbox deployment - name: Webhook Endpoints description: Merchant webhook subscriptions, lifecycle, and signing-secret rotation - name: Webhook Deliveries description: Durable webhook delivery history and replay paths: /v2/external/shipments: get: tags: - External Shipments summary: List or reconcile Merchant shipments description: List or reconcile Merchant shipments. operationId: listExternalMerchantShipments parameters: - $ref: '#/components/parameters/AcceptLanguage' - $ref: '#/components/parameters/BoundedLimit' - $ref: '#/components/parameters/PageCursor' - name: state in: query schema: $ref: '#/components/schemas/ShipmentState' - name: externalReference in: query schema: type: string minLength: 1 maxLength: 128 responses: '200': description: Merchant shipment page content: application/json: schema: $ref: '#/components/schemas/ExternalShipmentPage' '401': $ref: '#/components/responses/AuthenticationFailed' '403': $ref: '#/components/responses/AccessDenied' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimited' security: - oauthClientCredentials: - shipments:read components: parameters: AcceptLanguage: name: Accept-Language in: header required: false description: >- Preferred response language when a localized representation is available. schema: type: string maxLength: 64 example: en BoundedLimit: name: limit in: query required: false description: >- Maximum items to return. Default 25, maximum 100. Values outside 1..100 are rejected with 400; they are never clamped. schema: type: integer minimum: 1 maximum: 100 default: 25 PageCursor: name: cursor in: query required: false description: >- Opaque continuation token from a previous page's page.nextCursor. Bound to the tenant, parent resource, filter and sort of the originating query; a cursor presented to a different query is rejected with 400 INVALID_CURSOR. schema: type: string maxLength: 256 pattern: ^[A-Za-z0-9_-]{1,256}$ schemas: ShipmentState: type: string enum: - PENDING_APPROVAL - READY_FOR_DISPATCH - OFFERED - ACCEPTED - DISPATCH_UNRESOLVED - PICKED_UP - OUT_FOR_DELIVERY - DELIVERED - DELIVERY_FAILED - CANCELLED ExternalShipmentPage: type: object required: - data - page - links properties: data: type: array items: $ref: '#/components/schemas/ExternalShipment' page: $ref: '#/components/schemas/PageMetadata' links: $ref: '#/components/schemas/PageLinks' ExternalShipment: type: object additionalProperties: false required: - shipmentId - shipmentNumber - externalReference - state - pickup - destination - recipientName - maskedRecipientPhone - totalWeightKilograms - declaredValue - codAmount - currency - paymentMethod - pickupWindowStart - pickupWindowEnd - items - requirements - createdAt - approvedAt - version properties: shipmentId: $ref: '#/components/schemas/Uuid' shipmentNumber: type: string externalReference: type: - string - 'null' maxLength: 128 timelineMedia: type: array maxItems: 10 description: >- Existing READY assets attached only to the resulting shipment.created event. items: $ref: '#/components/schemas/ShipmentTimelineMediaRequest' state: $ref: '#/components/schemas/ShipmentState' recipientName: type: string maskedRecipientPhone: type: string description: Only the final four digits are visible. totalWeightKilograms: type: number declaredValue: type: number codAmount: type: number currency: type: string paymentMethod: type: string enum: - PREPAID - COD pickupWindowStart: $ref: '#/components/schemas/InstantUtc' pickupWindowEnd: $ref: '#/components/schemas/InstantUtc' createdAt: $ref: '#/components/schemas/InstantUtc' approvedAt: oneOf: - $ref: '#/components/schemas/InstantUtc' - type: 'null' version: type: integer format: int64 minimum: 0 destination: $ref: '#/components/schemas/ExternalLocation' pickup: oneOf: - $ref: '#/components/schemas/ExternalLocation' - type: 'null' items: type: array items: $ref: '#/components/schemas/ShipmentItem' requirements: type: array items: type: string uniqueItems: true PageMetadata: type: object required: - limit - hasMore additionalProperties: false properties: limit: type: integer minimum: 1 maximum: 100 description: The bounded limit the server actually applied. nextCursor: oneOf: - type: string maxLength: 256 - type: 'null' description: Continuation token, or null when the result set is exhausted. hasMore: type: boolean description: Always equal to (nextCursor is not null). examples: - limit: 25 nextCursor: null hasMore: false PageLinks: type: object required: - self additionalProperties: false properties: self: type: string maxLength: 512 description: Safe path of the originating query, without secrets or credentials. 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 traceId: type: string pattern: ^[0-9a-f]{32}$ violations: type: array maxItems: 20 items: $ref: '#/components/schemas/Violation' example: type: https://api.drop-hub.com/problems/access-denied title: Access denied status: 403 detail: Access to this resource is denied. instance: /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 Uuid: type: string format: uuid ShipmentTimelineMediaRequest: type: object additionalProperties: false required: - mediaAssetId - purpose - sortOrder properties: mediaAssetId: $ref: '#/components/schemas/Uuid' purpose: type: string enum: - SHIPMENT_CREATION_EVIDENCE sortOrder: type: integer minimum: 0 maximum: 99 InstantUtc: type: string format: date-time x-java-type: java.time.Instant x-postgresql-type: timestamptz(6) x-time-semantics: UTC-instant ExternalLocation: type: object additionalProperties: false required: - addressLine - cityCode - latitude - longitude properties: addressLine: type: string minLength: 1 maxLength: 240 cityCode: type: string pattern: ^[A-Z0-9_-]{2,32}$ latitude: type: number format: decimal minimum: -90 maximum: 90 longitude: type: number format: decimal minimum: -180 maximum: 180 ShipmentItem: type: object additionalProperties: false required: - description - quantity - weightKilograms properties: description: type: string minLength: 1 maxLength: 160 quantity: type: integer minimum: 1 maximum: 10000 weightKilograms: $ref: '#/components/schemas/PositiveQuantity' lengthCentimetres: oneOf: - $ref: '#/components/schemas/PositiveQuantity' - type: 'null' widthCentimetres: oneOf: - $ref: '#/components/schemas/PositiveQuantity' - type: 'null' heightCentimetres: oneOf: - $ref: '#/components/schemas/PositiveQuantity' - type: '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 PositiveQuantity: type: number exclusiveMinimum: 0 multipleOf: 0.000001 x-java-type: java.math.BigDecimal x-postgresql-type: numeric(19,6) responses: 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.drop-hub.com/problems/authentication-required title: Authentication required status: 401 detail: Authentication is required for this resource. instance: /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. The machine code is `ACCESS_DENIED`, except for two refusals that describe the caller's own session and are therefore safe to name: `ASSURANCE_REQUIRED`, when the caller holds the authority but the session has not proved a second factor, and `REAUTHENTICATION_REQUIRED`, when the session is no longer fresh enough for the operation. Both are answered by proving the session again and retrying — see `POST /v2/company-authentication/assurance-elevations`. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' MethodNotAllowed: description: The method is not supported for this resource. headers: Allow: description: Methods supported by this resource. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' RateLimited: description: The security operation is temporarily rate limited. headers: Retry-After: description: Suggested delay in seconds when available. schema: type: integer minimum: 1 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' headers: 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: /oauth/token scopes: shipments:read: Read Merchant-owned shipments shipments:write: Create and cancel Merchant-owned shipments webhooks:manage: Manage Merchant webhook endpoints, delivery history, and replay ````