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.

Partners

Represents a partner — a unified business entity the tenant transacts with.

Partners have no knowledge of roles (carrier, principal, supplier, customer). Roles are emergent, determined by which modules reference this PartnerId.

List all partners

Retrieve a paginated list of partners with optional filters.

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

Filter by partner status

search
string
Example: search=Acme

Search by name

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 a partner

Create a new partner.

Authorizations:
Bearer
Request Body schema: application/json
required

Partner creation data

name
required
string [ 1 .. 255 ] characters
email
string or null <email>
phone
string or null <= 50 characters
website
string or null <url>
taxId
string or null
registrationNumber
string or null
netDays
integer or null
currency
string or null
paymentMethod
string or null

Responses

Request samples

Content type
application/json
{
  • "name": "Acme Logistics Inc.",
  • "email": "[email protected]",
  • "phone": "string",
  • "website": "string",
  • "taxId": "string",
  • "registrationNumber": "string",
  • "netDays": 30,
  • "currency": "EUR",
  • "paymentMethod": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a partner

Retrieve a single partner by its UUID.

Authorizations:
Bearer
path Parameters
id
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",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Activate a partner

Activate a pending or suspended partner.

Authorizations:
Bearer
path Parameters
id
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",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Close a partner

Close an active or suspended partner.

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

Partner UUID

Request Body schema:
required

The new Partner 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",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Suspend a partner

Suspend an active partner.

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

Partner UUID

Request Body schema:
required

The new Partner 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",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Update a partner

Update partner details. Only provided fields will be updated.

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

Partner UUID

Request Body schema:
required

The new Partner resource

name
string or null [ 1 .. 255 ] characters
ContactInput (object) or null
AddressInput (object) or null
taxId
string or null
taxExempt
boolean or null
registrationNumber
string or null
PaymentTermsInput (object) or null

Responses

Request samples

Content type
{
  • "name": "string",
  • "contact": {},
  • "address": {
    },
  • "taxId": "string",
  • "taxExempt": true,
  • "registrationNumber": "string",
  • "paymentTerms": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Partner Roles

Represents a role attached to a partner.

Exposed through GET /partners/{id}/roles. Mutation endpoints (add / update status / remove) live on PartnerResource because roles are owned by the partner aggregate.

List partner roles

Retrieve all roles attached to the partner.

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

Partner UUID

type
required
string

PartnerRole identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Add a role to a partner

Add a new role (carrier, principal, customer, supplier) to the partner.

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

Partner UUID

Request Body schema:
required

The new Partner resource

type
required
string
Enum: "carrier" "principal" "customer" "supplier"
ref
required
string
label
string or null

Responses

Request samples

Content type
{
  • "type": "carrier",
  • "ref": "string",
  • "label": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Remove a role from a partner

Remove an existing role from the partner.

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

Partner UUID

roleType
required
string
Enum: "carrier" "principal" "customer" "supplier"
Example: carrier

Role type

Responses

Update a role status

Update the status of an existing partner role.

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

Partner UUID

roleType
required
string
Enum: "carrier" "principal" "customer" "supplier"
Example: carrier

Role type

Request Body schema:
required

The new Partner resource

status
required
string
Enum: "active" "inactive"

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "name": "Acme Logistics Inc.",
  • "type": "individual",
  • "classification": "regular",
  • "status": "pending_approval",
  • "contact": {
    },
  • "address": {
    },
  • "taxId": "DE123456789",
  • "taxExempt": false,
  • "registrationNumber": "HRB 12345",
  • "paymentTerms": {
    },
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}