Skip to main content

Create a delivery order

Use the external delivery API to send orders from a tenant’s shop or back office into OnDi.

1. Set up your tenant credential​

Use an approved API key whose owner belongs to the tenant. Keep the key on your server. Your tenant must already have a delivery service and a customer who can use it.

export ONDI_BASE_URL="https://staging-api.ondi.io/functions/v1"
export ONDI_TENANT_API_KEY="your-tenant-api-key"
export TENANT_ID="your-tenant-uuid"

2. Choose a delivery service​

Read the tenant’s services and select the service ID for this order. Confirm its delivery type, price and size limits before creating the order.

curl "$ONDI_BASE_URL/external/delivery-services?tenant_id=$TENANT_ID" \
  --header "X-API-Key: $ONDI_TENANT_API_KEY"

The delivery price endpoint can quote the order before submission.

3. Submit the order​

Save the body below as order.json, replacing the customer and service IDs, addresses and order reference with your tenant’s values. The customer and service must belong to that tenant. Customer-role credentials can infer their own customer ID; staff-owned credentials must provide it.

{
  "customer_id": "your-customer-uuid",
  "delivery_service_id": "your-delivery-service-uuid",
  "pickup_address": {
    "lat": 36.1901,
    "lng": 44.0092,
    "full_address": "Merchant pickup address"
  },
  "delivery_address": {
    "lat": 36.2050,
    "lng": 44.0250,
    "full_address": "Customer delivery address"
  },
  "payer_type": "sender",
  "payment_method": "cash",
  "external_reference_id": "shop-order-001",
  "unit_size": 1,
  "is_draft": true
}

unit_size must fit the selected service. Choose a new external reference for each order according to the tenant’s reference policy. This example creates a persisted draft order; it is not a dry run.

curl --request POST "$ONDI_BASE_URL/external/deliveries" \
  --header "X-API-Key: $ONDI_TENANT_API_KEY" \
  --header "Content-Type: application/json" \
  --data @order.json

4. Save the returned order reference​

A successful create returns HTTP 201 with success, error, message, currency_code and delivery. The external response’s delivery.id contains the delivery code. Save that returned reference for later tracking and detail requests.

Check the response before advancing your order workflow. Authentication, tenant ownership, service eligibility, payment and address validation can reject a request. The external delivery reference contains the full contract and examples.

Authentication · Complete Markdown reference