Inventory

scope: inventory

The inventory system manages your products, carton definitions, stock levels, and warehouses. All inventory endpoints require the inventory OAuth scope.

Data Model

Inventory is organized around four core concepts that work together:

Products

The items you store and ship. Each product has a unique SKU within your organization. Products are the building blocks — they go inside cartons.

Cartons

Box configurations that contain products. A carton defines what's inside (product + quantity), its physical dimensions, and weight. These are the units that sit on warehouse shelves.

Stock Levels

Read-only aggregated counts showing how much inventory you have. Available as product-level totals or carton-level breakdowns per warehouse.

Warehouses

Physical locations where your inventory is stored. Warehouses are referenced when creating shipments and appear in stock level breakdowns.

How It Fits Together

Data Flow

Product→Carton→Warehouse→Stock

Create products in your catalog (e.g. "Egg Shells", SKU: ABC123)
Define cartons that contain those products (e.g. "10-Pack Case" containing 10 units of Egg Shells)
Stock is received into warehouses as cartons (managed by the warehouse team)
Query stock levels to see how many units/cartons you have and where
Create shipments that reference these cartons or products to move inventory out

Shipment Impact on Inventory

Pick & Pack

Opens cartons, picks individual units, repacks. Per-unit labor fees.

Submit→Warehouse picks & repacks→Stock deducted on forward

SPD

Ships full cartons as-is. No opening or repacking.

Stock deducted on submit→Warehouse ships whole cartons

Endpoint Overview

The inventory API provides full CRUD for products and cartons, read-only stock level aggregations, and a warehouse listing endpoint.

Resource	Operations	Scope
Products	List, Get, Create, Update, Delete, Restore	`inventory`
Cartons	List, Get, Create, Update, Delete, Restore	`inventory`
Stock Levels	Product breakdown, Carton breakdown (read-only)	`inventory`
Warehouses	List (read-only)	`locations`

Resources

Products

Create and manage your product catalog. Each product has a unique, immutable SKU. Supports search, filtering, sorting, soft-delete and restore.

listcreateupdatedeleterestore

Cartons

Define box configurations with product contents, dimensions, and weight. Contents and specs are immutable after creation. Only the name can be updated.

listcreateupdatedeleterestore

Stock Levels

Read-only aggregated stock quantities. Product breakdown shows total units per product. Carton breakdown shows counts per warehouse with dimensions.

product breakdowncarton breakdownincremental sync

Warehouses

List available warehouse locations. Warehouses are referenced when creating shipments and appear in stock level breakdowns.

list

Soft Delete & Restore

Products and cartons support soft-deletion. When you DELETE a resource, it's not permanently removed — it's marked as deleted and excluded from default list results.

Behavior	Details
Delete precondition	Resource must have zero stock across all warehouses
deletedAt field	`null` when active, timestamp when deleted
Listing	Deleted items excluded unless `includeDeleted=true`
Restore	`PATCH /resource/:id/restore` sets deletedAt back to null
Stock levels	Deleted products and cartons report 0 quantity in breakdowns

Stock must be zero to delete

You cannot delete a product or carton that still has inventory in any warehouse. Transfer or deplete all stock first, then delete. This prevents accidental data loss.

Small Parcel (SPD)

Products