API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

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

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Sales - Acceptance Rules

Represents an acceptance rule set for auto-accepting/rejecting sourced orders.

Rule sets define conditions under which orders from a channel should be automatically accepted, rejected, or held for review.

List acceptance rule sets

Retrieve a list of acceptance rule sets, optionally filtered by channel.

Authorizations:
Bearer
query Parameters
channelId
string
Example: channelId=01HQWXYZ1234567890ABCDEF

Filter by sales channel ID

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Create an acceptance rule set

Create a new acceptance rule set for a sales channel.

Authorizations:
Bearer
Request Body schema: application/json
required

Acceptance rule set data

channelId
required
string

Sales channel ID

name
required
string

Human-readable name

required
Array of objects
action
required
string
Enum: "accept" "reject" "hold"
isActive
boolean
Default: true
priority
integer
Default: 0

Lower = evaluated first

Responses

Request samples

Content type
application/json
{
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "name": "Reject high-value orders",
  • "conditions": [
    ],
  • "action": "hold",
  • "isActive": true,
  • "priority": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "name": "Reject high-value orders",
  • "conditions": [
    ],
  • "action": "accept",
  • "isActive": true,
  • "priority": 0,
  • "createdAt": "2024-06-14T10:30:00+00:00"
}

Get an acceptance rule set

Retrieve a single acceptance rule set by its ID.

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

Acceptance rule set ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "name": "Reject high-value orders",
  • "conditions": [
    ],
  • "action": "accept",
  • "isActive": true,
  • "priority": 0,
  • "createdAt": "2024-06-14T10:30:00+00:00"
}

Delete an acceptance rule set

Permanently delete an acceptance rule set. This action cannot be undone.

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

Acceptance rule set ULID

Responses

Sales - Bulk Import

Represents the result of a bulk order import operation.

Bulk import orders

Import multiple orders from structured data for a specific channel.

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

Channel ULID

Request Body schema:
required

The new BulkImportResult resource

required
Array of objects [ 1 .. 500 ] items

Array of order data to import.

skipDuplicates
boolean
Default: true

Whether to skip duplicate orders.

Responses

Request samples

Content type
{
  • "orders": [
    ],
  • "skipDuplicates": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "totalOrders": 50,
  • "imported": 45,
  • "skipped": 3,
  • "failed": 2,
  • "errors": [
    ]
}

Sales - Analytics

Represents per-channel analytics metrics for sales channels.

Provides volume, acceptance rates, sync success rates, and processing metrics.

List analytics for all channels

Retrieve analytics metrics for all sales channels within a given time period.

Authorizations:
Bearer
query Parameters
period
string
Default: "30d"
Enum: "today" "7d" "30d" "90d" "all_time"
Example: period=30d

Time period for analytics

sortBy
string
Default: "orders"
Enum: "revenue" "orders" "acceptance_rate" "sync_success_rate"
Example: sortBy=orders

Sort channels by metric

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

Maximum number of channels to return

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Get analytics for a specific channel

Retrieve detailed analytics metrics for a single sales channel.

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

Channel ULID

query Parameters
period
string
Default: "30d"
Enum: "today" "7d" "30d" "90d" "all_time"
Example: period=30d

Time period for analytics

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Online Store",
  • "channelType": "string",
  • "totalOrdersImported": 1248,
  • "totalOrdersFailed": 12,
  • "ordersAccepted": 1180,
  • "ordersRejected": 56,
  • "ordersHeldForReview": 12,
  • "totalSyncs": 672,
  • "successfulSyncs": 665,
  • "failedSyncs": 7,
  • "acceptanceRate": 0.945,
  • "syncSuccessRate": 0.99,
  • "totalRevenueInCents": 18720000,
  • "averageOrderValueInCents": 15000,
  • "averageProcessingTimeSeconds": 45.2,
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "period": "today"
}

Sales Channels

Re-authorize an existing channel via OAuth.

POST /api/sales/channels/{channelId}/reconnect Resolves the channel's connected shop SERVER-SIDE and returns the provider authorize URL (with the channel bound into the signed state) the browser must navigate to. The UI needs no shop-domain input — it POSTs the channel id and redirects the user to authorizationUrl.

List all sales channels

Retrieve a paginated list of sales channels with optional filters.

Authorizations:
Bearer
query Parameters
type
string
Example: type=manual

Filter by channel type

status
string
Enum: "active" "paused" "disconnected"
Example: status=active

Filter by channel status

merchantId
string
Example: merchantId=01HQWXYZ1234567890ABCDEF

Filter to channels linked to this merchant (ULID)

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": [
    ]
}

Connect a sales channel

Connect a new sales channel to import orders from an e-commerce platform.

Authorizations:
Bearer
Request Body schema: application/json
required

Sales channel connection data

name
required
string

Display name for the sales channel

code
required
string

Short operator-assigned code, unique per tenant. Uppercase alphanumerics with single internal dashes, 2-12 chars (lowercase is accepted and upcased). Embedded in human-facing document numbers (e.g. ORD-WEB-2026-0001). Immutable once set.

type
required
string

Platform type

credentials
required
object

Platform-specific credentials

object or null

Order-sync configuration. Omit the block, or any key within it, to take the domain defaults.

Responses

Request samples

Content type
application/json
{
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "manual",
  • "credentials": {
    },
  • "syncSettings": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Discover the channels a connection's store exposes

List the channels the connected store exposes so an operator can pick the channel_code a Sales Channel binds to. Reaches the store over its Integration connection credentials. A credential/transport failure (or a connector without discovery support) returns a clean 4xx, never a 500.

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

Integration connection ULID

query Parameters
only_enabled
boolean
Example: only_enabled=true

When true, return only channels that are enabled on the store

Responses

Response samples

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

Initiate a channel OAuth authorization-code flow

Mints a signed state token and returns the platform authorize URL the browser must navigate to. The OAuth provider is the {provider} path segment (the channel-type id).

Authorizations:
Bearer
path Parameters
provider
required
string

ChannelOAuth identifier

Request Body schema: application/json
optional

Optional provider extras plus optional URL overrides.

shop
string or null

Optional provider-specific store/shop handle

redirectUri
string or null

OAuth redirect_uri override

returnUri
string or null

Final user-facing URL to bounce to after the callback

channelId
string or null

Sales channel the resulting access token is attached to; bound into the state so the callback knows where to persist the grant

Responses

Request samples

Content type
application/json
{
  • "shop": "string",
  • "redirectUri": "string",
  • "returnUri": "string",
  • "channelId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "provider": "channel",
  • "authorizationUrl": "string",
  • "state": "string",
  • "expiresInSeconds": 0
}

Cross-channel outbound sync-health rollup

Aggregate the per-channel catalog-drift data across all of the tenant's channels into one in-sync / drifted / never-pushed rollup with a per-channel breakdown.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "sync-health",
  • "totals": {
    },
  • "channels": [
    ]
}

Test a sales channel connection

Test connectivity to an e-commerce platform with provided credentials.

Authorizations:
Bearer
Request Body schema: application/json
required

Connection test data

type
required
string

Platform type

credentials
required
object

Platform-specific credentials

Responses

Request samples

Content type
application/json
{
  • "type": "manual",
  • "credentials": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "connected": true,
  • "errorCode": "string",
  • "errorMessage": "string",
  • "checkedAt": "string",
  • "storeInfo": {
    }
}

Get a channel's catalog drift (variants out of sync)

Recompute each listing's effective-content hash and compare to the last-pushed version; variants that differ (or were never pushed) are drifted.

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "channelId": "string",
  • "driftedCount": 0,
  • "items": [
    ]
}

List a channel's drifted variants (paginated grid)

Recompute each listing's effective-content hash and compare to the last-pushed HEAD; the variants that differ (or were never pushed) are returned as a paginated, enriched grid.

Authorizations:
Bearer
path Parameters
channelId
required
string

ChannelDriftRow identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Preview a variant's drift diff (what the next push would change)

Compute the field-level delta between the variant's current effective content and the last-pushed HEAD. status=no_baseline when never pushed, in_sync when unchanged, drifted otherwise.

Authorizations:
Bearer
path Parameters
channelId
required
string

VariantDriftDiff identifier

variantId
required
string

VariantDriftDiff identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "variantId": "string",
  • "channelId": "string",
  • "status": "drifted",
  • "fields": [
    ]
}

Import (initialize) a channel's catalog

Queue an async, tracked catalog import: pull the channel's products into the local Catalog, creating variants and per-channel listings, and record a products sync run. Returns the channel; the import counts appear on the settled run (Sync History + Jobs panel).

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Get the raw inbound payload stored for a channel order

Return the original JSON the channel sent for an external order (as stored on the inbox). Used by Sync-run details to inspect the payload behind a failed record. 404 when no inbound message was recorded for the pair.

Authorizations:
Bearer
path Parameters
channelId
required
string
Example: 01HQWXYZ1234567890ABCDEF01

Sales channel ULID

externalOrderId
required
string
Example: 27

The channel's own order id (as shown on the sync record)

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "channelId": "01HQWXYZ1234567890ABCDEF01",
  • "externalOrderId": "27",
  • "inboundMessageId": "01HQWXYZ1234567890ABCDEF05",
  • "platform": "woocommerce",
  • "payload": "string",
  • "receivedAt": "2026-06-14T10:30:00+00:00"
}

Publish (push) the local catalog to a channel

Queue an async, tracked catalog publish: resolve effective per-channel content for every listing, push it to the channel, stamp the publication version, and record a products push run. Returns the channel; the publish counts appear on the settled run (Sync History + Jobs panel).

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

Sales channel ULID

query Parameters
force
boolean
Default: false

Republish ALL in-scope variants regardless of drift (propagate now — e.g. push freshly-converted prices onto existing records). Default false = drift-aware (skip unchanged).

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Publish (push) available-to-promise stock levels to a channel

Queue an async, tracked inventory publish: resolve available-to-promise for every listing, translate it through the channel backorder policy (defaults to deny), push the quantity to the channel, and record an inventory push run. Returns the channel; the publish counts appear on the settled run (Sync History + Jobs panel).

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Re-authorize an existing channel via OAuth (server-resolved shop)

Resolves the channel's previously connected shop server-side and returns the provider authorize URL (channel bound into the signed state). No shop input required.

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "channelId": "",
  • "authorizationUrl": "string",
  • "state": "string",
  • "expiresInSeconds": 0
}

List sync history for a sales channel

Retrieve a paginated list of sync runs for a single sales channel.

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

Sales channel ULID

query Parameters
status
string
Enum: "success" "failed"
Example: status=failed

Filter by sync status

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

Page number

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

Items per page

Responses

Response samples

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

List the records processed by a single sync run

Retrieve a paginated, action-filterable list of the individual records (orders) a sync run created, updated, skipped, or failed.

Authorizations:
Bearer
path Parameters
channelId
required
string
Example: 01HQWXYZ1234567890ABCDEF01

Sales channel ULID

syncId
required
string
Example: 01HQWXYZ1234567890ABCDEF02

Sync run ULID

query Parameters
action
string
Enum: "created" "updated" "unchanged" "skipped" "failed"
Example: action=failed

Filter by outcome

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

Page number

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

Items per page

Responses

Response samples

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

List webhook topic subscriptions for a channel

Returns the topics this channel is currently subscribed to on its external platform.

Authorizations:
Bearer
path Parameters
channelId
required
string

ChannelWebhookSubscription identifier

query Parameters
page
integer >= 1
Default: 1
itemsPerPage
integer [ 1 .. 100 ]
Default: 30

Responses

Response samples

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

Subscribe a channel to a webhook topic

Registers the topic with the channel's external platform. Idempotent — returns the existing subscription if the topic is already registered.

Authorizations:
Bearer
path Parameters
channelId
required
string

ChannelWebhookSubscription identifier

Request Body schema: application/json
required

Topic to subscribe to.

topic
required
string

Platform-specific topic identifier (e.g. orders/create)

Responses

Request samples

Content type
application/json
{
  • "topic": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "topic": "string",
  • "channelId": "string",
  • "externalWebhookId": "string",
  • "callbackUrl": "string",
  • "subscribedAt": "string"
}

List inbound webhook deliveries for a channel

Returns the delivery audit log — most recent first — with topic, processing status, and any error message. Optional topic / status filters narrow to a specific subscription or error class.

Authorizations:
Bearer
path Parameters
channelId
required
string

ChannelWebhookDelivery identifier

query Parameters
topic
string

Filter by topic

status
string
Enum: "received" "processed" "signature_failed" "invalid_payload" "failed"

Filter by processing status

page
integer >= 1
Default: 1
itemsPerPage
integer [ 1 .. 100 ]
Default: 30

Responses

Response samples

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

Get a single webhook topic subscription

Get a single webhook topic subscription

Authorizations:
Bearer
path Parameters
channelId
required
string

ChannelWebhookSubscription identifier

topic
required
string

ChannelWebhookSubscription identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "topic": "string",
  • "channelId": "string",
  • "externalWebhookId": "string",
  • "callbackUrl": "string",
  • "subscribedAt": "string"
}

Unsubscribe a channel from a webhook topic

Removes the topic subscription on the external platform. Idempotent — 204 even when the topic was not subscribed.

Authorizations:
Bearer
path Parameters
channelId
required
string

ChannelWebhookSubscription identifier

topic
required
string

ChannelWebhookSubscription identifier

Responses

Get a sales channel

Retrieve a single sales channel by its ULID.

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Delete a never-synced sales channel

HARD-delete a sales channel, removing it and freeing its code for reuse. Permitted ONLY for never-synced channels (no orders, listings, or sync runs) — the read model exposes a deletable flag to gate this. Channels with any history return 409 (errorCode OPERATION_NOT_ALLOWED); disconnect them instead.

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

Sales channel ULID

Responses

Update a key/secret channel's connection credentials

Partial-merge the channel's connection credentials (e.g. WooCommerce store_url / consumer_key / consumer_secret) into its backing Integration connection vault. The body is a PARTIAL map — send only the keys you are changing; an omitted or blank ("") key keeps its existing vaulted value ("leave blank = keep"). Supplying credentials clears the channel's auth-failure block so sync resumes. A store_url ending in /wp-admin is normalized (the segment is trimmed) since the connector appends /wp-json. The response carries the refreshed channel plus a connectionStatus — the outcome of probing the connection with the merged credentials (advisory; the credentials are saved regardless).

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

Sales channel ULID

Request Body schema: application/json
required

Partial credential map — only the keys being changed

required
object

Partial credential map; only non-empty keys are applied

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "channel": {
    },
  • "connectionStatus": {
    }
}

Configure the channel invoicing currency override

Set the per-channel default invoicing currency and/or the enabled currency set. Omit defaultCurrency to leave it; set clearDefaultCurrency to remove it. supportedCurrencies null leaves the set; an array replaces it (empty = no restriction).

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

Sales channel ULID

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

The updated Channel resource

defaultCurrency
string or null = 3 characters

ISO-4217 default currency code prefilled on invoices/payments for this channel. Omit (null) to leave the current default unchanged; set $clearDefaultCurrency to remove it.

supportedCurrencies
Array of strings

The enabled set of ISO-4217 codes for this channel. Null = leave alone; an array (possibly empty) = replace. Empty array means "no restriction".

clearDefaultCurrency
boolean
Default: false

When true, explicitly clears the channel's default currency.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "defaultCurrency": "str",
  • "supportedCurrencies": [
    ],
  • "clearDefaultCurrency": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Disconnect a sales channel

Disconnect a sales channel. This action is permanent.

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Configure the channel storefront locale override

Set the per-channel default storefront locale (e.g. en_US) and/or the enabled locale set. These are typically PULLED from the channel API (refresh-capabilities) rather than typed. Omit defaultLocale to leave it; set clearDefaultLocale to remove it. supportedLocales null leaves the set; an array replaces it (empty = no restriction).

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

Sales channel ULID

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

The updated Channel resource

defaultLocale
string or null^([A-Za-z]{2,3}([_-][A-Za-z0-9]{2,8})*)$

Default storefront locale (en_US, fr-CA) prefilled for this channel.

supportedLocales
Array of strings

The enabled set of locale codes for this channel. Null = leave alone; an array (possibly empty) = replace. Empty array means "no restriction".

clearDefaultLocale
boolean
Default: false

When true, explicitly clears the channel's default locale.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "defaultLocale": "string",
  • "supportedLocales": [
    ],
  • "clearDefaultLocale": false
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Pause a sales channel

Pause order synchronization for a sales channel.

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Refresh the channel currency + locale capabilities from its API

Pull the channel's default/supported currencies and locales from its platform API and apply them fill-when-empty: the discovered DEFAULT currency/locale is adopted ONLY when the operator has not set one (never clobbers an override), while the discovered SUPPORTED sets replace the current sets. Discovery is best-effort — a channel that exposes nothing (or has no backing connection) simply keeps its current config. Returns the refreshed channel.

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Resume a sales channel

Resume order synchronization for a paused sales channel.

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Update a sales channel's name and/or order-sync settings

Rename the channel and/or replace its order-sync configuration. Both fields are independently optional — omit one to leave that part of the channel untouched; omitting both is a no-op. syncSettings is a whole-value replacement: omitted keys within it fall back to the domain defaults (autoImportEnabled true, syncIntervalMinutes 15, statusFilters null, daysToLookBack 7) rather than retaining the channel's current values.

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

Sales channel ULID

Request Body schema: application/json
required

New channel name and/or sync settings

name
string

New display name for the channel

object

Replacement order-sync configuration block

Responses

Request samples

Content type
application/json
{
  • "name": "EU Storefront",
  • "syncSettings": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Set a sales channel's sourcing Principal

Set the single sourcing Principal (Inventory goods-owner) this channel sells for — the keystone for owner-correct order resolution. The principal is referenced as an opaque ResourceUri (glacia:///inventory/principals/{id}).

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

Sales channel ULID

Request Body schema: application/json
required

Sourcing principal reference

principalRef
required
string

Sourcing Principal ResourceUri (glacia:///inventory/principals/{id})

Responses

Request samples

Content type
application/json
{
  • "principalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Sync orders from a sales channel

Queue an async, tracked order sync from the sales channel (cursor/incremental).

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

Sales channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "name": "My Online Store",
  • "code": "WEB",
  • "type": "string",
  • "status": "active",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "merchantId": "01HQWXYZ1234567890ABCDEF",
  • "sourcingPrincipalRef": "glacia:///inventory/principals/01HQWXYZ1234567890ABCDEF",
  • "pullAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "pushAssortmentId": "01HQWXYZ1234567890ABCDEF",
  • "defaultFulfilmentPolicyId": "01HQWXYZ1234567890ABCDEF",
  • "defaultCurrency": "EUR",
  • "supportedCurrencies": [
    ],
  • "defaultLocale": "en_US",
  • "supportedLocales": [
    ],
  • "hasWebhook": true,
  • "deletable": true,
  • "syncSettings": {
    },
  • "connectorConfig": {
    },
  • "connectionId": "01JQ8Z9K3M4N5P6Q7R8S9T0V1W",
  • "webhookTopics": [
    ],
  • "lastSyncAt": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00"
}

Get a variant's per-channel sync status

For every channel the variant is listed on, recompute its effective-content hash and compare to the last-pushed version: never_pushed (no publication), drifted (hash changed), or in_sync.

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

Catalog Variant ULID

Responses

Response samples

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

Receive a webhook from an external platform

Endpoint for external platforms to send webhook events.

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

Sales channel ULID

Responses

Response samples

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

Sales - Channel Health

Represents the health status of a sales channel connection.

Get channel health status

Retrieve the health and connectivity status of a sales channel.

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

Channel ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "status": "healthy",
  • "responseTimeMs": 250,
  • "lastCheckedAt": "2024-06-14T10:30:00+00:00",
  • "errorMessage": "Connection timeout after 30s",
  • "consecutiveFailures": 0
}

Sales Channels - Mapping

Represents a set of field mapping rules for a sales channel.

Mapping rule sets define how fields from external platforms are transformed and mapped to the internal order format during import.

List all mapping rule sets

Retrieve a list of field mapping rule sets.

Authorizations:
Bearer
query Parameters
channelId
string
Example: channelId=01HQWXYZ1234567890ABCDEF

Filter by sales channel ID

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Create a mapping rule set

Create a new field mapping rule set for a sales channel.

Authorizations:
Bearer
Request Body schema: application/json
required

Mapping rule set data

channelId
required
string

Sales channel ID to associate with

name
required
string

Display name for the rule set

required
Array of objects

Mapping rules

isActive
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "name": "Order Mapping",
  • "rules": [
    ],
  • "isActive": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "name": "Order Mapping",
  • "rules": [
    ],
  • "isActive": true,
  • "createdAt": "2024-06-14T10:30:00+00:00"
}

Get a mapping rule set

Retrieve a single mapping rule set by its ID.

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

Mapping rule set ID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "name": "Order Mapping",
  • "rules": [
    ],
  • "isActive": true,
  • "createdAt": "2024-06-14T10:30:00+00:00"
}

Update a mapping rule set

Update an existing field mapping rule set.

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

Mapping rule set ID

Request Body schema:
required

The updated MappingRuleSet resource

channelId
required
string <= 255 characters
name
required
string <= 255 characters
required
Array of objects

Mapping rules.

isActive
boolean
Default: true

Responses

Request samples

Content type
{
  • "channelId": "string",
  • "name": "string",
  • "rules": [
    ],
  • "isActive": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "name": "Order Mapping",
  • "rules": [
    ],
  • "isActive": true,
  • "createdAt": "2024-06-14T10:30:00+00:00"
}

Delete a mapping rule set

Delete a field mapping rule set.

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

Mapping rule set ID

Responses

Sales Channels - Orders

Represents an order imported from a sales channel.

Orders are imported from e-commerce platforms and processed for fulfillment.

List all orders

Retrieve a paginated list of orders with optional filters.

Authorizations:
Bearer
query Parameters
channelId
string
Example: channelId=01HQWXYZ1234567890ABCDEF

Filter by sales channel ID

status
string
Enum: "pending" "processing" "ready" "partially_fulfilled" "fulfilled" "cancelled"
Example: status=pending

Filter by order status

fulfillmentStatus
string
Enum: "unfulfilled" "partially_fulfilled" "fulfilled"
Example: fulfillmentStatus=unfulfilled

Filter by fulfillment status

dateFrom
string <date-time>
Example: dateFrom=2024-06-01T00:00:00+00:00

Filter orders from this date (ISO 8601)

dateTo
string <date-time>
Example: dateTo=2024-06-14T23:59:59+00:00

Filter orders until this date (ISO 8601)

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 an order

Retrieve a single order by its ULID.

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

Order ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Approve a paused split-fulfilment plan

Resume the OrderFulfilmentLifecycleSaga when it has paused waiting for operator approval of a multi-source split. No-op if the saga is not in AwaitingApproval.

Authorizations:
Bearer
path Parameters
id
required
string

Order identifier

Request Body schema:
required

The new Order resource

id
string

Unique identifier (ULID) for the order

channelId
string

Sales channel ID where the order originated

channelName
string or null

Sales channel display name where the order originated

partnerId
string or null

Partner ID linked to this order

partnerName
string or null

Partner display name linked to this order

customerRef
string or null

Resolved Customer master record ID (ULID) linked to this order

customerName
string or null

Resolved customer display name linked to this order

customerEmail
string or null

Resolved customer contact email linked to this order

resolutionStatus
string or null
Value: "linked"
externalOrderId
string

External order ID from the sales channel

orderNumber
string
Default: ""

Human-readable Sales Order number allocated on import

status
string
Enum: "pending" "processing" "ready" "partially_fulfilled" "fulfilled" "cancelled"
fulfillmentStatus
string
Enum: "unfulfilled" "partially_fulfilled" "fulfilled"
object

Customer information

OrderAddress (object) or null
OrderAddress (object) or null
Array of objects

Order line items

totalInCents
integer

Total order amount in cents

currency
string

ISO 4217 currency code

totalItems
integer

Total number of items in the order

totalWeightGrams
integer or null

Total weight of the order in grams

orderDate
string or null

Date when the order was placed (ISO 8601)

createdAt
string

Timestamp when the order was imported (ISO 8601)

updatedAt
string

Timestamp when the order was last updated (ISO 8601)

childFulfilmentOrderIds
Array of strings

IDs of FulfilmentOrders spawned by this order

childShipmentIds
Array of strings

IDs of Shipments created downstream for this order

returnIds
Array of strings

IDs of RMAs raised against this order

childFulfilmentOrdersCount
integer
Default: 0

Number of FulfilmentOrders spawned by this order

childShipmentsCount
integer
Default: 0

Number of Shipments created downstream for this order

returnsCount
integer
Default: 0

Number of RMAs raised against this order

paymentStatus
string
Enum: "unpaid" "authorized" "captured" "refunded" "failed"
paymentFailedReason
string or null

Reason captured at the moment the order was last marked payment-failed

paymentCapturedAt
string or null

Timestamp when payment was captured (ISO 8601)

paymentRefundedAt
string or null

Timestamp when payment was refunded (ISO 8601)

stockReservationRef
string or null

ResourceUri of the stock reservation covering this order; null when no reservation is placed. Required (with captured payment and no blocking hold) before the order can be marked ready for fulfilment, UNLESS the order's inventory.out_of_stock hold is overridden — an override waives this requirement.

Responses

Request samples

Content type
{
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Cancel an order

Cancel an order. This will stop any pending fulfillment.

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

Order ULID

Request Body schema: application/json
optional

Cancellation data

reason
string or null

Reason for cancellation

Responses

Request samples

Content type
application/json
{
  • "reason": "Customer requested cancellation"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Create a fulfilment order for a sales order

Create one FulfilmentOrder for a subset of the order's lines, targeting a single custodian. Repeatable until the order is fully fulfilled. The recipient address is resolved server-side from the order; the backend validates the requested quantities against the order and rejects over-fulfilment. Returns the id of the FulfilmentOrder (created asynchronously).

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

Sales order ULID

Request Body schema: application/json
required

Custodian, optional warehouse, and the lines to fulfil

custodianId
required
string <ulid>
warehouseId
string or null <ulid>
deliveryInstructions
string or null
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "custodianId": "string",
  • "warehouseId": "string",
  • "deliveryInstructions": "string",
  • "lines": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "",
  • "orderId": "",
  • "custodianId": "",
  • "warehouseId": "string",
  • "status": "created"
}

Capture payment for an order

Record payment capture on an order. Required before the order can advance to READY.

Authorizations:
Bearer
path Parameters
id
required
string

Order identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Mark order payment failed

Record a payment failure with a freeform reason.

Authorizations:
Bearer
path Parameters
id
required
string

Order identifier

Request Body schema:
required

The new Order resource

reason
required
string <= 500 characters
Default: ""

Responses

Request samples

Content type
{
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Refund payment for an order

Record a payment refund on an order.

Authorizations:
Bearer
path Parameters
id
required
string

Order identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Mark order ready for fulfillment

Mark an order as ready for fulfillment after processing is complete.

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

Order ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Reject a paused split-fulfilment plan

Reject the OrderFulfilmentLifecycleSaga's multi-source split plan with a reason. The saga dispatches CancelOrderCommand which cascade-cancels every still-pending FulfilmentOrder.

Authorizations:
Bearer
path Parameters
id
required
string

Order identifier

Request Body schema:
required

The new Order resource

reason
required
string <= 500 characters
Default: ""

Reason for rejecting the split — surfaced on the resulting OrderCancelled event so operators see WHY the split was rejected.

Responses

Request samples

Content type
{
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Start processing an order

Start processing an order to create loads for fulfillment.

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

Order ULID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "channelName": "Main Store",
  • "partnerId": "01HQWXYZ1234567890ABCDEF",
  • "partnerName": "Acme Logistics",
  • "customerRef": "01HQWXYZ1234567890ABCDEF",
  • "customerName": "Acme Corp",
  • "customerEmail": "billing@acme.example",
  • "resolutionStatus": "linked",
  • "externalOrderId": "#1001",
  • "orderNumber": "ORD0000042",
  • "status": "pending",
  • "fulfillmentStatus": "unfulfilled",
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "billingAddress": {
    },
  • "orderLines": [
    ],
  • "totalInCents": 5000,
  • "currency": "EUR",
  • "totalItems": 3,
  • "totalWeightGrams": 1500,
  • "orderDate": "2024-06-14T10:30:00+00:00",
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "childFulfilmentOrderIds": [
    ],
  • "childShipmentIds": [
    ],
  • "returnIds": [
    ],
  • "childFulfilmentOrdersCount": 1,
  • "childShipmentsCount": 1,
  • "returnsCount": 0,
  • "paymentStatus": "unpaid",
  • "paymentFailedReason": "Card declined",
  • "paymentCapturedAt": "string",
  • "paymentRefundedAt": "string",
  • "stockReservationRef": "glacia:///warehousing/stock-reservations/01HZ..."
}

Sales - Retry Queue

Represents a retryable operation in the retry queue.

List retry queue operations

Retrieve a list of operations in the retry queue.

Authorizations:
Bearer
query Parameters
channelId
string
Example: channelId=01HQWXYZ1234567890ABCDEF

Filter by channel ID

status
string
Enum: "pending" "retrying" "succeeded" "failed" "abandoned"
Example: status=pending

Filter by retry status

page
integer
Default: 1

The collection page number

Responses

Response samples

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

Get a retry queue operation

Retrieve a single retry queue operation by its ID.

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

Retry operation ID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01HQWXYZ1234567890ABCDEF",
  • "channelId": "01HQWXYZ1234567890ABCDEF",
  • "operationType": "Glacia\\Sales\\Application\\Order\\SyncOrdersCommand",
  • "payload": {
    },
  • "status": "pending",
  • "attempts": 2,
  • "maxAttempts": 5,
  • "lastAttemptAt": "2024-06-14T10:30:00+00:00",
  • "nextRetryAt": "2024-06-14T10:32:00+00:00",
  • "errorMessage": "Connection timeout",
  • "createdAt": "2024-06-14T10:30:00+00:00"
}

Sales - Number Generation

Resource 'Sales - Number Generation' operations.

Generate an order number

Generate an order number

Authorizations:
Bearer
Request Body schema:
required

The new OrderNumber resource

number
string

The generated order number

type
string

Resource type

barcode
string or null

GS1-128 barcode (if applicable)

generatedAt
string

Generation timestamp (ISO 8601)

Responses

Request samples

Content type
{
  • "number": "ORD0000000001",
  • "type": "sales.order_number",
  • "barcode": "string",
  • "generatedAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "ORD0000000001",
  • "type": "sales.order_number",
  • "barcode": "string",
  • "generatedAt": "string"
}

Preview the next order number

Preview the next order number

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "ORD0000000001",
  • "type": "sales.order_number",
  • "barcode": "string",
  • "generatedAt": "string"
}

Sales Channel Listings

The auto-resolution of an unmapped channel order line to a catalog Variant, served by GET /api/sales/channel-listings/resolve for the "Map this SKU" drawer. Given a channel + the line's external ids (+ SKU fallback), it returns either a confident resolvedVariantId (the drawer auto-fills) or a list of candidates (the drawer shows suggestions). The mapping itself is NEVER created here — the pin button reuses the CreateChannelListing command.

List channel listings

Retrieve a paginated list of per-channel product → Variant mappings.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Create a channel listing mapping

Create a channel listing mapping

Authorizations:
Bearer
Request Body schema:
required

The new ChannelListing resource

channelId
required
string <= 100 characters
variantId
required
string <= 100 characters
matchedBy
required
string
Enum: "variant_id" "product_id" "sku"
externalVariantId
string or null <= 255 characters
externalProductId
string or null <= 255 characters
externalSku
string or null <= 255 characters
channelTitleOverride
string or null <= 255 characters
status
string or null
Enum: "active" "disabled" "unmapped"

Responses

Request samples

Content type
{
  • "channelId": "string",
  • "variantId": "string",
  • "matchedBy": "variant_id",
  • "externalVariantId": "string",
  • "externalProductId": "string",
  • "externalSku": "string",
  • "channelTitleOverride": "string",
  • "status": "active"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "channelId": "string",
  • "externalVariantId": "gid://platform/ProductVariant/123",
  • "externalProductId": "string",
  • "externalSku": "ABC-123",
  • "variantId": "string",
  • "variantName": "Red T-Shirt (Large)",
  • "productId": "string",
  • "productName": "Classic T-Shirt",
  • "matchedBy": "variant_id",
  • "channelTitleOverride": "Red T-Shirt (Large)",
  • "status": "active",
  • "contentVersion": 3,
  • "contentHash": "a1b2c3…",
  • "lastSyncedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Auto-resolve an unmapped channel line to a Variant

Resolves the internal Catalog Variant for an unmapped channel order line from its external variant/product ids and SKU, using the Identification channel keys the catalog import attached. Returns a confident resolvedVariantId or a list of candidates; never creates the mapping.

Authorizations:
Bearer
query Parameters
channelId
required
any

The owning Sales Channel ID (ULID)

externalVariantId
any

The channel's variant id from the order line

externalProductId
any

The channel's product id from the order line

sku
any

The order line SKU (fallback match)

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "unmapped-line-resolution",
  • "resolvedVariantId": "string",
  • "resolvedVariantName": "Red T-Shirt (Large)",
  • "resolvedSku": "ABC-123",
  • "matchReason": "channel_variant_key",
  • "candidates": [
    ]
}

Get a channel listing

Get a channel listing

Authorizations:
Bearer
path Parameters
id
required
string

ChannelListing identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "channelId": "string",
  • "externalVariantId": "gid://platform/ProductVariant/123",
  • "externalProductId": "string",
  • "externalSku": "ABC-123",
  • "variantId": "string",
  • "variantName": "Red T-Shirt (Large)",
  • "productId": "string",
  • "productName": "Classic T-Shirt",
  • "matchedBy": "variant_id",
  • "channelTitleOverride": "Red T-Shirt (Large)",
  • "status": "active",
  • "contentVersion": 3,
  • "contentHash": "a1b2c3…",
  • "lastSyncedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a channel listing

Remove a channel listing

Authorizations:
Bearer
path Parameters
id
required
string

ChannelListing identifier

Responses

Response samples

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

Update a channel listing

Update a channel listing

Authorizations:
Bearer
path Parameters
id
required
string

ChannelListing identifier

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

The updated ChannelListing resource

matchedBy
string
Enum: "variant_id" "product_id" "sku"
status
string
Enum: "active" "disabled" "unmapped"
channelTitleOverride
string or null <= 255 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "matchedBy": "variant_id",
  • "status": "active",
  • "channelTitleOverride": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "channelId": "string",
  • "externalVariantId": "gid://platform/ProductVariant/123",
  • "externalProductId": "string",
  • "externalSku": "ABC-123",
  • "variantId": "string",
  • "variantName": "Red T-Shirt (Large)",
  • "productId": "string",
  • "productName": "Classic T-Shirt",
  • "matchedBy": "variant_id",
  • "channelTitleOverride": "Red T-Shirt (Large)",
  • "status": "active",
  • "contentVersion": 3,
  • "contentHash": "a1b2c3…",
  • "lastSyncedAt": "string",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Sales Customer Resolution

A per-order customer identity-resolution review item (design §3, §9.3): the outcome, the scored candidates, and the operator actions (confirm / assign / reject). Keyed by the order id (the resolution id is derived from it).

List the customer resolution review queue

Paginated queue of orders awaiting customer resolution (pending/held by default).

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Get the resolution for an order

Get the resolution for an order

Authorizations:
Bearer
path Parameters
id
required
string

CustomerResolution identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "outcome": "auto_linked",
  • "reviewState": "none",
  • "chosenCustomerId": "string",
  • "ruleSetVersion": "string",
  • "candidates": [
    ],
  • "decidedAt": "string"
}

Assign an operator-chosen customer to the order

Assign an operator-chosen customer to the order

Authorizations:
Bearer
path Parameters
id
required
string

CustomerResolution identifier

Request Body schema:
required

The new CustomerResolution resource

customerId
required
string
Default: ""

The customer master record (ULID) to link to the order

Responses

Request samples

Content type
{
  • "customerId": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "outcome": "auto_linked",
  • "reviewState": "none",
  • "chosenCustomerId": "string",
  • "ruleSetVersion": "string",
  • "candidates": [
    ],
  • "decidedAt": "string"
}

Book the order to the channel CpD bucket (operator override)

Book the order to the channel CpD bucket (operator override)

Authorizations:
Bearer
path Parameters
id
required
string

CustomerResolution identifier

Request Body schema:
required

The new CustomerResolution resource

id
string

The order (ULID) whose customer is being resolved

outcome
string
Enum: "auto_linked" "pending_review" "held" "no_match"
reviewState
string
Enum: "none" "open" "resolved" "rejected"
chosenCustomerId
string or null

The linked customer (ULID) when resolved

ruleSetVersion
string

Rule-set version the decision was made under

Array of objects (ResolutionCandidate)
decidedAt
string or null

When the decision was recorded (ISO 8601)

Responses

Request samples

Content type
{
  • "id": "string",
  • "outcome": "auto_linked",
  • "reviewState": "none",
  • "chosenCustomerId": "string",
  • "ruleSetVersion": "string",
  • "candidates": [
    ],
  • "decidedAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "outcome": "auto_linked",
  • "reviewState": "none",
  • "chosenCustomerId": "string",
  • "ruleSetVersion": "string",
  • "candidates": [
    ],
  • "decidedAt": "string"
}

Confirm a suggested customer (links it to the order)

Confirm a suggested customer (links it to the order)

Authorizations:
Bearer
path Parameters
id
required
string

CustomerResolution identifier

Request Body schema:
required

The new CustomerResolution resource

customerId
required
string
Default: ""

The customer master record (ULID) to link to the order

Responses

Request samples

Content type
{
  • "customerId": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "outcome": "auto_linked",
  • "reviewState": "none",
  • "chosenCustomerId": "string",
  • "ruleSetVersion": "string",
  • "candidates": [
    ],
  • "decidedAt": "string"
}

Reject all candidates (no link)

Reject all candidates (no link)

Authorizations:
Bearer
path Parameters
id
required
string

CustomerResolution identifier

Request Body schema:
required

The new CustomerResolution resource

id
string

The order (ULID) whose customer is being resolved

outcome
string
Enum: "auto_linked" "pending_review" "held" "no_match"
reviewState
string
Enum: "none" "open" "resolved" "rejected"
chosenCustomerId
string or null

The linked customer (ULID) when resolved

ruleSetVersion
string

Rule-set version the decision was made under

Array of objects (ResolutionCandidate)
decidedAt
string or null

When the decision was recorded (ISO 8601)

Responses

Request samples

Content type
{
  • "id": "string",
  • "outcome": "auto_linked",
  • "reviewState": "none",
  • "chosenCustomerId": "string",
  • "ruleSetVersion": "string",
  • "candidates": [
    ],
  • "decidedAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "outcome": "auto_linked",
  • "reviewState": "none",
  • "chosenCustomerId": "string",
  • "ruleSetVersion": "string",
  • "candidates": [
    ],
  • "decidedAt": "string"
}

Sales Customers

A customer's credit / accounts-receivable profile (Customer 360, task #82): the operator-set credit limit + payment terms, and the DERIVED outstanding balance, overdue amount, and remaining available credit.

Read via GET; the credit terms are set via PATCH .../credit-terms. The AR figures are derived from the customer's Finance invoices/payments — see {@see \Glacia\Sales\Infrastructure\Persistence\Doctrine\Query\DbalCustomerCreditQueryService}.

List customer master records

Retrieve a paginated list of customer master records.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Register a customer master record for an existing partner

Register a customer master record for an existing partner

Authorizations:
Bearer
Request Body schema:
required

The new Customer resource

partnerId
required
string <= 100 characters

The existing Partner this customer wraps (the AR counterparty).

displayName
required
string <= 255 characters

Responses

Request samples

Content type
{
  • "partnerId": "string",
  • "displayName": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "displayName": "Acme Corp",
  • "type": "regular",
  • "status": "active",
  • "segments": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get the credit / AR profile for a customer

Credit limit, payment terms, outstanding AR balance, overdue amount, and available credit.

Authorizations:
Bearer
path Parameters
customerId
required
string

CustomerCredit identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "customerId": "string",
  • "creditLimit": 5000,
  • "paymentTermsDays": 30,
  • "arBalance": 1234.56,
  • "overdue": 200,
  • "availableCredit": 3765.44,
  • "currency": "EUR"
}

Set a customer's credit terms (limit, payment terms, currency)

Set a customer's credit terms (limit, payment terms, currency)

Authorizations:
Bearer
path Parameters
customerId
required
string

CustomerCredit identifier

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

The updated CustomerCredit resource

creditLimit
number or null >= 0
paymentTermsDays
integer or null >= 0
currency
string = 3 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "creditLimit": 0,
  • "paymentTermsDays": 0,
  • "currency": "str"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "customerId": "string",
  • "creditLimit": 5000,
  • "paymentTermsDays": 30,
  • "arBalance": 1234.56,
  • "overdue": 200,
  • "availableCredit": 3765.44,
  • "currency": "EUR"
}

Get the Customer 360 hero KPIs for a customer

Lifetime value, order count, last-order date, and status for the customer.

Authorizations:
Bearer
path Parameters
customerId
required
string

CustomerKpi identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "customerId": "string",
  • "ltv": 1234.56,
  • "currency": "EUR",
  • "orderCount": 7,
  • "lastOrderAt": "string",
  • "status": "active"
}

Get a customer master record

Get a customer master record

Authorizations:
Bearer
path Parameters
id
required
string

Customer identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "displayName": "Acme Corp",
  • "type": "regular",
  • "status": "active",
  • "segments": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Add a segment / tag to this customer

Add a segment / tag to this customer

Authorizations:
Bearer
path Parameters
id
required
string

Customer identifier

Request Body schema:
required

The new Customer resource

segment
required
string <= 64 characters

Responses

Request samples

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

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "displayName": "Acme Corp",
  • "type": "regular",
  • "status": "active",
  • "segments": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a segment / tag from this customer

Remove a segment / tag from this customer

Authorizations:
Bearer
path Parameters
segment
required
string

The segment / tag to remove

id
required
string

Customer identifier

Responses

Response samples

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

Sales Merchants

A Sales merchant — the seller-of-record / channel-operator profile. LINKS to an existing Partner (the selling party's legal/contact identity) and layers selling-specific state on top: the seller-of-record selling name, default sales currency, and the tax registration used when selling.

Tenant-managed reference data. The linked partner is immutable once set.

List merchant profiles

Retrieve a paginated list of merchant (seller-of-record) profiles.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Register a merchant profile for an existing partner

Register a merchant profile for an existing partner

Authorizations:
Bearer
Request Body schema:
required

The new Merchant resource

partnerId
required
string <= 100 characters

The existing Partner this merchant wraps (the selling party's legal identity).

code
required
string [ 2 .. 12 ] characters ^([A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)$

Short operator-assigned code, unique per tenant. Embedded in human-facing document numbers, so the format is deliberately narrow — see {@see \Glacia\Sales\Domain\Merchant\MerchantCode}. Normalized to uppercase by the domain, so acme and ACME are the same code.

sellingName
required
string <= 255 characters
defaultCurrency
required
string = 3 characters
sellerTaxRegistration
string or null <= 64 characters

Responses

Request samples

Content type
{
  • "partnerId": "string",
  • "code": "string",
  • "sellingName": "string",
  • "defaultCurrency": "str",
  • "sellerTaxRegistration": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "code": "ACME",
  • "sellingName": "Acme Store",
  • "status": "onboarding",
  • "defaultCurrency": "USD",
  • "sellerTaxRegistration": "DE123456789",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a merchant profile

Get a merchant profile

Authorizations:
Bearer
path Parameters
id
required
string

Merchant identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "code": "ACME",
  • "sellingName": "Acme Store",
  • "status": "onboarding",
  • "defaultCurrency": "USD",
  • "sellerTaxRegistration": "DE123456789",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update a merchant selling profile

Update a merchant selling profile

Authorizations:
Bearer
path Parameters
id
required
string

Merchant identifier

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

The updated Merchant resource

sellingName
string <= 255 characters
defaultCurrency
string = 3 characters
sellerTaxRegistration
string or null <= 64 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "sellingName": "string",
  • "defaultCurrency": "str",
  • "sellerTaxRegistration": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "code": "ACME",
  • "sellingName": "Acme Store",
  • "status": "onboarding",
  • "defaultCurrency": "USD",
  • "sellerTaxRegistration": "DE123456789",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate a merchant profile

Activate a merchant profile

Authorizations:
Bearer
path Parameters
id
required
string

Merchant identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "code": "ACME",
  • "sellingName": "Acme Store",
  • "status": "onboarding",
  • "defaultCurrency": "USD",
  • "sellerTaxRegistration": "DE123456789",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate a merchant profile

Deactivate a merchant profile

Authorizations:
Bearer
path Parameters
id
required
string

Merchant identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "code": "ACME",
  • "sellingName": "Acme Store",
  • "status": "onboarding",
  • "defaultCurrency": "USD",
  • "sellerTaxRegistration": "DE123456789",
  • "createdAt": "string",
  • "updatedAt": "string"
}

Return

Resource 'Return' operations.

Retrieves the collection of Return resources.

Retrieves the collection of Return resources.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Creates a Return resource.

Creates a Return resource.

Authorizations:
Bearer
Request Body schema:
required

The new Return resource

orderId
required
string
Default: ""

Originating Sales.Order id (ULID)

partnerId
required
string
Default: ""

Customer Partner ID (ULID)

requestedBy
required
string
Default: ""

Identity URI of the customer or operator initiating the return

reason
string
Enum: "damaged" "wrong_item" "not_as_described" "no_longer_needed" "defective_on_arrival" "late_delivery" "other"
customerNote
string or null

Optional free-form note from the customer

Array of objects (ReturnLineInput)
orderDeliveredAt
string or null

When the originating order was delivered (drives eligibility window)

Responses

Request samples

Content type
{
  • "orderId": "",
  • "partnerId": "",
  • "requestedBy": "",
  • "reason": "damaged",
  • "customerNote": "string",
  • "lines": [
    ],
  • "orderDeliveredAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "orderId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "requestedBy": "string",
  • "reason": "string",
  • "customerNote": "string",
  • "status": "string",
  • "eligibilityWindow": "string",
  • "inboundShipmentId": "string",
  • "resolution": "string",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string",
  • "inspectionNotes": "string",
  • "operatorDecision": "string",
  • "rejectionReason": "string",
  • "cancellationReason": "string",
  • "requestedAt": "string",
  • "lines": [
    ]
}

Retrieves a Return resource.

Retrieves a Return resource.

Authorizations:
Bearer
path Parameters
id
required
string

Return identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "orderId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "requestedBy": "string",
  • "reason": "string",
  • "customerNote": "string",
  • "status": "string",
  • "eligibilityWindow": "string",
  • "inboundShipmentId": "string",
  • "resolution": "string",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string",
  • "inspectionNotes": "string",
  • "operatorDecision": "string",
  • "rejectionReason": "string",
  • "cancellationReason": "string",
  • "requestedAt": "string",
  • "lines": [
    ]
}

Creates a Return resource.

Creates a Return resource.

Authorizations:
Bearer
path Parameters
id
required
string

Return identifier

Request Body schema:
required

The new Return resource

authorizedBy
required
string
Default: ""

Identity URI of the operator authorizing

operatorNote
string or null

Optional operator note

Responses

Request samples

Content type
{
  • "authorizedBy": "",
  • "operatorNote": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "orderId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "requestedBy": "string",
  • "reason": "string",
  • "customerNote": "string",
  • "status": "string",
  • "eligibilityWindow": "string",
  • "inboundShipmentId": "string",
  • "resolution": "string",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string",
  • "inspectionNotes": "string",
  • "operatorDecision": "string",
  • "rejectionReason": "string",
  • "cancellationReason": "string",
  • "requestedAt": "string",
  • "lines": [
    ]
}

Creates a Return resource.

Creates a Return resource.

Authorizations:
Bearer
path Parameters
id
required
string

Return identifier

Request Body schema:
required

The new Return resource

cancelledBy
required
string
Default: ""

Identity URI of the actor cancelling

reason
required
string
Default: ""

Cancellation reason

Responses

Request samples

Content type
{
  • "cancelledBy": "",
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "orderId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "requestedBy": "string",
  • "reason": "string",
  • "customerNote": "string",
  • "status": "string",
  • "eligibilityWindow": "string",
  • "inboundShipmentId": "string",
  • "resolution": "string",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string",
  • "inspectionNotes": "string",
  • "operatorDecision": "string",
  • "rejectionReason": "string",
  • "cancellationReason": "string",
  • "requestedAt": "string",
  • "lines": [
    ]
}

Creates a Return resource.

Creates a Return resource.

Authorizations:
Bearer
path Parameters
id
required
string

Return identifier

Request Body schema:
required

The new Return resource

operatorRef
required
string
Default: ""

Identity URI of the inspecting operator

Array of objects (LineInspectionInput)
inspectionNotes
string or null

Optional inspection notes

Responses

Request samples

Content type
{
  • "operatorRef": "",
  • "results": [
    ],
  • "inspectionNotes": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "orderId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "requestedBy": "string",
  • "reason": "string",
  • "customerNote": "string",
  • "status": "string",
  • "eligibilityWindow": "string",
  • "inboundShipmentId": "string",
  • "resolution": "string",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string",
  • "inspectionNotes": "string",
  • "operatorDecision": "string",
  • "rejectionReason": "string",
  • "cancellationReason": "string",
  • "requestedAt": "string",
  • "lines": [
    ]
}

Creates a Return resource.

Creates a Return resource.

Authorizations:
Bearer
path Parameters
id
required
string

Return identifier

Request Body schema:
required

The new Return resource

rejectedBy
required
string
Default: ""

Identity URI of the operator rejecting

reason
required
string
Default: ""

Reason for rejection

Responses

Request samples

Content type
{
  • "rejectedBy": "",
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "orderId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "requestedBy": "string",
  • "reason": "string",
  • "customerNote": "string",
  • "status": "string",
  • "eligibilityWindow": "string",
  • "inboundShipmentId": "string",
  • "resolution": "string",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string",
  • "inspectionNotes": "string",
  • "operatorDecision": "string",
  • "rejectionReason": "string",
  • "cancellationReason": "string",
  • "requestedAt": "string",
  • "lines": [
    ]
}

Creates a Return resource.

Creates a Return resource.

Authorizations:
Bearer
path Parameters
id
required
string

Return identifier

Request Body schema:
required

The new Return resource

operatorRef
required
string
Default: ""

Identity URI of the resolving operator

resolution
string
Enum: "refunded" "partially_refunded" "store_credit" "replaced" "rejected_after_inspection"
refundAmountCents
integer or null

Refund amount in cents (required when resolution generates a credit note)

restockingFeeCents
integer or null

Restocking fee in cents

currencyCode
string or null

ISO 4217 currency code (required when monetary amounts are supplied)

Responses

Request samples

Content type
{
  • "operatorRef": "",
  • "resolution": "refunded",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "number": "string",
  • "orderId": "string",
  • "partnerId": "string",
  • "partnerName": "string",
  • "requestedBy": "string",
  • "reason": "string",
  • "customerNote": "string",
  • "status": "string",
  • "eligibilityWindow": "string",
  • "inboundShipmentId": "string",
  • "resolution": "string",
  • "refundAmountCents": 0,
  • "restockingFeeCents": 0,
  • "currencyCode": "string",
  • "inspectionNotes": "string",
  • "operatorDecision": "string",
  • "rejectionReason": "string",
  • "cancellationReason": "string",
  • "requestedAt": "string",
  • "lines": [
    ]
}