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.

Webhooks

Closed catalog of subscribable webhook events.

The catalog is derived from NotificationTopic and grouped as module → aggregate → event so the UI can render a three-tier tree picker. The endpoint is a singleton (no identifier) — clients always GET the full tree.

List webhook deliveries

Retrieve a paginated list of webhook delivery records with optional filters.

Authorizations:
Bearer
query Parameters
endpointId
string <uuid>
Example: endpointId=01912345-6789-7abc-def0-123456789abc

Filter by webhook endpoint UUID

status
string
Enum: "pending" "sending" "succeeded" "failed" "cancelled"
Example: status=succeeded

Filter by delivery status

eventType
string
Example: eventType=shipment.delivered

Filter by event type

dateFrom
string <date>
Example: dateFrom=2024-06-01

Filter deliveries from this date (inclusive)

dateTo
string <date>
Example: dateTo=2024-06-30

Filter deliveries up to this date (inclusive)

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

Page number for pagination

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

Number of items per page

Responses

Response samples

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

Get a webhook delivery

Retrieve a single webhook delivery by its UUID. Returns full details including attempt history.

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

Webhook delivery UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "endpointId": "01912345-6789-7abc-def0-123456789abc",
  • "endpointUrl": "https://api.example.com/webhooks/glacia",
  • "eventType": "shipment.delivered",
  • "status": "pending",
  • "attemptCount": 1,
  • "maxAttempts": 5,
  • "lastResponseCode": 200,
  • "lastResponseBody": "{\"status\": \"received\"}",
  • "lastDurationMs": 150,
  • "lastError": "Connection timeout",
  • "nextRetryAt": "2024-06-15T14:35:00+00:00",
  • "firstAttemptAt": "2024-06-15T14:30:00+00:00",
  • "lastAttemptAt": "2024-06-15T14:30:00+00:00",
  • "succeededAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-15T14:30:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Retry a failed webhook delivery

Manually retry a failed webhook delivery. The delivery will be queued for immediate retry.

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

Webhook delivery UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "endpointId": "01912345-6789-7abc-def0-123456789abc",
  • "endpointUrl": "https://api.example.com/webhooks/glacia",
  • "eventType": "shipment.delivered",
  • "status": "pending",
  • "attemptCount": 1,
  • "maxAttempts": 5,
  • "lastResponseCode": 200,
  • "lastResponseBody": "{\"status\": \"received\"}",
  • "lastDurationMs": 150,
  • "lastError": "Connection timeout",
  • "nextRetryAt": "2024-06-15T14:35:00+00:00",
  • "firstAttemptAt": "2024-06-15T14:30:00+00:00",
  • "lastAttemptAt": "2024-06-15T14:30:00+00:00",
  • "succeededAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-15T14:30:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

List webhook endpoints

Retrieve a paginated list of webhook endpoints with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "active" "paused" "failed" "disabled"
Example: status=active

Filter by endpoint status

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

Page number for pagination

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

Number of items per page

Responses

Response samples

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

Create a webhook endpoint

Create a new webhook endpoint subscription. The endpoint will be active immediately after creation.

Authorizations:
Bearer
Request Body schema: application/json
required

Webhook endpoint configuration

url
required
string <uri>

URL to receive webhook payloads

events
required
Array of strings

List of events to subscribe to. See GET /webhooks/events for the full catalog.

description
string or null <= 255 characters

Human-readable description of the endpoint

object or null

Custom headers to include in webhook requests

Responses

Request samples

Content type
application/json
{
  • "url": "https://api.example.com/webhooks/glacia",
  • "events": [
    ],
  • "description": "Order management system notifications",
  • "headers": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "url": "https://api.example.com/webhooks/glacia",
  • "description": "Order management system notifications",
  • "status": "active",
  • "events": [
    ],
  • "headers": {
    },
  • "secret": "whsec_abc123...",
  • "failureCount": 0,
  • "lastSuccessAt": "2024-06-15T14:30:00+00:00",
  • "lastFailureAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Get a webhook endpoint

Retrieve a single webhook endpoint by its UUID. Returns full details including event subscriptions.

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

Webhook endpoint UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "url": "https://api.example.com/webhooks/glacia",
  • "description": "Order management system notifications",
  • "status": "active",
  • "events": [
    ],
  • "headers": {
    },
  • "secret": "whsec_abc123...",
  • "failureCount": 0,
  • "lastSuccessAt": "2024-06-15T14:30:00+00:00",
  • "lastFailureAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Delete a webhook endpoint

Permanently delete a webhook endpoint. This action cannot be undone.

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

Webhook endpoint UUID

Responses

Update a webhook endpoint

Update webhook endpoint configuration. Only provided fields will be updated.

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

Webhook endpoint UUID

Request Body schema: application/json
optional

Webhook endpoint update data

url
string <uri>

URL to receive webhook payloads

events
Array of strings

List of events to subscribe to

description
string or null

Human-readable description

object or null

Custom headers to include

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "events": [
    ],
  • "description": "string",
  • "headers": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "url": "https://api.example.com/webhooks/glacia",
  • "description": "Order management system notifications",
  • "status": "active",
  • "events": [
    ],
  • "headers": {
    },
  • "secret": "whsec_abc123...",
  • "failureCount": 0,
  • "lastSuccessAt": "2024-06-15T14:30:00+00:00",
  • "lastFailureAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Pause a webhook endpoint

Temporarily pause webhook delivery to this endpoint. Events will be queued and delivered when resumed.

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

Webhook endpoint UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "url": "https://api.example.com/webhooks/glacia",
  • "description": "Order management system notifications",
  • "status": "active",
  • "events": [
    ],
  • "headers": {
    },
  • "secret": "whsec_abc123...",
  • "failureCount": 0,
  • "lastSuccessAt": "2024-06-15T14:30:00+00:00",
  • "lastFailureAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Resume a webhook endpoint

Resume webhook delivery to a paused endpoint. Queued events will be delivered.

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

Webhook endpoint UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "url": "https://api.example.com/webhooks/glacia",
  • "description": "Order management system notifications",
  • "status": "active",
  • "events": [
    ],
  • "headers": {
    },
  • "secret": "whsec_abc123...",
  • "failureCount": 0,
  • "lastSuccessAt": "2024-06-15T14:30:00+00:00",
  • "lastFailureAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Rotate webhook signing secret

Generate a new signing secret for the webhook endpoint. The old secret becomes invalid immediately.

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

Webhook endpoint UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "url": "https://api.example.com/webhooks/glacia",
  • "description": "Order management system notifications",
  • "status": "active",
  • "events": [
    ],
  • "headers": {
    },
  • "secret": "whsec_abc123...",
  • "failureCount": 0,
  • "lastSuccessAt": "2024-06-15T14:30:00+00:00",
  • "lastFailureAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-01-15T10:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00"
}

Test a webhook endpoint

Send a test payload to the webhook endpoint to verify connectivity and configuration.

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

Webhook endpoint UUID

Request Body schema:
required

The new WebhookEndpoint resource

eventType
string or null <= 255 characters

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "success": true,
  • "responseCode": 200,
  • "responseTimeMs": 142,
  • "responseBody": "{\"ok\":true}",
  • "errorMessage": "HTTP 405"
}

List subscribable webhook events

Returns every event a webhook endpoint may subscribe to, grouped by module and aggregate for tree-picker UIs.

Authorizations:
Bearer

Responses

Response samples

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

Integration Webhooks

The single generic inbound-webhook receiver. Every external platform (Shopify, WooCommerce, ShipBob, carriers, …) POSTs here, keyed by the Integration connection. The connection's providerKey + capabilities select the verifier and domain handler. PUBLIC — the sender carries no JWT; the HMAC signature IS the authentication.

Receive an inbound webhook from an external platform

Generic receiver for external platforms (Shopify, WooCommerce, ShipBob, carriers, …). Keyed by the Integration connection id; the HMAC signature is verified fail-closed.

Authorizations:
Bearer
path Parameters
connectionId
required
string
Example: 01HQWXYZ1234567890ABCDEF

Integration connection ULID

Responses

Response samples

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

Integration - Connections

OAuth-connect entry point for the Integration module.

POST /api/integration/connections/oauth/init — start an OAuth flow; returns the authorization URL the browser must navigate to.

The matching GET /api/integration/connections/oauth/callback lives on a plain Symfony route (see OAuthConnectCallbackProvider) because an OAuth callback carries no path identifier.

List integration connections

List integration connections

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Connect an external service

Connect an external service

Authorizations:
Bearer
Request Body schema:
required

The new IntegrationConnection resource

providerKey
required
string
Default: ""
object

Responses

Request samples

Content type
{
  • "providerKey": "",
  • "secrets": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "reference": "glacia:///integration/connections/01HZY...",
  • "providerKey": "",
  • "status": "",
  • "grantedCapabilities": [
    ],
  • "createdAt": ""
}

Begin an OAuth-connect flow for a provider

Returns the authorization URL the browser must navigate to. The signed state is embedded in the URL.

Authorizations:
Bearer
Request Body schema:
required

The new IntegrationOAuthConnect resource

providerKey
string
Default: ""

Responses

Request samples

Content type
{
  • "providerKey": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "oauth-connect",
  • "authorizationUrl": ""
}

Get a connection by id

Get a connection by id

Authorizations:
Bearer
path Parameters
id
required
string

IntegrationConnection identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "reference": "glacia:///integration/connections/01HZY...",
  • "providerKey": "",
  • "status": "",
  • "grantedCapabilities": [
    ],
  • "createdAt": ""
}

Grant a capability on a connection

Grant a capability on a connection

Authorizations:
Bearer
path Parameters
id
required
string

IntegrationConnection identifier

Request Body schema:
required

The new IntegrationConnection resource

capabilityKey
required
string
Default: ""

Responses

Request samples

Content type
{
  • "capabilityKey": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "reference": "glacia:///integration/connections/01HZY...",
  • "providerKey": "",
  • "status": "",
  • "grantedCapabilities": [
    ],
  • "createdAt": ""
}

Purge a connection and wipe its secrets

Purge a connection and wipe its secrets

Authorizations:
Bearer
path Parameters
id
required
string

IntegrationConnection identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "reference": "glacia:///integration/connections/01HZY...",
  • "providerKey": "",
  • "status": "",
  • "grantedCapabilities": [
    ],
  • "createdAt": ""
}

Revoke a capability on a connection

Revoke a capability on a connection

Authorizations:
Bearer
path Parameters
id
required
string

IntegrationConnection identifier

Request Body schema:
required

The new IntegrationConnection resource

capabilityKey
required
string
Default: ""

Responses

Request samples

Content type
{
  • "capabilityKey": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "reference": "glacia:///integration/connections/01HZY...",
  • "providerKey": "",
  • "status": "",
  • "grantedCapabilities": [
    ],
  • "createdAt": ""
}

Integration - Providers

A connectable external-service provider descriptor.

Drives the connect-form picker: clients read this catalog to learn which providers exist, which surface capabilities each declares, whether the connect flow is an OAuth redirect (oauth: true) or a credential form, and — for credential-form providers — the fields to render.

List connectable providers

Returns the provider catalog that drives the connect-form picker. Filter with ?capability=channel|carrier|custodian|storage.

Authorizations:
Bearer

Responses

Response samples

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