Create Handling Class

cURL

curl --request POST \
  --url 'https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}'

import json
import requests

url = "https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code"
headers = {"Authorization": "Bearer <token>"}
payload = json.loads('{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}')

response = requests.request('POST', url, headers=headers, json=payload)
print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}),
};

fetch('https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code', options)
  .then(response => response.json())
  .then(response => console.log(response));

<?php

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code',
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => '{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer <token>', 'Content-Type: application/json'],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    request, _ := http.NewRequest("POST", "https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code", strings.NewReader(`{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}`))
    request.Header.Add("Authorization", "Bearer <token>")
    request.Header.Add("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(request)
    defer response.Body.Close()
    body, _ := io.ReadAll(response.Body)
    fmt.Println(string(body))
}

HttpResponse<String> response = Unirest.post("https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\"name\":\"Heavy Bulky\",\"code\":\"heavy_bulky\",\"sort_order\":20,\"warehouses\":[{\"type\":\"Warehouse\",\"id\":1}],\"conditions\":{\"or\":[{\"and\":[{\">=\":[{\"var\":\"weight\"},{\"value\":70,\"unit\":\"lb\"}]},{\"contains_any\":[{\"var\":\"product_profiles\"},[31]]}]}]}}")
  .asString();

require 'uri'
require 'net/http'

url = URI('https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code')
request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}'

response = Net::HTTP.start(url.hostname, url.port, use_ssl: true) do |http|
  http.request(request)
end
puts response.read_body

{
  "resource": {
    "type": "HandlingClass",
    "id": 14,
    "name": "Heavy Bulky",
    "code": "heavy_bulky",
    "sort_order": 20,
    "warehouses": [
      {
        "type": "Warehouse",
        "id": 1
      }
    ],
    "referenced_product_profiles": [
      {
        "type": "ProductProfile",
        "id": 31
      }
    ],
    "conditions": {
      "or": [
        {
          "and": [
            {
              ">=": [
                {
                  "var": "weight"
                },
                {
                  "value": 70,
                  "unit": "lb"
                }
              ]
            },
            {
              "contains_any": [
                {
                  "var": "product_profiles"
                },
                [
                  31
                ]
              ]
            }
          ]
        }
      ]
    },
    "matched_count": 0,
    "classification": {
      "status": "queued",
      "indexed_at": null
    },
    "created_at": "2026-08-05T10:30:00Z",
    "updated_at": "2026-08-05T10:30:00Z"
  },
  "included": {
    "Warehouse": [
      {
        "type": "Warehouse",
        "id": 1,
        "name": "Newark NJ"
      }
    ],
    "ProductProfile": [
      {
        "type": "ProductProfile",
        "id": 31,
        "name": "Oversized Products",
        "code": "oversized_products"
      }
    ]
  }
}

{
  "errors": [
    {
      "type": "parameters",
      "message": "The supplied parameters are invalid."
    }
  ]
}

{
  "errors": [
    {
      "type": "unable_to_process",
      "message": "There was an error processing the request."
    }
  ]
}

POST

inventory

handling-classes

cURL

curl --request POST \
  --url 'https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}'

import json
import requests

url = "https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code"
headers = {"Authorization": "Bearer <token>"}
payload = json.loads('{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}')

response = requests.request('POST', url, headers=headers, json=payload)
print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}),
};

fetch('https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code', options)
  .then(response => response.json())
  .then(response => console.log(response));

<?php

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code',
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => '{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer <token>', 'Content-Type: application/json'],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    request, _ := http.NewRequest("POST", "https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code", strings.NewReader(`{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}`))
    request.Header.Add("Authorization", "Bearer <token>")
    request.Header.Add("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(request)
    defer response.Body.Close()
    body, _ := io.ReadAll(response.Body)
    fmt.Println(string(body))
}

HttpResponse<String> response = Unirest.post("https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\"name\":\"Heavy Bulky\",\"code\":\"heavy_bulky\",\"sort_order\":20,\"warehouses\":[{\"type\":\"Warehouse\",\"id\":1}],\"conditions\":{\"or\":[{\"and\":[{\">=\":[{\"var\":\"weight\"},{\"value\":70,\"unit\":\"lb\"}]},{\"contains_any\":[{\"var\":\"product_profiles\"},[31]]}]}]}}")
  .asString();

require 'uri'
require 'net/http'

url = URI('https://example.shipstream.app/api/global/v1/inventory/handling-classes?fields=conditions&fields:warehouses=name&fields:referenced_product_profiles=name,code')
request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{"name":"Heavy Bulky","code":"heavy_bulky","sort_order":20,"warehouses":[{"type":"Warehouse","id":1}],"conditions":{"or":[{"and":[{">=":[{"var":"weight"},{"value":70,"unit":"lb"}]},{"contains_any":[{"var":"product_profiles"},[31]]}]}]}}'

response = Net::HTTP.start(url.hostname, url.port, use_ssl: true) do |http|
  http.request(request)
end
puts response.read_body

{
  "resource": {
    "type": "HandlingClass",
    "id": 14,
    "name": "Heavy Bulky",
    "code": "heavy_bulky",
    "sort_order": 20,
    "warehouses": [
      {
        "type": "Warehouse",
        "id": 1
      }
    ],
    "referenced_product_profiles": [
      {
        "type": "ProductProfile",
        "id": 31
      }
    ],
    "conditions": {
      "or": [
        {
          "and": [
            {
              ">=": [
                {
                  "var": "weight"
                },
                {
                  "value": 70,
                  "unit": "lb"
                }
              ]
            },
            {
              "contains_any": [
                {
                  "var": "product_profiles"
                },
                [
                  31
                ]
              ]
            }
          ]
        }
      ]
    },
    "matched_count": 0,
    "classification": {
      "status": "queued",
      "indexed_at": null
    },
    "created_at": "2026-08-05T10:30:00Z",
    "updated_at": "2026-08-05T10:30:00Z"
  },
  "included": {
    "Warehouse": [
      {
        "type": "Warehouse",
        "id": 1,
        "name": "Newark NJ"
      }
    ],
    "ProductProfile": [
      {
        "type": "ProductProfile",
        "id": 31,
        "name": "Oversized Products",
        "code": "oversized_products"
      }
    ]
  }
}

{
  "errors": [
    {
      "type": "parameters",
      "message": "The supplied parameters are invalid."
    }
  ]
}

{
  "errors": [
    {
      "type": "unable_to_process",
      "message": "There was an error processing the request."
    }
  ]
}

Authorizations

Authorization

string

header

required

Generate a JWT access token through a Custom Global Integration and provide it with each request in the Authorization header prefixed with "Bearer" and then a single space.

Query Parameters

fields

enum<string>[]

Select fields of the HandlingClass object. See the selecting fields page for more information. Specify fields of the HandlingClass object to include in the response.

Available options:

all,

name,

code,

sort_order,

warehouses,

conditions,

referenced_product_profiles,

conditions_readable,

matched_count,

classification,

created_at,

updated_at

fields:warehouses

enum<string>[]

Specify fields of the referenced Warehouse objects to include under included.Warehouse. type and id are always returned. See the selecting fields page for more information. Specify additional fields of the Warehouse object to be included in the response.

Available options:

basic,

all,

id,

name,

is_active,

abbreviation

fields:referenced_product_profiles

enum<string>[]

Specify fields of the referenced ProductProfile objects to include under included.ProductProfile. type and id are always returned. See the selecting fields page for more information. Specify fields of an included ProductProfile object.

Available options:

basic,

all,

name,

code,

conditions,

conditions_readable,

matched_count,

classification,

created_at,

updated_at

Body

application/json

name

string

required

Human-readable Handling Class name.

Required string length: 1 - 255

Example:

"Heavy Bulky"

sort_order

integer

required

Evaluation precedence within every selected Warehouse.

Required range: 0 <= x <= 1000000

Example:

20

warehouses

(WarehouseRef · object | null)[]

required

Warehouses where the Handling Class is evaluated.

Minimum array length: 1

A reference to a Warehouse by id.

Show child attributes

conditions

object

required

A one-level OR-of-AND condition tree. The server accepts the {"and": [...]} shorthand for a single group and always returns the canonical {"or": [{"and": [...]}]} form.

OpenAPI validates the structural envelope. ShipStream remains authoritative for available Product fields, field/operator compatibility, option values, measurement units, raw CEL validity, normalization, the limit of 64 condition rows across all groups, and the 65,535-byte compiled-expression limit. Editor clients can load the applicable Product field catalogue from GET /api/global/v1/inventory/product-profiles/condition-fields or GET /api/global/v1/inventory/handling-classes/condition-fields.

Option 1
Option 2

Show child attributes

Example:

{
  "or": [
    {
      "and": [
        {
          "<=": [
            { "var": "weight" },
            { "value": 15, "unit": "lb" }
          ]
        }
      ]
    }
  ]
}

code

string

Optional stable code; blank or omitted values are generated from the name.

Maximum string length: 64

Pattern: ^[A-Za-z0-9_]*$

Example:

"heavy_bulky"

Response

Handling Class created and Warehouse classification scheduled.

resource

HandlingClass · object

A Warehouse-scoped Product classification used by Slotting and Replenishment. Classification is asynchronous: after conditions or Warehouse assignments change, poll the resource until classification.status is up_to_date. Product changes flow through a separate asynchronous changelog and may not appear immediately in materialized classification.

Show child attributes

Example:

{
  "type": "HandlingClass",
  "id": 14,
  "name": "Heavy Bulky",
  "code": "heavy_bulky",
  "sort_order": 20,
  "warehouses": [{ "type": "Warehouse", "id": 1 }],
  "referenced_product_profiles": [{ "type": "ProductProfile", "id": 31 }],
  "matched_count": 318,
  "classification": {
    "status": "up_to_date",
    "indexed_at": "2026-08-04T09:15:00Z"
  },
  "created_at": "2026-07-15T14:30:00Z",
  "updated_at": "2026-08-04T09:15:00Z"
}

included

object

Related Warehouses and Product Profiles requested through nested fields:* parameters.

Show child attributes

Example:

{}

Get Started

Common Features

Inventory API v1

Receiving API v1

Shipping API v1

System API v1

Authorizations

Query Parameters

Body

Response