Skip to Content
Welcome to Zendera Knowledge Hub
API DocumentationOrders Import

Orders Import API

v3

Import single or multiple orders into the Zendera system with comprehensive support for hierarchical products and flexible configuration.

Interactive API Explorer

Loading API Documentation...

Endpoint

POST /v3/orders/import

Authentication

Authorization: apikey YOUR_API_KEY_HERE

Base URLs

  • Production: https://app.zenderatms.com/api/
  • Staging: https://staging.zenderatms.com/api/

Key Features

  • Batch Import: Import multiple orders in a single request
  • Flexible Identifiers: Use external IDs, names, or internal Zendera IDs for lookup
  • Update Control: Configure how existing orders should be handled
  • Validation: Comprehensive error reporting for invalid data
  • ERP Integration: Built-in support for ERP system integration
  • Hierarchical Products: Support for atoms (colli/trade items) with parent-child relationships

Request Structure

{
  "orders": [
    {
      "externalId": "ORDER_123",
      "date": "2024-01-15",
      "reference": "Customer Reference",
      "customer": {
        "id": 123,
        "businessName": "Customer Name",
        "externalId": "CUST_001"
      },
      "vehicleType": {
        "id": 5,
        "name": "Van"
      },
      "orderType": {
        "id": 2,
        "name": "Delivery"
      },
      "pickup": {
        "name": "Warehouse",
        "address": {
          "address1": "Main Street 123",
          "city": "Oslo",
          "postalCode": "0123",
          "country": "Norway"
        },
        "earliest": "2024-01-15T08:00:00Z",
        "latest": "2024-01-15T10:00:00Z",
        "contacts": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "phoneNumber": "+4712345678",
            "emailAddress": "john@example.com"
          }
        ]
      },
      "delivery": {
        "name": "Customer Location",
        "address": {
          "address1": "Customer Street 456",
          "city": "Bergen",
          "postalCode": "5000",
          "country": "Norway"
        },
        "earliest": "2024-01-15T14:00:00Z",
        "latest": "2024-01-15T16:00:00Z"
      },
      "products": [
        {
          "name": "Pallet",
          "quantity": 1,
          "weight": 50.0,
          "length": 120.0,
          "width": 80.0,
          "height": 180.0,
          "barcodeId": "PALLET_001",
          "externalId": "PALLET_001",
          "atomType": "colli"
        },
        {
          "name": "Product A",
          "quantity": 10,
          "weight": 2.0,
          "externalId": "PROD_A_001",
          "parentExternalId": "PALLET_001",
          "atomType": "trade item"
        }
      ]
    }
  ],
  "fallbackCustomer": {
    "id": 1,
    "businessName": "Default Customer"
  },
  "updateConfig": {
    "orderLocation": "REPLACE_EXISTING_ORDER_LOCATION_BEHAVIOR",
    "orderProducts": "REPLACE_EXISTING_ORDER_PRODUCT",
    "order": "REPLACE_EXISTING_ORDER_BEHAVIOR",
    "allowMerge": true
  }
}

Atom Types Explained

Atom Types define the nature of products in hierarchical structures:

"colli" - Container Items

  • Used for grouping multiple trade items
  • Examples: pallets, boxes, parcels
  • Can have child products
  • Typically scanned as a unit

"trade item" - Individual Products (default)

  • End products that customers purchase
  • Can be part of a colli
  • Usually the leaf nodes in hierarchies

Hierarchical Structure Example

Pallet (colli) - PALLET_001
├── Product A (trade item) - PROD_A_001 (qty: 10)
└── Product B (trade item) - PROD_B_001 (qty: 5)

Customer Identification

You can identify customers using any of these fields (in priority order):

  • id: Zendera internal customer ID
  • externalId: Your system’s customer identifier
  • businessName: Customer name for lookup

Product Hierarchy Fields

  • externalId: Your product identifier (required)
  • parentExternalId: Parent product’s external ID for hierarchy
  • atomType: Either "colli" or "trade item"
  • externalInstanceNumber: Unique instance identifier for individual product instances

Location Fields

  • earliest/latest: ISO 8601 timestamps for time windows
  • estimatedTimeOnLocation: Minutes expected to spend at location
  • sendNotificationBeforeArriving: Enable/disable customer notifications
  • skills: Array of required/prohibited skills for location

Update Configuration

The updateConfig object controls how existing data is handled during import:

Order Location Update Behavior

orderLocation: Controls how existing order locations (pickup/delivery stops) are handled.

Options:

  • "UNKNOWN_UPDATE_ORDER_LOCATION_BEHAVIOR" (default): Use system default behavior
  • "IGNORE_EXISTING_ORDER_LOCATION_BEHAVIOR": Skip updates to existing locations
  • "REPLACE_EXISTING_ORDER_LOCATION_BEHAVIOR": Completely replace existing location data

Product Update Behavior

orderProducts: Controls how existing products on orders are handled.

Options:

  • "UNKNOWN_UPDATE_PRODUCT_BEHAVIOR" (default): Use system default behavior
  • "IGNORE_EXISTING_ORDER_PRODUCT": Skip updates to existing products
  • "REPLACE_EXISTING_ORDER_PRODUCT": Replace all product data
  • "REPLACE_IF_NOT_MODIFIED_ORDER_PRODUCT": Replace only if product hasn’t been manually modified

Order Update Behavior

order: Controls how existing orders are handled.

Options:

  • "UNKNOWN_UPDATE_ORDER_BEHAVIOR" (default): Use system default behavior
  • "IGNORE_EXISTING_ORDER_BEHAVIOR": Skip updates to existing orders
  • "REPLACE_EXISTING_ORDER_BEHAVIOR": Replace order data

Merge Settings

allowMerge: Boolean flag to control ERP order merging.

  • true: Allow multiple ERP orders to be merged into a single Zendera order
  • false: Keep ERP orders separate
  • null: Use organization default setting

Response Structure

{
  "results": [
    {
      "orderCreated": {
        "OrderID": 12345,
        "externalId": "ORDER_123"
      }
    }
  ]
}

Error Handling

Common error codes:

  • CUSTOMER_NOT_FOUND_CODE: Customer lookup failed
  • VEHICLE_TYPE_NOT_FOUND_CODE: Vehicle type not found
  • ORDER_TYPE_NOT_FOUND_CODE: Order type not found
  • INVALID_PICKUP_ADDRESS_CODE: Pickup address validation failed
  • INVALID_DELIVERY_ADDRESS_CODE: Delivery address validation failed

Example Usage

curl -X POST "https://app.zenderatms.com/api/v3/orders/import" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [{
      "externalId": "ORDER_123",
      "date": "2024-01-15",
      "customer": {"id": 123},
      "vehicleType": {"id": 5},
      "orderType": {"id": 2},
      "pickup": {
        "name": "Warehouse",
        "address": {
          "address1": "Main Street 123",
          "city": "Oslo",
          "postalCode": "0123",
          "country": "Norway"
        }
      },
      "delivery": {
        "name": "Customer Location",
        "address": {
          "address1": "Customer Street 456",
          "city": "Bergen",
          "postalCode": "5000",
          "country": "Norway"
        }
      },
      "products": [
        {
          "name": "Product A",
          "externalId": "PROD_A_001",
          "quantity": 10,
          "weight": 20.0,
          "atomType": "trade item"
        }
      ]
    }]
  }'
Last updated on
OrdersOrder Summary