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.

Notifications - Channel Policy

Represents a tenant's org-level notification channel policy — the "ceiling" that decides which channels each topic may use before any per-user preference narrows it further.

The policy is a per-tenant singleton addressed at a fixed path; the resource identifier is therefore a constant. It is modeled as a topic x channel matrix — every entry is a (type, channel, enabled) cell.

Get the org-level notification channel policy

Retrieve the org-level notification channel policy (topic x channel matrix) for the current tenant. Every topic/channel cell is returned with its effective enabled flag — Email and Storage default on, every other channel defaults off until enabled.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "policy",
  • "entries": [
    ]
}

Configure the org-level notification channel policy

Update the org-level notification channel policy matrix for the current tenant. Cells absent from the request retain their previous on/off state.

Authorizations:
Bearer
Request Body schema: application/json
required

Channel policy configuration data

Array of objects

Policy matrix cells to update

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "policy",
  • "entries": [
    ]
}

Notifications - Preferences

Represents a user's notification preferences.

Preferences are modeled as a topic x channel matrix — every entry is a (type, channel, enabled) cell. The dispatch pipeline asks the matrix "is this topic enabled on this channel" before delivering.

Get current user notification preferences

Retrieve the notification preferences (topic x channel matrix) for the currently authenticated user.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Update notification preferences

Update the notification preference matrix for the currently authenticated user. Cells absent from the request retain their previous on/off state.

Authorizations:
Bearer
Request Body schema: application/json
required

Notification preferences update data

Array of objects

Preference matrix cells to update

doNotDisturb
boolean

Whether do not disturb mode is enabled

doNotDisturbStart
string or null

Start time for do not disturb (HH:MM format)

doNotDisturbEnd
string or null

End time for do not disturb (HH:MM format)

Responses

Request samples

Content type
application/json
{
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbStart": "22:00",
  • "doNotDisturbEnd": "08:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Disable do not disturb

Disable do not disturb mode for the current user. Notifications will resume delivery.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Enable do not disturb

Enable do not disturb mode for the current user. When enabled, notifications will not be delivered.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "entries": [
    ],
  • "doNotDisturb": false,
  • "doNotDisturbUntil": "2024-06-14T08:00:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Notifications

Notification API Resource.

List notifications

Retrieve a paginated list of notifications for the current user.

Authorizations:
Bearer
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Number of items per page

type
string
Enum: "operational" "incident" "financial" "maintenance" "account" "announcement"
Example: type=operational

Filter by the coarse NotificationType bucket

isRead
boolean

Filter by read status

Responses

Response samples

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

Mark all notifications as read

Mark all notifications as read for the current user.

Authorizations:
Bearer

Responses

Response samples

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

Get unread notification count

Get the count of unread notifications for the current user.

Authorizations:
Bearer

Responses

Response samples

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

Get a notification by id

Returns a single stored notification, including subject, body, payload, and read state.

Authorizations:
Bearer
path Parameters
id
required
string

StoredNotification identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "type": "string",
  • "topic": "string",
  • "title": "string",
  • "message": "string",
  • "priority": "string",
  • "isRead": true,
  • "createdAt": "string",
  • "readAt": "string",
  • "resourceId": "string",
  • "resourceType": "string",
  • "subject": "string"
}

Delete a notification

Delete a stored notification.

Authorizations:
Bearer
path Parameters
id
required
string
Example: notif-123

Notification ID

Responses

Mark notification as read

Mark a single notification as read.

Authorizations:
Bearer
path Parameters
id
required
string
Example: notif-123

Notification ID

Responses

Response samples

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

Notifications - Push

Push notification subscription resource.

List push subscriptions

List all push notification subscriptions for the current user.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Subscribe to push notifications

Register a Web Push subscription for the current user. If a subscription with the same endpoint already exists, the keys are updated.

Authorizations:
Bearer
Request Body schema:
required

The new PushSubscription resource

endpoint
string
p256dhKey
string
authKey
string
userAgent
string or null
expiresAt
string or null

Responses

Request samples

Content type
{
  • "endpoint": "string",
  • "p256dhKey": "string",
  • "authKey": "string",
  • "userAgent": "string",
  • "expiresAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "userId": "01HQWXYZ1234567890ABCDEF",
  • "endpoint": "https://fcm.googleapis.com/fcm/send/abcdef...",
  • "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "expiresAt": "2025-06-14T10:30:00+00:00"
}

Unsubscribe from push notifications

Remove a Web Push subscription by endpoint URL.

Authorizations:
Bearer
Request Body schema:
required

The new PushSubscription resource

endpoint
string

Responses

Request samples

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

Response samples

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

Notifications - Templates

Notification Template API Resource.

List notification templates

Retrieve a list of all notification templates.

Authorizations:
Bearer
query Parameters
notificationType
string
Example: notificationType=route.assigned

Filter by notification type

channelType
string
Enum: "storage" "email" "sms" "push"
Example: channelType=email

Filter by channel type

locale
string
Example: locale=en

Filter by locale

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Create a notification template

Create a new notification template.

Authorizations:
Bearer
Request Body schema:
required

The new NotificationTemplate resource

notificationType
required
string
Enum: "shipping.shipment.delayed" "shipping.shipment.delivered" "finance.payment.failed" "finance.payment.completed" "routing.incident.raised" "sales.order.fulfillment_blocked" "sales.order.fulfilled" "iam.tenant.invitation_sent" "iam.identity.password_reset" "iam.identity.email_verification" "admin.platform.announcement" "finance.invoice.overdue" "iam.identity.mfa_challenge_issued" "iam.identity.new_device_login" "finance.settlement.created" "finance.settlement.posted" "finance.settlement.paid" "iam.tenant.welcome_sent" "document.documentrequest.submitted" "document.documentrequest.review_started" "document.documentrequest.validated" "document.documentrequest.rejected" "document.documentrequest.cancelled" "document.document.finalized" "document.document.voided" "document.compliance.expiry_scan" "finance.invoice.issued" "finance.invoice.paid" "finance.creditnote.issued" "finance.bill.received" "finance.outgoing_payment.submitted" "finance.outgoing_payment.completed" "fulfilment.order.created" "fulfilment.order.progressed" "fulfilment.order.closed" "fulfilment.order.cancelled" "fulfilment.reservation.requires_attention" "fulfilment.fulfilment.handed_off" "fulfilment.return.requested" "fulfilment.return.authorized" "fulfilment.return.rejected" "fulfilment.return.received" "fulfilment.return.resolved" "partner.partner.created" "partner.partner.status_changed" "inventory.lot.recalled" "inventory.lot.expired" "inventory.serial_unit.status_changed" "inventory.item.discontinued" "iam.membership.created" "iam.membership.member_joined" "iam.membership.suspended" "iam.membership.reinstated" "iam.membership.role_assigned" "iam.membership.role_revoked" "sales.channel.sync_failed" "sales.order.ready" "sales.order.cancelled" "shipping.shipment.created" "shipping.shipment.scheduled" "shipping.shipment.in_transit" "shipping.shipment.out_for_delivery" "shipping.shipment.cancelled" "shipping.shipment.lost" "shipping.shipment.damaged" "shipping.shipment.refused" "platform.billing.invoice.reminder" "messaging.message.new" "messaging.message.mention"
channelType
required
string
Enum: "storage" "email" "sms" "push" "webhook" "slack"
name
required
string <= 255 characters
subjectTemplate
required
string
bodyTemplate
required
string
htmlBodyTemplate
string or null
locale
required
string <= 10 characters
Default: "en"
tenantId
string or null <ulid>

Responses

Request samples

Content type
{
  • "notificationType": "shipping.shipment.delayed",
  • "channelType": "storage",
  • "name": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "locale": "en",
  • "tenantId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "notificationType": "string",
  • "channelType": "string",
  • "name": "string",
  • "locale": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true,
  • "tenantId": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a notification template

Retrieve a single notification template by ID.

Authorizations:
Bearer
path Parameters
id
required
string

NotificationTemplate identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "notificationType": "string",
  • "channelType": "string",
  • "name": "string",
  • "locale": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true,
  • "tenantId": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Delete a notification template

Delete a notification template.

Authorizations:
Bearer
path Parameters
id
required
string

NotificationTemplate identifier

Responses

Update a notification template

Update an existing notification template.

Authorizations:
Bearer
path Parameters
id
required
string

NotificationTemplate identifier

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

The updated NotificationTemplate resource

name
string or null <= 255 characters
subjectTemplate
string or null
bodyTemplate
string or null
htmlBodyTemplate
string or null
isActive
boolean or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "notificationType": "string",
  • "channelType": "string",
  • "name": "string",
  • "locale": "string",
  • "subjectTemplate": "string",
  • "bodyTemplate": "string",
  • "htmlBodyTemplate": "string",
  • "isActive": true,
  • "tenantId": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Notifications - Subscriptions

Self-service topic-watch resource.

A user watches (subscribes to) a notification topic — optionally scoped to a single subject — so the SubscribersResolver includes them as a recipient. GET reports the current watch state for the FE toggle; POST watches; POST /unsubscribe unwatches. All operations act on the authenticated identity within its tenant.

Get topic watch state

Whether the current identity watches the given topic (optionally scoped to a subject). Backs the FE watch toggle.

Authorizations:
Bearer
query Parameters
topic
required
string

Dotted topic value, e.g. shipping.shipment.delivered

subject
string

Exact subject URI to scope the watch; omit to query the whole-topic watch

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "topic": "string",
  • "subject": "string",
  • "subscribed": true
}

Watch a topic

Subscribe the current identity to a topic (optionally scoped to a subject). Idempotent — watching again is a no-op.

Authorizations:
Bearer
Request Body schema:
required

The new TopicSubscription resource

topic
required
string
Default: ""
Enum: "shipping.shipment.delayed" "shipping.shipment.delivered" "finance.payment.failed" "finance.payment.completed" "routing.incident.raised" "sales.order.fulfillment_blocked" "sales.order.fulfilled" "iam.tenant.invitation_sent" "iam.identity.password_reset" "iam.identity.email_verification" "admin.platform.announcement" "finance.invoice.overdue" "iam.identity.mfa_challenge_issued" "iam.identity.new_device_login" "finance.settlement.created" "finance.settlement.posted" "finance.settlement.paid" "iam.tenant.welcome_sent" "document.documentrequest.submitted" "document.documentrequest.review_started" "document.documentrequest.validated" "document.documentrequest.rejected" "document.documentrequest.cancelled" "document.document.finalized" "document.document.voided" "document.compliance.expiry_scan" "finance.invoice.issued" "finance.invoice.paid" "finance.creditnote.issued" "finance.bill.received" "finance.outgoing_payment.submitted" "finance.outgoing_payment.completed" "fulfilment.order.created" "fulfilment.order.progressed" "fulfilment.order.closed" "fulfilment.order.cancelled" "fulfilment.reservation.requires_attention" "fulfilment.fulfilment.handed_off" "fulfilment.return.requested" "fulfilment.return.authorized" "fulfilment.return.rejected" "fulfilment.return.received" "fulfilment.return.resolved" "partner.partner.created" "partner.partner.status_changed" "inventory.lot.recalled" "inventory.lot.expired" "inventory.serial_unit.status_changed" "inventory.item.discontinued" "iam.membership.created" "iam.membership.member_joined" "iam.membership.suspended" "iam.membership.reinstated" "iam.membership.role_assigned" "iam.membership.role_revoked" "sales.channel.sync_failed" "sales.order.ready" "sales.order.cancelled" "shipping.shipment.created" "shipping.shipment.scheduled" "shipping.shipment.in_transit" "shipping.shipment.out_for_delivery" "shipping.shipment.cancelled" "shipping.shipment.lost" "shipping.shipment.damaged" "shipping.shipment.refused" "platform.billing.invoice.reminder" "messaging.message.new" "messaging.message.mention"
subject
string or null

Responses

Request samples

Content type
{
  • "topic": "shipping.shipment.delayed",
  • "subject": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "topic": "string",
  • "subject": "string",
  • "subscribed": true
}

Unwatch a topic

Remove the current identity's watch for a topic (optionally subject-scoped). No-op when not watched.

Authorizations:
Bearer
Request Body schema:
required

The new TopicSubscription resource

topic
required
string
Default: ""
Enum: "shipping.shipment.delayed" "shipping.shipment.delivered" "finance.payment.failed" "finance.payment.completed" "routing.incident.raised" "sales.order.fulfillment_blocked" "sales.order.fulfilled" "iam.tenant.invitation_sent" "iam.identity.password_reset" "iam.identity.email_verification" "admin.platform.announcement" "finance.invoice.overdue" "iam.identity.mfa_challenge_issued" "iam.identity.new_device_login" "finance.settlement.created" "finance.settlement.posted" "finance.settlement.paid" "iam.tenant.welcome_sent" "document.documentrequest.submitted" "document.documentrequest.review_started" "document.documentrequest.validated" "document.documentrequest.rejected" "document.documentrequest.cancelled" "document.document.finalized" "document.document.voided" "document.compliance.expiry_scan" "finance.invoice.issued" "finance.invoice.paid" "finance.creditnote.issued" "finance.bill.received" "finance.outgoing_payment.submitted" "finance.outgoing_payment.completed" "fulfilment.order.created" "fulfilment.order.progressed" "fulfilment.order.closed" "fulfilment.order.cancelled" "fulfilment.reservation.requires_attention" "fulfilment.fulfilment.handed_off" "fulfilment.return.requested" "fulfilment.return.authorized" "fulfilment.return.rejected" "fulfilment.return.received" "fulfilment.return.resolved" "partner.partner.created" "partner.partner.status_changed" "inventory.lot.recalled" "inventory.lot.expired" "inventory.serial_unit.status_changed" "inventory.item.discontinued" "iam.membership.created" "iam.membership.member_joined" "iam.membership.suspended" "iam.membership.reinstated" "iam.membership.role_assigned" "iam.membership.role_revoked" "sales.channel.sync_failed" "sales.order.ready" "sales.order.cancelled" "shipping.shipment.created" "shipping.shipment.scheduled" "shipping.shipment.in_transit" "shipping.shipment.out_for_delivery" "shipping.shipment.cancelled" "shipping.shipment.lost" "shipping.shipment.damaged" "shipping.shipment.refused" "platform.billing.invoice.reminder" "messaging.message.new" "messaging.message.mention"
subject
string or null

Responses

Request samples

Content type
{
  • "topic": "shipping.shipment.delayed",
  • "subject": "string"
}

Response samples

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