External International Delivery

2 API calls in this section.

This endpoint uses the global External API JSON response contract

success is always boolean, error is null on success or a stable snake_case code on failure, and message is always a localized readable message. Existing delivery, inventory, receiving-order, validation-detail, and other endpoint-specific fields remain unchanged.

Create International Delivery

External & Carrier Integrations / External International Delivery

POST/external/international-deliveries

Create an international delivery using a warehouse pickup and a delivery address object.

• Requires X-API-Key authentication.

Key behavior

• Pickup address is resolved from warehouse_id; do not send pickup_address.

• Creates inventory items from products.

• Creates a receiving order tied to the created inventory item(s).

• Creates the delivery with status draft.

Notes

• reference_number for the receiving order is auto-generated as RIO-<timestamp>.

• receiving_orders.status is created as pending.

• delivery.status is created as draft.

External delivery response enrichment

• Top-level response includes currency_code. Each delivery object also includes currency_code.

• delivery.track_order is the public tracking page URL built as {track_url}/tracking?code={delivery_code}; track_url resolves from tenant track_orders.track_url, then the WEB_URL secret, then system external_links.delivery_customer_portal_url, then https://staging-app.ondi.io.

• delivery.customer_receipt_url is a signed receipt URL when a successful delivery payment receipt exists; otherwise null.

• delivery.status_updated_at is derived from the latest status_updates[].timestamp, falling back to updated_at.

• delivery.delivery_services includes description and image_url when available.

• delivery.proofs is grouped as { pickup: [], delivery: [] } using OnDi proof records.

• delivery.proof_of_pickup and delivery.proof_of_delivery are aggregate proof summaries when captured, shaped as { signature, photos }.

• delivery.failure_reason is populated from delivery_failure_reason when present.

• Top-level delivery_type is not returned; use delivery.delivery_services.delivery_type.

• Response payment_method is documented as wallet | cash.

Headers

Parameter	Type	Description
X-API-Key	string	Example: {{api_key}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
warehouse_idRequired	string	Warehouse UUID used as the pickup source. Warehouse UUID used as the pickup source.
delivery_addressRequired	object	Delivery address payload. Delivery address payload.
delivery_address.latRequired	number	Delivery latitude. Delivery latitude.
delivery_address.lngRequired	number	Delivery longitude. Delivery longitude.
delivery_address.full_addressRequired	string	Full delivery address text. Full delivery address text.
delivery_address.cityOptional	string	City name. City name.
delivery_address.stateOptional	string	State or province. State or province.
delivery_address.countryOptional	string	Country name or code. Country name or code.
delivery_address.postal_codeOptional	string	Postal or ZIP code. Postal or ZIP code.
delivery_address.contact_infoOptional	object	Receiver contact details. Receiver contact details.
delivery_address.contact_info.full_nameOptional	string	Receiver full name. Receiver full name.
delivery_address.contact_info.phoneOptional	string	Receiver phone number. Receiver phone number.

Show 44 more body fields

Additional body parameters

Parameter	Type	Description
delivery_address.contact_info.emailOptional	string	Receiver email address. Receiver email address.
delivery_address.contact_info.tel_phoneOptional	string	Alternate receiver phone value used by some integrations. Alternate receiver phone value used by some integrations.
customer_id	string	Required for non-customer callers. For customer/no-role callers it is auto-filled from the authenticated user. Required for non-customer callers. For customer/no-role callers it is auto-filled from the authenticated user.
delivery_service_idRequired	string	Delivery service UUID. Delivery service UUID.
payer_typeRequired	string	Supported values: sender, receiver. Supported values: sender, receiver.
payment_methodRequired	string	Accepted values: wallet, cash, cod. cod is normalized to cash. Accepted values: wallet, cash, cod. cod is normalized to cash.
external_reference_idRequired	string	External reference. When delivery_external_reference.unique_per_customer=true (default), it must be unique among root orders for the same tenant customer; when false, duplicates are allowed. External reference. When delivery_external_reference.unique_per_customer=true (default), it must be unique among root orders for the same tenant customer; when false, duplicates are allowed.
order_numberRequired	string	Customer-facing order number used on shipment labels. Customer-facing order number used on shipment labels.
cod_amountOptional	number	Cash-on-delivery amount. Use 0 when not applicable. Cash-on-delivery amount. Use 0 when not applicable.
notesOptional	string	General delivery / receiving notes. General delivery / receiving notes.
scheduled_pickup_timeOptional	string	ISO 8601 datetime for planned pickup. ISO 8601 datetime for planned pickup.
scheduled_delivery_timeOptional	string	ISO 8601 datetime for planned delivery. ISO 8601 datetime for planned delivery.
unit_sizeOptional	number	Positive unit size override. If omitted, the backend uses products totals and may derive size from package_details.items. Positive unit size override. If omitted, the backend uses products totals and may derive size from package_details.items.
tracking_providerOptional	string	Tracking provider identifier. Tracking provider identifier.
package_detailsOptional	object	Parcel-level metadata. Parcel-level metadata.
package_details.special_instructionsOptional	string	Handling / packing notes. Handling / packing notes.
package_details.itemsOptional	array<object>	Parcel items used for unit-size calculation when needed. Parcel items used for unit-size calculation when needed.
package_details.items[].nameOptional	string	Item name. Item name.
package_details.items[].descriptionOptional	string	Item description. Item description.
package_details.items[].quantityOptional	number	Quantity for unit-size calculation. Defaults to 1 when omitted. Quantity for unit-size calculation. Defaults to 1 when omitted.
package_details.items[].weightOptional	number	Item weight. Item weight.
package_details.items[].lengthOptional	number	Item length. Item length.
package_details.items[].widthOptional	number	Item width. Item width.
package_details.items[].heightOptional	number	Item height. Item height.
productsRequired	array<object>	Minimum 1 product. Used to create inventory items. Minimum 1 product. Used to create inventory items.
products[].nameRequired	string	Product name. Product name.
products[].skuRequired	string	SKU. SKU.
products[].barcodeRequired	string	Barcode. Barcode.
products[].unit_sizeRequired	number	Unit size for this product line. Unit size for this product line.
products[].quantityRequired	number	Quantity for this product line. Quantity for this product line.
products[].descriptionOptional	string	Product description. Product description.
products[].brandOptional	string	Brand name. Brand name.
products[].modelOptional	string	Model name or number. Model name or number.
products[].categoryOptional	string	Product category. Product category.
products[].subcategoryOptional	string	Product subcategory. Product subcategory.
senderRequired	object	Sender details used for labels / inventory linkage. Sender details used for labels / inventory linkage.
sender.nameRequired	string	Sender name. Sender name.
sender.phoneRequired	string	Sender phone number. Sender phone number.
sender.full_addressOptional	string	Sender full address. Recommended; omitted values fall back to an empty string in label data. Sender full address. Recommended; omitted values fall back to an empty string in label data.
expected_arrival_dateOptional	string	Receiving order ETA date (YYYY-MM-DD). Receiving order ETA date (YYYY-MM-DD).
receiving_detailsOptional	object	Free-form receiving order metadata. Example keys: carrier, incoterms. Free-form receiving order metadata. Example keys: carrier, incoterms.
actual_arrival_dateOptional	string | null	Present in the sample payload, but not currently consumed by the external handler. Present in the sample payload, but not currently consumed by the external handler.
received_byOptional	string | null	Present in the sample payload, but not currently consumed by the external handler. Present in the sample payload, but not currently consumed by the external handler.
supplier_idOptional	string | null	Supplier identifier passed into receiving-order creation. Supplier identifier passed into receiving-order creation.

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/external/international-deliveries" \2  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "warehouse_id": "{{warehouse_id}}",6  "delivery_address": {7    "lat": {{delivery_lat}},8    "lng": {{delivery_lng}},9    "full_address": "{{delivery_full_address}}",10    "city": "{{delivery_city}}",11    "state": "{{delivery_state}}",12    "country": "{{delivery_country}}",13    "postal_code": "{{delivery_postal_code}}",14    "contact_info": {15      "full_name": "{{receiver_name}}",16      "phone": "{{receiver_phone}}",17      "email": "{{receiver_email}}",18      "tel_phone": "{{receiver_tel}}"19    }20  },21  "customer_id": "{{customer_id}}",22  "delivery_service_id": "{{delivery_service_id}}",23  "payer_type": "sender",24  "payment_method": "wallet",25  "external_reference_id": "{{external_reference_id}}",26  "order_number": "{{order_number}}",27  "cod_amount": 0,28  "notes": "International shipment",29  "scheduled_pickup_time": "2024-01-15T10:00:00Z",30  "scheduled_delivery_time": "2024-01-20T18:00:00Z",31  "unit_size": 1,32  "tracking_provider": "internal",33  "package_details": {34    "special_instructions": "International shipment - handle with care",35    "items": [36      {37        "name": "{{item_name}}",38        "description": "{{item_description}}",39        "quantity": 1,40        "weight": 2.5,41        "length": 30,42        "width": 20,43        "height": 1544      }45    ]46  },47  "products": [48    {49      "name": "Widget A",50      "sku": "WIDGET-A",51      "barcode": "1234567890123",52      "unit_size": 1,53      "quantity": 2,54      "description": "Blue widget",55      "brand": "Acme",56      "model": "A1",57      "category": "Widgets",58      "subcategory": "Standard"59    },60    {61      "name": "Gadget B",62      "sku": "GADGET-B",63      "barcode": "9876543210987",64      "unit_size": 1,65      "quantity": 166    }67  ],68  "sender": {69    "name": "{{sender_name}}",70    "phone": "{{sender_phone}}",71    "full_address": "{{sender_full_address}}"72  },73  "expected_arrival_date": "2024-01-19",74  "receiving_details": {75    "carrier": "DHL",76    "incoterms": "DAP"77  },78  "actual_arrival_date": null,79  "received_by": null,80  "supplier_id": null81}'

Replace {{placeholders}} with your own values before sending.

Response examples

201 · Success - Created400 · Error - Unit Size Above Service Maximum409 · Error - Missing tenant_id400 · Error - Validation (products array)404 · Error - Warehouse Not Found400 · Error - Delivery Address Creation Failed400 · Error - External Reference Already Exists500 · Error - Server Error (inventory creation)

201Created

Response body

json

1{2  "success": true,3  "error": null,4  "message": "Delivery created successfully",5  "delivery": {6    "id": "DEL-000001",7    "delivery_code": "DEL-000001"8  },9  "pickup_address_id": "warehouse-address-uuid",10  "delivery_address": {11    "id": "address-uuid",12    "full_address": "456 Broadway..."13  },14  "inventory_item": {15    "id": "item-uuid-1",16    "sku": "WIDGET-A",17    "name": "Widget A"18  },19  "receiving_order": {20    "id": "ro-uuid",21    "reference_number": "RIO-1700000000000",22    "status": "pending"23  }24}

Create International Delivery

External & Carrier Integrations / External International Delivery

POST/external/international-deliveries

Create an international delivery using a warehouse pickup and a delivery address object.

• Requires X-API-Key authentication.

Key behavior

• Pickup address is resolved from warehouse_id; do not send pickup_address.

• Creates inventory items from products.

• Creates a receiving order tied to the created inventory item(s).

• Creates the delivery with status draft.

Notes

• reference_number for the receiving order is auto-generated as RIO-<timestamp>.

• receiving_orders.status is created as pending.

• delivery.status is created as draft.

Headers

Parameter	Type	Description
X-API-Key	string	Example: {{api_key}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
warehouse_idRequired	string	Warehouse UUID used as the pickup source. Warehouse UUID used as the pickup source.
delivery_addressRequired	object	Delivery address payload. Delivery address payload.
delivery_address.latRequired	number	Delivery latitude. Delivery latitude.
delivery_address.lngRequired	number	Delivery longitude. Delivery longitude.
delivery_address.full_addressRequired	string	Full delivery address text. Full delivery address text.
delivery_address.cityOptional	string	City name. City name.
delivery_address.stateOptional	string	State or province. State or province.
delivery_address.countryOptional	string	Country name or code. Country name or code.
delivery_address.postal_codeOptional	string	Postal or ZIP code. Postal or ZIP code.
delivery_address.contact_infoOptional	object	Receiver contact details. Receiver contact details.
delivery_address.contact_info.full_nameOptional	string	Receiver full name. Receiver full name.
delivery_address.contact_info.phoneOptional	string	Receiver phone number. Receiver phone number.

Show 44 more body fields

Additional body parameters

Parameter	Type	Description
delivery_address.contact_info.emailOptional	string	Receiver email address. Receiver email address.
delivery_address.contact_info.tel_phoneOptional	string	Alternate receiver phone value used by some integrations. Alternate receiver phone value used by some integrations.
customer_id	string	Required for non-customer callers. For customer/no-role callers it is auto-filled from the authenticated user. Required for non-customer callers. For customer/no-role callers it is auto-filled from the authenticated user.
delivery_service_idRequired	string	Delivery service UUID. Delivery service UUID.
payer_typeRequired	string	Supported values: sender, receiver. Supported values: sender, receiver.
payment_methodRequired	string	Accepted values: wallet, cash, cod. cod is normalized to cash. Accepted values: wallet, cash, cod. cod is normalized to cash.
external_reference_idRequired	string	External reference. When delivery_external_reference.unique_per_customer=true (default), it must be unique among root orders for the same tenant customer; when false, duplicates are allowed. External reference. When delivery_external_reference.unique_per_customer=true (default), it must be unique among root orders for the same tenant customer; when false, duplicates are allowed.
order_numberRequired	string	Customer-facing order number used on shipment labels. Customer-facing order number used on shipment labels.
cod_amountOptional	number	Cash-on-delivery amount. Use 0 when not applicable. Cash-on-delivery amount. Use 0 when not applicable.
notesOptional	string	General delivery / receiving notes. General delivery / receiving notes.
scheduled_pickup_timeOptional	string	ISO 8601 datetime for planned pickup. ISO 8601 datetime for planned pickup.
scheduled_delivery_timeOptional	string	ISO 8601 datetime for planned delivery. ISO 8601 datetime for planned delivery.
unit_sizeOptional	number	Positive unit size override. If omitted, the backend uses products totals and may derive size from package_details.items. Positive unit size override. If omitted, the backend uses products totals and may derive size from package_details.items.
tracking_providerOptional	string	Tracking provider identifier. Tracking provider identifier.
package_detailsOptional	object	Parcel-level metadata. Parcel-level metadata.
package_details.special_instructionsOptional	string	Handling / packing notes. Handling / packing notes.
package_details.itemsOptional	array<object>	Parcel items used for unit-size calculation when needed. Parcel items used for unit-size calculation when needed.
package_details.items[].nameOptional	string	Item name. Item name.
package_details.items[].descriptionOptional	string	Item description. Item description.
package_details.items[].quantityOptional	number	Quantity for unit-size calculation. Defaults to 1 when omitted. Quantity for unit-size calculation. Defaults to 1 when omitted.
package_details.items[].weightOptional	number	Item weight. Item weight.
package_details.items[].lengthOptional	number	Item length. Item length.
package_details.items[].widthOptional	number	Item width. Item width.
package_details.items[].heightOptional	number	Item height. Item height.
productsRequired	array<object>	Minimum 1 product. Used to create inventory items. Minimum 1 product. Used to create inventory items.
products[].nameRequired	string	Product name. Product name.
products[].skuRequired	string	SKU. SKU.
products[].barcodeRequired	string	Barcode. Barcode.
products[].unit_sizeRequired	number	Unit size for this product line. Unit size for this product line.
products[].quantityRequired	number	Quantity for this product line. Quantity for this product line.
products[].descriptionOptional	string	Product description. Product description.
products[].brandOptional	string	Brand name. Brand name.
products[].modelOptional	string	Model name or number. Model name or number.
products[].categoryOptional	string	Product category. Product category.
products[].subcategoryOptional	string	Product subcategory. Product subcategory.
senderRequired	object	Sender details used for labels / inventory linkage. Sender details used for labels / inventory linkage.
sender.nameRequired	string	Sender name. Sender name.
sender.phoneRequired	string	Sender phone number. Sender phone number.
sender.full_addressOptional	string	Sender full address. Recommended; omitted values fall back to an empty string in label data. Sender full address. Recommended; omitted values fall back to an empty string in label data.
expected_arrival_dateOptional	string	Receiving order ETA date (YYYY-MM-DD). Receiving order ETA date (YYYY-MM-DD).
receiving_detailsOptional	object	Free-form receiving order metadata. Example keys: carrier, incoterms. Free-form receiving order metadata. Example keys: carrier, incoterms.
actual_arrival_dateOptional	string | null	Present in the sample payload, but not currently consumed by the external handler. Present in the sample payload, but not currently consumed by the external handler.
received_byOptional	string | null	Present in the sample payload, but not currently consumed by the external handler. Present in the sample payload, but not currently consumed by the external handler.
supplier_idOptional	string | null	Supplier identifier passed into receiving-order creation. Supplier identifier passed into receiving-order creation.

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/external/international-deliveries" \2  --header "X-API-Key: ${ONDI_TENANT_API_KEY}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "warehouse_id": "{{warehouse_id}}",6  "delivery_address": {7    "lat": {{delivery_lat}},8    "lng": {{delivery_lng}},9    "full_address": "{{delivery_full_address}}",10    "city": "{{delivery_city}}",11    "state": "{{delivery_state}}",12    "country": "{{delivery_country}}",13    "postal_code": "{{delivery_postal_code}}",14    "contact_info": {15      "full_name": "{{receiver_name}}",16      "phone": "{{receiver_phone}}",17      "email": "{{receiver_email}}",18      "tel_phone": "{{receiver_tel}}"19    }20  },21  "customer_id": "{{customer_id}}",22  "delivery_service_id": "{{delivery_service_id}}",23  "payer_type": "sender",24  "payment_method": "wallet",25  "external_reference_id": "{{external_reference_id}}",26  "order_number": "{{order_number}}",27  "cod_amount": 0,28  "notes": "International shipment",29  "scheduled_pickup_time": "2024-01-15T10:00:00Z",30  "scheduled_delivery_time": "2024-01-20T18:00:00Z",31  "unit_size": 1,32  "tracking_provider": "internal",33  "package_details": {34    "special_instructions": "International shipment - handle with care",35    "items": [36      {37        "name": "{{item_name}}",38        "description": "{{item_description}}",39        "quantity": 1,40        "weight": 2.5,41        "length": 30,42        "width": 20,43        "height": 1544      }45    ]46  },47  "products": [48    {49      "name": "Widget A",50      "sku": "WIDGET-A",51      "barcode": "1234567890123",52      "unit_size": 1,53      "quantity": 2,54      "description": "Blue widget",55      "brand": "Acme",56      "model": "A1",57      "category": "Widgets",58      "subcategory": "Standard"59    },60    {61      "name": "Gadget B",62      "sku": "GADGET-B",63      "barcode": "9876543210987",64      "unit_size": 1,65      "quantity": 166    }67  ],68  "sender": {69    "name": "{{sender_name}}",70    "phone": "{{sender_phone}}",71    "full_address": "{{sender_full_address}}"72  },73  "expected_arrival_date": "2024-01-19",74  "receiving_details": {75    "carrier": "DHL",76    "incoterms": "DAP"77  },78  "actual_arrival_date": null,79  "received_by": null,80  "supplier_id": null81}'

Replace {{placeholders}} with your own values before sending.

Response examples

201 · Success - Created400 · Error - Missing tenant_id400 · Error - Validation (products array)404 · Error - Warehouse Not Found400 · Error - Delivery Address Creation Failed400 · Error - External Reference Already Exists500 · Error - Server Error (inventory creation)

201Created

Response body

json

1{2  "success": true,3  "error": null,4  "message": "Delivery created successfully",5  "delivery": {6    "id": "DEL-INT-000001",7    "status": "draft",8    "tenant_id": "tenant-uuid",9    "external_reference_id": "EXT-REF-INT-123",10    "customer_id": "customer-uuid",11    "delivery_service_id": "service-uuid",12    "payer_type": "sender",13    "payment_method": "wallet",14    "delivery_fee": 45,15    "cod_amount": 0,16    "notes": "International shipment",17    "unit_size": 1,18    "tracking_provider": "internal",19    "carrier_type": "internal",20    "pickup_warehouse_id": "warehouse-uuid",21    "dropoff_warehouse_id": null,22    "pickup_location_id": "warehouse-address-uuid",23    "delivery_location_id": "address-uuid",24    "receiver_user_id": null,25    "assigned_carrier_id": null,26    "assigned_to_user_id": null,27    "package_details": {28      "special_instructions": "International shipment - handle with care",29      "items": [30        {31          "name": "Item 1",32          "description": "Widget",33          "quantity": 1,34          "weight": 2.535        }36      ]37    },38    "scheduled_pickup_time": "2024-01-15T10:00:00Z",39    "scheduled_delivery_time": "2024-01-20T18:00:00Z",40    "started_at": null,41    "picked_up_at": null,42    "delivered_at": null,43    "cancelled_at": null,44    "delivery_failure_reason": null,45    "created_at": "2024-01-15T08:00:00Z",46    "updated_at": "2024-01-15T08:00:00Z",47    "barcode": "DEL-INT-000001",48    "delivery_code": "DEL-INT-000001"49  },50  "pickup_address_id": "warehouse-address-uuid",51  "delivery_address": {52    "id": "address-uuid",53    "full_address": "456 Broadway, New York, NY 10013",54    "latitude": 40.7589,55    "longitude": -73.9851,56    "city": "New York",57    "state": "NY",58    "country": "US",59    "postal_code": "10013",60    "contact_info": {61      "full_name": "Jane Receiver",62      "phone": "+1-555-0200",63      "email": "[email protected]"64    }65  },66  "inventory_item": {67    "id": "item-uuid-1",68    "sku": "WIDGET-A",69    "name": "Widget A"70  },71  "receiving_order": {72    "id": "ro-uuid",73    "reference_number": "RIO-1700000000000",74    "status": "pending"75  }76}