Editing Handling Class Conditions

Handling Classes classify Products asynchronously and can refer to Product Profiles. A list or detail response returns the compact class summary by default. Load the condition definition only when a user opens the editor.

Load a Handling Class for editing

Request the canonical condition tree and its readable expression explicitly. The two nested field parameters resolve the direct Warehouse and Product Profile references without loading their own relationships:

Request

GET /api/global/v1/inventory/handling-classes/18?fields=conditions,conditions_readable&fields:warehouses=name&fields:referenced_product_profiles=name

Response

{
  "resource": {
    "type": "HandlingClass",
    "id": 18,
    "name": "Heavy Oversized",
    "code": "heavy_oversized",
    "sort_order": 30,
    "warehouses": [
      { "type": "Warehouse", "id": 1 },
      { "type": "Warehouse", "id": 2 }
    ],
    "conditions": {
      "or": [
        {
          "and": [
            {
              ">=": [
                { "var": "weight" },
                { "value": 70, "unit": "lb", "base_value": 70 }
              ]
            },
            {
              "contains_any": [
                { "var": "product_profiles" },
                [31]
              ]
            }
          ]
        }
      ]
    },
    "referenced_product_profiles": [
      { "type": "ProductProfile", "id": 31 }
    ],
    "conditions_readable": "((present(weight) && weight >= 70.0) && (present(product_profiles) && (31 in product_profiles)))",
    "matched_count": 127,
    "classification": {
      "status": "up_to_date",
      "indexed_at": "2026-08-04T10:05:00Z"
    },
    "created_at": "2026-07-18T11:20:00Z",
    "updated_at": "2026-08-04T10:05:00Z"
  },
  "included": {
    "Warehouse": [
      { "type": "Warehouse", "id": 1, "name": "Los Angeles Fulfillment Center" },
      { "type": "Warehouse", "id": 2, "name": "Dallas Fulfillment Center" }
    ],
    "ProductProfile": [
      { "type": "ProductProfile", "id": 31, "name": "Oversized Furniture" }
    ]
  },
  "meta": {
    "processing_time": 0.0092
  }
}

type and id are always present in an included resource, so request only the additional fields the control displays. For a grid that needs only Handling Class data, omit both nested field parameters; the compact references remain available and ShipStream does not load the related Warehouse or Product Profile records. List responses bulk-load each requested related type once for the page rather than once per Handling Class.

Build the editor from metadata

Call List Handling Class condition fields when the editor loads. The response describes the shared Product fields and the additional product_profiles selector. Product Profile options are a finite ID-to-name map; save their numeric IDs in product_profiles condition values. Fields such as SKU and Product name advertise a value_source instead of embedding every Product. After the operator types at least two characters, call the advertised endpoint with a bounded limit:

Request

GET /api/global/v1/inventory/product-condition-values?field=sku&q=FURN-&limit=50

Response

{
  "options": [
    {
      "value": "FURN-CHAIR-OAK",
      "label": "FURN-CHAIR-OAK — Oak Dining Chair"
    },
    {
      "value": "FURN-TABLE-6FT",
      "label": "FURN-TABLE-6FT — Six Foot Dining Table"
    }
  ],
  "meta": {
    "processing_time": 0.0067
  }
}

The lookup returns simple Products only and at most 50 options. Do not preload the full Product catalogue. If another selector needs Product data, request the Product endpoint with a bounded limit and only the fields the control displays; see Selecting Fields.

Save and poll classification

Send the edited condition tree to the Handling Class update endpoint. Omitted fields remain unchanged.

Request

PUT /api/global/v1/inventory/handling-classes/18
Content-Type: application/json

{
  "conditions": {
    "or": [
      {
        "and": [
          {
            ">=": [
              { "var": "weight" },
              { "value": 80, "unit": "lb" }
            ]
          },
          {
            "contains_any": [
              { "var": "product_profiles" },
              [31]
            ]
          }
        ]
      }
    ]
  }
}

The update returns 200 with no response body. Poll the Handling Class until classification.status becomes up_to_date. While work is pending, the status may be queued or processing; a failed classification reports failed.

Condition values store Product Profile IDs. The referenced_product_profiles response field exposes the same dependencies as { "type": "ProductProfile", "id": ... } references. Add fields:referenced_product_profiles=name when the editor needs their labels; the matching shallow objects are returned in included.ProductProfile.

Get Started

Common Features

Inventory API v1

Receiving API v1

Shipping API v1

System API v1

Load a Handling Class for editing

Build the editor from metadata

Save and poll classification

​Load a Handling Class for editing

​Build the editor from metadata

​Save and poll classification

Load a Handling Class for editing

Build the editor from metadata

Save and poll classification