External International Delivery

1 API call in this section.

Create International Delivery

External & Carrier Integrations / Deliveries / 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. If payment is wallet and the fee is positive, the fee is moved from usable wallet balance to reserved without a wallet transaction or payment. Confirmation captures it; draft cancellation releases it.

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. Reservation data does not return currency; integrations use tenant configuration.

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-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}