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.

Fulfilment - Policies

Fulfilment policy — the tenant's routing brain. A policy owns an ordered set of WHEN…THEN rules plus a default strategy (mode + custodian priorities); it is assigned per channel / channel-type / org-default and consulted by the placement engine. Item detail (rules) comes from the event-sourced aggregate; the collection is served from the lean read-model.

List fulfilment policies

All fulfilment policies for the current tenant, newest first.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Create a fulfilment policy

Create a draft policy with a name, default mode, and (optional) custodian priorities.

Authorizations:
Bearer
Request Body schema:
required

The new FulfilmentPolicy resource

name
required
string <= 255 characters
Default: ""
mode
required
string
Default: "priority"
Enum: "priority" "exclusive"
custodianPriorities
Array of strings
currency
string or null

ISO-4217 currency the policy's money thresholds are expressed in. Optional — the org default currency is used (resolved at write time) when omitted.

https://schema.org/priceCurrency

Responses

Request samples

Content type
{
  • "name": "",
  • "mode": "priority",
  • "custodianPriorities": [
    ],
  • "currency": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Get a fulfilment policy

A single policy with its ordered rules loaded from the aggregate.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Activate the policy

Activate the policy

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Archive the policy

Archive the policy

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Assign the policy to a scope (channel / channel-type / org-default)

Assign the policy to a scope (channel / channel-type / org-default)

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

scope
required
string
Default: ""
Enum: "channel" "channel_type" "org_default"
scopeKey
string or null

Responses

Request samples

Content type
{
  • "scope": "channel",
  • "scopeKey": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Clear a scope assignment

Clear a scope assignment

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

scope
required
string
Default: ""
Enum: "channel" "channel_type" "org_default"
scopeKey
string or null

Responses

Request samples

Content type
{
  • "scope": "channel",
  • "scopeKey": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Dry-run a decision

Evaluate the policy against a sample order context and return the decision without creating anything.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

channelId
string or null
channelType
string or null
destinationCountry
string or null <= 2 characters
orderValue
integer or null >= 0
currency
string or null <= 3 characters
totalWeightGrams
integer or null >= 0
itemFlags
Array of strings
skus
Array of strings
categoryIds
Array of strings

Responses

Request samples

Content type
{
  • "channelId": "string",
  • "channelType": "string",
  • "destinationCountry": "st",
  • "orderValue": 0,
  • "currency": "str",
  • "totalWeightGrams": 0,
  • "itemFlags": [
    ],
  • "skus": [
    ],
  • "categoryIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "outcome": "assign",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "custodianId": "string",
  • "reason": "string"
}

Remove a rule

Remove a rule

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

ruleId
required
string <ulid>
Default: ""

Responses

Request samples

Content type
{
  • "ruleId": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Rename a policy

Rename a policy

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

name
required
string <= 255 characters
Default: ""

Responses

Request samples

Content type
{
  • "name": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Reorder rules (drag-to-sort priority)

Reorder rules (drag-to-sort priority)

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

orderedRuleIds
Array of strings non-empty

Responses

Request samples

Content type
{
  • "orderedRuleIds": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Append a rule

Append a rule

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

ruleId
string or null <ulid>
enabled
boolean
Default: true
Array of objects (FulfilmentRuleConditionInput)
required
object (FulfilmentRuleActionInput)

Responses

Request samples

Content type
{
  • "ruleId": "string",
  • "enabled": true,
  • "conditions": [
    ],
  • "action": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Set the default mode + custodian priorities

Set the default mode + custodian priorities

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

mode
required
string
Default: "priority"
Enum: "priority" "exclusive"
custodianPriorities
Array of strings

Responses

Request samples

Content type
{
  • "mode": "priority",
  • "custodianPriorities": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Replace an existing rule in place

Replace an existing rule in place

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentPolicy identifier

Request Body schema:
required

The new FulfilmentPolicy resource

ruleId
required
string <ulid>
Default: ""
enabled
boolean
Default: true
Array of objects (FulfilmentRuleConditionInput)
required
object (FulfilmentRuleActionInput)

Responses

Request samples

Content type
{
  • "ruleId": "",
  • "enabled": true,
  • "conditions": [
    ],
  • "action": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "name": "string",
  • "mode": "priority",
  • "currency": "string",
  • "status": "draft",
  • "ruleCount": 0,
  • "custodianPriorities": [
    ],
  • "rules": [
    ],
  • "createdAt": "string"
}

Policy assignment matrix

Every sales channel with the fulfilment policy bound at each scope tier and the resolved effective policy.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Fulfilment - Orders

Resource 'Fulfilment - Orders' operations.

List fulfilment orders

Retrieve a paginated list of fulfilment orders with optional filters.

Authorizations:
Bearer
query Parameters
sourceOrderId
string <ulid>
number
string
custodianId
string <ulid>
status
string
policyId
string <ulid>
page
integer >= 1
Default: 1
itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Responses

Response samples

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

Get a fulfilment order

Retrieve a single fulfilment order by its ULID.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentOrder identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "custodianName": "string",
  • "node": "string",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "lineItems": [
    ],
  • "status": "held",
  • "holdOutcome": "reject",
  • "holdReason": "string",
  • "expectedShipAt": "string",
  • "expectedDeliveryAt": "string",
  • "notes": "string",
  • "externalIds": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "closedAt": "string"
}

Cancel a fulfilment order

Cancel a non-terminal fulfilment order with a reason.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentOrder identifier

Request Body schema:
required

The new FulfilmentOrder resource

reason
required
string [ 1 .. 1024 ] characters
Default: ""

Responses

Request samples

Content type
{
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "custodianName": "string",
  • "node": "string",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "lineItems": [
    ],
  • "status": "held",
  • "holdOutcome": "reject",
  • "holdReason": "string",
  • "expectedShipAt": "string",
  • "expectedDeliveryAt": "string",
  • "notes": "string",
  • "externalIds": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "closedAt": "string"
}

Mark a fulfilment order incomplete

Flag a fulfilment order as partially-dispatched-only with a reason — the remainder is treated as cancelled.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentOrder identifier

Request Body schema:
required

The new FulfilmentOrder resource

reason
required
string [ 1 .. 1024 ] characters
Default: ""

Responses

Request samples

Content type
{
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "custodianName": "string",
  • "node": "string",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "lineItems": [
    ],
  • "status": "held",
  • "holdOutcome": "reject",
  • "holdReason": "string",
  • "expectedShipAt": "string",
  • "expectedDeliveryAt": "string",
  • "notes": "string",
  • "externalIds": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "closedAt": "string"
}

Override expected delivery date

Operator override of the FulfilmentOrder expected delivery date. Pass null/omit to clear.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentOrder identifier

Request Body schema:
required

The new FulfilmentOrder resource

expectedDeliveryAt
string or null

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "custodianName": "string",
  • "node": "string",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "lineItems": [
    ],
  • "status": "held",
  • "holdOutcome": "reject",
  • "holdReason": "string",
  • "expectedShipAt": "string",
  • "expectedDeliveryAt": "string",
  • "notes": "string",
  • "externalIds": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "closedAt": "string"
}

Override expected ship-by date

Operator override of the FulfilmentOrder expected ship-by date. Pass null/omit to clear.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentOrder identifier

Request Body schema:
required

The new FulfilmentOrder resource

expectedShipAt
string or null

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "custodianName": "string",
  • "node": "string",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "lineItems": [
    ],
  • "status": "held",
  • "holdOutcome": "reject",
  • "holdReason": "string",
  • "expectedShipAt": "string",
  • "expectedDeliveryAt": "string",
  • "notes": "string",
  • "externalIds": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "closedAt": "string"
}

Reassign a fulfilment order

Change the (custodian, warehouse) assignment of a CREATED fulfilment order. Reassignment is forbidden once a custodian has accepted (OPEN) the order.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentOrder identifier

Request Body schema:
required

The new FulfilmentOrder resource

custodianId
required
string <ulid>
Default: ""

Responses

Request samples

Content type
{
  • "custodianId": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "custodianName": "string",
  • "node": "string",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "lineItems": [
    ],
  • "status": "held",
  • "holdOutcome": "reject",
  • "holdReason": "string",
  • "expectedShipAt": "string",
  • "expectedDeliveryAt": "string",
  • "notes": "string",
  • "externalIds": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "closedAt": "string"
}

Resolve a held fulfilment order

Assign a custodian to a HELD order (policy Reject / Manual review) so it enters the normal assigned lifecycle.

Authorizations:
Bearer
path Parameters
id
required
string

FulfilmentOrder identifier

Request Body schema:
required

The new FulfilmentOrder resource

custodianId
required
string <ulid>
Default: ""

Responses

Request samples

Content type
{
  • "custodianId": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "custodianName": "string",
  • "node": "string",
  • "policyId": "string",
  • "appliedRuleIds": [
    ],
  • "lineItems": [
    ],
  • "status": "held",
  • "holdOutcome": "reject",
  • "holdReason": "string",
  • "expectedShipAt": "string",
  • "expectedDeliveryAt": "string",
  • "notes": "string",
  • "externalIds": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "closedAt": "string"
}

Get a fulfilment order pipeline

Retrieve a fulfilment order together with its 3PL execution snapshot (provider type/status/sync) and a backend-computed operator ladder in a single response.

Authorizations:
Bearer
path Parameters
orderId
required
string

FulfilmentOrderPipeline identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "orderId": "string",
  • "orderNumber": "string",
  • "orderStatus": "string",
  • "sourceOrderId": "string",
  • "custodianId": "string",
  • "node": "string",
  • "execution": {
    },
  • "stages": [
    ]
}