> ## Documentation Index > Fetch the complete documentation index at: https://docs.haulstow.co/llms.txt > Use this file to discover all available pages before exploring further. # Create deliveries in bulk > Creates 1–100 deliveries in one request. Each item in `deliveries` is exactly the `POST /deliveries` request body and follows the same rules. Works on both the live and sandbox servers; the environment still comes from the host and key. The request runs in two phases: 1. **Validation (all-or-nothing).** Every item is validated with the single-create rules, and `external_id` values must be unique within the request. If any item is invalid, nothing is created and the API returns `422 BULK_VALIDATION_FAILED` with one entry per problem in `error.details.errors`. A count outside 1–100 returns `422 VALIDATION_ERROR`. 2. **Creation (per item).** Valid items are created one at a time in request order. Each is an independent delivery with its own `delivery.created` webhook. One item failing at creation, such as an unavailable quote or an `external_id` used by an earlier request, does not stop the others. `data.results` holds one result per input item in input order. The status is `201` when every item was created and `207` when at least one item failed, including when every item failed at creation. The complete response, including per-item failures, is stored under the one `Idempotency-Key` and replayed on retry. To retry only failed items, send a new request containing just those items with a new key. One bulk call counts as a single request against the per-key and per-business rate limits. Each item may carry its own `sandbox` object on the sandbox server. If any item sends `sandbox` with a live key, the whole request returns `400 SANDBOX_ONLY_FIELD` and nothing is created. A sandbox item whose scenario cannot start fails on its own with `SIMULATION_NOT_APPLICABLE` or `SIMULATION_LIMIT` in its result. ## OpenAPI ````yaml /openapi.yaml post /deliveries/bulk openapi: 3.1.0 info: title: HaulStow Developer Delivery API version: 1.0.0 summary: Create, quote, track, and test HaulStow deliveries. description: > The HaulStow Developer Delivery API is a server-to-server API for existing HaulStow business customers. Authenticate every request with a business-bound `hsg_live_key_...` API key. Use a test key with the sandbox base URL for deterministic, side-effect-free integration testing. All JSON responses use the same envelope. Every response includes `X-Request-ID` and rate-limit headers. Keep the request ID when contacting HaulStow support. contact: name: HaulStow Developer Support email: support@haulstow.co servers: - url: https://developer.haulstow.co/v1 description: Live security: - DeveloperApiKey: [] tags: - name: Quotes description: Calculate a delivery quote without creating a delivery. - name: Recipients description: Manage business-scoped recipients and reusable addresses. - name: Pickup locations description: >- Save the places riders collect from and name them by ID on deliveries and quotes. - name: Deliveries description: Create and inspect deliveries created by the authenticated application. - name: Sandbox description: Test-only helpers that never affect live operations. - name: Webhooks description: Signed delivery lifecycle callbacks sent by HaulStow. paths: /deliveries/bulk: post: tags: - Deliveries summary: Create deliveries in bulk description: | Creates 1–100 deliveries in one request. Each item in `deliveries` is exactly the `POST /deliveries` request body and follows the same rules. Works on both the live and sandbox servers; the environment still comes from the host and key. The request runs in two phases: 1. **Validation (all-or-nothing).** Every item is validated with the single-create rules, and `external_id` values must be unique within the request. If any item is invalid, nothing is created and the API returns `422 BULK_VALIDATION_FAILED` with one entry per problem in `error.details.errors`. A count outside 1–100 returns `422 VALIDATION_ERROR`. 2. **Creation (per item).** Valid items are created one at a time in request order. Each is an independent delivery with its own `delivery.created` webhook. One item failing at creation, such as an unavailable quote or an `external_id` used by an earlier request, does not stop the others. `data.results` holds one result per input item in input order. The status is `201` when every item was created and `207` when at least one item failed, including when every item failed at creation. The complete response, including per-item failures, is stored under the one `Idempotency-Key` and replayed on retry. To retry only failed items, send a new request containing just those items with a new key. One bulk call counts as a single request against the per-key and per-business rate limits. Each item may carry its own `sandbox` object on the sandbox server. If any item sends `sandbox` with a live key, the whole request returns `400 SANDBOX_ONLY_FIELD` and nothing is created. A sandbox item whose scenario cannot start fails on its own with `SIMULATION_NOT_APPLICABLE` or `SIMULATION_LIMIT` in its result. operationId: bulkCreateDeliveries parameters: - $ref: '#/components/parameters/XRequestID' - $ref: '#/components/parameters/RequiredIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkCreateDeliveriesRequest' example: deliveries: - external_id: shop-order-1842 recipient: name: Ama Mensah phone_number: '+233245412312' address: label: Home address: 15 Independence Avenue, Accra latitude: 5.56 longitude: -0.2057 municipality: Accra Metropolitan pickup: name: Osu Store contact: '+233200000001' address: Oxford Street, Osu, Accra latitude: 5.556 longitude: -0.182 payment: type: cod goods_value: 185 vehicle_type: bike - external_id: shop-order-1843 recipient_id: rcp_3f1a821cdb58498cbb52f4706545a089 recipient_address_id: adr_78de60204f574a64be88ba9bd94a049f pickup: name: Osu Store contact: '+233200000001' address: Oxford Street, Osu, Accra latitude: 5.556 longitude: -0.182 payment: type: delivery_only vehicle_type: bike responses: '201': description: Every delivery was created. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/BulkDeliverySuccessResponse' example: success: true statusCode: 201 message: Deliveries created data: created: 1 failed: 0 results: - index: 0 status: created delivery: id: dlv_3f1a821cdb58498cbb52f4706545a089 external_id: shop-order-1842 reference: H-RS83223 environment: live simulated: false status: booked recipient: id: rcp_3f1a821cdb58498cbb52f4706545a089 name: Ama Mensah phone_number: '+233245412312' pickup: name: Osu Store contact: '+233200000001' address: Oxford Street, Osu, Accra latitude: 5.556 longitude: -0.182 dropoff: id: adr_78de60204f574a64be88ba9bd94a049f label: Home address: 15 Independence Avenue, Accra latitude: 5.56 longitude: -0.2057 municipality: Accra Metropolitan payment: type: cod goods_value: 185 vehicle_type: bike currency: GHS delivery_fee: 20 requires_custom_quote: false tracking_url: https://track.haulstow.co/H-RS83223 created_at: '2026-08-20T14:20:00Z' updated_at: '2026-08-20T14:20:00Z' '207': description: | At least one item failed at creation. Every other item was created. Read each entry in `data.results`. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/BulkDeliverySuccessResponse' example: success: true statusCode: 207 message: Some deliveries failed data: created: 1 failed: 1 results: - index: 0 status: created delivery: id: dlv_3f1a821cdb58498cbb52f4706545a089 external_id: shop-order-1842 reference: H-RS83223 environment: live simulated: false status: booked recipient: id: rcp_3f1a821cdb58498cbb52f4706545a089 name: Ama Mensah phone_number: '+233245412312' pickup: name: Osu Store contact: '+233200000001' address: Oxford Street, Osu, Accra latitude: 5.556 longitude: -0.182 dropoff: id: adr_78de60204f574a64be88ba9bd94a049f label: Home address: 15 Independence Avenue, Accra latitude: 5.56 longitude: -0.2057 municipality: Accra Metropolitan payment: type: cod goods_value: 185 vehicle_type: bike currency: GHS delivery_fee: 20 requires_custom_quote: false tracking_url: https://track.haulstow.co/H-RS83223 created_at: '2026-08-20T14:20:00Z' updated_at: '2026-08-20T14:20:00Z' - index: 1 status: failed error: code: EXTERNAL_ID_CONFLICT message: External ID is already in use '400': $ref: '#/components/responses/DeliveryBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/IdempotencyConflict' '422': $ref: '#/components/responses/BulkValidationError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: XRequestID: name: X-Request-ID in: header required: false description: > Optional caller correlation ID. Use 1–128 ASCII letters, digits, `.`, `_`, `-`, or `:`. Invalid values are replaced. The accepted/generated value is returned in the response. schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._:-]+$ example: req_shop_1842_create RequiredIdempotencyKey: name: Idempotency-Key in: header required: true description: A unique key for this logical mutation. Retained for 24 hours. schema: type: string minLength: 8 maxLength: 255 example: shop-order-1842-create-v1 schemas: BulkCreateDeliveriesRequest: type: object additionalProperties: false required: - deliveries properties: deliveries: type: array minItems: 1 maxItems: 100 description: | The deliveries to create, in order. Each item is exactly the `POST /deliveries` request body. `external_id` values must be unique within the request. items: $ref: '#/components/schemas/CreateDeliveryRequest' BulkDeliverySuccessResponse: $ref: '#/components/schemas/SuccessEnvelopeBulkDelivery' CreateDeliveryRequest: type: object additionalProperties: false required: - payment - vehicle_type properties: external_id: type: string minLength: 1 maxLength: 128 description: Unique within the authenticated application when supplied. recipient_id: $ref: '#/components/schemas/RecipientID' recipient_address_id: $ref: '#/components/schemas/AddressID' recipient: $ref: '#/components/schemas/InlineRecipientRequest' pickup: $ref: '#/components/schemas/Pickup' pickup_location_id: $ref: '#/components/schemas/PickupLocationID' payment: $ref: '#/components/schemas/DeliveryPaymentRequest' vehicle_type: $ref: '#/components/schemas/VehicleType' delivery_instructions: type: string maxLength: 500 sandbox: $ref: '#/components/schemas/SandboxSimulationRequest' allOf: - oneOf: - title: Existing recipient and address required: - recipient_id - recipient_address_id not: required: - recipient - title: Inline recipient and address required: - recipient allOf: - not: required: - recipient_id - not: required: - recipient_address_id - oneOf: - title: Inline pickup required: - pickup not: required: - pickup_location_id - title: Saved pickup location required: - pickup_location_id not: required: - pickup SuccessEnvelopeBulkDelivery: type: object additionalProperties: false required: - success - statusCode - message - data properties: success: type: boolean const: true statusCode: type: integer enum: - 201 - 207 message: type: string data: $ref: '#/components/schemas/BulkDeliveryResult' ErrorResponse: type: object additionalProperties: false required: - success - statusCode - message - error properties: success: type: boolean const: false statusCode: type: integer minimum: 400 maximum: 599 message: type: string error: $ref: '#/components/schemas/ErrorPayload' RecipientID: type: string pattern: ^rcp_[a-f0-9]{32}$ example: rcp_3f1a821cdb58498cbb52f4706545a089 AddressID: type: string pattern: ^adr_[a-f0-9]{32}$ example: adr_78de60204f574a64be88ba9bd94a049f InlineRecipientRequest: type: object additionalProperties: false required: - phone_number - address properties: name: type: string minLength: 1 maxLength: 255 phone_number: type: string pattern: ^\+[1-9][0-9]{7,14}$ address: $ref: '#/components/schemas/CreateAddressRequest' Pickup: type: object additionalProperties: false required: - name - contact - address - latitude - longitude properties: name: type: string minLength: 1 maxLength: 255 contact: type: string minLength: 5 maxLength: 64 address: type: string minLength: 2 maxLength: 500 latitude: type: number format: double minimum: -90 maximum: 90 longitude: type: number format: double minimum: -180 maximum: 180 PickupLocationID: type: string pattern: ^pkp_[a-f0-9]{32}$ example: pkp_9b2f0c1e4d5a4b6c8e7f1a2b3c4d5e6f DeliveryPaymentRequest: oneOf: - $ref: '#/components/schemas/CODPaymentRequest' - $ref: '#/components/schemas/NonCODPaymentRequest' discriminator: propertyName: type VehicleType: type: string enum: - bike - minivan example: bike SandboxSimulationRequest: type: object additionalProperties: false required: - scenario description: Sandbox only. Makes the delivery play out a scenario by itself. properties: scenario: $ref: '#/components/schemas/SimulationScenario' step_delay_seconds: type: integer minimum: 1 maximum: 60 default: 5 description: The wait before each step. BulkDeliveryResult: type: object additionalProperties: false required: - created - failed - results properties: created: type: integer minimum: 0 description: Number of items created. failed: type: integer minimum: 0 description: Number of items that failed at creation. results: type: array description: One result per input item, in input order. items: $ref: '#/components/schemas/BulkDeliveryItemResult' ErrorPayload: type: object additionalProperties: false required: - code properties: code: type: string description: Stable machine-readable error code. example: VALIDATION_ERROR details: type: object additionalProperties: true description: >- Optional structured context. Do not parse `message` for control flow. CreateAddressRequest: type: object additionalProperties: false required: - address - latitude - longitude properties: label: type: string maxLength: 64 address: type: string minLength: 2 maxLength: 500 latitude: type: number format: double minimum: -90 maximum: 90 longitude: type: number format: double minimum: -180 maximum: 180 municipality: type: string maxLength: 128 delivery_notes: type: string maxLength: 500 CODPaymentRequest: type: object additionalProperties: false required: - type - goods_value properties: type: type: string const: cod goods_value: type: number format: double exclusiveMinimum: 0 NonCODPaymentRequest: type: object additionalProperties: false required: - type properties: type: type: string enum: - delivery_only - client_billed SimulationScenario: type: string enum: - delivered - cod_settled - cod_partial_collection - cancelled_before_assignment - cancelled_after_assignment - failed - failed_then_retried - outsourced example: failed_then_retried BulkDeliveryItemResult: type: object additionalProperties: false required: - index - status properties: index: type: integer minimum: 0 maximum: 99 description: >- The 0-based position of this item in the request's `deliveries` array. status: type: string enum: - created - failed delivery: $ref: '#/components/schemas/Delivery' error: $ref: '#/components/schemas/BulkDeliveryItemError' oneOf: - title: Created required: - delivery properties: status: const: created - title: Failed required: - error properties: status: const: failed Delivery: type: object additionalProperties: false required: - id - environment - simulated - status - recipient - pickup - dropoff - payment - vehicle_type - currency - requires_custom_quote - created_at - updated_at properties: id: $ref: '#/components/schemas/DeliveryID' external_id: type: - string - 'null' maxLength: 128 reference: type: - string - 'null' description: HaulStow's human-readable delivery reference. example: H-RS83223 environment: $ref: '#/components/schemas/Environment' simulated: type: boolean status: $ref: '#/components/schemas/DeliveryStatus' recipient: $ref: '#/components/schemas/DeliveryRecipient' pickup: $ref: '#/components/schemas/Pickup' dropoff: $ref: '#/components/schemas/DeliveryDropoff' payment: $ref: '#/components/schemas/DeliveryPayment' vehicle_type: $ref: '#/components/schemas/VehicleType' delivery_instructions: type: - string - 'null' currency: type: string const: GHS delivery_fee: type: - number - 'null' format: double minimum: 0 description: '`null` when a manual quote is required.' requires_custom_quote: type: boolean tracking_url: type: - string - 'null' format: uri description: Always `null` for sandbox deliveries. simulation: description: | Sandbox only. The automatic simulation on this delivery, or `null` when none was ever started. Live deliveries do not have this field. oneOf: - $ref: '#/components/schemas/Simulation' - type: 'null' created_at: type: string format: date-time updated_at: type: string format: date-time BulkDeliveryItemError: type: object additionalProperties: false required: - code - message properties: code: type: string description: >- Stable machine-readable error code, as returned by `POST /deliveries`. example: QUOTE_UNAVAILABLE message: type: string DeliveryID: type: string pattern: ^dlv_[a-f0-9]{32}$ example: dlv_3f1a821cdb58498cbb52f4706545a089 Environment: type: string enum: - test - live example: live DeliveryStatus: type: string enum: - booked - assigned - picked_up - in_transit - delivered - failed - cancelled - outsourced example: in_transit DeliveryRecipient: type: object additionalProperties: false required: - id - phone_number properties: id: $ref: '#/components/schemas/RecipientID' name: type: - string - 'null' phone_number: type: string DeliveryDropoff: type: object additionalProperties: false required: - id - address - latitude - longitude properties: id: $ref: '#/components/schemas/AddressID' label: type: - string - 'null' address: type: string latitude: type: number format: double longitude: type: number format: double municipality: type: - string - 'null' delivery_notes: type: - string - 'null' DeliveryPayment: type: object additionalProperties: false required: - type properties: type: type: string enum: - cod - delivery_only - client_billed goods_value: type: number format: double exclusiveMinimum: 0 description: Present only for COD. Simulation: type: object additionalProperties: false required: - scenario - status - step - steps_total - next_step_at properties: scenario: $ref: '#/components/schemas/SimulationScenario' status: type: string enum: - running - completed - stopped - failed step: type: integer minimum: 0 description: How many steps have run so far. steps_total: type: integer minimum: 1 description: How many steps this simulation runs from where it started. next_step_at: type: - string - 'null' format: date-time description: When the next step runs. `null` unless `status` is `running`. example: scenario: failed_then_retried status: running step: 3 steps_total: 8 next_step_at: '2026-10-02T10:15:05Z' headers: XRequestID: description: Correlation ID for the request. schema: type: string example: 01J5T33T75A8S2JCB37Y6Z5Y4N RateLimitLimit: description: Maximum requests available in the current window. schema: type: integer minimum: 0 example: 120 RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer minimum: 0 example: 119 RateLimitReset: description: Unix timestamp in seconds when the current window resets. schema: type: integer format: int64 example: 1787236260 IdempotentReplayed: description: >- Present and `true` when the response was replayed from an earlier completed request. schema: type: boolean example: true RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 1 example: 30 responses: DeliveryBadRequest: description: A required header is missing, or a live key sent a sandbox-only field. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotencyKeyRequired: value: success: false statusCode: 400 message: Idempotency-Key header is required error: code: IDEMPOTENCY_KEY_REQUIRED sandboxOnlyField: value: success: false statusCode: 400 message: sandbox is accepted only with a test key error: code: SANDBOX_ONLY_FIELD Unauthorized: description: >- API key is missing, malformed, revoked, expired, or belongs to another environment. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid: value: success: false statusCode: 401 message: API key is invalid error: code: INVALID_API_KEY revoked: value: success: false statusCode: 401 message: API key has been revoked error: code: API_KEY_REVOKED expired: value: success: false statusCode: 401 message: API key has expired error: code: API_KEY_EXPIRED environment: value: success: false statusCode: 401 message: API key does not match this environment error: code: ENVIRONMENT_MISMATCH Forbidden: description: The authenticated key lacks the operation's required scope. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false statusCode: 403 message: API key lacks the required scope error: code: INSUFFICIENT_SCOPE details: required_scope: deliveries:write IdempotencyConflict: description: >- Idempotency key is missing, in progress, or was reused with a different request. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: value: success: false statusCode: 409 message: Idempotency key was already used with another request error: code: IDEMPOTENCY_CONFLICT inProgress: value: success: false statusCode: 409 message: A request with this idempotency key is still in progress error: code: IDEMPOTENCY_IN_PROGRESS BulkValidationError: description: | The batch is invalid and nothing was created. `BULK_VALIDATION_FAILED` lists each invalid item in `error.details.errors`; `VALIDATION_ERROR` means the batch was empty or had more than 100 items. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: bulkValidation: value: success: false statusCode: 422 message: 2 of 4 deliveries are invalid error: code: BULK_VALIDATION_FAILED details: errors: - index: 1 code: COD_GOODS_VALUE_REQUIRED message: Goods value is required for COD deliveries - index: 3 code: DUPLICATE_EXTERNAL_ID message: external_id is repeated within this request batchSize: value: success: false statusCode: 422 message: deliveries must contain 1 to 100 items error: code: VALIDATION_ERROR RateLimited: description: Rate limit exceeded. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false statusCode: 429 message: Too many requests; please try again later error: code: RATE_LIMIT_EXCEEDED InternalError: description: Unexpected server error. Quote `X-Request-ID` when contacting support. headers: X-Request-ID: $ref: '#/components/headers/XRequestID' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false statusCode: 500 message: Internal server error error: code: INTERNAL_SERVER_ERROR securitySchemes: DeveloperApiKey: type: http scheme: bearer bearerFormat: hsg_live_key_... or hsg_test_key_... description: > A business-bound HaulStow API key. Send `Authorization: Bearer hsg_live_key_...` to the live server or a `hsg_test_key_...` key to the sandbox server. Never expose this key in a browser. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.