Bulk Delivery Order Creations

10 API calls in this section.

Request Signed Upload URL

Delivery & Last-Mile / Bulk Delivery Order Creations

POST/delivery/bulk-order-creations/upload-url?tenant_id=&language=en

Step 1 of the bulk import flow. Returns a one-time signed PUT URL the client uploads the file to. The returned file_key must be passed back to Create Bulk Order Creation Job. Request Body: - file_name (required): original file name; extension must be csv, xls, or xlsx. - file_size_bytes (optional): if provided, must be ≤ 15 MB (15728640 bytes). Validation: - Unsupported extension → 400 unsupported_file_extension - File too large → 413 file_too_large (limit returned in response) Permissions: manage:operations:tenant or system admin.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request POST "$ONDI_BASE_URL/delivery/bulk-order-creations/upload-url?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "file_name": "orders_batch_a.csv",7  "file_size_bytes": 5242888}'

Request body

json

1{2  "file_name": "orders_batch_a.csv",3  "file_size_bytes": 5242884}

Query parameters

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Preferred language for response messages

Request body fields

file_nameExample

string

Example field from the request body.

file_size_bytesExample

number

Example field from the request body.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Content-TypeOptional

header string

application/json

Responses

Success Response200OK

Error - Unsupported Extension400Bad Request

Error - File Too Large413Payload Too Large

Upload File To Signed URL (Client Side)

Delivery & Last-Mile / Bulk Delivery Order Creations

PUT/{{upload_url}}

Step 2 of the bulk import flow. Client PUTs the file bytes directly to the signed URL returned by Request Signed Upload URL. No tenant headers — the URL is pre-authorized. Use the matching Content-Type: - text/csv for .csv - application/vnd.ms-excel for .xls - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for .xlsx

Most OnDi APIs require an authenticated session or service token. Public endpoints are marked by their path and module context.

Request

curl

1curl --request PUT "$ONDI_BASE_URL/{{upload_url}}" \2  --header "Content-Type: text/csv"

Path parameters

upload_urlRequired

path string

Variable used inside the request path.

Headers

Content-TypeOptional

header string

text/csv

Responses

No response example is available for this endpoint yet.

Create Bulk Order Creation Job

Delivery & Last-Mile / Bulk Delivery Order Creations

POST/delivery/bulk-order-creations?tenant_id=&language=en

Step 3 of the bulk import flow. Creates the job row, verifies the file at file_key exists in storage, then kicks off the background worker. Returns 202 with the job row. Request Body: - name (optional): human-friendly label for the import - source_view (required): dispatcher | admin - customer_id (required, UUID): tenant customer the deliveries are billed to / created for - delivery_service_id (required, UUID): determines delivery_type_id server-side; do NOT send delivery_type_id - payer_type (required): sender | receiver - payment_method (required): wallet | cod | card | etc. - mappings (required, object): maps your CSV header names → worker logical fields - total_records (optional, int): client-side row count for UI; the worker reads the actual count from the file - file_key (required): exact value returned by upload-url — the server uses the full storage key as the idempotency token (same file_key returns the existing job) - file_kind (required): csv | xls | xlsx - file_size_bytes (optional) Logical fields (used as mappings values): - Required: pickup_full_address, pickup_latitude, pickup_longitude, pickup_city, pickup_country, delivery_full_address, delivery_latitude, delivery_longitude, delivery_city, delivery_country, delivery_contact_name, delivery_contact_phone - Optional: external_reference_id, cod_amount, package_special_instructions, package_items (CSV cell holds a JSON array string) Row behavior: - unit_size is calculated from package_items using the same package-based logic as direct delivery creation. - If external_reference_id already exists on another delivery, that row is marked failed with external_reference_id_already_present. Permissions: manage:operations:tenant or system admin.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request POST "$ONDI_BASE_URL/delivery/bulk-order-creations?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "name": "Q2 storefront orders – batch A",7  "source_view": "dispatcher",8  "customer_id": "uuid",9  "delivery_service_id": "uuid",10  "payer_type": "sender",11  "payment_method": "wallet",12  "mappings": {13    "Pickup Address": "pickup_full_address",14    "Pickup Lat": "pickup_latitude",15    "Pickup Lng": "pickup_longitude",16    "Pickup City": "pickup_city",17    "Pickup Country": "pickup_country",18    "Drop Address": "delivery_full_address",19    "Drop Lat": "delivery_latitude",20    "Drop Lng": "delivery_longitude",21    "Drop City": "delivery_city",22    "Drop Country": "delivery_country",23    "Recipient Name": "delivery_contact_name",24    "Recipient Phone": "delivery_contact_phone",25    "Reference": "external_reference_id",26    "COD": "cod_amount",27    "Notes": "package_special_instructions",28    "Items": "package_items"29  },30  "total_records": 50,31  "file_key": "imports/<tenant_id>/<uuid>/original.csv",32  "file_kind": "csv",33  "file_size_bytes": 52428834}'

Request body

json

1{2  "name": "Q2 storefront orders – batch A",3  "source_view": "dispatcher",4  "customer_id": "uuid",5  "delivery_service_id": "uuid",6  "payer_type": "sender",7  "payment_method": "wallet",8  "mappings": {9    "Pickup Address": "pickup_full_address",10    "Pickup Lat": "pickup_latitude",11    "Pickup Lng": "pickup_longitude",12    "Pickup City": "pickup_city",13    "Pickup Country": "pickup_country",14    "Drop Address": "delivery_full_address",15    "Drop Lat": "delivery_latitude",16    "Drop Lng": "delivery_longitude",17    "Drop City": "delivery_city",18    "Drop Country": "delivery_country",19    "Recipient Name": "delivery_contact_name",20    "Recipient Phone": "delivery_contact_phone",21    "Reference": "external_reference_id",22    "COD": "cod_amount",23    "Notes": "package_special_instructions",24    "Items": "package_items"25  },26  "total_records": 50,27  "file_key": "imports/<tenant_id>/<uuid>/original.csv",28  "file_kind": "csv",29  "file_size_bytes": 52428830}

Query parameters

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Preferred language for response messages

Request body fields

nameExample

string

Example field from the request body.

source_viewExample

string

Example field from the request body.

customer_idExample

string

Example field from the request body.

delivery_service_idExample

string

Example field from the request body.

payer_typeExample

string

Example field from the request body.

payment_methodExample

string

Example field from the request body.

mappingsExample

object

Example field from the request body.

mappings.Pickup AddressExample

string

Example field from the request body.

mappings.Pickup LatExample

string

Example field from the request body.

mappings.Pickup LngExample

string

Example field from the request body.

mappings.Pickup CityExample

string

Example field from the request body.

mappings.Pickup CountryExample

string

Example field from the request body.

mappings.Drop AddressExample

string

Example field from the request body.

mappings.Drop LatExample

string

Example field from the request body.

mappings.Drop LngExample

string

Example field from the request body.

mappings.Drop CityExample

string

Example field from the request body.

mappings.Drop CountryExample

string

Example field from the request body.

mappings.Recipient NameExample

string

Example field from the request body.

mappings.Recipient PhoneExample

string

Example field from the request body.

mappings.ReferenceExample

string

Example field from the request body.

mappings.CODExample

string

Example field from the request body.

mappings.NotesExample

string

Example field from the request body.

mappings.ItemsExample

string

Example field from the request body.

total_recordsExample

number

Example field from the request body.

file_keyExample

string

Example field from the request body.

file_kindExample

string

Example field from the request body.

file_size_bytesExample

number

Example field from the request body.

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Content-TypeOptional

header string

application/json

Responses

Success Response202Accepted

Idempotent Replay200OK

Error - Uploaded File Not Found400Bad Request

Row Failure - Duplicate External Reference202Accepted

Error - File Key Tenant Mismatch400Bad Request

Error - Insufficient Permissions403Forbidden

List Bulk Order Creations

Delivery & Last-Mile / Bulk Delivery Order Creations

GET/delivery/bulk-order-creations?page=1&limit=20&status=&search=&tenant_id=&language=en

Paginated list of bulk import jobs for the current tenant, newest first. Permissions: manage:operations:tenant or system admin.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/delivery/bulk-order-creations?page=1&limit=20&status=&search=&tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Query parameters

pageOptional

query string

1

Page number for pagination

limitOptional

query string

20

Items per page (max 200)

statusOptional

query string

Filter by status (pending | processing | completed | failed)

searchOptional

query string

ilike match on name OR idempotency_key

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Preferred language for response messages

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Success Response200OK

Get Bulk Order Creation

Delivery & Last-Mile / Bulk Delivery Order Creations

GET/delivery/bulk-order-creations/:jobId?tenant_id=&language=en

Returns the full job row plus signed download URLs (original_signed_url, success_signed_url, failed_signed_url), the event_timeline array (milestones: file_accepted, mapping_received, import_started, import_completed / import_failed), and failed_order_logs (per-row diagnostics). Permissions: manage:operations:tenant or system admin.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/delivery/bulk-order-creations/:jobId?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

jobIdRequired

path string

uuid

Bulk order creation job ID

Query parameters

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Preferred language for response messages

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Success Response200OK

Error - Job Not Found404Not Found

Download Success CSV

Delivery & Last-Mile / Bulk Delivery Order Creations

GET/delivery/bulk-order-creations/:jobId/success-csv?tenant_id=&language=en

302 redirect to a signed URL for success.csv. Each CSV row carries the original CSV columns plus a delivery_id column. Returns 404 csv_not_ready if the worker has not yet generated the file.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/delivery/bulk-order-creations/:jobId/success-csv?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

jobIdRequired

path string

uuid

Bulk order creation job ID

Query parameters

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Preferred language for response messages

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Redirect To Signed URL302Found

Download Failed CSV

Delivery & Last-Mile / Bulk Delivery Order Creations

GET/delivery/bulk-order-creations/:jobId/failed-csv?tenant_id=&language=en

302 redirect to a signed URL for failed.csv. Each CSV row carries the original CSV columns plus row_number, error_field, error_code columns. Returns 404 csv_not_ready if the worker has not yet generated the file.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request GET "$ONDI_BASE_URL/delivery/bulk-order-creations/:jobId/failed-csv?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

jobIdRequired

path string

uuid

Bulk order creation job ID

Query parameters

tenant_idOptional

query string

Tenant ID (optional if in auth token)

languageOptional

query string

en

Preferred language for response messages

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Redirect To Signed URL302Found

Resume Job (Internal Cron)

Delivery & Last-Mile / Bulk Delivery Order Creations

POST/delivery/bulk-order-creations/:jobId/_resume

Internal cron-only hook invoked by the watchdog when a processing job's lease has expired. Re-triggers the worker, which re-runs all rows from the start; rows that already produced a delivery for the same bulk job are counted as success on recovery, while external-reference collisions with other deliveries remain row failures. Skips authentication.

Most OnDi APIs require an authenticated session or service token. Public endpoints are marked by their path and module context.

Request

curl

1curl --request POST "$ONDI_BASE_URL/delivery/bulk-order-creations/:jobId/_resume" \2  --header "Authorization: Bearer $ONDI_ACCESS_TOKEN"

Path parameters

jobIdRequired

path string

uuid

Bulk order creation job ID

Responses

Success Response200OK

Abort Job

Delivery & Last-Mile / Bulk Delivery Order Creations

POST/delivery/bulk-order-creations/:jobId/abort?tenant_id=&language=en

Marks a pending or processing job as cancelled and stops the worker from processing remaining rows. The job's worker_lease_id is cleared — any in-flight worker invocation will fail its next refreshLease call and exit cleanly. Already-created deliveries are kept (not deleted automatically). Use DELETE /:id/deliveries if you want to remove them. Errors: - job_not_found 404 — unknown ID or wrong tenant - job_already_terminal 409 — job status is already completed, failed, or cancelled - insufficient_permissions 403 Permissions: manage:operations:tenant or system admin.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request POST "$ONDI_BASE_URL/delivery/bulk-order-creations/:jobId/abort?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

jobIdRequired

path string

uuid

Bulk order creation job ID

Query parameters

tenant_idOptional

query string

Tenant ID

languageOptional

query string

en

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Success Response200OK

Error - Already Terminal409Conflict

Error - Not Found404Not Found

Delete Job Deliveries

Delivery & Last-Mile / Bulk Delivery Order Creations

DELETE/delivery/bulk-order-creations/:jobId/deliveries?tenant_id=&language=en

Soft-deletes all delivery records (deleted_at set to now) that were created by this bulk import job. Only allowed when the job is in a terminal state (cancelled, completed, or failed). If the job is still pending or processing, abort it first. Returns: deleted_count — number of deliveries that were soft-deleted. Errors: - job_not_found 404 - job_still_running 409 — job is still active; abort first - insufficient_permissions 403 Permissions: manage:operations:tenant or system admin.

Send a bearer token in the Authorization header for an authenticated OnDi user session.

Request

curl

1curl --request DELETE "$ONDI_BASE_URL/delivery/bulk-order-creations/:jobId/deliveries?tenant_id=&language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

jobIdRequired

path string

uuid

Bulk order creation job ID

Query parameters

tenant_idOptional

query string

Tenant ID

languageOptional

query string

en

Headers

AuthorizationOptional

header string

Bearer {{access_token}}

Responses

Success Response200OK

Error - Job Still Running409Conflict

Error - Not Found404Not Found