Atoms API

Where this fits in your operation

The atom tree is the physical packing structure of an order — what is loaded on what:

• Read the tree to see how an order’s items are organised into pallets/colli before it ships.
• Repacking: goods were consolidated onto fewer pallets at your warehouse — patch the tree so scanning and terminal handling match the physical load.

Interactive API Explorer

Authentication

Authorization: apikey YOUR_API_KEY_HERE

Base URLs

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

Endpoints Overview

GET   /v1/atoms/{orderId}/tree
PATCH /v1/atoms/{orderId}/tree

Atoms are the parent/child structure of the products on an order — the way the goods are physically packed (pallet → carton → unit). The atoms tree endpoint changes how products relate to each other (typical use: your WMS reporting how goods were packed onto pallets). To change what products exist on an order, see the Product Upsert API.

The GET response contains a single top-level atoms array. Each atom carries its own nested children, statuses, skills, groups, and units arrays — these are nested per-atom, not returned as separate top-level lookup lists.

Endpoints

Get Atom Tree

Retrieve the complete hierarchical structure of products for an order.

GET /v1/atoms/{orderId}/tree

Parameters:

• orderId (path): Zendera order ID

Response:

{
  "atoms": [
    {
      "id": 1001,
      "type": "colli",
      "name": "Pallet",
      "description": "Standard pallet",
      "quantity": 1,
      "length": 120.0,
      "width": 80.0,
      "height": 180.0,
      "weight": 50.0,
      "internalProductNumber": "PALLET_001",
      "internalOrderProductNumber": "OP_001",
      "barcodeId": "PALLET_BARCODE_001",
      "barcodeType": "CODE128",
      "parentId": null,
      "children": [
        {
          "id": 1002,
          "type": "trade item",
          "name": "Product A",
          "quantity": 10,
          "weight": 20.0,
          "internalProductNumber": "PROD_A_001",
          "parentId": 1001,
          "children": [],
          "statuses": [
            {
              "status": "PENDING_ORDER_PRODUCT_ORDER_LOCATION_STATUS",
              "type": "PICKUP",
              "isScanned": false
            },
            {
              "status": "PENDING_ORDER_PRODUCT_ORDER_LOCATION_STATUS",
              "type": "DELIVERY",
              "isScanned": false
            }
          ]
        }
      ],
      "statuses": [
        {
          "status": "PENDING_ORDER_PRODUCT_ORDER_LOCATION_STATUS",
          "type": "PICKUP",
          "isScanned": false
        }
      ],
      "skills": [
        {
          "id": 123,
          "type": "REQUIRED",
          "name": "Forklift",
          "description": "Requires forklift handling"
        }
      ],
      "groups": [
        {
          "id": 456,
          "name": "Fragile Items",
          "description": "Handle with care"
        }
      ],
      "units": [
        {
          "id": 789,
          "quantity": 1,
          "unitId": 1,
          "name": "Pallet",
          "description": "Standard EUR pallet"
        }
      ]
    }
  ]
}

Update Atom Hierarchy

Modify the parent-child relationships between atoms.

PATCH /v1/atoms/{orderId}/tree

Parameters:

• orderId (path): Zendera order ID

Request Body:

{
  "id": 1002,
  "parentId": 1001
}

This moves atom with ID 1002 to become a child of atom 1001.

Request body fields:

• id (integer): The atom to re-parent.
• parentId (integer): The new parent atom’s ID. Set parentId to 0 to re-parent the atom to the top level (make it a root atom with no parent).

Re-parent to top level:

{
  "id": 1002,
  "parentId": 0
}

Response:

The full, updated atom tree (same shape as GET):

{
  "atoms": [
    // Updated atom tree structure
  ]
}

Atom Fields Explained

Core Atom Properties

• id: Zendera internal atom ID
• type: Atom type ("colli" or "trade item")
• name: Product name
• description: Product description
• quantity: Number of items
• parentId: Parent atom ID (null for root items)

Physical Properties

• length, width, height: Dimensions in cm
• weight: Weight in kg

Identification

• internalProductNumber: Your product identifier
• internalOrderProductNumber: Unique order product identifier
• barcodeId: Barcode for scanning
• barcodeType: Type of barcode (CODE128, EAN13, etc.)

Warehouse Management

• pickupWarehouseLocation: Pickup warehouse identifier
• deliveryWarehouseLocation: Delivery warehouse identifier

Status Tracking

• statuses: Array of status per location type (PICKUP/DELIVERY)
• isScanned: Whether the item has been scanned

Skills & Requirements

• skills: Array of required/prohibited skills for handling
• groups: Classification groups
• units: Custom measurement units

Atom Hierarchy Patterns

Simple Container

Pallet (colli)
├── Product A (trade item) × 10
└── Product B (trade item) × 5

Nested Containers

Pallet (colli)
├── Box 1 (colli)
│   ├── Product A (trade item) × 5
│   └── Product B (trade item) × 3
└── Box 2 (colli)
    ├── Product C (trade item) × 2
    └── Product D (trade item) × 8

Mixed Structure

Order
├── Loose Item (trade item) × 1
├── Pallet 1 (colli)
│   └── Products (trade item) × 20
└── Pallet 2 (colli)
    ├── Box A (colli)
    │   └── Small Items (trade item) × 50
    └── Large Item (trade item) × 3

Status Values

Location Status Options

• NOT_READY_ORDER_PRODUCT_LOCATION_STATUS: Product not ready for this location
• PENDING_ORDER_PRODUCT_ORDER_LOCATION_STATUS: Awaiting processing at location
• COMPLETE_ORDER_PRODUCT_ORDER_LOCATION_STATUS: Processing complete at location
• REMOVED_ORDER_PRODUCT_ORDER_LOCATION_STATUS: Product removed/cancelled

Location Types

• PICKUP: Status at pickup location
• DELIVERY: Status at delivery location

Best Practices

1. Use for Visualization Only

The Atoms API is primarily for viewing and understanding product hierarchies. Use the Product Upsert API for modifying products. For bulk hierarchy changes, it is often easier to use the Product Upsert API with hierarchicalMode: true and parentExternalId set on each product, which sets parent/child relationships at upsert time.

2. Cache Atom Trees

Atom trees can be large. Cache the response when possible and only refresh when needed:

3. Handle Large Hierarchies

For orders with many products, consider pagination or filtering:

4. Integration with Other APIs

Combine with Order Summary and Product Upsert APIs for complete workflows:

Error Handling

Common error scenarios:

• ORDER_NOT_FOUND: Order ID doesn’t exist
• INVALID_ATOM_ID: Atom ID in PATCH request doesn’t exist
• CIRCULAR_REFERENCE: Attempting to create circular parent-child relationships
• INVALID_HIERARCHY: Invalid parent-child relationship (e.g., trade item as parent of colli)