API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: [email protected] License: Proprietary

Commerce and order-fulfilment platform API for 4klyft.

Overview

This API provides endpoints for managing:

  • Catalog (PIM/DAM): products, variants, attributes, options, categories, brands, collections, assortments, and media
  • Sales: orders, customers, merchants, sales channels, and channel order import
  • Inventory: stock items, levels, lots, and serial units across custodians
  • Warehousing & Operations: goods receipt/issue, holds, and custodian operations
  • Fulfilment: fulfilment orders dispatched to third-party (3PL) providers
  • Shipping: carriers, shipments, labels, tracking, returns, and proof of delivery
  • Finance & Billing: payments, settlements, invoices, credit notes, tax, and subscriptions
  • Integration: sales-channel connections, providers, webhooks, and catalog/order sync
  • Documents: operational document generation and requests
  • Storage: file/drive storage with chunked upload and signed access
  • Identity & Access (IAM): authentication, users, roles, permissions, and tenants
  • Platform services: notifications, scheduling, numbering, data exchange, analytics, and workspace tables & views

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

Every /api/ request is rate-limited per caller — by your authenticated identity when a token is present, otherwise by client IP. The authentication endpoints (/auth/login, /auth/refresh, /auth/request-password-reset) carry stricter, IP-based limits.

Each response advertises your current budget via headers:

  • X-RateLimit-Limit — the bucket size
  • X-RateLimit-Remaining — tokens left in the current window
  • X-RateLimit-Reset — Unix timestamp when a token next frees up

Exceeding a limit returns 429 Too Many Requests (RFC 6585) with a Retry-After header (seconds to wait). Back off and retry after the indicated delay rather than hammering the endpoint.

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Inventory - Items

Represents an inventory item — a SKU-level product definition.

List all inventory items

Retrieve a paginated list of inventory items with optional filters.

Authorizations:
Bearer
query Parameters
id[]
Array of strings <uuid> [ items <uuid > ]

Batch-resolve items by id (repeat as id[]=…); accepts one or many ids

status
string
Enum: "active" "discontinued"
Example: status=active

Filter by item status

principalId
string <uuid>

Filter by principal ID

search
string
Example: search=Widget

Search by name or SKU

trackingMode
string
Enum: "plain" "batched" "serial"
Example: trackingMode=plain

Filter by tracking mode discriminator

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register an inventory item

Register a new inventory item (SKU).

Authorizations:
Bearer
Request Body schema: application/json
required

Inventory item registration data

sku
required
string non-empty
name
required
string non-empty
unitOfMeasure
string or null
principalId
required
string <uuid>
description
string or null
trackingMode
string or null
Default: "plain"
Enum: "plain" "batched" "serial"

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "0a52818d-1e0c-4e64-848e-4d04f9e914e5",
  • "description": "string",
  • "trackingMode": "plain"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "packagingProfileId": "01912345-6789-7abc-def0-123456789abc",
  • "hazmatClass": "3",
  • "handlingRequirements": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get an inventory item

Retrieve a single inventory item by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "packagingProfileId": "01912345-6789-7abc-def0-123456789abc",
  • "hazmatClass": "3",
  • "handlingRequirements": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Assign a packaging profile to an inventory item

Set the packaging profile this item resolves its physicals from.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Inventory item UUID

Request Body schema: application/json
required

Packaging profile to assign

packagingProfileId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "packagingProfileId": "b4955bf0-8f5b-47df-8132-be6850815516"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "packagingProfileId": "01912345-6789-7abc-def0-123456789abc",
  • "hazmatClass": "3",
  • "handlingRequirements": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Change the tracking mode of an inventory item

Switch the discriminator between plain, batched, and serial. Rejected when the item already has lots or serial units.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Request Body schema: application/json
required

New tracking mode

trackingMode
required
string
Enum: "plain" "batched" "serial"

Responses

Request samples

Content type
application/json
{
  • "trackingMode": "plain"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "packagingProfileId": "01912345-6789-7abc-def0-123456789abc",
  • "hazmatClass": "3",
  • "handlingRequirements": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Discontinue an inventory item

Mark an inventory item as discontinued.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Request Body schema: application/json
optional

Optional discontinuation reason

reason
string or null <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "reason": "Replaced by Widget B"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "packagingProfileId": "01912345-6789-7abc-def0-123456789abc",
  • "hazmatClass": "3",
  • "handlingRequirements": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update an inventory item

Update inventory item details. Only provided fields will be updated.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Inventory item UUID

Request Body schema:
required

The new InventoryItem resource

name
string or null [ 1 .. 255 ] characters
description
string or null
unitOfMeasure
string or null
InventoryItemWeightInput (object) or null
InventoryItemDimensionsInput (object) or null
unitsPerPallet
integer or null >= 0
packagingProfileId
string or null
hazmatClass
string or null <= 16 characters
handlingRequirements
Array of strings

Responses

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "unitOfMeasure": "string",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 0,
  • "packagingProfileId": "string",
  • "hazmatClass": "string",
  • "handlingRequirements": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "sku": "SKU-001",
  • "name": "Widget A",
  • "unitOfMeasure": "H87",
  • "principalId": "01912345-6789-7abc-def0-123456789abc",
  • "principalName": "string",
  • "description": "string",
  • "status": "active",
  • "trackingMode": "plain",
  • "discontinuationReason": "Replaced by Widget B",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "packagingProfileId": "01912345-6789-7abc-def0-123456789abc",
  • "hazmatClass": "3",
  • "handlingRequirements": [
    ],
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Inventory - Levels

Availability of an item at a custodian (item × custodian grain). Read-only except for the manual set/override POST. Quantities are capability-gated: when dataState is unsupported or restricted they are null, never 0.

List inventory availability levels

Paginated availability per (item, custodian), filterable by item and/or custodian. Each row carries a capability-gated data state.

Authorizations:
Bearer
query Parameters
inventoryItemId
string <uuid>
custodianId
string <uuid>
page
integer >= 1
Default: 1
itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Manually set an inventory availability level

Set or override the availability for a (item, custodian) pair — for custodians that cannot be inspected, or as an operator override. Returns the resulting level.

Authorizations:
Bearer
Request Body schema:
required

The new InventoryLevel resource

inventoryItemId
required
string
custodianId
required
string
availableQuantity
required
integer >= 0
onHandQuantity
integer or null >= 0
asOfAt
string or null

ISO-8601 timestamp the count is as-of; null → now.

https://schema.org/DateTime

Responses

Request samples

Content type
{
  • "inventoryItemId": "string",
  • "custodianId": "string",
  • "availableQuantity": 0,
  • "onHandQuantity": 0,
  • "asOfAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "inventoryItemId": "string",
  • "custodianId": "string",
  • "availableQuantity": 0,
  • "onHandQuantity": 0,
  • "dataState": "supported",
  • "source": "string",
  • "node": "string",
  • "asOfAt": "string",
  • "canListInventory": false,
  • "warehouseVisibility": "tenant_picks_warehouse"
}

Inventory - Lots

Represents a lot — a batch of an inventory item with tracking and expiry.

List all lots

Retrieve a paginated list of lots with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "available" "depleted" "expired" "recalled"
Example: status=available

Filter by lot status

inventoryItemId
string <uuid>

Filter by inventory item ID

search
string
Example: search=LOT-2024

Search by lot number

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register a lot

Register a new lot for an inventory item.

Authorizations:
Bearer
Request Body schema: application/json
required

Lot registration data

inventoryItemId
required
string <uuid>
lotNumber
required
string non-empty
totalQuantity
required
integer >= 1
expiryDate
string or null <date-time>
manufactureDate
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "inventoryItemId": "ef1bc09e-447a-46aa-a9d9-d86e3d490831",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "manufactureDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a lot

Retrieve a single lot by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Lot UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Adjust lot quantity

Adjust the quantity of a lot (positive or negative).

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Lot UUID

Request Body schema:
required

The new Lot resource

adjustment
required
integer
reason
required
string <= 500 characters

Responses

Request samples

Content type
{
  • "adjustment": 0,
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Recall a lot

Recall a lot, marking it as unavailable.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Lot UUID

Request Body schema:
required

The new Lot resource

reason
required
string

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "lotNumber": "LOT-2024-001",
  • "totalQuantity": 1000,
  • "availableQuantity": 850,
  • "status": "available",
  • "lastAdjustmentReason": "Customer order",
  • "expiryDate": "2025-12-31T00:00:00+00:00",
  • "manufactureDate": "2024-01-15T00:00:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Inventory - Packaging Profiles

A reusable packaging profile — an item's own physical spec (weight, optional dimensions, optional units-per-pallet) that inventory items resolve their physicals from. Tenant-managed reference data; money-free.

List packaging profiles

Retrieve a paginated list of packaging profiles with optional filters.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a packaging profile

Create a packaging profile

Authorizations:
Bearer
Request Body schema:
required

The new PackagingProfile resource

name
string or null <= 255 characters
required
InventoryItemWeightInput (object) or null
packagingType
string
Default: "loose"
Enum: "loose" "box" "bag" "tube" "pallet"
code
string or null <= 191 characters
InventoryItemDimensionsInput (object) or null
unitsPerPallet
integer or null >= 0
weightUnit
string or null
Enum: "g" "kg"

Display hint for weight; values are always stored in grams.

dimensionUnit
string or null
Enum: "mm" "cm"

Display hint for dimensions; values are always stored in millimetres.

Responses

Request samples

Content type
{
  • "name": "string",
  • "weight": {
    },
  • "packagingType": "loose",
  • "code": "string",
  • "dimensions": {
    },
  • "unitsPerPallet": 0,
  • "weightUnit": "g",
  • "dimensionUnit": "mm"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "small_mailer",
  • "name": "Small mailer 20x15x5",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "weightUnit": "g",
  • "dimensionUnit": "mm",
  • "packagingType": "loose",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a packaging profile

Get a packaging profile

Authorizations:
Bearer
path Parameters
id
required
string

PackagingProfile identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "small_mailer",
  • "name": "Small mailer 20x15x5",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "weightUnit": "g",
  • "dimensionUnit": "mm",
  • "packagingType": "loose",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update a packaging profile

Update mutable fields. Only provided fields are changed; the code is immutable.

Authorizations:
Bearer
path Parameters
id
required
string

PackagingProfile identifier

Request Body schema: application/merge-patch+json
required

The updated PackagingProfile resource

name
string or null [ 1 .. 255 ] characters
InventoryItemWeightInput (object) or null
InventoryItemDimensionsInput (object) or null
unitsPerPallet
integer or null >= 0
packagingType
string or null
Enum: "loose" "box" "bag" "tube" "pallet"
weightUnit
string or null
Enum: "g" "kg"

Display hint for weight; values are always stored in grams.

dimensionUnit
string or null
Enum: "mm" "cm"

Display hint for dimensions; values are always stored in millimetres.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 0,
  • "packagingType": "loose",
  • "weightUnit": "g",
  • "dimensionUnit": "mm"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "small_mailer",
  • "name": "Small mailer 20x15x5",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "weightUnit": "g",
  • "dimensionUnit": "mm",
  • "packagingType": "loose",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Archive a packaging profile

Archive a packaging profile

Authorizations:
Bearer
path Parameters
id
required
string

PackagingProfile identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "small_mailer",
  • "name": "Small mailer 20x15x5",
  • "weight": {
    },
  • "dimensions": {
    },
  • "unitsPerPallet": 48,
  • "weightUnit": "g",
  • "dimensionUnit": "mm",
  • "packagingType": "loose",
  • "status": "active",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Bulk-assign this profile to inventory items

The grid bulk action — assigns this packaging profile to every inventory item id in the body.

Authorizations:
Bearer
path Parameters
id
required
string

PackagingProfile identifier

Request Body schema:
required

The new PackagingProfile resource

itemIds
Array of strings non-empty

Responses

Request samples

Content type
{
  • "itemIds": [
    ]
}

Response samples

Content type
{
  • "type": "/errors/validation-error",
  • "title": "Validation Error",
  • "status": 400,
  • "detail": "The provided input is invalid",
  • "violations": [
    ],
  • "instance": "string"
}

Inventory - Principals

Represents an inventory principal — a partner acting as a goods owner in the inventory domain.

List all inventory principals

Retrieve a paginated list of inventory principals with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "suspended" "closed"
Example: status=active

Filter by principal status

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create an inventory principal

Create a new inventory principal from an existing partner.

Authorizations:
Bearer
Request Body schema: application/json
required

Principal creation data

partnerId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "partnerId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Find a principal by partner

Resolve the principal profile held by a partner. Returns 404 when the partner holds no principal.

Authorizations:
Bearer
path Parameters
partnerId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Partner UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Onboard an existing partner as a principal

Create a principal for an EXISTING partner and assign the Partner.Principal role. Idempotent: returns the existing principal (200) when the partner already holds one.

Authorizations:
Bearer
Request Body schema: application/json
required

Onboarding data

partnerId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "partnerId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get an inventory principal

Retrieve a single inventory principal by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Principal UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Activate an inventory principal

Activate a suspended inventory principal.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Principal UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Suspend an inventory principal

Suspend an active inventory principal.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Principal UUID

Request Body schema:
required

The new InventoryPrincipal resource

reason
required
string

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "partnerId": "01912345-6789-7abc-def0-123456789abc",
  • "partnerName": "Acme Logistics",
  • "status": "active",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Inventory - Serial Units

Represents a serial unit — an individually tracked unit of inventory.

List all serial units

Retrieve a paginated list of serial units with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "available" "allocated" "in_transit" "delivered" "returned" "damaged" "lost"
Example: status=available

Filter by serial unit status

inventoryItemId
string <uuid>

Filter by inventory item ID

lotId
string <uuid>

Filter by lot ID

search
string
Example: search=SN-001

Search by serial number

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 20
Example: itemsPerPage=20

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Register a serial unit

Register a new serial unit for an inventory item.

Authorizations:
Bearer
Request Body schema: application/json
required

Serial unit registration data

inventoryItemId
required
string <uuid>
serialNumber
required
string non-empty
quantity
required
integer >= 1
lotId
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "inventoryItemId": "ef1bc09e-447a-46aa-a9d9-d86e3d490831",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "lotId": "e8c5065f-4319-4b13-ad99-eb9182a42d06"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "status": "available",
  • "lotId": "01912345-6789-7abc-def0-123456789abc",
  • "lotNumber": "string",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a serial unit

Retrieve a single serial unit by its UUID.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Serial unit UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "status": "available",
  • "lotId": "01912345-6789-7abc-def0-123456789abc",
  • "lotNumber": "string",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get serial unit audit timeline

Return the curated event-by-event audit timeline for a serial unit, oldest first.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Serial unit UUID

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Update serial unit status

Update the status of a serial unit.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Serial unit UUID

Request Body schema:
required

The new SerialUnit resource

status
required
string

Responses

Request samples

Content type
{
  • "status": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemId": "01912345-6789-7abc-def0-123456789abc",
  • "inventoryItemName": "string",
  • "serialNumber": "SN-001",
  • "quantity": 1,
  • "status": "available",
  • "lotId": "01912345-6789-7abc-def0-123456789abc",
  • "lotNumber": "string",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}