System Settings

5 API calls in this section.

Get Mobile Staging Access

System Configuration / System Settings

GET/system-settings/mobile-staging-access

Returns only safe global mobile staging status to authenticated system administrators: enabled, passcode_configured, and passcode_updated_at. It never returns the PIN or its hash.

Query parameters

Parameter	Type	Description
language	string	Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/system-settings/mobile-staging-access?language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

No saved response example. Use Try it to inspect a staging response.

Update Mobile Staging Access

System Configuration / System Settings

PUT/system-settings/mobile-staging-access

Enables/disables the global Operation-app staging switch and optionally replaces its PIN. Requires system_admin. A new 8–12 digit PIN replaces the old PIN without asking for it; omit passcode to retain the existing hash. Enabling is rejected until a PIN exists. Raw PINs are redacted from audits.

Query parameters

Parameter	Type	Description
language	string	Example: en

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
enabled	boolean	—
passcode	string	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/system-settings/mobile-staging-access?language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "enabled": true,6  "passcode": "12345678"7}'

Response examples

No saved response example. Use Try it to inspect a staging response.

Get System Settings

System Configuration / System Settings

GET/system-settings

Retrieve system settings. Requires system admin access.

The general bucket includes language settings such as default_system_language and tenant_available_languages. general.unit_size.settings.missing_unit_size_fallback controls delivery orders that provide neither a unit size nor usable measurements. Its allowed values are service_min, service_half, service_max, and error; missing_unit_size_fallback_options returns every value with a localized label for the admin selector. The warehouse.package setting includes auto_execute_delivery_order_on_receive, which defaults to false and controls whether fully received warehouse items auto-activate related draft delivery orders.

Response

Wallet Settings returns two entries under system_settings.wallet: wallet_minimum_balance.settings.minimum_balance for Drivers Minimum Balance and customer_wallet_minimum_balance.settings.minimum_balance for Customer Minimum Balance. These are the defaults used when a tenant has no override of the corresponding key. The new customer default starts at the previous shared value.

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for response localization (e.g., 'en') Language code for response localization (Optional, default: en) Language code for response localization (e.g., 'en') Example: en

Headers

Parameter	Type	Description
AuthorizationRequired	string	Bearer token for authentication (required) Bearer token for authentication (required) Example: Bearer {{access_token}}
X-API-Key	string	Alternative authentication method using API key Alternative authentication method using API key

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/system-settings?language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "X-API-Key: "

Response examples

200 · Success Response401 · Error - Unauthorized403 · Error - Forbidden (Not System Admin)500 · Error - Database Error200 · Success (200 OK)

200OK

Response body

json

1{2  "success": true,3  "message": "System settings retrieved successfully",4  "system_settings": {5    "general": {6      "default_system_language": {7        "settings": {8          "default_language": "en"9        },10        "description": "Default language used as the system-wide localization fallback"11      },12      "tenant_available_languages": {13        "settings": {14          "available_languages": [15            "en",16            "ar",17            "ku",18            "fa"19          ],20          "language_names": {21            "en": "English",22            "ar": "Arabic",23            "ku": "Kurdish",24            "fa": "Farsi"25          }26        },27        "description": "Languages available for tenant and app language configuration"28      }29    },30    "warehouse": {31      "package": {32        "settings": {33          "handoff_required": false,34          "auto_execute_delivery_order_on_receive": false35        },36        "description": "Warehouse package handling settings. auto_execute_delivery_order_on_receive controls whether a related draft delivery order is automatically moved to pending after its warehouse item is fully received."37      }38    }39  }40}

Update System Settings

System Configuration / System Settings

PUT/system-settings

Update system settings. Requires system admin access.

If setting_key = unit_size, send settings.missing_unit_size_fallback as one of service_min, service_half, service_max, or error. Existing unit calculation fields are preserved, and the response returns canonical missing_unit_size_fallback_options with localized labels.

If setting_key = package, settings may include:

Both fields must be booleans when provided. auto_execute_delivery_order_on_receive=false keeps warehouse receiving behavior unchanged; true lets backend receive logic move related draft delivery orders to pending after their warehouse item is fully received.

If setting_key = default_system_language, settings must be:

If setting_key = tenant_available_languages, settings must be:

If setting_key = phone_login, settings must be:

If setting_key = storefront_custom_domain_vercel, settings must be:

Field purpose

• api_token: authenticates Edge Function calls to Vercel for add, verify, inspect, and delete domain operations.

• project_id: tells the backend which Vercel project owns the storefront custom domains.

• team_id: needed when the Vercel project belongs to a team/workspace instead of a personal account.

• deploy_hook_url: optional fallback used by the admin redeploy action when you want deploy-hook based rebuilds.

Rules

• api_token is required.

• project_id is required.

• team_id is optional.

• deploy_hook_url is optional but must be a valid URL when present.

Response

Wallet minimum settings

send { "setting_key": "customer_wallet_minimum_balance", "settings": { "minimum_balance": -1000000 } } for customers or use setting_key=wallet_minimum_balance for drivers. Each accepts only minimum_balance as a required finite JSON number. Strings, missing values, arrays, or unknown fields return HTTP 400 with localized validation errors. Negative values allow debt down to the limit; zero allows no debt. The response returns the saved system_settings.settings.minimum_balance. Frontend integration: show both fields in Wallet Settings and save each key independently. Customer balance checks use only the customer key; driver operations use the existing key.

Query parameters

Parameter	Type	Description
languageOptional	string	Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Language code for response localization (Optional, default: en) Language code for localized response messages (e.g., 'en') Example: en

Headers

Parameter	Type	Description
AuthorizationRequired	string	Bearer token for authentication (required) Bearer token for authentication (required) Example: Bearer {{access_token}}
Content-TypeRequired	string	application/json (required) application/json (required) Example: application/json
X-API-Key	string	Alternative authentication method using API key Alternative authentication method using API key

Body parameters

Parameter	Type	Description
setting_keyRequired	string	(required) (required)
settingsRequired	object	(required) (required)
settings.actions	array<object>	—
settings.actions.key	string	—
settings.actions.label	string	—
settings.types	array<object>	—
settings.types.code	string	—
settings.types.label	string	—
settings.types.allowed_statuses	array<string>	—
settings.types.action_keys	array<string>	—

More examples

If setting_key = package, settings may include

json

1{2  "handoff_required": false,3  "auto_execute_delivery_order_on_receive": false4}

If setting_key = default_system_language, settings must be

json

1{2  "default_language": "en"3}

If setting_key = tenant_available_languages, settings must be

json

1{2  "available_languages": [3    "en",4    "ar",5    "ku",6    "fa"7  ]8}

If setting_key = phone_login, settings must be

json

1{2  "allowed_countries": [3    {4      "code": "IN",5      "name": "India",6      "dial_code": "+91"7    }8  ],9  "default_country": {10    "code": "IN",11    "name": "India",12    "dial_code": "+91"13  }14}

If setting_key = storefront_custom_domain_vercel, settings must be

json

1{2  "api_token": "vercel_api_token_here",3  "project_id": "prj_123456789",4  "team_id": "team_123456789",5  "deploy_hook_url": "https://api.vercel.com/v1/integrations/deploy/prj_123456789/trigger"6}

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/system-settings?language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --header "X-API-Key: " \5  --data-raw '{6  "setting_key": "exception_types",7  "settings": {8    "actions": [9      {10        "key": "retry",11        "label": "Retry delivery"12      },13      {14        "key": "return_to_sender",15        "label": "Return to sender"16      },17      {18        "key": "cancel",19        "label": "Cancel order"20      }21    ],22    "types": [23      {24        "code": "customer_refused",25        "label": "Customer refused",26        "allowed_statuses": [27          "pending",28          "assigned",29          "en_route_to_pickup",30          "in_transit"31        ],32        "action_keys": [33          "retry",34          "return_to_sender",35          "cancel"36        ]37      }38    ]39  }40}'

Response examples

200 · Success Response401 · Error - Unauthorized403 · Error - Forbidden (Not System Admin)500 · Error - Database Error200 · Success (200 OK)

200OK

Response body

json

1{2  "success": true,3  "message": "System settings updated successfully",4  "systemSettings": {5    "id": "uuid",6    "setting_key": "exception_types",7    "settings": {8      "actions": [9        {10          "key": "retry",11          "label": "Retry delivery"12        },13        {14          "key": "return_to_sender",15          "label": "Return to sender"16        },17        {18          "key": "cancel",19          "label": "Cancel order"20        }21      ],22      "types": [23        {24          "code": "customer_refused",25          "label": "Customer refused",26          "allowed_statuses": [27            "pending",28            "assigned",29            "en_route_to_pickup",30            "in_transit"31          ],32          "action_keys": [33            "retry",34            "return_to_sender",35            "cancel"36          ]37        }38      ]39    },40    "is_active": true,41    "created_at": "timestamp",42    "updated_at": "timestamp",43    "updated_by": "uuid"44  }45}

Update Transfer Manifest Defaults

System Configuration / System Settings

PUT/system-settings

System-admin update for tenant-scoped transfer-manifest defaults. settings.branch_only_destinations=false preserves branch-or-address manifest order destinations. When true, all three manifest destination/order-creation endpoints require destination_branch_id; address-only requests return HTTP 400 manifest_destination_branch_required. settings.allow_warehouse_staging_without_assigned_driver is boolean and defaults to false; when enabled, unassigned Transfer Manifest P&D staging may use the tenant assignment fallback driver. available_delivery_service_ids is an array of service UUIDs and defaults to [], meaning no G2G limitation. When non-empty, default_delivery_service_id must be included. The partial object is merged with existing defaults.

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
setting_key	string	—
settings	object	—
settings.branch_only_destinations	boolean	—
settings.allow_warehouse_staging_without_assigned_driver	boolean	—
settings.default_delivery_service_id	null	—
settings.available_delivery_service_ids	array	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/system-settings" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "setting_key": "transfer_manifest",6  "settings": {7    "branch_only_destinations": false,8    "allow_warehouse_staging_without_assigned_driver": false,9    "default_delivery_service_id": null,10    "available_delivery_service_ids": []11  }12}'

Response examples

200 · Updated400 · Invalid branch-only destination value

200Updated

Response body

json

1{2  "success": true,3  "message": "system_settings_updated_successfully",4  "system_settings": {5    "setting_key": "transfer_manifest",6    "scope": "tenant",7    "settings": {8      "branch_only_destinations": false9    }10  }11}