Core Inventory Flow

This workflow exercises the main public API concepts without relying on external connectors.

Use it when onboarding a new integration, validating credentials or smoke testing an environment.

Prerequisites

• API base URL.
• Organization id.
• API key with the scopes required by the operations you will run.
• A stable idempotency key for every write operation.

For the full workflow, use:

products:read
products:write
inventory:read
inventory:write
reservations:read
reservations:write
transfers:read
transfers:write

1. Create Product And Locations

Create a product:

POST /v1/organizations/{organizationId}/products
Idempotency-Key: product-demo-001

Create a source location and a destination location:

POST /v1/organizations/{organizationId}/locations
Idempotency-Key: location-source-demo-001

POST /v1/organizations/{organizationId}/locations
Idempotency-Key: location-destination-demo-001

Products use products:write. Locations use inventory:write.

2. Create Or Reuse Inventory Segments

Inventory owners and channels let you segment stock by operational ownership and selling channel.

GET /v1/organizations/{organizationId}/inventory-owners
GET /v1/organizations/{organizationId}/inventory-channels

Create owner/channel records only when the defaults are not enough:

POST /v1/organizations/{organizationId}/inventory-owners
POST /v1/organizations/{organizationId}/inventory-channels

If ownerId or channelId is omitted in stock operations, Skunivo uses the organization defaults for the environment.

3. Receive Stock

Receive stock into the source location:

POST /v1/organizations/{organizationId}/stock/receive
Idempotency-Key: receive-demo-001

Include ownerId and channelId when validating segmented inventory behavior.

Receiving stock creates ledger movements and updates balances. Do not update balances directly.

4. Read Balances And Movements

Read current stock state:

GET /v1/organizations/{organizationId}/balances?ownerId=...&channelId=...

Read the ledger behind that state:

GET /v1/organizations/{organizationId}/movements?ownerId=...&channelId=...

Balances explain current quantities. Movements explain how those quantities changed.

5. Create A Reservation

Reserve available stock:

POST /v1/organizations/{organizationId}/reservations
Idempotency-Key: reservation-demo-001

A reservation moves quantity from available to reserved. Commit, release or cancel the reservation through explicit reservation actions.

6. Create And Receive A Transfer

Create a transfer between locations:

POST /v1/organizations/{organizationId}/transfers
Idempotency-Key: transfer-demo-001

For partial shipment and receiving flows, use:

POST /v1/organizations/{organizationId}/transfers/{transferId}/ship
POST /v1/organizations/{organizationId}/transfers/{transferId}/receive

Receiving cannot exceed shipped quantity. Closing a transfer records an auditable difference without creating stock movements.

7. Create An Inbound

Create expected stock:

POST /v1/organizations/{organizationId}/inbounds
Idempotency-Key: inbound-demo-001

An inbound increases incoming without changing onHand. Receiving the inbound decrements incoming, increments onHand and increments available.

8. Create An Outbound

Create an outbound request:

POST /v1/organizations/{organizationId}/outbounds
Idempotency-Key: outbound-demo-001

Outbounds support multiline requests, allocation, pick, pack, ship, legacy fulfillment and cancellation before completion.

The physical flow is:

allocate -> pick -> pack -> ship

pick and pack do not change balances. ship decrements committed and onHand.

Validate The Result

After each write, re-read balances and movements. A healthy integration can explain every balance change from ledger movements and can safely retry writes with the same idempotency key after a timeout.