Inventory

Hydra tracks inventory at the variant level. Every stock change - whether from a manual set, a relative adjustment, or an order - is recorded as an immutable adjustment for audit purposes.

Base URL: https://api.hydrajs.dev

Auth: All inventory endpoints require a secret key (sk_live_* or sk_test_*).

Endpoints

Method	Path	Description
GET	/v1/inventory	List inventory levels
PATCH	/v1/inventory/{variant_id}	Set inventory level (absolute)
POST	/v1/inventory/{variant_id}/adjust	Adjust inventory (relative +/-)
GET	/v1/inventory/adjustments	List adjustments by product
GET	/v1/inventory/{variant_id}/adjustments	List adjustments for a single variant

---

List inventory levels

GET /v1/inventory

Returns a paginated list of inventory levels across all variants. Each entry includes the product and variant context.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1–100)
cursor	string	-	Pagination cursor from a previous response
sort	string	updated_at	Sort field: updated_at
order	string	desc	Sort direction: asc, desc
product_id	string	-	Filter by product ID
sku	string	-	Filter by exact SKU
low_stock	boolean	-	Only items below their low stock threshold
fields	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/inventory?low_stock=true&limit=10 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"variant_id": "var_def456",
			"product_id": "prod_abc123",
			"product_title": "Classic T-Shirt",
			"variant_title": "Small / Black",
			"sku": "TS-SM-BLK",
			"inventory_quantity": 3,
			"updated_at": "2026-08-06T12:00:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 1
	}
}

---

Set inventory level

PATCH /v1/inventory/{variant_id}

Sets the inventory quantity to an absolute value. Records an adjustment if the quantity changed.

Request body

Field	Type	Required	Description
quantity	integer	Yes	New quantity (≥ 0)
reason	string	No	Reason for the change (max 500 chars, defaults to "set")

Request

curl -X PATCH https://api.hydrajs.dev/v1/inventory/var_def456 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 50, "reason": "Restock from supplier"}'

Response 200

{
	"data": {
		"variant_id": "var_def456",
		"product_id": "prod_abc123",
		"product_title": "Classic T-Shirt",
		"variant_title": "Small / Black",
		"sku": "TS-SM-BLK",
		"inventory_quantity": 50,
		"updated_at": "2026-08-17T09:30:00Z",
		"adjustment": {
			"id": "adj_abc123",
			"variant_id": "var_def456",
			"quantity_before": 3,
			"quantity_after": 50,
			"adjustment": 47,
			"reason": "Restock from supplier",
			"created_at": "2026-08-17T09:30:00Z"
		}
	}
}

If the quantity is unchanged, adjustment will be null.

---

Adjust inventory

POST /v1/inventory/{variant_id}/adjust

Applies a relative adjustment (+/-) to the current quantity. Returns 400 if the result would be negative.

Request body

Field	Type	Required	Description
adjustment	integer	Yes	Quantity change (non-zero)
reason	string	Yes	Reason for the change (1–500 chars)

Request

curl -X POST https://api.hydrajs.dev/v1/inventory/var_def456/adjust \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"adjustment": -5, "reason": "Damaged goods"}'

Response 200

{
	"data": {
		"variant_id": "var_def456",
		"product_id": "prod_abc123",
		"product_title": "Classic T-Shirt",
		"variant_title": "Small / Black",
		"sku": "TS-SM-BLK",
		"inventory_quantity": 45,
		"updated_at": "2026-08-17T09:35:00Z",
		"adjustment": {
			"id": "adj_def456",
			"variant_id": "var_def456",
			"quantity_before": 50,
			"quantity_after": 45,
			"adjustment": -5,
			"reason": "Damaged goods",
			"created_at": "2026-08-17T09:35:00Z"
		}
	}
}

Error 400 - negative inventory

{
	"error": {
		"code": "invalid_request",
		"message": "Adjustment would result in negative inventory."
	}
}

---

List adjustments by product

GET /v1/inventory/adjustments?product_id=prod_abc123

Returns adjustment history across all variants of a product. Each entry includes variant_title and sku for display context. Ordered by most recent first.

Query parameters

Parameter	Type	Required	Description
product_id	string	Yes	Product ID to filter by
limit	integer	No	Results per page (1–100, default 25)
cursor	string	No	Pagination cursor
fields	string	No	Comma-separated fields to return

Request

curl "https://api.hydrajs.dev/v1/inventory/adjustments?product_id=prod_abc123&limit=10" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "adj_def456",
			"variant_id": "var_def456",
			"variant_title": "Small / Black",
			"sku": "TS-SM-BLK",
			"quantity_before": 50,
			"quantity_after": 45,
			"adjustment": -5,
			"reason": "Damaged goods",
			"created_at": "2026-08-17T09:35:00Z"
		},
		{
			"id": "adj_abc123",
			"variant_id": "var_def456",
			"variant_title": "Small / Black",
			"sku": "TS-SM-BLK",
			"quantity_before": 3,
			"quantity_after": 50,
			"adjustment": 47,
			"reason": "Restock from supplier",
			"created_at": "2026-08-17T09:30:00Z"
		}
	],
	"pagination": {
		"cursor": null,
		"has_more": false,
		"total": 2
	}
}

---

List adjustments for a variant

GET /v1/inventory/{variant_id}/adjustments

Returns adjustment history for a single variant. Same pagination as other list endpoints.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1–100)
cursor	string	-	Pagination cursor
fields	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/inventory/var_def456/adjustments?limit=5 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "adj_def456",
			"variant_id": "var_def456",
			"quantity_before": 50,
			"quantity_after": 45,
			"adjustment": -5,
			"reason": "Damaged goods",
			"created_at": "2026-08-17T09:35:00Z"
		}
	],
	"pagination": {
		"cursor": null,
		"has_more": false,
		"total": 1
	}
}